@theokit/agents 0.43.0 → 0.44.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { G as Guardrail, R as ReasoningEffort } from './types-DVA4LQsA.js';
 export { A as AgentOptions, a as ApprovalOptions, B as BudgetOptions, C as CostBudgetExceededError, b as GuardrailAction, c as GuardrailPhase, d as GuardrailResult, e as GuardrailViolationError, H as HumanInTheLoopOptions, M as MainLoopMeta, f as MainLoopOptions, P as PolicyHandler, T as TimeoutAction, g as ToolOptions, h as ToolboxOptions } from './types-DVA4LQsA.js';
-import { L as LoopStrategy, R as ReflectionStrategy, C as CompiledAgentOptions, a as CompiledTool, b as RoundStreamFactory, S as StreamEvent, D as DelegationResult, A as AgentManifestEntry } from './bridge-entry-Bo3LsMQF.js';
-export { c as AGENT_BRAND, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinition, g as AgentDefinitionError, h as AgentExecutionContext, i as AgentManifest, j as AgentManifestTool, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentStreamEvent, o as AgentTurnMetadata, p as AgentWalkResult, q as AgentWarningCode, r as AgentsPluginOptions, s as ApiErrorContext, t as ApiErrorDecision, u as ApiErrorPolicy, v as ApprovalRequiredEvent, w as ArtifactChunkEvent, x as ArtifactStartEvent, B as BackgroundDelegation, y as BeforeToolCallContext, z as BudgetExceededError, E as CheckpointSavedEvent, F as CompiledContextWindow, G as ContextualTool, H as DEFAULT_MAX_ITERATIONS, I as DefineAgentConfig, J as DelegateFn, K as DelegateOptions, M as DelegationError, N as DoneEvent, O as ErrorEvent, P as FileEditEvent, Q as HitlDecision, T as InferAgentInput, U as InferAgentToolNames, V as IterationEvent, W as LLMCallContext, X as LoopFinishReason, Y as LoopOutcome, Z as LoopStrategyConfig, _ as McpApprovalSpec, $ as McpRegistryConfig, a0 as McpRequestContext, a1 as McpSelection, a2 as PartialToolCallEvent, a3 as ProcessInputContext, a4 as ReflectionContext, a5 as ReflectionResult, a6 as ReflectionStrategyConfig, a7 as RunStartedEvent, a8 as ScoreVerdict, a9 as ScoredDelegation, aa as Scorer, ab as SdkMessage, ac as Segment, ad as SkillsRequestContext, ae as SkillsSelection, af as StateUpdateEvent, ag as TextDeltaEvent, ah as ThinkingEvent, ai as ToolCallEvent, aj as ToolCallVeto, ak as ToolHooks, al as ToolHooksPlugin, am as ToolResultEvent, an as ToolWalkResult, ao as ToolboxWalkResult, ap as agent, aq as agentsPlugin, ar as buildModelSelection, as as compileAgent, at as compileAgentDefinition, au as compileAgentModule, av as compileContextWindow, aw as compileProjectContext, ax as compileSkills, ay as compileTools, az as contextualTool, aA as createAgentExecutionContext, aB as createApiErrorHandler, aC as createSdkAgentStream, aD as createThinkTagExtractor, aE as createToolHooksPlugin, aF as delegate, aG as delegateBackground, aH as delegateWithScoring, aI as extractThinkTagStream, aJ as generateAgentManifest, aK as generateAgentRoutes, aL as isAgentContext, aM as isAgentDefinition, aN as isApprovalRequired, aO as isDone, aP as isError, aQ as isPartialToolCall, aR as isTextDelta, aS as isToolCall, aT as isToolResult, aU as ladderReflectionStrategy, aV as loopStrategyConfigSchema, aW as mcpRegistry, aX as mcpToolApprovals, aY as noopReflectionStrategy, aZ as projectContextMetadataOnlyKnobs, a_ as reflectionStrategyConfigSchema, a$ as resolveEnabledSkills, b0 as resolveLoopStrategy, b1 as resolveMcpServers, b2 as runWithApiErrorHandling, b3 as streamAgentResponse, b4 as streamAgentUIMessages, b5 as translateSdkEvent, b6 as translateToUIMessageStream, b7 as validateUniqueRoutes, b8 as walkAgentMetadata } from './bridge-entry-Bo3LsMQF.js';
+import { L as LoopStrategy, R as ReflectionStrategy, C as CompiledAgentOptions, a as CompiledTool, b as RoundStreamFactory, S as StreamEvent, D as DelegationResult, A as AgentManifestEntry } from './bridge-entry-BW1ifbWg.js';
+export { c as AGENT_BRAND, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinition, g as AgentDefinitionError, h as AgentExecutionContext, i as AgentManifest, j as AgentManifestTool, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentStreamEvent, o as AgentTurnMetadata, p as AgentWalkResult, q as AgentWarningCode, r as AgentsPluginOptions, s as ApiErrorContext, t as ApiErrorDecision, u as ApiErrorPolicy, v as ApprovalRequiredEvent, w as ArtifactChunkEvent, x as ArtifactStartEvent, B as BackgroundDelegation, y as BeforeToolCallContext, z as BudgetExceededError, E as CheckpointSavedEvent, F as CompiledContextWindow, G as ContextualTool, H as DEFAULT_MAX_ITERATIONS, I as DefineAgentConfig, J as DelegateFn, K as DelegateOptions, M as DelegationError, N as DoneEvent, O as ErrorEvent, P as FileEditEvent, Q as HitlDecision, T as InferAgentInput, U as InferAgentToolNames, V as IterationEvent, W as LLMCallContext, X as LoopFinishReason, Y as LoopOutcome, Z as LoopStrategyConfig, _ as McpApprovalSpec, $ as McpRegistryConfig, a0 as McpRequestContext, a1 as McpSelection, a2 as PartialToolCallEvent, a3 as ProcessInputContext, a4 as ReflectionContext, a5 as ReflectionResult, a6 as ReflectionStrategyConfig, a7 as RunStartedEvent, a8 as ScoreVerdict, a9 as ScoredDelegation, aa as Scorer, ab as SdkAgentHandle, ac as SdkMessage, ad as Segment, ae as SkillsRequestContext, af as SkillsSelection, ag as StateUpdateEvent, ah as TextDeltaEvent, ai as ThinkingEvent, aj as ToolCallEvent, ak as ToolCallVeto, al as ToolHooks, am as ToolHooksPlugin, an as ToolResultEvent, ao as ToolWalkResult, ap as ToolboxWalkResult, aq as agent, ar as agentsPlugin, as as buildModelSelection, at as compileAgent, au as compileAgentDefinition, av as compileAgentModule, aw as compileContextWindow, ax as compileProjectContext, ay as compileSkills, az as compileTools, aA as contextualTool, aB as createAgentExecutionContext, aC as createApiErrorHandler, aD as createSdkAgentStream, aE as createThinkTagExtractor, aF as createToolHooksPlugin, aG as delegate, aH as delegateBackground, aI as delegateWithScoring, aJ as extractThinkTagStream, aK as generateAgentManifest, aL as generateAgentRoutes, aM as isAgentContext, aN as isAgentDefinition, aO as isApprovalRequired, aP as isDone, aQ as isError, aR as isPartialToolCall, aS as isTextDelta, aT as isToolCall, aU as isToolResult, aV as ladderReflectionStrategy, aW as loopStrategyConfigSchema, aX as mcpRegistry, aY as mcpToolApprovals, aZ as noopReflectionStrategy, a_ as projectContextMetadataOnlyKnobs, a$ as reflectionStrategyConfigSchema, b0 as resolveEnabledSkills, b1 as resolveLoopStrategy, b2 as resolveMcpServers, b3 as runWithApiErrorHandling, b4 as streamAgentResponse, b5 as streamAgentUIMessages, b6 as toAgentFactory, b7 as translateSdkEvent, b8 as translateToUIMessageStream, b9 as validateUniqueRoutes, ba as walkAgentMetadata } from './bridge-entry-BW1ifbWg.js';
 import { PluginsSettings, Plugin, ProviderRoutingSettings, AgentDefinition, BudgetTracker, CustomTool } from '@theokit/sdk';
 import { RetryOptions } from '@theokit/sdk/retry';
 import { CompressibleMessage } from '@theokit/sdk/compaction';

