@moldea.ai/adapter-claude-agent-sdk 2.0.1 → 3.0.1

package/README.md

@@ -8,10 +8,10 @@ The package implements the official `claude-agent-sdk` runtime adapter for `@mol
 
 ## Supported target
 
-Version `2.0.1` supports:
+Version `3.0.1` supports:
 
 - Repository Format version `1`
-- `@moldea.ai/core ^3.0.0`
+- `@moldea.ai/core ^4.0.0`
 - TypeScript ESM source
 - npm `@anthropic-ai/claude-agent-sdk >=0.3.234`
 - directly exported functions containing direct `query({ ... })` calls
@@ -88,3 +88,12 @@ 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
+
+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/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,29 @@
+---
+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.

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": "2.0.1",
+  "version": "3.0.1",
   "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"
   ],
@@ -33,7 +34,7 @@
     "node": ">=22.11.0"
   },
   "dependencies": {
-    "@moldea.ai/core": "^3.0.0",
+    "@moldea.ai/core": "^4.0.0",
     "@moldea.ai/repository": "^2.0.0",
     "semver": "7.8.5",
     "typescript": "6.0.3"