From d26cccadd79c499bbbde538a0dca45cfff0c2e1e Mon Sep 17 00:00:00 2001 From: Joseph Schorr Date: Wed, 28 Oct 2026 11:48:14 -0400 Subject: [PATCH 1/8] oap: add a [?] filter marker for install-question bindings A resourceList answer bound to Kind/name#path[?] keeps only the list elements whose discriminator the answer names, in the CR's own order. It lets a bundle offer a menu (every candidate declared, the installer picks which stay). An answer naming no element fails the install rather than being silently dropped, and re-applying the same answer is a no-op. --- pkg/platform/oap/overlay.go | 50 +++++++++++++++++++++ pkg/platform/oap/overlay_test.go | 76 ++++++++++++++++++++++++++++++++ pkg/platform/oap/target.go | 21 ++++++++- pkg/platform/oap/target_test.go | 9 ++++ 4 files changed, 154 insertions(+), 2 deletions(-) diff --git a/pkg/platform/oap/overlay.go b/pkg/platform/oap/overlay.go index 0f727210..f8d96017 100644 --- a/pkg/platform/oap/overlay.go +++ b/pkg/platform/oap/overlay.go @@ -80,6 +80,50 @@ func normalize(v any) any { } } +// filterList cuts the list at cur[field] down to the elements whose +// discriminator appears in the answer list, keeping the CR's own order. An +// answer naming no element fails closed: a typo'd selection must not silently +// install an agent missing the thing the operator chose. Filtering an +// already-filtered list by the same answer is a no-op, so a re-install applies +// byte-identical spec. +func filterList(cur map[string]any, field string, value any) error { + keep, ok := value.([]any) + if !ok { + return fmt.Errorf("filter marker %q[?] requires a list answer, got %T", field, value) + } + listRaw, ok := cur[field].([]any) + if !ok { + return fmt.Errorf("path element %q is not a list", field) + } + disc := discriminatorFor(field) + present := make(map[string]bool, len(listRaw)) + for _, item := range listRaw { + if mm, ok := item.(map[string]any); ok { + if s, _ := mm[disc].(string); s != "" { + present[s] = true + } + } + } + wanted := make(map[string]bool, len(keep)) + for _, k := range keep { + s, _ := k.(string) + if !present[s] { + return fmt.Errorf("no %s element with %s=%q", field, disc, s) + } + wanted[s] = true + } + filtered := make([]any, 0, len(keep)) + for _, item := range listRaw { + if mm, ok := item.(map[string]any); ok { + if s, _ := mm[disc].(string); wanted[s] { + filtered = append(filtered, item) + } + } + } + cur[field] = filtered + return nil +} + // setAtPath walks node along path and sets value at the final segment. func setAtPath(node map[string]any, path []Segment, value any) error { cur := node @@ -111,6 +155,12 @@ func setAtPath(node map[string]any, path []Segment, value any) error { cur[seg.Field] = merged return nil } + if seg.Filter { + if !last { + return fmt.Errorf("filter marker %q[?] must be the final path segment", seg.Field) + } + return filterList(cur, seg.Field, value) + } if seg.Selector == "" { if last { cur[seg.Field] = value diff --git a/pkg/platform/oap/overlay_test.go b/pkg/platform/oap/overlay_test.go index ac0152aa..0f89593f 100644 --- a/pkg/platform/oap/overlay_test.go +++ b/pkg/platform/oap/overlay_test.go @@ -124,6 +124,82 @@ func TestApply_AppendMarker_NestedMapField(t *testing.T) { "answer appended onto the pre-declared empty list at spec.config.allowedRepos") } +// skillsClassFixture is an AgentClass declaring every candidate skill a bundle +// offers; a `spec.skills[?]` question keeps only the ones the installer picks. +func skillsClassFixture(names ...string) *unstructured.Unstructured { + skills := make([]any, len(names)) + for i, n := range names { + skills[i] = map[string]any{"name": n, "ref": "github.com/example/skills//skills/" + n + "@v1"} + } + return &unstructured.Unstructured{Object: map[string]any{ + "apiVersion": "agentprimitives.authzed.com/v1alpha1", + "kind": "AgentClass", + "metadata": map[string]any{"name": "demo-agent"}, + "spec": map[string]any{"skills": skills}, + }} +} + +func skillNames(t *testing.T, cls *unstructured.Unstructured) []string { + t.Helper() + skills, _, err := unstructured.NestedSlice(cls.Object, "spec", "skills") + require.NoError(t, err) + out := []string{} + for _, s := range skills { + out = append(out, s.(map[string]any)["name"].(string)) + } + return out +} + +func TestApply_FilterMarker(t *testing.T) { + skillsQ := []Question{{Name: "skills", Type: QResourceList, + Binding: []Binding{{Target: "AgentClass/demo-agent#spec.skills[?]"}}}} + + cases := []struct { + name string + have []string + answer any + want []string + wantErr string + }{ + {name: "subset selected: only the named elements survive, in CR order", + have: []string{"alpha", "beta", "gamma"}, answer: []string{"gamma", "alpha"}, want: []string{"alpha", "gamma"}}, + {name: "every element selected: list unchanged", + have: []string{"alpha", "beta"}, answer: []string{"alpha", "beta"}, want: []string{"alpha", "beta"}}, + {name: "nothing selected: list emptied, not left whole", + have: []string{"alpha", "beta"}, answer: []string{}, want: []string{}}, + {name: "unknown name: fails closed instead of silently dropping it", + have: []string{"alpha"}, answer: []string{"alpah"}, wantErr: `no skills element with name="alpah"`}, + {name: "scalar answer: refused", + have: []string{"alpha"}, answer: "alpha", wantErr: "requires a list answer"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + cls := skillsClassFixture(tc.have...) + err := Apply([]*unstructured.Unstructured{cls}, skillsQ, Answers{"skills": tc.answer}) + if tc.wantErr != "" { + require.Error(t, err) + assert.Contains(t, err.Error(), tc.wantErr) + return + } + require.NoError(t, err) + assert.Equal(t, tc.want, skillNames(t, cls)) + }) + } +} + +func TestApply_FilterMarker_IdempotentReapply(t *testing.T) { + // Filtering an already-filtered list by the same answer is a no-op, so a + // re-install SSA-applies byte-identical spec. + cls := skillsClassFixture("alpha", "beta", "gamma") + qs := []Question{{Name: "skills", Type: QResourceList, + Binding: []Binding{{Target: "AgentClass/demo-agent#spec.skills[?]"}}}} + ans := Answers{"skills": []string{"beta"}} + require.NoError(t, Apply([]*unstructured.Unstructured{cls}, qs, ans)) + first := cls.DeepCopy() + require.NoError(t, Apply([]*unstructured.Unstructured{cls}, qs, ans)) + assert.Equal(t, first.Object, cls.Object) +} + func TestApply_MissingTargetCR_Errors(t *testing.T) { qs := []Question{{Name: "endpoint", Type: QString, Binding: []Binding{{Target: "MCPServer/nope#spec.upstream.endpoint"}}}} err := Apply([]*unstructured.Unstructured{agentClassFixture()}, qs, Answers{"endpoint": "x"}) diff --git a/pkg/platform/oap/target.go b/pkg/platform/oap/target.go index a803c39d..af701a8a 100644 --- a/pkg/platform/oap/target.go +++ b/pkg/platform/oap/target.go @@ -12,7 +12,12 @@ import ( // A segment is a map key ("spec", "channelID") or a typed list selector // "field[key]" selecting the list element whose discriminator equals key // (e.g. "boundEntities[github_repo]" → the element with -// resourceType=="github_repo"). See discriminatorFor in overlay.go. +// resourceType=="github_repo"). See discriminatorFor in overlay.go. Two +// bracket forms are markers rather than selectors, and both must be the final +// segment: "field[]" unions the answer list onto the field, and "field[?]" +// filters the field's list down to the elements whose discriminator the answer +// names — the way a bundle offers a menu (every candidate skill declared, the +// installer picks which ones stay). type Target struct { Kind string Name string @@ -23,6 +28,7 @@ type Segment struct { Field string // always set Selector string // non-empty → list element selected by discriminator==Selector Append bool // "field[]" (empty brackets) → union the answer list onto the field + Filter bool // "field[?]" → keep only the list elements the answer names } func ParseTarget(s string) (Target, error) { @@ -49,11 +55,19 @@ func ParseTarget(s string) (Target, error) { if seg.Field == "" { return Target{}, fmt.Errorf("target %q: bad selector in %q", s, raw) } - if seg.Selector == "" { + switch seg.Selector { + case "": // Empty brackets "field[]" are the append/union marker, not an // element selector. The answer list is merged onto whatever the // CR already declares for this field (see setAtPath). seg.Append = true + case "?": + // "field[?]" is the filter marker: the CR's list is cut down to + // the elements the answer names (see setAtPath). "?" can never + // be a real discriminator value worth selecting by, so it is + // safe to reserve. + seg.Selector = "" + seg.Filter = true } } t.Path = append(t.Path, seg) @@ -62,6 +76,9 @@ func ParseTarget(s string) (Target, error) { if seg.Append && i != len(t.Path)-1 { return Target{}, fmt.Errorf("target %q: append marker %q[] must be the final segment", s, seg.Field) } + if seg.Filter && i != len(t.Path)-1 { + return Target{}, fmt.Errorf("target %q: filter marker %q[?] must be the final segment", s, seg.Field) + } } return t, nil } diff --git a/pkg/platform/oap/target_test.go b/pkg/platform/oap/target_test.go index 96de164a..d8868f6d 100644 --- a/pkg/platform/oap/target_test.go +++ b/pkg/platform/oap/target_test.go @@ -16,6 +16,14 @@ func TestParseTarget_AppendMarker(t *testing.T) { assert.Equal(t, []Segment{{Field: "spec"}, {Field: "toolchains", Append: true}}, got.Path) } +func TestParseTarget_FilterMarker(t *testing.T) { + // `field[?]` marks the terminal segment as a filter: the CR's list is cut + // down to the elements the answer names, instead of being added to. + got, err := ParseTarget("AgentClass/demo-agent#spec.skills[?]") + require.NoError(t, err) + assert.Equal(t, []Segment{{Field: "spec"}, {Field: "skills", Filter: true}}, got.Path) +} + func TestParseTarget(t *testing.T) { t.Run("scalar path", func(t *testing.T) { got, err := ParseTarget("MCPServer/pm-linear#spec.upstream.endpoint") @@ -42,6 +50,7 @@ func TestParseTarget(t *testing.T) { {"empty segment", "AgentClass/pm#spec..x", "empty path segment"}, {"unterminated selector", "AgentClass/pm#spec.boundEntities[github_repo.defaults", "unterminated selector"}, {"append marker not final", "AgentClass/pm#spec.boundEntities[].defaults", "final segment"}, + {"filter marker not final", "AgentClass/pm#spec.skills[?].ref", "final segment"}, } for _, tc := range bad { t.Run(tc.name+": error", func(t *testing.T) { From 5daade48e7ae49057f47143695c481022ceb227d Mon Sep 17 00:00:00 2001 From: Joseph Schorr Date: Wed, 28 Oct 2026 11:48:14 -0400 Subject: [PATCH 2/8] examples: add messagingbot, an open-source brand-designer agent Turns a brief into an on-brand HTML artifact grounded in the design and messaging repositories chosen at install, and revises it from annotations left on the rendered page. GitHub access is read-only and limited to the approved repositories; the design skills are a menu the installer picks from. --- examples/messagingbot/README.md | 142 +++++++++++++++ examples/messagingbot/assets/logo.svg | 13 ++ .../messagingbot/manifests/agentclass.yaml | 162 ++++++++++++++++++ .../messagingbot/manifests/agentidentity.yaml | 24 +++ .../messagingbot/manifests/skillsources.yaml | 39 +++++ .../messagingbot/manifests/spiceboxclass.yaml | 28 +++ examples/messagingbot/manifests/toolspec.yaml | 48 ++++++ examples/messagingbot/oap.yaml | 73 ++++++++ .../toolspec/messagingbot_constraints_test.go | 125 ++++++++++++++ 9 files changed, 654 insertions(+) create mode 100644 examples/messagingbot/README.md create mode 100644 examples/messagingbot/assets/logo.svg create mode 100644 examples/messagingbot/manifests/agentclass.yaml create mode 100644 examples/messagingbot/manifests/agentidentity.yaml create mode 100644 examples/messagingbot/manifests/skillsources.yaml create mode 100644 examples/messagingbot/manifests/spiceboxclass.yaml create mode 100644 examples/messagingbot/manifests/toolspec.yaml create mode 100644 examples/messagingbot/oap.yaml create mode 100644 pkg/tools/toolspec/messagingbot_constraints_test.go diff --git a/examples/messagingbot/README.md b/examples/messagingbot/README.md new file mode 100644 index 00000000..40a6ab1b --- /dev/null +++ b/examples/messagingbot/README.md @@ -0,0 +1,142 @@ + + +# messagingbot + +A senior brand-designer agent, packaged as a `.oap` agent container. Give it a +brief and it scopes the work, reads your design system and messaging from +GitHub (read-only), and produces an on-brand **HTML** artifact: a landing +section, an announcement, a one-pager, an email-ready block. Open the artifact +in the live viewer, pin notes to the elements that are wrong, send them, and it +revises the same artifact in place. + +It is the open-source version of the brand agent we run internally, and it is +built entirely from primitives OAP already has — the artifact system, the +viewer's annotation interaction, agent skills, and a read-only toolspec. See +the [case study](https://openap.org/stories/claude-design) for the +walkthrough. + +No channel is baked in. A Channel is per-install config, not part of the +container; attach one after installing (see below). + +## Bundle layout + +``` +messagingbot/ + oap.yaml # manifest: the PAT, brand repos, and skill-menu questions + manifests/ + agentclass.yaml # AgentClass messagingbot (prompt, skill menu, config plane, capabilities) + agentidentity.yaml # AgentIdentity messagingbot-id (injects the PAT as GITHUB_TOKEN) + spiceboxclass.yaml # SpiceboxClass messagingbot-gh (sandbox: gh only, GitHub-only egress) + toolspec.yaml # SpiceboxToolspec messagingbot-gh-read (GET-only, allowlisted repos) + skillsources.yaml # one SkillSource per selectable skill, pinned to a commit + assets/logo.svg + README.md +``` + +The Secret holding the PAT is **not** in the bundle. It is materialized at +install from the `githubToken` question and never travels with the container. + +## Install questions + +| Question | What it sets | Default | +| ------------- | ------------------------------------------------ | --------------------------------- | +| `githubToken` | Secret `messagingbot-github` | (required) | +| `brandRepos` | appended to `spec.config.readableRepos` | none: designs from skills alone | +| `skills` | which `spec.skills` entries stay (`[?]` filter) | `frontend-design`, `theme-factory` | + +### Selectable skills + +`agentclass.yaml` declares the whole menu in `spec.skills`. The `skills` +question binds to `AgentClass/messagingbot#spec.skills[?]`, a **filter** marker: +the list is narrowed to the entries whose `name` you pick, in the order the +AgentClass declares them. Picking a name that isn't on the menu fails the +install instead of silently dropping it, and re-installing with the same +answer is a byte-identical no-op. + +| Skill | Source | Why | +| ----------------- | ---------------------------------------------- | --------------------------------------------------------------------------- | +| `frontend-design` | `github.com/anthropics/skills//skills/frontend-design` | A deliberate visual direction instead of templated defaults. | +| `theme-factory` | `github.com/anthropics/skills//skills/theme-factory` | Ten preset palettes and font pairings, or a generated theme, when there is no brand system. | + +To add your own skill, such as your company's brand-voice skill, add a +SkillSource for its repository and an entry to `spec.skills` with its +canonical name, then add the name to the question's `enum`. + +Both sources are pinned to a commit SHA. A skill is instructions the model +follows, so a branch ref would let those instructions change under an unchanged +install. Bump the SkillSource `ref` and the `spec.skills` refs together. + +`load_skill` returns a skill's `SKILL.md` only. Supporting files (for example +theme-factory's `themes/`) are read from `anthropics/skills` with the same +read-only `gh` tool, which is why that repository ships in +`spec.config.readableRepos`. + +## Read-only access: three rings + +1. **The token.** Create a fine-grained PAT at + https://github.com/settings/personal-access-tokens/new with **Contents: + Read-only** on your brand repositories, and nothing else. No call can write, + whatever the toolspec allows. +2. **The verbs.** `messagingbot-gh-read` allows `gh api`, `gh repo view`, and + `gh auth status`. `gh api` is GET-only: no `-X`, `-f`/`-F`, `--input`, or + `--hostname`, and only `repos/OWNER/NAME/...` endpoints, so every call names + a repository. +3. **The repositories.** Every repository a call names must match + `spec.config.readableRepos`: `anthropics/skills` plus whatever you answered + for `brandRepos`. Entries are lowercase `owner/repo` or `owner/*`. + +## Prerequisites + +- A cluster with OAP installed (`oap install`) and a **cluster default model** + configured (`oap init` / `oap settings wizard`). This agent pins no model. +- The `oap` CLI on your PATH. +- The read-only PAT described above. + +## Install + +```bash +oap agent lint examples/messagingbot +oap agent install examples/messagingbot --namespace default +``` + +Non-interactively: + +```bash +cat > /tmp/messagingbot-values.yaml <<'EOF' +githubToken: github_pat_... +brandRepos: [acme/design, acme/messaging] +skills: [frontend-design] +EOF +oap agent install examples/messagingbot --namespace default --values /tmp/messagingbot-values.yaml +``` + +Install isolated copies with `--name `: every CR and the Secret are +prefixed together. + +## Attach a channel + +```bash +oap channel create --kind slack +``` + +Pick `messagingbot` when asked which AgentClass to bind. Slack posts the HTML +artifact with a button that opens it in the live viewer, where the annotations +happen. The browser chat works too. + +## Try it + +> Design a landing-page hero announcing our autopilot feature for warehouse +> ops leads. Goal: book a demo. Use acme/design and acme/messaging. + +1. If the brief is thin, it asks 2–4 clarifying questions first. +2. It posts a plan, loads its skills, and reads your repos. +3. It returns an HTML artifact and offers the live view. +4. In the viewer, annotate the elements you want changed and send the batch. + It revises the same artifact, and the revision history keeps every version. + +## Notes + +- **HTML + CSS only.** JavaScript, remote stylesheets, iframes, and remote SVG + are stripped on render. `data:` images and inline `