@theokit/agents 0.30.2 → 0.32.0

package/dist/index.js

@@ -23,7 +23,7 @@ import {
   getToolboxConfig,
   isCommandAllowed,
   isPathAllowed
-} from "./chunk-K4MCMREI.js";
+} from "./chunk-AAG26UJ7.js";
 import {
   AGENT_BRAND,
   AgentDefinitionError,
@@ -31,9 +31,12 @@ import {
   AgentRunnerBuilder,
   AgentWarningCode,
   BudgetExceededError,
+  CostBudgetExceededError,
   DEFAULT_KEEP_TOKENS,
   DEFAULT_MAX_ITERATIONS,
   DelegationError,
+  GuardrailViolationError,
+  agent,
   agentsPlugin,
   buildModelSelection,
   compactionStrategyConfigSchema,
@@ -44,11 +47,18 @@ import {
   compileProjectContext,
   compileSkills,
   compileTools,
+  contextualTool,
+  costGuard,
   createAgentExecutionContext,
+  createApiErrorHandler,
   createSdkAgentStream,
   createThinkTagExtractor,
+  createToolHooksPlugin,
   defineAgent,
   delegate,
+  delegateBackground,
+  delegateWithScoring,
+  estimateTokens,
   extractThinkTagStream,
   generateAgentManifest,
   generateAgentRoutes,
@@ -63,19 +73,30 @@ import {
   isToolResult,
   ladderReflectionStrategy,
   loopStrategyConfigSchema,
+  mcpRegistry,
+  mcpToolApprovals,
+  moderateOutputStream,
   noopReflectionStrategy,
+  outputModeration,
+  piiDetector,
   projectContextMetadataOnlyKnobs,
+  promptInjectionDetector,
   reflectionStrategyConfigSchema,
   resolveCompactionStrategy,
   resolveLoopStrategy,
+  resolveMcpServers,
+  runInputGuards,
+  runOutputGuards,
+  runWithApiErrorHandling,
   streamAgentResponse,
   streamAgentUIMessages,
   tokenBudgetCompactionStrategy,
   translateSdkEvent,
   translateToUIMessageStream,
+  unicodeNormalizer,
   validateUniqueRoutes,
   walkAgentMetadata
-} from "./chunk-QJKU2YMC.js";
+} from "./chunk-5VIRIPVV.js";
 import {
   Agent,
   Audit,
@@ -108,10 +129,282 @@ import {
   getSkillsConfig,
   getSubAgents,
   resolveSessionId
-} from "./chunk-FI6ZG2YP.js";
-import "./chunk-7QVYU63E.js";
+} from "./chunk-3AX6M5TF.js";
+import {
+  __name
+} from "./chunk-7QVYU63E.js";
+
+// src/a2a/agent-card.ts
+function trimTrailingSlash(url) {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+__name(trimTrailingSlash, "trimTrailingSlash");
+function buildAgentCard(entry, options) {
+  const base = trimTrailingSlash(options.baseUrl);
+  return {
+    name: entry.name,
+    description: options.description ?? `TheoKit agent "${entry.name}".`,
+    url: `${base}${entry.route}`,
+    version: "1.0",
+    capabilities: {
+      streaming: entry.stream,
+      pushNotifications: false,
+      stateTransitionHistory: false
+    },
+    defaultInputModes: [
+      "text"
+    ],
+    defaultOutputModes: [
+      "text"
+    ],
+    skills: entry.tools.map((t) => ({
+      id: t.name,
+      name: t.name,
+      description: t.description
+    }))
+  };
+}
+__name(buildAgentCard, "buildAgentCard");
+function wellKnownCardPath(agentName) {
+  return `/.well-known/${agentName}/agent-card.json`;
+}
+__name(wellKnownCardPath, "wellKnownCardPath");
+
+// src/a2a/mcp-server-manifest.ts
+var MCP_PROTOCOL_VERSION = "2024-11-05";
+function buildMcpToolDescriptors(entry) {
+  return entry.tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  }));
+}
+__name(buildMcpToolDescriptors, "buildMcpToolDescriptors");
+function mcpServerInfo(entry) {
+  return {
+    name: entry.name,
+    version: "1.0",
+    protocolVersion: MCP_PROTOCOL_VERSION
+  };
+}
+__name(mcpServerInfo, "mcpServerInfo");
+
+// src/a2a/a2a-client.ts
+function buildHeaders(config) {
+  const headers = {
+    "content-type": "application/json",
+    ...config.headers
+  };
+  if (config.auth?.bearer) headers.authorization = `Bearer ${config.auth.bearer}`;
+  if (config.auth?.apiKey) headers[config.auth.apiKey.header] = config.auth.apiKey.value;
+  return headers;
+}
+__name(buildHeaders, "buildHeaders");
+function createA2ATool(config) {
+  const doFetch = config.fetchImpl ?? fetch;
+  return {
+    name: config.name,
+    description: config.description,
+    inputSchema: {
+      type: "object",
+      properties: {
+        message: {
+          type: "string",
+          description: "The message to send to the remote agent."
+        }
+      },
+      required: [
+        "message"
+      ]
+    },
+    handler: /* @__PURE__ */ __name(async (input) => {
+      const message = typeof input.message === "string" ? input.message : "";
+      const res = await doFetch(config.url, {
+        method: "POST",
+        headers: buildHeaders(config),
+        body: JSON.stringify({
+          message
+        })
+      });
+      if (!res.ok) {
+        throw new Error(`A2A call to "${config.name}" failed: ${res.status} ${res.statusText}`);
+      }
+      const data = await res.json();
+      return data.response ?? data.text ?? "";
+    }, "handler")
+  };
+}
+__name(createA2ATool, "createA2ATool");
+
+// src/conversation-scope.ts
+var SEPARATOR = "/";
+function deriveConversationId(resource, thread) {
+  if (!resource) throw new Error("[@theokit/agents] deriveConversationId: resource must be non-empty");
+  if (!thread) throw new Error("[@theokit/agents] deriveConversationId: thread must be non-empty");
+  return `${encodeURIComponent(resource)}${SEPARATOR}${encodeURIComponent(thread)}`;
+}
+__name(deriveConversationId, "deriveConversationId");
+function parseConversationId(id) {
+  const idx = id.indexOf(SEPARATOR);
+  if (idx <= 0 || idx >= id.length - 1) return null;
+  const resource = decodeURIComponent(id.slice(0, idx));
+  const thread = decodeURIComponent(id.slice(idx + 1));
+  if (!resource || !thread) return null;
+  return {
+    resource,
+    thread
+  };
+}
+__name(parseConversationId, "parseConversationId");
+
+// src/skills-resolver.ts
+async function resolveEnabledSkills(selection, ctx) {
+  if (selection === void 0) return void 0;
+  if (typeof selection !== "function") return [
+    ...selection
+  ];
+  const resolved = await selection(ctx);
+  if (!Array.isArray(resolved)) {
+    throw new Error("[@theokit/agents] skills resolver must return an array of skill names");
+  }
+  return [
+    ...resolved
+  ];
+}
+__name(resolveEnabledSkills, "resolveEnabledSkills");
+
+// src/acp/protocol.ts
+function encodeAcpMessage(message) {
+  return `${JSON.stringify(message)}
+`;
+}
+__name(encodeAcpMessage, "encodeAcpMessage");
+var AcpMessageDecoder = class {
+  static {
+    __name(this, "AcpMessageDecoder");
+  }
+  buffer = "";
+  /** Feed a chunk; returns the messages completed by this chunk (possibly empty). */
+  push(chunk) {
+    this.buffer += chunk;
+    const messages = [];
+    let newlineIndex = this.buffer.indexOf("\n");
+    while (newlineIndex !== -1) {
+      const line = this.buffer.slice(0, newlineIndex).trim();
+      this.buffer = this.buffer.slice(newlineIndex + 1);
+      if (line.length > 0) {
+        try {
+          messages.push(JSON.parse(line));
+        } catch (cause) {
+          throw new Error(`[@theokit/agents] ACP decode failed on line: ${line}`, {
+            cause
+          });
+        }
+      }
+      newlineIndex = this.buffer.indexOf("\n");
+    }
+    return messages;
+  }
+};
+
+// src/acp/client.ts
+function isResponse(m) {
+  return typeof m.id === "number" && ("result" in m || "error" in m) && !("method" in m);
+}
+__name(isResponse, "isResponse");
+function isServerRequest(m) {
+  return typeof m.method === "string" && typeof m.id === "number";
+}
+__name(isServerRequest, "isServerRequest");
+var AcpClient = class {
+  static {
+    __name(this, "AcpClient");
+  }
+  transport;
+  nextId = 1;
+  pending = /* @__PURE__ */ new Map();
+  handlers = /* @__PURE__ */ new Map();
+  decoder = new AcpMessageDecoder();
+  constructor(transport) {
+    this.transport = transport;
+    transport.subscribe((chunk) => {
+      for (const message of this.decoder.push(chunk)) {
+        this.dispatch(message);
+      }
+    });
+  }
+  /** Send a JSON-RPC request and resolve with its `result` (or reject on `error`). */
+  request(method, params) {
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, {
+        resolve,
+        reject
+      });
+      this.transport.send(encodeAcpMessage({
+        jsonrpc: "2.0",
+        id,
+        method,
+        params
+      }));
+    });
+  }
+  /** Register a handler for a server→client request method (e.g. `session/request_permission`). */
+  onRequest(method, handler) {
+    this.handlers.set(method, handler);
+  }
+  dispatch(message) {
+    if (isResponse(message)) {
+      const entry = this.pending.get(message.id);
+      if (!entry) return;
+      this.pending.delete(message.id);
+      if (message.error) entry.reject(new Error(message.error.message));
+      else entry.resolve(message.result);
+      return;
+    }
+    if (isServerRequest(message)) {
+      void this.handleServerRequest(message);
+    }
+  }
+  async handleServerRequest(req) {
+    const handler = this.handlers.get(req.method);
+    if (!handler) {
+      this.transport.send(encodeAcpMessage({
+        jsonrpc: "2.0",
+        id: req.id,
+        error: {
+          code: -32601,
+          message: `No handler: ${req.method}`
+        }
+      }));
+      return;
+    }
+    try {
+      const result = await handler(req.params);
+      this.transport.send(encodeAcpMessage({
+        jsonrpc: "2.0",
+        id: req.id,
+        result
+      }));
+    } catch (err) {
+      this.transport.send(encodeAcpMessage({
+        jsonrpc: "2.0",
+        id: req.id,
+        error: {
+          code: -32603,
+          message: err instanceof Error ? err.message : "handler failed"
+        }
+      }));
+    }
+  }
+};
 export {
   AGENT_BRAND,
+  AcpClient,
+  AcpMessageDecoder,
   Agent,
   AgentDefinitionError,
   AgentRunner,
@@ -125,14 +418,17 @@ export {
   Compaction,
   ContextWindow,
   Conversation,
+  CostBudgetExceededError,
   DEFAULT_KEEP_TOKENS,
   DEFAULT_MAX_ITERATIONS,
   DelegationError,
   EditFormat,
   Gateway,
+  GuardrailViolationError,
   Hook,
   HumanInTheLoop,
   MCP,
+  MCP_PROTOCOL_VERSION,
   MainLoop,
   Memory,
   Mixin,
@@ -148,8 +444,11 @@ export {
   Tool,
   Toolbox,
   Trace,
+  agent,
   agentsPlugin,
   applyDecorators,
+  buildAgentCard,
+  buildMcpToolDescriptors,
   buildModelSelection,
   compactionStrategyConfigSchema,
   compileAgent,
@@ -159,11 +458,21 @@ export {
   compileProjectContext,
   compileSkills,
   compileTools,
+  contextualTool,
+  costGuard,
+  createA2ATool,
   createAgentExecutionContext,
+  createApiErrorHandler,
   createSdkAgentStream,
   createThinkTagExtractor,
+  createToolHooksPlugin,
   defineAgent,
   delegate,
+  delegateBackground,
+  delegateWithScoring,
+  deriveConversationId,
+  encodeAcpMessage,
+  estimateTokens,
   extractThinkTagStream,
   generateAgentManifest,
   generateAgentRoutes,
@@ -203,18 +512,33 @@ export {
   isToolResult,
   ladderReflectionStrategy,
   loopStrategyConfigSchema,
+  mcpRegistry,
+  mcpServerInfo,
+  mcpToolApprovals,
+  moderateOutputStream,
   noopReflectionStrategy,
+  outputModeration,
+  parseConversationId,
+  piiDetector,
   projectContextMetadataOnlyKnobs,
+  promptInjectionDetector,
   reflectionStrategyConfigSchema,
   resolveCompactionStrategy,
+  resolveEnabledSkills,
   resolveLoopStrategy,
+  resolveMcpServers,
   resolveSessionId,
+  runInputGuards,
+  runOutputGuards,
+  runWithApiErrorHandling,
   streamAgentResponse,
   streamAgentUIMessages,
   tokenBudgetCompactionStrategy,
   translateSdkEvent,
   translateToUIMessageStream,
+  unicodeNormalizer,
   validateUniqueRoutes,
-  walkAgentMetadata
+  walkAgentMetadata,
+  wellKnownCardPath
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../src/a2a/agent-card.ts","../src/a2a/mcp-server-manifest.ts","../src/a2a/a2a-client.ts","../src/conversation-scope.ts","../src/skills-resolver.ts","../src/acp/protocol.ts","../src/acp/client.ts"],"sourcesContent":["/**\n * M15 (theokit-ai-first) — A2A agent card generation (ADR-0040 § D2, home/discovery concern).\n *\n * Produces an [A2A](https://github.com/google/A2A)-spec Agent Card from the framework's\n * `AgentManifestEntry`, so other systems can discover a TheoKit agent's capabilities over HTTP at\n * `/.well-known/<name>/agent-card.json`. Pure data transform — no LLM, no runtime (G2).\n */\nimport type { AgentManifestEntry } from '../manifest/agent-manifest.js'\n\n/** A single capability exposed by an A2A agent (maps from a TheoKit tool). */\nexport interface A2ASkill {\n  id: string\n  name: string\n  description: string\n}\n\n/** A2A agent-card capabilities block. */\nexport interface A2ACapabilities {\n  streaming: boolean\n  pushNotifications: boolean\n  stateTransitionHistory: boolean\n}\n\n/** An A2A-spec Agent Card (the subset TheoKit advertises). */\nexport interface AgentCard {\n  name: string\n  description: string\n  url: string\n  version: string\n  capabilities: A2ACapabilities\n  defaultInputModes: string[]\n  defaultOutputModes: string[]\n  skills: A2ASkill[]\n}\n\nexport interface BuildAgentCardOptions {\n  /** Absolute base URL of the deployment (e.g. `https://app.example.com`). A trailing slash is trimmed. */\n  baseUrl: string\n  /** Human description of the agent. Defaults to a generated sentence when omitted (spec requires non-empty). */\n  description?: string\n}\n\n/** Strip a single trailing slash so `${baseUrl}${route}` never doubles the separator. */\nfunction trimTrailingSlash(url: string): string {\n  return url.endsWith('/') ? url.slice(0, -1) : url\n}\n\n/** Build an A2A agent card from a manifest entry. */\nexport function buildAgentCard(entry: AgentManifestEntry, options: BuildAgentCardOptions): AgentCard {\n  const base = trimTrailingSlash(options.baseUrl)\n  return {\n    name: entry.name,\n    description: options.description ?? `TheoKit agent \"${entry.name}\".`,\n    url: `${base}${entry.route}`,\n    version: '1.0',\n    capabilities: {\n      streaming: entry.stream,\n      pushNotifications: false,\n      stateTransitionHistory: false,\n    },\n    defaultInputModes: ['text'],\n    defaultOutputModes: ['text'],\n    skills: entry.tools.map((t) => ({ id: t.name, name: t.name, description: t.description })),\n  }\n}\n\n/** The A2A discovery path for an agent: `/.well-known/<name>/agent-card.json`. */\nexport function wellKnownCardPath(agentName: string): string {\n  return `/.well-known/${agentName}/agent-card.json`\n}\n","/**\n * M16 (theokit-ai-first) — MCP server manifest generation (ADR-0040 § D2, home concern).\n *\n * Exposes a TheoKit agent's tools to external MCP clients as `tools/list` descriptors, so the app\n * can advertise its agents over its OWN HTTP routes. Pure data transform — no LLM, no runtime, and\n * NO stdio transport (that stays SDK-side per sdk-runtime.md). Serving these over `GET /mcp` and the\n * JSON-RPC envelope are follow-ups (mount path).\n */\nimport type { AgentManifestEntry } from '../manifest/agent-manifest.js'\n\n/** The MCP protocol revision these descriptors target. */\nexport const MCP_PROTOCOL_VERSION = '2024-11-05'\n\n/** A JSON-schema object (the shape MCP expects for a tool's `inputSchema`). */\nexport interface McpJsonSchema {\n  type: 'object'\n  properties: Record<string, unknown>\n  required?: string[]\n}\n\n/** An MCP `tools/list` tool descriptor. */\nexport interface McpToolDescriptor {\n  name: string\n  description: string\n  inputSchema: McpJsonSchema\n}\n\n/** MCP `initialize` server info. */\nexport interface McpServerInfo {\n  name: string\n  version: string\n  protocolVersion: string\n}\n\n/**\n * Map an agent's tools to MCP tool descriptors. The manifest tool carries name + description; the\n * per-tool JSON schema is not retained in the manifest, so a permissive empty-object schema is\n * emitted (MCP clients accept it and pass through arbitrary args). Wiring the real per-tool schema\n * is a follow-up once the manifest carries it.\n */\nexport function buildMcpToolDescriptors(entry: AgentManifestEntry): McpToolDescriptor[] {\n  return entry.tools.map((t) => ({\n    name: t.name,\n    description: t.description,\n    inputSchema: { type: 'object', properties: {} },\n  }))\n}\n\n/** Build the MCP `initialize` server-info block for an agent. */\nexport function mcpServerInfo(entry: AgentManifestEntry): McpServerInfo {\n  return { name: entry.name, version: '1.0', protocolVersion: MCP_PROTOCOL_VERSION }\n}\n","/**\n * M15 (theokit-ai-first) — A2A client: call a remote A2A agent as a tool (ADR-0040 § D2).\n *\n * `createA2ATool` returns a `CustomTool` whose handler POSTs the input message to a remote agent's\n * HTTP endpoint and returns its text response — cross-network delegation. Uses `fetch` (Web\n * Standards, G8). The target is a remote AGENT endpoint, not an LLM provider, so the G2 grep guard\n * (`openrouter.ai|api.openai.com|api.anthropic.com`) is unaffected. `fetchImpl` is injectable for tests.\n */\nimport type { CustomTool } from '@theokit/sdk'\n\n/** How to authenticate to the remote agent. */\nexport interface A2AAuth {\n  /** Bearer token → `Authorization: Bearer <token>`. */\n  bearer?: string\n  /** API-key header pair → `<name>: <value>` (e.g. `x-api-key`). */\n  apiKey?: { header: string; value: string }\n}\n\nexport interface A2AToolConfig {\n  /** Remote agent endpoint URL (POST target). */\n  url: string\n  /** Tool name the model calls. */\n  name: string\n  /** Tool description surfaced to the model. */\n  description: string\n  /** Static headers merged into every request. */\n  headers?: Record<string, string>\n  /** Auth applied to every request. */\n  auth?: A2AAuth\n  /** Injected fetch (defaults to the global). Narrowed to the call shape this client uses. */\n  fetchImpl?: (url: string, init: RequestInit) => Promise<Response>\n}\n\n/** Build the request headers from static headers + auth. */\nfunction buildHeaders(config: A2AToolConfig): Record<string, string> {\n  const headers: Record<string, string> = { 'content-type': 'application/json', ...config.headers }\n  if (config.auth?.bearer) headers.authorization = `Bearer ${config.auth.bearer}`\n  if (config.auth?.apiKey) headers[config.auth.apiKey.header] = config.auth.apiKey.value\n  return headers\n}\n\n/**\n * Create a tool that delegates to a remote A2A agent. The remote is expected to answer a\n * `{ message }` POST with a JSON body carrying a `response` (or `text`) string.\n */\nexport function createA2ATool(config: A2AToolConfig): CustomTool {\n  const doFetch = config.fetchImpl ?? fetch\n  return {\n    name: config.name,\n    description: config.description,\n    inputSchema: {\n      type: 'object',\n      properties: { message: { type: 'string', description: 'The message to send to the remote agent.' } },\n      required: ['message'],\n    },\n    handler: async (input: Record<string, unknown>): Promise<string> => {\n      // The input schema requires `message: string`; narrow defensively (never base-to-string).\n      const message = typeof input.message === 'string' ? input.message : ''\n      const res = await doFetch(config.url, {\n        method: 'POST',\n        headers: buildHeaders(config),\n        body: JSON.stringify({ message }),\n      })\n      if (!res.ok) {\n        throw new Error(`A2A call to \"${config.name}\" failed: ${res.status} ${res.statusText}`)\n      }\n      const data = (await res.json()) as { response?: string; text?: string }\n      return data.response ?? data.text ?? ''\n    },\n  }\n}\n","/**\n * M11 (theokit-ai-first) — {resource, thread} conversation scoping (ADR-0040 § D2, home concern).\n *\n * Maps a request's (resource, thread) pair to a deterministic, collision-safe conversation id so\n * multi-tenant apps isolate history without hand-building `user-${id}-thread-${id}` strings. This\n * is the app's request→conversation mapping — NOT the SDK's storage engine (which the derived id is\n * simply handed to). Background compression of long histories stays SDK-side.\n *\n * Encoding: each component is `encodeURIComponent`-escaped and joined with `/`. Since\n * `encodeURIComponent` escapes a raw `/` to `%2F`, the separator is unambiguous — `('a/b','c')` and\n * `('a','b/c')` derive DIFFERENT ids (collision-safe). Reversible via {@link parseConversationId}.\n */\n\nconst SEPARATOR = '/'\n\n/** Derive a deterministic conversation id from a (resource, thread) pair. Fails fast on empty input. */\nexport function deriveConversationId(resource: string, thread: string): string {\n  if (!resource) throw new Error('[@theokit/agents] deriveConversationId: resource must be non-empty')\n  if (!thread) throw new Error('[@theokit/agents] deriveConversationId: thread must be non-empty')\n  return `${encodeURIComponent(resource)}${SEPARATOR}${encodeURIComponent(thread)}`\n}\n\n/**\n * Reverse a derived conversation id back to its (resource, thread). Returns `null` for a value that\n * is not a derived scope id (no separator, or an empty component) — callers treat that as \"opaque id,\n * not scoped\".\n */\nexport function parseConversationId(id: string): { resource: string; thread: string } | null {\n  const idx = id.indexOf(SEPARATOR)\n  if (idx <= 0 || idx >= id.length - 1) return null\n  const resource = decodeURIComponent(id.slice(0, idx))\n  const thread = decodeURIComponent(id.slice(idx + 1))\n  if (!resource || !thread) return null\n  return { resource, thread }\n}\n","/**\n * M13 (theokit-ai-first) — per-request skills resolution (ADR-0040 § D2, home/boundary concern).\n *\n * The static `skills.enabled` filter already works (`compile-skills` maps `include` → the SDK's\n * `enabled`). This adds a PER-REQUEST resolver so multi-tenant apps expose different skill sets to\n * different users. A selection is either a static list or a function of the request context (the M7\n * run-context). Discovery + injection stay in the SDK; this only CHOOSES the enabled set per call.\n */\n\n/** The request context handed to a skills resolver (the M7 run-context — opaque per-request data). */\nexport type SkillsRequestContext = Record<string, unknown>\n\n/**\n * How the enabled skill set is chosen:\n * - `string[]`  — a static list (same shape `skills.enabled` accepts today).\n * - a function  — resolved per request from the {@link SkillsRequestContext} (sync or async).\n */\nexport type SkillsSelection =\n  | readonly string[]\n  | ((ctx: SkillsRequestContext) => readonly string[] | Promise<readonly string[]>)\n\n/**\n * Resolve the enabled skill names for a request. Returns `undefined` when no selection is given (the\n * SDK then enables every discovered skill). Fails fast if a resolver returns a non-array.\n */\nexport async function resolveEnabledSkills(\n  selection: SkillsSelection | undefined,\n  ctx: SkillsRequestContext,\n): Promise<string[] | undefined> {\n  if (selection === undefined) return undefined\n  if (typeof selection !== 'function') return [...selection]\n  const resolved = await selection(ctx)\n  if (!Array.isArray(resolved)) {\n    throw new Error('[@theokit/agents] skills resolver must return an array of skill names')\n  }\n  return [...resolved]\n}\n","/**\n * M17 (theokit-ai-first) — ACP (Agent Client Protocol) stdio framing.\n *\n * ACP talks to a coding agent (Claude Code, Amp, Codex) over stdio as newline-delimited JSON. This\n * is the transport-agnostic CORE: encode a message to a line, and decode a byte/char stream that may\n * split a message across chunks. Pure — no subprocess, no Node API. The subprocess spawn lives in the\n * adapter layer (G8) / SDK; `createACPTool` (wrapping this codec + an injected transport) is a\n * follow-up once the adapter ships.\n */\n\n/** Serialize a message to a single newline-terminated JSON line. */\nexport function encodeAcpMessage(message: unknown): string {\n  return `${JSON.stringify(message)}\\n`\n}\n\n/**\n * Incremental decoder for newline-delimited JSON. Feed it chunks with {@link push}; it buffers a\n * partial trailing line across calls and returns every WHOLE message parsed so far. Blank lines are\n * skipped. A completed non-JSON line fails fast with a typed error (error-handling.md) — a corrupt\n * frame must never be silently dropped.\n */\nexport class AcpMessageDecoder {\n  private buffer = ''\n\n  /** Feed a chunk; returns the messages completed by this chunk (possibly empty). */\n  push(chunk: string): unknown[] {\n    this.buffer += chunk\n    const messages: unknown[] = []\n    let newlineIndex = this.buffer.indexOf('\\n')\n    while (newlineIndex !== -1) {\n      const line = this.buffer.slice(0, newlineIndex).trim()\n      this.buffer = this.buffer.slice(newlineIndex + 1)\n      if (line.length > 0) {\n        try {\n          messages.push(JSON.parse(line))\n        } catch (cause) {\n          throw new Error(`[@theokit/agents] ACP decode failed on line: ${line}`, { cause })\n        }\n      }\n      newlineIndex = this.buffer.indexOf('\\n')\n    }\n    return messages\n  }\n}\n","/**\n * M17 (theokit-ai-first) — ACP client: JSON-RPC over the stdio framing.\n *\n * Drives a coding agent (Claude Code, Amp, Codex) over an INJECTED {@link AcpTransport}. The\n * subprocess spawn is a Node API and lives in the adapter layer (G8); this client is transport-\n * agnostic and testable. It correlates responses to requests by `id`, and dispatches server→client\n * requests (e.g. `session/request_permission`) to a registered handler, replying with its decision.\n */\nimport { AcpMessageDecoder, encodeAcpMessage } from './protocol.js'\n\n/** The stdio channel to the coding-agent subprocess (abstracted for testability + G8). */\nexport interface AcpTransport {\n  /** Write one already-encoded (newline-terminated) line to the agent's stdin. */\n  send(line: string): void\n  /** Subscribe to raw lines/chunks from the agent's stdout. */\n  subscribe(onData: (chunk: string) => void): void\n}\n\ninterface JsonRpcResponse {\n  id: number\n  result?: unknown\n  error?: { code: number; message: string }\n}\ninterface JsonRpcServerRequest {\n  id: number\n  method: string\n  params?: unknown\n}\n\ninterface Pending {\n  resolve: (value: unknown) => void\n  reject: (err: Error) => void\n}\n/** Return a value or a Promise — `unknown` already includes `Promise<unknown>`; `await` handles both. */\ntype ServerRequestHandler = (params: unknown) => unknown\n\nfunction isResponse(m: Record<string, unknown>): m is JsonRpcResponse & Record<string, unknown> {\n  return typeof m.id === 'number' && (('result' in m) || ('error' in m)) && !('method' in m)\n}\nfunction isServerRequest(m: Record<string, unknown>): m is JsonRpcServerRequest & Record<string, unknown> {\n  return typeof m.method === 'string' && typeof m.id === 'number'\n}\n\nexport class AcpClient {\n  private nextId = 1\n  private readonly pending = new Map<number, Pending>()\n  private readonly handlers = new Map<string, ServerRequestHandler>()\n  private readonly decoder = new AcpMessageDecoder()\n\n  constructor(private readonly transport: AcpTransport) {\n    transport.subscribe((chunk) => {\n      for (const message of this.decoder.push(chunk)) {\n        this.dispatch(message as Record<string, unknown>)\n      }\n    })\n  }\n\n  /** Send a JSON-RPC request and resolve with its `result` (or reject on `error`). */\n  request(method: string, params: unknown): Promise<unknown> {\n    const id = this.nextId++\n    return new Promise<unknown>((resolve, reject) => {\n      this.pending.set(id, { resolve, reject })\n      this.transport.send(encodeAcpMessage({ jsonrpc: '2.0', id, method, params }))\n    })\n  }\n\n  /** Register a handler for a server→client request method (e.g. `session/request_permission`). */\n  onRequest(method: string, handler: ServerRequestHandler): void {\n    this.handlers.set(method, handler)\n  }\n\n  private dispatch(message: Record<string, unknown>): void {\n    if (isResponse(message)) {\n      const entry = this.pending.get(message.id)\n      if (!entry) return\n      this.pending.delete(message.id)\n      if (message.error) entry.reject(new Error(message.error.message))\n      else entry.resolve(message.result)\n      return\n    }\n    if (isServerRequest(message)) {\n      void this.handleServerRequest(message)\n    }\n  }\n\n  private async handleServerRequest(req: JsonRpcServerRequest): Promise<void> {\n    const handler = this.handlers.get(req.method)\n    if (!handler) {\n      this.transport.send(\n        encodeAcpMessage({ jsonrpc: '2.0', id: req.id, error: { code: -32601, message: `No handler: ${req.method}` } }),\n      )\n      return\n    }\n    try {\n      const result = await handler(req.params)\n      this.transport.send(encodeAcpMessage({ jsonrpc: '2.0', id: req.id, result }))\n    } catch (err) {\n      this.transport.send(\n        encodeAcpMessage({\n          jsonrpc: '2.0',\n          id: req.id,\n          error: { code: -32603, message: err instanceof Error ? err.message : 'handler failed' },\n        }),\n      )\n    }\n  }\n}\n"],"mappings":"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","names":["trimTrailingSlash","url","endsWith","slice","buildAgentCard","entry","options","base","baseUrl","name","description","route","version","capabilities","streaming","stream","pushNotifications","stateTransitionHistory","defaultInputModes","defaultOutputModes","skills","tools","map","t","id","wellKnownCardPath","agentName","MCP_PROTOCOL_VERSION","buildMcpToolDescriptors","entry","tools","map","t","name","description","inputSchema","type","properties","mcpServerInfo","version","protocolVersion","buildHeaders","config","headers","auth","bearer","authorization","apiKey","header","value","createA2ATool","doFetch","fetchImpl","fetch","name","description","inputSchema","type","properties","message","required","handler","input","res","url","method","body","JSON","stringify","ok","Error","status","statusText","data","json","response","text","SEPARATOR","deriveConversationId","resource","thread","Error","encodeURIComponent","parseConversationId","id","idx","indexOf","length","decodeURIComponent","slice","resolveEnabledSkills","selection","ctx","undefined","resolved","Array","isArray","Error","encodeAcpMessage","message","JSON","stringify","AcpMessageDecoder","buffer","push","chunk","messages","newlineIndex","indexOf","line","slice","trim","length","parse","cause","Error","isResponse","m","id","isServerRequest","method","AcpClient","nextId","pending","Map","handlers","decoder","AcpMessageDecoder","transport","subscribe","chunk","message","push","dispatch","request","params","Promise","resolve","reject","set","send","encodeAcpMessage","jsonrpc","onRequest","handler","entry","get","delete","error","Error","result","handleServerRequest","req","code","err"]}

package/dist/{skills-Dx_KJ6Eg.d.ts → skills-DvI_LYWZ.d.ts}

@@ -194,6 +194,12 @@ interface HumanInTheLoopOptions {
     onTimeout?: TimeoutAction;
     /** Show the tool input to the approver (default: true). */
     showInput?: boolean;
+    /**
+     * M20 — an optional JSON-schema descriptor of the custom payload the approver may attach (edited
+     * args, a review note). Carried into the `approval_required` event + `GET /approvals` so the UI
+     * knows what to collect. A plain JSON object, not a live Zod schema (keeps the wire serializable).
+     */
+    payloadSchema?: Record<string, unknown>;
 }
 declare function HumanInTheLoop(options: HumanInTheLoopOptions): MethodDecorator;
 declare function getHumanInTheLoopConfig(target: Function, propertyKey: string | symbol): HumanInTheLoopOptions | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/agents",
-  "version": "0.30.2",
+  "version": "0.32.0",
   "description": "Unified decorator runtime — AI agents as first-class citizens of the TheoKit pipeline. @Agent() compiles to SDK Agent.create(), @Tool() compiles to defineTool().",
   "type": "module",
   "sideEffects": false,
@@ -29,9 +29,14 @@
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
   "peerDependencies": {
     "@theokit/http": ">=0.1.0-alpha.0",
-    "@theokit/sdk": ">=2.13.0",
+    "@theokit/sdk": ">=2.20.0",
     "@theokit/sdk-tools": ">=0.2.0",
     "ai": ">=7.0.0",
     "reflect-metadata": ">=0.2.0",
@@ -46,22 +51,17 @@
     }
   },
   "devDependencies": {
-    "@theokit/sdk": "^2.13.0",
+    "@theokit/http": "workspace:*",
+    "@theokit/sdk": "^2.20.0",
     "@theokit/sdk-tools": "^0.2.0",
     "ai": "^7.0.14",
     "reflect-metadata": "^0.2.2",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^3.2.6",
-    "zod": "^4.4.3",
-    "@theokit/http": "0.5.4"
+    "zod": "^4.4.3"
   },
   "engines": {
     "node": ">=22.12.0"
-  },
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest"
   }
-}
+}