@ai-zen/agents-sdk

AI-Zen SDK — shared business logic layer providing a unified Agent runtime for CLI and Desktop. Works out of the box, with preconfigured vendor settings, a default Agent, and a default SubAgent.

Source of Truth

docs/sdk-design-v1.md is the single source of truth for this package's design. All implementations must stay consistent with the document. (Pre-refactor design is kept in docs/sdk-design-v0.md.)

Architecture

CLI ──┐
      ├── @ai-zen/agents-sdk ──┐
Desktop ──┘                    │
                          LLM API

Module Layering

types         ← pure types, zero business dependencies (incl. ToolEnv)
config        ← ConfigManager + constants: config.json read/write + directory setup + factory defaults
crud          ← capability-entity CRUD (Agent definitions; conversations/drafts are persisted by each consumer)
runtime       ← model factory + Agent assembly + task handoff/migration (cancellable via `AbortSignal`; createModel / createAgent / SdkAgent / HandoffService / HandoffGuardPlugin)
scope         ← Scope orchestration container + ScopePlugin contract + PermissionEvaluator / disclosure + plugins/ (5 self-contained capability sources: discovery + tools + plugin)
agent-plugins ← Agent plugins (autoMigrate, autoRefreshTools, contextGuard, unknownToolHint)
shared        ← content blocks (file → content block transport), entity repository, logging, errors

Dependency direction: agent-plugins → runtime → scope; runtime → scope / crud / shared / types, scope → types / shared. Upper layers depend on lower layers.

Core Concepts

Permission Model

The four dimensions are independent; allow/deny are mutually exclusive, no match means deny, and permission is disclosure (denied items are completely invisible to the LLM).

Agent.permissions
  ├── tools:      { allow: string[] } | { deny: string[] }
  ├── skills:     { allow: string[] } | { deny: string[] }
  ├── mcps:       { allow: string[] } | { deny: string[] }
  └── subagents:  { allow: string[] } | { deny: string[] }

Consumption

const scope = new Scope({
  config,
  cwd: "/path/to/workspace", // one working directory per Scope; parallel sessions don't interfere
  agentsDir,
}).use(
  ...allInOne({ skillsPaths, toolsPaths, subAgentsPaths, mcpPaths }),
);
await scope.init();

const agent = await createAgent(scope, "my-agent");
const handoffService = new HandoffService({ handoffDir: "/work/.ai-zen/handoffs", skillDirs });
agent.use(new ContextGuardPlugin({ guardTokens, isSuspended: () => handoffService.busy }));
agent.use(new AutoMigratePlugin({ service: handoffService, handoffTokens }));
agent.use(new AutoRefreshToolsPlugin());
agent.use(new UnknownToolHintPlugin({ scope }));
await agent.init();
await agent.send("Hello");

await scope.dispose(); // disconnect MCP, release plugin resources

Development Status

Built-in Tools

All built-in tools are classes (extending SdkCallbackTool), instantiated by the built-in-tools plugin (BuiltinToolsScopePlugin) with a ToolEnv — one set of instances per Scope, with cwd injected and relative paths resolved against Scope.cwd, never depending on the global process.cwd().

Conditionally injected based on the active model / config:

Tool output protection: AppConfig.maxToolOutput (in characters, default 32768) is the unified ceiling for tool output. Each tool handles overflow itself — exec dumps stdout.log / stderr.log separately (returning head/tail previews per stream), find_text / glob / ls dump result.json (returning a head preview), and read only warns and suggests batched reads via range. Dumps go to <tmpdir>/ai-zen/tool-output/<tool>-<timestamp>-<random>/, one directory per call, with no self-cleanup. See docs/sdk-design-v1.md §12.

Interrupt strategies live in the config: AppConfig.abortedMessageStrategy (keep / drop, factory keep — the model can continue the half-sentence after an interrupt) and AppConfig.abortedToolRoundStrategy (fill / drop, factory fill — whole rounds go in or out, because tool_calls must pair with results). createAgent() reads them from scope.config when no explicit option is passed, keeping a single source of truth.

Built-in Plugins

Language

The SDK is English-only: every model-facing and user-facing string — tool schema descriptions, factory prompts, runtime-injected guidance, tool results, error messages, factory catalog data — is a fixed English literal. There is no locale field, no message catalog, and no runtime language switch. UI language belongs entirely to each consumer (the CLI's i18n/, the Desktop's language setting).

This is a performance boundary, not a convenience choice — SDK behaviour and performance must not vary by the user's language:

• Thresholds are absolute. Model.tokenThresholds.handoff / guard and AppConfig.maxToolOutput are absolute token / character counts. A localized tool schema is a different token count, so handoff and context-guard would trip at different amounts of real content for the same config.json — same config, different behaviour per language.
• Schema cost is paid every turn. Description text is re-sent with every request, so a token delta is a standing cost in request size, context usage and spend rather than a one-off.
• Cache prefixes stop being comparable. Prompt caching matches on the prefix; letting language into the SDK multiplies the prefix shapes of one code path and removes the single variable that benchmarks rely on.
• Diagnosis needs one shape. Performance data, bug reproductions and tool-call success rates have to be comparable across users; once behaviour drifts with locale, every conclusion needs a "what language are you on?" qualifier first.

Following the user's language is handled by one language-neutral instruction in the factory system prompt — Always reply in the same language the user writes in. — which adapts per message rather than per installation, and needs no locale plumbing in the SDK. Full rationale: docs/sdk-design-v1.md §1.

Design Principles

See the project-root PRINCIPLES.md:

1. Logical consistency
2. Design first, documentation as the source of truth
3. Symmetry and uniformity
4. No over-engineering
5. Occam's razor
6. Refactor as you go; keep clean layering
7. Tests are the foundation