Capabilities
A capability is a typed, versioned, atomic unit of execution with declared inputs, outputs, effect class, and boundary. Capabilities are the instruction set of Zakardo — the building blocks that plans are composed from.
Capability Definition
Section titled “Capability Definition”Every capability is a JSON object that declares everything the runtime needs to know:
import type { CapabilityDefinition } from '@zakardo/core';
const listContacts: CapabilityDefinition = { name: 'contacts_list', // Unique identifier version: '1.0.0', // Semver version description: 'List all contacts, optionally filtered by tag.', effect_class: 'READ', // What it does boundary: 'LOCAL', // Where it runs input_schema: { // JSON Schema for inputs type: 'object', properties: { tag: { type: 'string', description: 'Filter by tag' }, }, 'x-zakardo': { kind: 'capability-input', version: '1.0.0' }, }, output_schema: { // JSON Schema for outputs type: 'object', properties: { contacts: { type: 'array', items: { type: 'object' }, description: 'Contact list' }, total: { type: 'number', description: 'Total count' }, }, 'x-zakardo': { kind: 'capability-output', version: '1.0.0' }, }, interaction_spec: null, // Optional: mid-plan user interaction anchored_view: null, // Optional: persistent UI view tags: ['contacts', 'read'], // Discovery tags metadata: { author: 'my-app', created_at: '2026-01-01T00:00:00Z', deprecated: false, },};Effect Classes
Section titled “Effect Classes”Every capability declares its effect class — what side effects it produces:
| Effect Class | Meaning | Examples |
|---|---|---|
READ | Only reads data, no mutations | List contacts, get analytics |
WRITE_INTERNAL | Mutates data within the application | Create contact, update deal stage |
WRITE_EXTERNAL | Produces side effects outside the system | Send email, call external API |
DESTRUCTIVE | Irreversible operations | Delete contact, purge data |
Effect classes drive governance: DESTRUCTIVE capabilities trigger approval gates by default, and WRITE_EXTERNAL capabilities have their side effects deferred until all plan steps succeed.
See Effect Classes for the full governance matrix.
Boundaries
Section titled “Boundaries”The boundary declares where the capability executes:
| Boundary | Meaning |
|---|---|
LOCAL | Runs within the server process |
REMOTE | Calls an external service (HTTP, gRPC) |
USER_ENV | Executes in the user’s environment (browser, device) |
Capability Implementation
Section titled “Capability Implementation”The definition declares what a capability does. The implementation is the function that does it:
import type { CapabilityFn } from '@zakardo/core';
const listContactsImpl: CapabilityFn = async (inputs) => { const tag = inputs['tag'] as string | undefined; const contacts = await db.contacts.findMany({ where: tag ? { tags: { has: tag } } : undefined, }); return { contacts, total: contacts.length };};Implementations are registered separately from definitions, allowing different implementations per environment (production vs test vs simulation).
Interaction Specs
Section titled “Interaction Specs”Capabilities can declare mid-plan interaction points — moments where the capability needs user input to proceed:
| Interaction Type | Use Case |
|---|---|
SELECT | User picks one option from a list |
COMPARE | User compares options side by side |
REVIEW | User reviews and approves data before it is used |
INPUT | User provides free-form input |
CONFIRM | User confirms a specific action |
The runtime pauses execution at interaction points, sends an A2UI message to the frontend for rendering, and resumes when the user responds.
The Three-Tier Pattern
Section titled “The Three-Tier Pattern”Capabilities follow a three-tier design pattern:
| Tier | Description | Example |
|---|---|---|
| Atomic | Single operation, immediate result | contacts_create — create one contact |
| Batch | Multiple operations in one call | contacts_import — import 100 contacts |
| Async Job | Long-running operation with progress | report_generate — generate monthly report |
The Request Pattern
Section titled “The Request Pattern”When a capability is blocked by policy (e.g., a user lacks permission to delete), the Planner uses the Request Pattern — instead of including the blocked capability, it includes a request_* capability that submits a request for approval:
User: "Delete all inactive contacts"→ Policy blocks contacts_delete for this user→ Planner generates: contacts_delete_request (WRITE_INTERNAL)→ An admin later approves the requestThis ensures plans always succeed — the user gets a valid plan, just with a different path to the goal.
Registration
Section titled “Registration”Capabilities are registered with the runtime during server setup:
const { app, runtime } = await createZakardoApp({ config, capabilities: [listContacts, createContact], implementations: [ { name: 'contacts_list', version: '1.0.0', fn: listContactsImpl }, { name: 'contacts_create', version: '1.0.0', fn: createContactImpl }, ], policies: [],});Further Reading
Section titled “Further Reading”- Defining Capabilities Guide — step-by-step guide to writing capabilities
- Effect Classes — governance implications of each effect class
- Capability System Specification — full 1,600+ line specification