Capabilities

What it does

A capability is one named action with a contract and a server-side handler. The contract declares the name, input, output, failure, and metadata. The handler implements the action on the server.¶

Effect is a library for describing work with typed failures³⁶ and required services. A service is a named interface for one job. Schema describes accepted values, their TypeScript types, and the rules for checking and converting them at runtime.¶

defineContract declares input, output, and failure with Effect Schema. It sets metadata describing the action, such as whether it is read-only, and any approval requirements. implement connects the contract to one handler.¶

A projection builds a callable interface from a capability. The projections in packages/capability provide:¶

A command line.¶
An HTTP API with OpenAPI, which describes its routes, inputs, outputs, and errors.¶
MCP tools. Model Context Protocol²⁷ lets an agent discover and call tools.¶
RPC calls. Remote procedure call lets a client call a named server operation.¶
Code mode²¹, which combines capability calls in one program inside a restricted environment. See one capability, every surface¹⁸ for why.¶

ratstack.sh serves seven: search, read, backlinks, neighbors, mentions, path, and execute. The registry lives in apps/site/src/capabilities/index.ts. The local command line projects the core registry in apps/cli/src/surfaces.ts.¶

The standard

Application actions exposed through generated routes, tools, and commands come from capabilities. Static pages, discovery documents, result pages, and protocol routing are composed separately. Rpc.make, RpcGroup.make, HttpApi*, Tool.make, and Toolkit.make outside packages/capability fail lint (rat-stack-boundaries/no-hand-rolled-surface).¶
Input, output, and failure are Effect schemas. JSON Schema, OpenAPI¹⁵, and the code-mode declarations are derived from them, never written by hand.¶
Invalid input is rejected before the handler runs.¶
A declared failure returns the declared error type. MCP returns it as a tool error.¶
A capability that needs approval adds an Approval requirement and an ApprovalDenied failure on every interface. Approval is denied by default. HTTP answers a denial with 403.¶
Browser code imports contracts only, never handlers (rat-stack-boundaries/no-browser-server-imports).¶
Code mode reaches only capabilities, through their schemas.¶

Code-mode discovery and execution

Code mode derives tool declarations from capability schemas. The default discovery budget is 2,000 estimated tokens. The estimate uses four characters per token.¶

Discovery selects the shortest declarations and gives each namespace a turn. Namespace summaries mark the selected tools as COMPLETE or PARTIAL.¶

catalogBudget sets the budget. declarations: "inline" includes all declarations; "search" includes none. An explicit catalogBudget takes precedence over either setting. The declarations resource always contains the full catalog.¶

Programs can call tools.$codemode.search to find declarations. An exact tool path returns only that tool. Other queries rank path segments, path substrings, descriptions, then input fields.¶

limit and offset bound each page. next holds the next offset; remaining counts matching tools after this page. total keeps its meaning as the full catalog size.¶

Execution returns result, logs, diagnostic, toolCalls, and truncated. Check diagnostic before using result. A declared tool failure retains its tag and a safe message. Parse errors, invalid data, timeouts, and program failures also return diagnostics.¶

Host cancellation still interrupts execution.¶

The HTTP execute response uses status 200 for execution diagnostics. Failure diagnostics have a null result. Consumers that parsed SandboxError bodies must read diagnostic instead. A health check must reject a non-null result when it expects failure.¶

toolCalls lists admitted calls in dispatch order, including failed calls. maxToolCalls rejects extra calls before their handlers run. Both sandbox adapters run at most eight tool calls at once. maxOutputBytes bounds returned JSON and log content by UTF-8 bytes.¶

Output cuts set truncated and keep the diagnostic and call history. The budget excludes diagnostic, call-history, and transport-envelope bytes. Both limits are optional; zero is a valid limit.¶

Handlers keep the services captured when the program starts. Devtools records each handler’s duration and outcome through the existing CallWatch. A downstream storage adapter owns its statement and row limits.¶

How to check

curl -sS https://ratstack.sh/openapi.json | jq -r '.paths | keys[]' lists one route per capability. The MCP tools/list request in the agent guide returns the same seven names.¶
pnpm --filter @rat-stack/capability test covers input rejection before the handler and typed failures as tool errors. It checks approval denial as a 403 and a typed tool error, denial by default, and code-mode calls through capability schemas.¶
pnpm lint fails on any callable interface built outside packages/capability.¶
pnpm --filter @rat-stack/capability exec vitest run test/catalog.test.ts test/sandbox-limits.test.ts test/sandbox-conformance.test.ts test/code-mode-context.test.ts checks discovery, search pages, limits, and captured services.¶
pnpm --filter @rat-stack/site exec vitest run test/code-mode-runtime.test.ts checks the same diagnostics, limits, and concurrency in local workerd.¶
pnpm --filter @rat-stack/devtools test checks handler duration and failure recording during code-mode execution.¶

