@moldea.ai/adapter-claude-agent-sdk 3.0.0 → 3.0.2

package/README.md

@@ -8,7 +8,7 @@ The package implements the official `claude-agent-sdk` runtime adapter for `@mol
 
 ## Supported target
 
-Version `3.0.0` supports:
+Version `3.0.2` supports:
 
 - Repository Format version `1`
 - `@moldea.ai/core ^4.0.0`
@@ -88,3 +88,14 @@ pnpm --filter @moldea.ai/adapter-claude-agent-sdk build
 ```
 
 Unit and integration tests are colocated with their implementation modules. Adapter-specific conformance fixtures live under `/fixtures/adapter-claude-agent-sdk`.
+
+## Documentation
+
+- [Complete binding example](docs/binding-example.md): manifest, canonical instructions, runtime source, and supported schema or routing relationships.
+
+These guides are included in the installed package. Open only the page relevant to your task.
+
+- [Package overview](docs/index.md)
+- [Verified target](docs/verified-target.md)
+- [Evidence and diagnostics](docs/evidence-and-diagnostics.md)
+- [Limitations](docs/limitations.md)

package/docs/binding-example.md

@@ -0,0 +1,235 @@
+---
+title: Binding example
+description: Complete manifest and source files for inspecting claude-agent-sdk bindings locally.
+order: 5
+---
+
+# Binding example
+
+Read this example before searching adapter implementation for binding syntax. It is a complete **static inspection** file set, not a deployment starter or a live provider test. The files are checked together through this adapter and Core without installing or executing the target SDK. Keep application setup, credentials, provider model access, tool execution, and deployment configuration separate.
+
+## How the bindings connect
+
+Bind the query function and each exported programmatic subagent object separately. Query `systemPrompt` and child `prompt` call their canonical loaders. Query `outputFormat.schema` binds the JSON Schema constant. `tools: ['Agent']` enables delegation; child `description` matches its canonical handoff description. MCP tool names use the query server key (`mcp__support__find_order`), not the server's display name. `tool` takes a Zod property map, whereas `outputFormat` takes JSON Schema. This target does not establish tool output-schema evidence.
+
+Paths below are repository-root-relative logical paths. Keep the canonical instructions as the policy source. General manifest semantics belong to the [Repository Format specification](https://packages.moldea.ai/repository-format/). Use the other local guides for the full supported boundary and limitations; this example does not expand them.
+
+## Files
+
+<!-- example:start -->
+
+### /moldea/moldea.yaml
+
+```yaml
+version: 1
+agents:
+  billing:
+    runtime:
+      id: 'claude-agent-sdk'
+    bindings:
+      runtimeAgent:
+        path: '/src/agents.ts'
+        symbol: 'billingAgent'
+      instructionLoader:
+        path: '/src/instructions.ts'
+        symbol: 'loadBillingInstruction'
+    tools:
+      find-order:
+        name: 'mcp__support__find_order'
+        description: 'Retrieves one order by its identifier.'
+        implementation:
+          path: '/src/find-order.ts'
+          symbol: 'findOrder'
+        registration:
+          path: '/src/tools.ts'
+          symbol: 'findOrderTool'
+        inputSchema:
+          path: '/src/contracts.ts'
+          symbol: 'FindOrderInputSchema'
+  triage:
+    runtime:
+      id: 'claude-agent-sdk'
+    bindings:
+      runtimeAgent:
+        path: '/src/runtime.ts'
+        symbol: 'triageAgent'
+      instructionLoader:
+        path: '/src/instructions.ts'
+        symbol: 'loadTriageInstruction'
+      outputSchema:
+        path: '/src/contracts.ts'
+        symbol: 'TriageOutputSchema'
+    tools:
+      find-order:
+        name: 'mcp__support__find_order'
+        description: 'Retrieves one order by its identifier.'
+        implementation:
+          path: '/src/find-order.ts'
+          symbol: 'findOrder'
+        registration:
+          path: '/src/tools.ts'
+          symbol: 'findOrderTool'
+        inputSchema:
+          path: '/src/contracts.ts'
+          symbol: 'FindOrderInputSchema'
+```
+
+### /moldea/project.md
+
+```markdown
+# Claude Agent SDK adapter fixture
+```
+
+### /moldea/agents/billing/description.md
+
+```markdown
+Handles customer billing requests.
+```
+
+### /moldea/agents/billing/handoff-description.md
+
+```markdown
+Route billing questions and payment issues here.
+```
+
+### /moldea/agents/billing/instruction.md
+
+```markdown
+You are the `billing` agent.
+
+Resolve billing requests from the supplied facts. Ask when essential details are missing.
+```
+
+### /moldea/agents/triage/description.md
+
+```markdown
+Routes customer support requests.
+```
+
+### /moldea/agents/triage/instruction.md
+
+```markdown
+You are the `triage` agent.
+
+Route billing requests to billing. Do not invent account facts.
+```
+
+### /package.json
+
+```json
+{
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.234",
+    "zod": "4.6.4"
+  },
+  "name": "binding-example",
+  "private": true,
+  "type": "module"
+}
+```
+
+### /src/agents.ts
+
+```typescript
+import { loadBillingInstruction } from './instructions.js';
+
+export const billingAgent = {
+  description: 'Route billing questions and payment issues here.',
+  prompt: loadBillingInstruction(),
+  tools: ['mcp__support__find_order'],
+};
+```
+
+### /src/contracts.ts
+
+```typescript
+import { z } from 'zod';
+
+// response and tool contracts
+export const TriageOutputSchema = {
+  type: 'object',
+  properties: { summary: { type: 'string' } },
+  required: ['summary'],
+  additionalProperties: false,
+} as const;
+export const FindOrderInputSchema = { orderId: z.string() };
+```
+
+### /src/find-order.ts
+
+```typescript
+/** Returns one sample order as MCP text content. */
+export const findOrder = async ({ orderId }: { orderId: string }) => ({
+  content: [
+    {
+      type: 'text' as const,
+      text: JSON.stringify({ orderId, status: orderId === 'order-1042' ? 'shipped' : 'not_found' }),
+    },
+  ],
+});
+```
+
+### /src/instructions.ts
+
+```typescript
+import { readFileSync } from 'node:fs';
+
+/** Reads the canonical billing instruction. */
+export const loadBillingInstruction = (): string =>
+  readFileSync(new URL('../moldea/agents/billing/instruction.md', import.meta.url), 'utf8');
+
+/** Reads the canonical triage instruction. */
+export const loadTriageInstruction = (): string =>
+  readFileSync(new URL('../moldea/agents/triage/instruction.md', import.meta.url), 'utf8');
+```
+
+### /src/runtime.ts
+
+```typescript
+import { query } from '@anthropic-ai/claude-agent-sdk';
+
+import { billingAgent } from './agents.js';
+import { TriageOutputSchema } from './contracts.js';
+import { loadTriageInstruction } from './instructions.js';
+import { supportServer } from './tools.js';
+
+export const triageAgent = async (prompt: string) =>
+  query({
+    prompt,
+    options: {
+      systemPrompt: await loadTriageInstruction(),
+      outputFormat: { type: 'json_schema', schema: TriageOutputSchema },
+      agents: { billing: billingAgent },
+      tools: ['Agent'],
+      mcpServers: { support: supportServer },
+    },
+  });
+```
+
+### /src/tools.ts
+
+```typescript
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+
+import { FindOrderInputSchema } from './contracts.js';
+import { findOrder } from './find-order.js';
+
+export const findOrderTool = tool(
+  'find_order',
+  'Retrieves one order by its identifier.',
+  FindOrderInputSchema,
+  findOrder,
+);
+
+export const supportServer = createSdkMcpServer({
+  name: 'support-tools',
+  version: '1.0.0',
+  tools: [findOrderTool],
+});
+```
+
+<!-- example:end -->
+
+## What the check establishes
+
+The integration check reads these exact file blocks, requires positive adapter evidence for the documented relationships, and rejects a broken runtime binding. It does not prove that instructions are followed, that every SDK version accepts these forms, or that the application is ready for production. Continue using the installed adapter diagnostics for your actual source.

package/docs/evidence-and-diagnostics.md

@@ -0,0 +1,27 @@
+---
+title: Evidence and diagnostics
+description: Emitted evidence, stable diagnostics, availability, and all-or-nothing Core integration.
+order: 20
+---
+
+# Evidence and diagnostics
+
+## Evidence
+
+The target may emit `runtime-package`, `language`, `runtime-pattern`, `agent-definition`, `instruction-loader`, `schema`, `tool-registration`, and `handoff-registration` evidence.
+
+`runtime-pattern` identifies a direct query wrapper. `agent-definition` identifies a supported immutable programmatic definition. `handoff-registration` requires an active query context whose built-in `Agent` tool is available. `tool-registration` requires a canonical server key, an exact fully qualified runtime name, and available query or subagent tool state.
+
+Evidence contains no repository content, prompts, descriptions, credentials, API keys, tool arguments, provider payloads, MCP results, session transcripts, or model responses. Missing local evidence is not itself a diagnostic.
+
+## Diagnostic catalog
+
+The package owns the stable codes documented in its package README. They cover invalid package or source state, missing bound symbols, unwired instruction/schema/tool relationships, unsupported MCP server keys, tool-name mismatches, ambiguous subagent targets, and missing or mismatched routing descriptions.
+
+Diagnostics use Core's shared adapter shape, preserve logical source locations, and remain deterministically ordered. Dynamic or indirect patterns yield partial or no evidence rather than guessed failures. Core validates adapter output and applies all-or-nothing inspection semantics.
+
+`CLAUDE_AGENT_SDK_TOOL_NAME_MISMATCH` and `CLAUDE_AGENT_SDK_TOOL_REGISTRATION_NOT_WIRED` are mutually exclusive for one closed registration analysis: an exact tool mounted only under the wrong runtime name produces the mismatch, while complete absence produces not wired.
+
+## Package detection
+
+Detection stops at the nearest existing `package.json` owning each runtime-agent source. Supported dependency fields are considered collectively. A collectively disjoint range produces the unsupported-version diagnostic without package evidence; an ambiguous range remains evidence rather than being promoted to verified support. Invalid UTF-8 or NUL in the owning manifest produces only `CLAUDE_AGENT_SDK_PACKAGE_MANIFEST_INVALID`; source text failures remain source diagnostics.

package/docs/index.md

@@ -0,0 +1,31 @@
+---
+title: Claude Agent SDK runtime adapter
+navigationTitle: Overview
+description: Deterministic evidence and diagnostics for the verified Claude Agent SDK TypeScript target.
+order: 0
+---
+
+# Claude Agent SDK runtime adapter
+
+`@moldea.ai/adapter-claude-agent-sdk` implements the official `claude-agent-sdk` runtime adapter for Core. It statically inspects explicitly bound TypeScript source through Core's source-neutral repository reader and produces deterministic evidence and diagnostics for query wrappers, programmatic subagents, structured output, SDK MCP tools, and routing descriptions.
+
+```typescript
+import { claudeAgentSdkAdapter } from '@moldea.ai/adapter-claude-agent-sdk';
+import { createCore } from '@moldea.ai/core';
+
+const core = createCore({ adapters: [claudeAgentSdkAdapter] });
+```
+
+The local CLI registers the adapter automatically. Applications composing Core directly register the immutable singleton explicitly.
+
+## Current state
+
+The package is available. Its technical target covers TypeScript ESM using npm `@anthropic-ai/claude-agent-sdk >=0.3.234`, Repository Format version `1`, and compatible Core `^4.0.0`.
+
+The adapter never imports or calls the SDK, requires no API key, executes no repository code, and makes no network request. It proves supported static relationships; it does not verify credentials, settings, provider behavior, model availability, permission decisions, actual delegation, tool execution, or schema semantics.
+
+## Public surface
+
+The package exports only `claudeAgentSdkAdapter`. It has no default export, configuration factory, SDK facade, parser export, public diagnostic registry, or mutable runtime state. The generated [API reference](https://packages.moldea.ai/adapters/claude-agent-sdk/api/) derives that surface from the package export.
+
+Start with the [complete binding example](https://packages.moldea.ai/adapters/claude-agent-sdk/binding-example/) when connecting runtime source to canonical instructions, schemas, tools, or routing metadata. The same example ships locally as `docs/binding-example.md` in the installed package.

package/docs/limitations.md

@@ -0,0 +1,27 @@
+---
+title: Boundaries and limitations
+description: Unsupported SDK surfaces, source forms, dynamic behavior, and the adapter security boundary.
+order: 30
+---
+
+# Boundaries and limitations
+
+The current verified target does not claim support for:
+
+- JavaScript, Python, CommonJS, or source outside the verified TypeScript ESM boundary
+- indirect query wrappers, query input variables, nested callback calls, or unstable session APIs
+- filesystem-defined agents, built-in agents, observer agents, or dynamically assembled definitions
+- query main-thread `agent` selection or `toolAliases` interpretation
+- string-array system prompts, CLAUDE.md, settings, hooks, plugins, skills, or prompt transformations
+- programmatic-subagent output schemas or manifest tool output schemas
+- per-agent MCP server configuration
+- external stdio, SSE, HTTP, remote, proxy, plugin, provider-hosted, or built-in tools
+- SDK server instructions as canonical moldea instruction-loader content
+- arbitrary compiler resolution, `tsconfig` path aliases, directory indexes, package exports, or re-export graphs
+- runtime-generated strings, SDK key normalization, schema-content validation, permission evaluation, or provider behavior
+
+Package detection uses nearest manifests, not lockfiles or installed `node_modules`. Static dependency ranges are observations; the adapter does not prove which package build executes at runtime.
+
+Each invocation sees one declared agent, exact same-runtime binding resolution, and only the bounded operations Core supplies through `IRuntimeAdapterRepository`. It receives no complete agent collection, project body index, host path, Anthropic credential, environment variable, network client, or runtime process. It does not execute TypeScript, dynamically import source, load the inspected SDK, or follow source symlinks.
+
+The [Runtime Compatibility Matrix](https://packages.moldea.ai/compatibility/) remains authoritative. A focused specification or future design does not broaden this page until the canonical matrix and released implementation do.

package/docs/verified-target.md

@@ -0,0 +1,42 @@
+---
+title: Verified target
+description: Exact query, subagent, instruction, schema, MCP tool, availability, and routing support.
+order: 10
+---
+
+# Verified target
+
+The canonical Runtime Compatibility Matrix defines the technical target `typescript-query-subagents-0-3`.
+
+## Supported boundary
+
+- TypeScript ESM `.ts`, `.tsx`, and `.mts` files
+- a nearest owning package manifest declaring npm `@anthropic-ai/claude-agent-sdk >=0.3.234`
+- named value imports from the package root, including aliases
+- directly exported function declarations, arrow functions, or function expressions containing direct `query(...)` calls in their own lexical body
+- directly exported immutable object-literal programmatic `AgentDefinition` values
+- direct or awaited instruction-loader calls through query `systemPrompt`, `claude_code` preset `append`, and subagent `prompt`
+- query JSON Schema output through the exact `outputFormat` shape
+- directly exported positional `tool(...)` declarations with direct implementation and input-schema bindings
+- module-local `createSdkMcpServer(...)` declarations with closed tool arrays
+- closed query `agents` and `mcpServers` maps
+- query and subagent tool availability using closed `tools` and `disallowedTools` arrays
+- active subagent delegation only when query-configured `Agent` availability is proved available
+- exact target mapping by source path and exported symbol
+- exact `AgentDefinition.description` comparison with the target's effective handoff description
+
+Bindings must remain lexically visible at each matched use. Supported relative named imports resolve an exact TypeScript path, `.js` to `.ts` or `.tsx`, and `.mjs` to `.mts`. Re-exports, directory indexes, path aliases, CommonJS, and package-export resolution are outside the target.
+
+## Relationship closure
+
+Query inputs, query options, programmatic definitions, SDK MCP servers, and tool definitions are analyzed independently by relationship. Computed or duplicate relationship properties, object spreads, unsupported values, and observable mutation leave only affected relationships unresolved.
+
+Positive evidence is existential across supported query calls. Negative wiring diagnostics require every relevant candidate to be closed and contradictory, with no dynamic or availability-unresolved context that could establish the relationship.
+
+## Availability
+
+The built-in `Agent` tool and SDK MCP tools use `available`, `unavailable`, and `unresolved` states. `allowedTools` does not establish or restore availability. Supported `disallowedTools` entries use exact complete-name matching with `*` as the only wildcard. Query `agent` and `toolAliases` fields make otherwise available delegation and tool relationships unresolved; they cannot restore an already unavailable tool.
+
+## Static strings
+
+Routing descriptions, map keys, tool names, server names and versions, and tool-list entries support literals, no-substitution templates, immutable module-local constants, and directly imported immutable string constants. Values are compiler-parsed and are never trimmed, case-folded, or Unicode-normalized.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldea.ai/adapter-claude-agent-sdk",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Deterministic runtime evidence and diagnostics for Claude Agent SDK query and subagent integrations.",
   "homepage": "https://github.com/moldea-ai/packages/tree/main/projects/adapter-claude-agent-sdk#readme",
   "bugs": {
@@ -18,6 +18,7 @@
   "files": [
     "cover.png",
     "dist",
+    "docs",
     "LICENSE",
     "README.md"
   ],