Capabilities

src/capabilities is the L3 Tools layer — the built-in tool set plus the kernel that registers and runs it. Imported as indusagi/capabilities, or as the capabilities namespace from indusagi.

The layer ships a declarative tool-authoring kernel (defineTool + ToolRegistry), the concrete built-in tools, Node-backed filesystem/shell backends, and a one-call toolBox assembler that produces a runnable ToolBox for the runtime.

Table of Contents

• Public exports
• Sub-directories
• The built-in tools
• Assembling a toolbox
• Authoring a tool
• Relationship to neighbors

Public exports

From src/capabilities/index.ts:

Authoring/type vocabulary is also re-exported: ToolSpec, ToolResult, ToolContentBlock (TextContentBlock / JsonContentBlock), ToolContext, DefinedTool, the Fs/Shell backend interfaces, OutputBudget/ClipEnd, the context-factory types, ToolCollection, and the todo types (TodoItem, TodoStatus).

The two outward contracts — the runtime's ToolCall/ToolOutcome/ToolBox/ ToolRunner and the gateway's ToolDescriptor/JsonSchema — are deliberately not re-exported here; import those from indusagi/runtime (or its contract) and indusagi/llmgateway respectively.

Sub-directories

The built-in tools

The barrel exports twelve tool singletons. They cover eleven capabilities — the todo capability is two distinct tools (todoSetTool and todoReadTool):

planning/todo.ts also exports the todoStore singleton, the TodoStore class, and resetTodos; shell/process.ts exports resetProcessTable.

Assembling a toolbox

builtinRegistry() mints a fresh ToolRegistry populated with all twelve tools and three named collections:

• read-only — tools that only observe the workspace and the web (read, ls, grep, find, websearch, webfetch).
• coding — read-only plus the mutating and stateful tools (write, edit, bash, todo_set, todo_read, process).
• all — every registered tool.

toolBox(collection, cwd?) returns a runnable ToolBox backed by the real Node filesystem and shell. It advertises exactly the chosen collection's descriptors and mints a fresh ToolContext rooted at cwd (defaulting to process.cwd()) per dispatch:

import { toolBox } from "indusagi/capabilities";

const tools = toolBox("coding");          // or "read-only" / "all"
// pass to the runtime as AgentConfig.tools

Authoring a tool

A tool is declared with defineTool over a ToolSpec and runs against a ToolContext (which carries the Fs/Shell backends). Output is windowed with clamp against an OutputBudget:

import { defineTool, ToolRegistry } from "indusagi/capabilities";

const myTool = defineTool({
  name: "echo",
  description: "Echo a string back",
  parameters: { type: "object", properties: { text: { type: "string" } } },
  async run(input, ctx) {
    return { content: [{ kind: "text", text: String((input as any).text) }] };
  },
});

const registry = new ToolRegistry();
registry.registerAll([myTool]);

Relationship to neighbors

The capabilities layer is the Runtime's tool boundary — toolBox produces the ToolBox a host passes as AgentConfig.tools, and the runtime's scheduler invokes its ToolRunner. The kernel shares the gateway's ToolDescriptor/JsonSchema contract for tool schemas. The SaaS gateway and the Interop bridge both register their own DefinedTools into a ToolRegistry from this layer, so remote tools and built-ins share one surface.

Back to the Architecture overview.