feat(agents): formal declarative agent-definition schema (#51) - #62
Merged
Conversation
Second slice of the "creator way" (#58): one validated shape describing everything an agent IS as data, so an agent can be defined without a platform code change. - lib/agent-definition.ts: AgentDefinition + sanitizeAgentDefinition(input) — composes the existing per-field sanitizers (capabilities, tools, settings schema) + the canonical defaultGuardrails normalizer, and emits exactly the agents.config shape the platform already reads (identity{personality,goal,guardrails,welcomeMessage} + capabilities{surfaces,runtime,workflow,tools} + settingsSchema). Never throws — coerces/drops to safe defaults, so it's safe on an untrusted request body. - agent-capabilities.ts: sanitizeDeclaredCapabilities(raw) — validates a raw capabilities object (drop unknown surfaces/runtime/workflow, tools via sanitizeToolList). Reused by the definition + usable by PUT /:id/capabilities. Round-trip test proves the emitted config resolves through the same agentCapabilities registry the runtime uses. 692 workers/api tests pass; typecheck clean. Pure library — no route/DO changes; wiring create/update to accept a full definition is the next PR. Part of #58. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
5 tasks
serge-ivo
pushed a commit
that referenced
this pull request
Aug 1, 2026
) sanitizeAgentDefinition / AgentDefinition had zero non-test consumers — built as a "pure library, wiring deferred to the next PR" that never came. The lead-finder (and every agent so far) is a standalone worker or a config chat agent; nothing consumes the declarative definition. Removed agent-definition.{ts,test.ts} plus the helpers added solely for it (sanitizeDeclaredCapabilities, DeclaredCapabilities, KNOWN_RUNTIMES, KNOWN_WORKFLOWS). KEPT (live): the tool catalog + capabilities.tools allowlist (PR #59) — repo-chat uses it via migration 0050 through toolNamesFor. Recoverable from PR #62 history if/when the create/update wiring is actually built. 715 workers/api tests pass; typecheck clean.
serge-ivo
pushed a commit
that referenced
this pull request
Aug 1, 2026
…ead code Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
serge-ivo
pushed a commit
that referenced
this pull request
Aug 2, 2026
…141) The Coder agent's runtime is already fully capability-driven (surfaces/ runtime/workflow/tools), not slug-hardcoded — but capabilities could only be set via SQL migrations. This adds the missing authoring path so a Coder-equivalent (or any agent built from existing primitives) is stampable as pure data with no platform code change. - sanitizeDeclaredCapabilities(input): validates the closed-enum power fields (surfaces ∈ KNOWN_SURFACES, runtime ∈ {browser,coding,null}, workflow ∈ {JOB_APPLY,CODING_SESSION,INSURANCE_QUOTES,null}) + tools via sanitizeToolList. Only present keys returned → clean partial PATCH. - POST /agents accepts an optional `capabilities` object at creation. - GET/PUT /agents/:id/capabilities now round-trip surfaces/runtime/ workflow/tools alongside customSurfaces; PUT merges per-key and no longer wipes customSurfaces on a capabilities-only PATCH. - Console AgentDetail: a Capabilities editor (surfaces/runtime/workflow/ tools) beside the existing custom-surfaces + settings-schema editors. Closed-enum validation is the safety boundary — no arbitrary code, so this is safe operator-side now; opening it to third-party creators is gated on the trust model (#142). Refs #51, #58, #62 (removed dead code). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Second slice of the creator way (epic #58, workstream #51), building on the tool catalog (#59) and the repo-chat dogfood (#61).
Why
An agent's config is currently assembled and validated piecemeal — create sets a few columns + inits the DO, while
capabilitiesandsettingsSchemahave their own separate PUT routes and guardrails live only in DO state. There's no single "here is a complete agent, as data" shape. A third-party creator (or the authoring UI / AI builder) needs exactly that.What
lib/agent-definition.ts—AgentDefinition+sanitizeAgentDefinition(input): one validator that composes the existing sanitizers (sanitizeDeclaredCapabilities,sanitizeToolList,sanitizeSettingsSchema) + the canonicaldefaultGuardrailsnormalizer, and emits exactly theagents.configshape the platform already reads (per the repo-chat seed):{ identity: { personality, goal, guardrails, welcomeMessage }, capabilities: { surfaces, runtime, workflow, tools }, settingsSchema? }. Never throws — coerces/drops to safe defaults, so it's safe directly on an untrusted body.sanitizeDeclaredCapabilities(raw)inagent-capabilities.ts— validates a raw capabilities object (drops unknown surfaces/runtime/workflow; tools viasanitizeToolList). Reused by the definition and available toPUT /:id/capabilities.Safety / scope
Guardrailstype +defaultGuardrails; no shape is redefined.Tests
agent-definition.test.ts(6): normalize/trim, guardrail defaulting, drop-unknown capabilities, settingsSchema omission, never-throws-on-garbage, and a round-trip proving the emitted config resolves through the sameagentCapabilitiesregistry the runtime uses.workers/apitests pass, typecheck clean.Next in #51
Wire
POST /(andPUT /:id) to accept a fulldefinition— validate withsanitizeAgentDefinition, persist asconfig, and init the DO with the identity/guardrails — so an agent can be created from one declarative payload (the end-to-end creator way). Then the "view/fork source" example gallery.Part of #58.