orchestration-capability-builder

Extend BaseCapability with a Zod schema, an OpenAI-compatible function definition, and an execute method, then register the class in registry.ts, create the AiCapability database row, and bind it to the agent. All four steps are required for the tool to work.

Use the call_external_api capability with a recipe for HTTP-shaped integrations like sending email, charging payments, or posting to chat. Build a fresh capability only for stateful integrations, multi-step OAuth flows, or logic that does not fit a single HTTP request/response.

Internal runs TypeScript business logic in the app and requires a registered class. Api calls an external REST endpoint directly with no code needed. Webhook is fire-and-forget notification where the response is not fed back to the LLM.

Unknown_capability means the handler class is not registered in registry.ts. Capability_inactive means the database row has isActive set to false. The dispatch pipeline returns the error code for exactly the step that failed.

Set processesPii to true and override redactProvenance to mask sensitive fields using helpers like maskEmail, maskPhone, and redactedString. The registry refuses to load a PII-handling capability without an explicit redactor override.

Set isIdempotent to true only when the capability is provably safe to rerun, such as idempotent PUTs or vendors handling Idempotency-Key headers. The default false keeps the dispatch cache active, which deduplicates side effects on re-drive after crashes.