package/dist/index.js

@@ -63,13 +63,14 @@ import {
   runWithApiErrorHandling,
   streamAgentResponse,
   streamAgentUIMessages,
+  toAgentFactory,
   tokenBudgetCompactionStrategy,
   translateSdkEvent,
   translateToUIMessageStream,
   unicodeNormalizer,
   validateUniqueRoutes,
   walkAgentMetadata
-} from "./chunk-5VK63XGX.js";
+} from "./chunk-6WOLHCZB.js";
 import "./chunk-NERDIS45.js";
 import {
   __name
@@ -418,6 +419,7 @@ export {
   runWithApiErrorHandling,
   streamAgentResponse,
   streamAgentUIMessages,
+  toAgentFactory,
   tokenBudgetCompactionStrategy,
   translateSdkEvent,
   translateToUIMessageStream,

package/dist/index.js.map

@@ -1 +1 @@
-{"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\nimport type { InlineSkill } from '@theokit/sdk'\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 skill set is chosen:\n * - a static array of `string` (filesystem skill NAMES → `skills.enabled`) and/or `InlineSkill`\n *   objects from `createSkill` (code-defined skills → `skills.inline`, injected into the `<skills>`\n *   block). A mixed list is split at compile time.\n * - a function — resolved per request from the {@link SkillsRequestContext} (sync or async). The\n *   resolver returns filesystem skill NAMES (inline skills are static — declared on the agent).\n */\nexport type SkillsSelection =\n  | readonly (string | InlineSkill)[]\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. The static\n * array is compiled ahead of time (see `compileSkillsSelection`), so this is exercised for the\n * resolver form; a static array is defensively narrowed to its string (name) members.\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') {\n    return selection.filter((s): s is string => typeof s === 'string')\n  }\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","filter","s","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"]}
+{"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\nimport type { InlineSkill } from '@theokit/sdk'\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 skill set is chosen:\n * - a static array of `string` (filesystem skill NAMES → `skills.enabled`) and/or `InlineSkill`\n *   objects from `createSkill` (code-defined skills → `skills.inline`, injected into the `<skills>`\n *   block). A mixed list is split at compile time.\n * - a function — resolved per request from the {@link SkillsRequestContext} (sync or async). The\n *   resolver returns filesystem skill NAMES (inline skills are static — declared on the agent).\n */\nexport type SkillsSelection =\n  | readonly (string | InlineSkill)[]\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. The static\n * array is compiled ahead of time (see `compileSkillsSelection`), so this is exercised for the\n * resolver form; a static array is defensively narrowed to its string (name) members.\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') {\n    return selection.filter((s): s is string => typeof s === 'string')\n  }\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","filter","s","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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/agents",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "AI agents as first-class citizens of the TheoKit pipeline. The fluent agent()/tool() builders compile to SDK Agent.create() (M31 builder-only authoring API).",
   "type": "module",
   "sideEffects": false,
@@ -25,6 +25,11 @@
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
   "peerDependencies": {
     "@theokit/http": ">=0.1.0-alpha.0",
     "@theokit/sdk": "^4.0.1",
@@ -42,6 +47,7 @@
     }
   },
   "devDependencies": {
+    "@theokit/http": "workspace:*",
     "@theokit/sdk": "^4.1.0",
     "@theokit/sdk-tools": "^0.11.0",
     "ai": "^7.0.14",
@@ -49,15 +55,9 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^3.2.6",
-    "zod": "^4.4.3",
-    "@theokit/http": "0.7.0"
+    "zod": "^4.4.3"
   },
   "engines": {
     "node": ">=22.12.0"
-  },
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest"
   }
-}
+}

package/LICENSE

@@ -1,201 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for describing the origin of the Work and
-      reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2026 usetheo.dev
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.