Removing an interface

The README’s Keep or cut table lists the files for “No HTTP”, “No MCP”, and “No code mode.” Cutting MCP cuts code mode, because code mode is built on the MCP toolkit.¶

Sources

rat-stack/packages/capability/src/contract.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Contract definition; used for schemas, annotations, and approval settings. Accessed 2026-10-01.
rat-stack/packages/capability/src/implement.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Handler binding; used for schema validation and declared failures. Accessed 2026-10-01.
rat-stack/apps/site/src/capabilities/index.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Hosted registry; used to identify the capabilities served by ratstack.sh. Accessed 2026-10-01.
rat-stack/apps/cli/src/surfaces.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. CLI composition; used to show the local projections. Accessed 2026-10-01.
rat-stack/packages/capability/test at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Projection tests; used to check validation, approvals, and sandbox calls. Accessed 2026-10-01.

Last changed 2026-10-10 in 978dccc. Source on GitHub. Change log.

Linked from

A clean playground. rat-stack does real work with packages that stay easy to add and remove.
The website’s search and read capabilities, named actions with shared contracts and handlers, serve the public repo.
add-a-capability. Learn how one contract and its handler become a command, HTTP route, MCP tool, browser RPC, and sandbox call.
Add the implementation to the capabilities tuple consumed by its composition root.
Agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
Capabilities — Named application actions exposed through generated interfaces share one definition and one server-side implementation.
Agent rules for rat-stack (AGENTS.md). What you may change, which commands to run, and which changes need approval.
Define schemas and metadata with defineContract; bind a server-side handler with implement and add the capability to capabilities.
An MCP your users want. Rhys Sullivan's practical guide gives rat-stack a checklist for useful MCP tools.
Build and run rat-stack (README.md). What is in the repo, how the example works, and how to run it.
Add another to capabilities, then verify every projection you keep; CLI command registration lives in apps/cli/src/command.ts.
Change log. What changed in the files served here, newest first.
Capabilities — edited: docs: point live docs, skills and Brain pages at apps/site
Effect + Alchemy peer patterns. Source-grounded patterns from repos on nearby Effect and Alchemy pins.
Link context
Capability fence: test or lint that every surface, including toRpc, originates from the capability registry; make the test prove its guarded paths exist and contain files.
Feature flags. Typed feature flags with owners, removal dates, and stable subject rollouts.
Each capability shares its contract across surfaces.
Full agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
learn. Present Effect, Alchemy, XState, and application-design concepts during real work when the operator enables learn mode. Use for adaptive explanations and local learning progress.
Confirm storage only after the capability returns a feedback id.¶
learn-rat-stack. Trace a capability through Effect, XState, five projections, the CLI, and Alchemy. Try hosted search and read.
Start with inspectFile, a capability: one named action with a contract and a server-side handler.
One capability, every surface. A schema-typed contract and one handler feed every interface rat-stack keeps.
Register it in capabilities, then check each interface you keep.
One schema, three surfaces. A capability contract feeds CLI, HTTP, and MCP; OpenAPI is generated output, not their input.
A capability contract owns Effect schemas.¶
Property-based testing. State a rule that must hold for every input, then let a generator hunt for the smallest input that breaks it.
The same schema defines the capability’s contract and generates its test inputs.
Rat Stack lore | rat-stack. Short, source-grounded notes on the ideas and decisions behind rat-stack.
One schema, three surfaces — A capability contract feeds CLI, HTTP, and MCP; OpenAPI is generated output, not their input.
Rat Stack systems | rat-stack. The systems rat-stack ships, the standard each keeps, and how to check it.
Capabilities — Named application actions exposed through generated interfaces share one definition and one server-side implementation.
rat-stack. An Effect stack so pure (aspirational) Kit Langton will blush.
Run Effect at the integration boundary. Build the runtime where a calling framework enters, reuse its services, and dispose it when that integration ends.
A new runner does not authorize a handler that skips the capability contract.¶
Schemas define the boundary. Define accepted data with Schema, decode unknown input before dispatch, and encode results through the declared contract.
In rat-stack, one capability contract supplies schemas to every interface projection.¶
Source change history (log.md). The generated change log as Markdown.
Capabilities — edited: docs: point live docs, skills and Brain pages at apps/site

Unlinked mentions (45)

A service captures its construction dependencies → rat-stack also uses capability projections, cartridge packages, and a no-comments rule.¶
add-a-capability → A capability is one named action with a contract and a server-side handler.
add-a-lifecycle-machine → watchActor does nothing until devtools runs the capability.
add-a-store → A capability is one named action with shared value definitions and a server-side implementation.¶
Agent rules for rat-stack (AGENTS.md) → Alchemy confirmations use the capability approval service; unattended input prompts fail typed.
Analytics → withEventCapture wraps the Worker’s fetch handler.¶
Auth → A capability is one named action with shared value definitions and a server-side implementation.
Build and run rat-stack (README.md) → Bind a server-side handler, then project the capability onto every agent surface.
Cartridges → See one capability, every surface for the shared contract and a clean playground for the house rule behind these boundaries.¶
Database → RunLog records a capability run with its outcome and lists a person’s recent runs.
Devtools → A capability is one named action with shared value definitions and a server-side handler, the code that implements it.
Effect + Alchemy peer patterns → Keep capability schemas in packages/core, the toRpc projection in packages/capability, and UI atoms in the web app.
Effect basics → Handle expected failures without hiding defects shows the file error and its CLI handler.¶
Effect keeps the surfaces on one contract → A projection builds an interface from a capability, a named action with a contract and handler.
Feature flags → setFlag is an approval-gated capability on the CLI.
HATEOAS → txt, the markdown variant, MCP responses, and capability responses.
Hexagonal architecture → One capability, every surface starts with a contract, binds a handler, and projects CLI, HTTP, MCP, RPC, and code mode.
Hosted agent interfaces → A capability is one named action with shared input, output, and failure definitions and a server-side implementation.¶
Interest signup → An agent applies for a person through the joinInterest capability.
keep-or-cut → A capability is one named action with a contract and a server-side handler.
Learn mode presents concepts at useful depths → A capability is one named action with shared value definitions and a server-side implementation.
learn-alchemy → A capability is one named action with shared value definitions and a server-side implementation.¶
learn-rat-stack → Start with inspectFile, a capability: one named action with a contract and a server-side handler.
Lifecycles are machines → See one capability, every surface for how a capability can own a machine and the fence for the rule that protects it.¶
MCP is another surface → The job does not need a protocol-specific handler.¶
One capability, every surface → A capability is one named action with a contract and a server-side handler.
One program can replace several tool calls → A capability is a named action with a typed contract and a handler.
One prompt serves people and agents → A capability is one named action with shared value definitions and a server-side implementation.
One schema, three surfaces → A capability is a named action with a contract and handler.
Oxlint rule limits → It recognizes this template’s paths; package exports, conditions, and custom aliases need their own resolver contract.
Purpose and boundaries of rat-stack (VISION.md) → Capability and MCP next-action links are a direction to prove, not something the projections guarantee today.
Rat King binds agents into one encrypted network → Every surface projects the same contract.
rat-stack → A projection exposes the capability through one interface, such as the CLI (command-line interface) or HTTP.
rat-stack-mode → A capability is one named action with shared value definitions and a server-side implementation.
Run Effect at the integration boundary → This module keeps only the handler; the excerpt does not prove explicit disposal on development-server shutdown.
Schema projections: 2026-09-18 history → Deliberately compact MCP surface: search (discovery over Vectorize plus lexical) and execute (sandboxed capability calls).
Schemas define the boundary → A contract declares an action’s input, output, and failures.
Shared caches hold completed values → Keep request-local work inside its request handler.¶
Structure an Effect codebase by domain → rat-stack keeps one capability per file and derives routes.¶
Tests prove behavior through supplied services → A capability is a named action; a projection converts it into an interface.¶
Trace operations where they mean something → Devtools records capability calls and watched actor lifecycles.
uncomplect → Put behavior in a capability handler.
use-a-prompt → Call listPrompts through an available capability surface.¶
Worker init runs twice → The check now surrounds the rate-limit declarations and WorkerLoader declaration; the request-serving handler remains available at runtime.¶
write-a-wiki-page → A handler implements an action on the server.¶