@theokit/sdk 1.6.1 → 1.7.0

package/dist/internal/plugins/index.cjs

@@ -0,0 +1,228 @@
+'use strict';
+
+// src/internal/plugins/context.ts
+function createPluginContext() {
+  const registrations = {
+    tools: [],
+    commands: [],
+    hooks: /* @__PURE__ */ new Map(),
+    injected: []
+  };
+  const impl = {
+    registerTool(tool) {
+      registrations.tools.push(tool);
+    },
+    registerCommand(name, handler, opts = {}) {
+      const entry = { name, handler };
+      if (opts.description !== void 0) entry.description = opts.description;
+      registrations.commands.push(entry);
+    },
+    on(hook, handler) {
+      if (typeof handler !== "function") {
+        process.stderr.write(`[theokit-sdk] ignoring non-function handler for hook "${hook}"
+`);
+        return;
+      }
+      const existing = registrations.hooks.get(hook) ?? [];
+      existing.push(handler);
+      registrations.hooks.set(hook, existing);
+    },
+    injectMessage(content, role = "user") {
+      registrations.injected.push({ content, role });
+    }
+  };
+  const ctx = shouldSeal() ? sealContext(impl) : impl;
+  return { ctx, registrations };
+}
+function shouldSeal() {
+  return process.env.NODE_ENV !== "production";
+}
+function sealContext(impl) {
+  return new Proxy(impl, {
+    set(_target, prop) {
+      throw new Error(
+        `[theokit-sdk] PluginContext is sealed \u2014 cannot set ${String(prop)}. Plugins must use registerTool, registerCommand, on, or injectMessage.`
+      );
+    },
+    deleteProperty(_target, prop) {
+      throw new Error(`[theokit-sdk] PluginContext is sealed \u2014 cannot delete ${String(prop)}.`);
+    }
+  });
+}
+
+// src/internal/plugins/lifecycle.ts
+async function runFireAndForgetHooks(handlers, ctx) {
+  for (const h of handlers) {
+    try {
+      await h(ctx);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[theokit-sdk] plugin hook threw (continuing): ${msg}
+`);
+    }
+  }
+}
+async function runTransformHooks(handlers, initial) {
+  let current = initial;
+  for (const h of handlers) {
+    try {
+      const next = await h(current);
+      if (next !== void 0) current = next;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[theokit-sdk] plugin transform hook threw (continuing): ${msg}
+`);
+    }
+  }
+  return current;
+}
+
+// src/internal/plugins/manager.ts
+var PluginManager = class {
+  #aggregated = {
+    tools: [],
+    commands: [],
+    hooks: /* @__PURE__ */ new Map(),
+    injected: [],
+    providerProfiles: [],
+    memoryProviders: []
+  };
+  #initialized = false;
+  async initialize(plugins) {
+    if (this.#initialized) {
+      throw new Error("PluginManager.initialize called twice \u2014 register only once per process");
+    }
+    this.#initialized = true;
+    const seen = /* @__PURE__ */ new Set();
+    for (const plugin of plugins) {
+      if (seen.has(plugin.name)) {
+        process.stderr.write(
+          `[theokit-sdk] duplicate plugin name "${plugin.name}" \u2014 both will register independently
+`
+        );
+      }
+      seen.add(plugin.name);
+      await this.#dispatchPlugin(plugin);
+    }
+  }
+  get aggregated() {
+    return this.#aggregated;
+  }
+  /**
+   * Run all `pre_tool_call` hooks; first decision with `block: true` wins.
+   * D101: veto pattern — return `{ block: true, message }` makes the loop
+   * surface a tool_result with `isError: false, content: message` so the
+   * LLM can self-correct.
+   */
+  async runPreToolCallHooks(ctx) {
+    const handlers = this.#aggregated.hooks.get("pre_tool_call") ?? [];
+    for (const h of handlers) {
+      const decision = await h(ctx);
+      if (decision !== void 0 && decision.block === true) {
+        return decision;
+      }
+    }
+    return void 0;
+  }
+  /** Aggregated handlers for a given hook (read-only view). @internal */
+  hooksFor(name) {
+    return this.#aggregated.hooks.get(name) ?? [];
+  }
+  /**
+   * Run all `pre_user_send` hooks; concatenate non-empty `recalledContext`
+   * outputs with `\n\n` and cap total length at `maxRecallContextBytes`
+   * (EC-A). Per-handler failures are caught + logged to stderr (EC-8) so a
+   * single broken adapter never blocks the LLM call (graceful degrade).
+   *
+   * Returns the assembled context (or undefined if empty after cap).
+   *
+   * @internal
+   */
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: per-handler try/catch + EC-A cap + EC-8 isolation are 3 concerns that share state (parts buffer); splitting fragments the single-pass aggregation.
+  async runPreUserSendHooks(ctx, maxRecallContextBytes) {
+    const handlers = this.#aggregated.hooks.get("pre_user_send") ?? [];
+    if (handlers.length === 0) return void 0;
+    const parts = [];
+    for (const h of handlers) {
+      try {
+        const result = await h(ctx);
+        if (result?.recalledContext && result.recalledContext.length > 0) {
+          parts.push(result.recalledContext);
+        }
+      } catch (err) {
+        process.stderr.write(
+          `[theokit-sdk] pre_user_send hook failed: ${err instanceof Error ? err.message : String(err)}
+`
+        );
+      }
+    }
+    if (parts.length === 0) return void 0;
+    let combined = parts.join("\n\n");
+    if (combined.length > maxRecallContextBytes) {
+      combined = `${combined.slice(0, maxRecallContextBytes)}
+\u2026[truncated]`;
+    }
+    return combined;
+  }
+  /**
+   * Run all `post_assistant_reply` hooks. Fire-and-forget: errors are
+   * surfaced to stderr (EC-O) so a slow/broken sync never blocks the
+   * caller's `wait()`. Returns a Promise that callers may optionally
+   * await for tests; production code typically `void`s it.
+   *
+   * @internal
+   */
+  async runPostAssistantReplyHooks(ctx) {
+    const handlers = this.#aggregated.hooks.get("post_assistant_reply") ?? [];
+    for (const h of handlers) {
+      try {
+        await h(ctx);
+      } catch (err) {
+        process.stderr.write(
+          `[theokit-sdk] post_assistant_reply hook failed: ${err instanceof Error ? err.message : String(err)}
+`
+        );
+      }
+    }
+  }
+  async #dispatchPlugin(plugin) {
+    if (plugin.kind === "general") {
+      const { ctx, registrations } = createPluginContext();
+      await plugin.register(ctx);
+      this.#merge(registrations);
+    } else if (plugin.kind === "model-provider") {
+      this.#aggregated.providerProfiles.push({
+        pluginName: plugin.name,
+        profile: plugin.profile
+      });
+    } else if (plugin.kind === "memory") {
+      this.#aggregated.memoryProviders.push({
+        pluginName: plugin.name,
+        createProvider: plugin.createProvider
+      });
+    }
+  }
+  #merge(r) {
+    this.#aggregated.tools.push(...r.tools);
+    this.#aggregated.commands.push(...r.commands);
+    for (const [hook, handlers] of r.hooks.entries()) {
+      const existing = this.#aggregated.hooks.get(hook) ?? [];
+      existing.push(...handlers);
+      this.#aggregated.hooks.set(hook, existing);
+    }
+    this.#aggregated.injected.push(...r.injected);
+  }
+};
+
+// src/internal/plugins/types.ts
+function definePlugin(p) {
+  return p;
+}
+
+exports.PluginManager = PluginManager;
+exports.createPluginContext = createPluginContext;
+exports.definePlugin = definePlugin;
+exports.runFireAndForgetHooks = runFireAndForgetHooks;
+exports.runTransformHooks = runTransformHooks;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/internal/plugins/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/internal/plugins/context.ts","../../../src/internal/plugins/lifecycle.ts","../../../src/internal/plugins/manager.ts","../../../src/internal/plugins/types.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * PluginContext implementation + dev-mode seal (T1.2, ADR D99).\n *\n * `createPluginContext()` returns a fresh `{ ctx, registrations }` pair\n * for each plugin. In dev mode (`NODE_ENV !== \"production\"`) the context\n * is wrapped in a Proxy that throws on `set`/`delete` to catch plugin\n * abuse early. In production the raw impl is returned (zero overhead).\n *\n * @internal\n */\n\nimport type { CustomTool } from \"../../types/agent.js\";\nimport type {\n  CommandHandler,\n  CommandOptions,\n  HookHandler,\n  HookName,\n  PluginContext,\n} from \"./types.js\";\n\ninterface CommandEntry {\n  name: string;\n  handler: CommandHandler;\n  description?: string;\n}\n\ninterface InjectedMessage {\n  content: string;\n  role: \"user\" | \"system\";\n}\n\nexport interface PluginRegistrations {\n  tools: CustomTool[];\n  commands: CommandEntry[];\n  hooks: Map<HookName, HookHandler[]>;\n  injected: InjectedMessage[];\n}\n\nexport function createPluginContext(): {\n  ctx: PluginContext;\n  registrations: PluginRegistrations;\n} {\n  const registrations: PluginRegistrations = {\n    tools: [],\n    commands: [],\n    hooks: new Map(),\n    injected: [],\n  };\n\n  const impl: PluginContext = {\n    registerTool(tool) {\n      registrations.tools.push(tool);\n    },\n    registerCommand(name, handler, opts: CommandOptions = {}) {\n      const entry: CommandEntry = { name, handler };\n      if (opts.description !== undefined) entry.description = opts.description;\n      registrations.commands.push(entry);\n    },\n    on(hook, handler) {\n      // EC-2 fix: defense-in-depth. Plugin author can bypass TS via `as any`\n      // and pass null/undefined; ignore + warn rather than crash the loop\n      // downstream when `runPreToolCallHooks` tries to invoke the handler.\n      if (typeof handler !== \"function\") {\n        process.stderr.write(`[theokit-sdk] ignoring non-function handler for hook \"${hook}\"\\n`);\n        return;\n      }\n      const existing = registrations.hooks.get(hook) ?? [];\n      existing.push(handler);\n      registrations.hooks.set(hook, existing);\n    },\n    injectMessage(content, role = \"user\") {\n      registrations.injected.push({ content, role });\n    },\n  };\n\n  const ctx = shouldSeal() ? sealContext(impl) : impl;\n  return { ctx, registrations };\n}\n\nfunction shouldSeal(): boolean {\n  return process.env.NODE_ENV !== \"production\";\n}\n\nfunction sealContext(impl: PluginContext): PluginContext {\n  return new Proxy(impl, {\n    set(_target, prop) {\n      throw new Error(\n        `[theokit-sdk] PluginContext is sealed — cannot set ${String(prop)}. ` +\n          `Plugins must use registerTool, registerCommand, on, or injectMessage.`,\n      );\n    },\n    deleteProperty(_target, prop) {\n      throw new Error(`[theokit-sdk] PluginContext is sealed — cannot delete ${String(prop)}.`);\n    },\n  });\n}\n","/**\n * Hook dispatch helpers (T1.4, extracted from manager to keep both modules\n * small).\n *\n *   - `runFireAndForgetHooks` — runs all handlers, swallows + logs throws,\n *     no return value (post_tool_call, on_session_start/end, etc.).\n *   - `runTransformHooks` — chains handlers, each can return a new value\n *     that replaces the input for the next handler. `undefined` keeps the\n *     current; `null` REPLACES current with null (EC-6 explicit).\n *\n * @internal\n */\n\nimport type { HookHandler } from \"./types.js\";\n\nexport async function runFireAndForgetHooks<C>(\n  handlers: ReadonlyArray<HookHandler>,\n  ctx: C,\n): Promise<void> {\n  for (const h of handlers) {\n    try {\n      await (h as (c: C) => unknown)(ctx);\n    } catch (err) {\n      const msg = err instanceof Error ? err.message : String(err);\n      process.stderr.write(`[theokit-sdk] plugin hook threw (continuing): ${msg}\\n`);\n    }\n  }\n}\n\nexport async function runTransformHooks<T>(\n  handlers: ReadonlyArray<HookHandler>,\n  initial: T,\n): Promise<T> {\n  let current = initial;\n  for (const h of handlers) {\n    try {\n      const next = await (h as (c: T) => T | undefined)(current);\n      // EC-6 explicit semantics: `undefined` = no-op; any other value\n      // (including `null`) REPLACES current.\n      if (next !== undefined) current = next;\n    } catch (err) {\n      const msg = err instanceof Error ? err.message : String(err);\n      process.stderr.write(`[theokit-sdk] plugin transform hook threw (continuing): ${msg}\\n`);\n    }\n  }\n  return current;\n}\n","/**\n * PluginManager — constructs PluginContext per plugin, invokes register()\n * once, aggregates registrations + provider profiles + memory factories\n * (T1.3, ADRs D97-D101).\n *\n * @internal\n */\n\nimport type { ProviderProfile } from \"../providers/types.js\";\nimport { createPluginContext, type PluginRegistrations } from \"./context.js\";\nimport type {\n  HookHandler,\n  MemoryProviderFactory,\n  Plugin,\n  PostAssistantReplyContext,\n  PreToolCallContext,\n  PreToolCallDecision,\n  PreUserSendContext,\n  PreUserSendResult,\n} from \"./types.js\";\n\nexport interface ProviderEntry {\n  pluginName: string;\n  profile: ProviderProfile;\n}\n\nexport interface MemoryEntry {\n  pluginName: string;\n  createProvider: MemoryProviderFactory;\n}\n\nexport interface AggregatedPlugins {\n  tools: PluginRegistrations[\"tools\"];\n  commands: PluginRegistrations[\"commands\"];\n  hooks: PluginRegistrations[\"hooks\"];\n  injected: PluginRegistrations[\"injected\"];\n  providerProfiles: ProviderEntry[];\n  memoryProviders: MemoryEntry[];\n}\n\nexport class PluginManager {\n  #aggregated: AggregatedPlugins = {\n    tools: [],\n    commands: [],\n    hooks: new Map(),\n    injected: [],\n    providerProfiles: [],\n    memoryProviders: [],\n  };\n  #initialized = false;\n\n  async initialize(plugins: ReadonlyArray<Plugin>): Promise<void> {\n    if (this.#initialized) {\n      throw new Error(\"PluginManager.initialize called twice — register only once per process\");\n    }\n    this.#initialized = true;\n    // EC-4: surface duplicate plugin names so operators notice. Two plugins\n    // with the same name are usually a mistake (npm install with override).\n    const seen = new Set<string>();\n    for (const plugin of plugins) {\n      if (seen.has(plugin.name)) {\n        process.stderr.write(\n          `[theokit-sdk] duplicate plugin name \"${plugin.name}\" — both will register independently\\n`,\n        );\n      }\n      seen.add(plugin.name);\n      await this.#dispatchPlugin(plugin);\n    }\n  }\n\n  get aggregated(): Readonly<AggregatedPlugins> {\n    return this.#aggregated;\n  }\n\n  /**\n   * Run all `pre_tool_call` hooks; first decision with `block: true` wins.\n   * D101: veto pattern — return `{ block: true, message }` makes the loop\n   * surface a tool_result with `isError: false, content: message` so the\n   * LLM can self-correct.\n   */\n  async runPreToolCallHooks(ctx: PreToolCallContext): Promise<PreToolCallDecision | undefined> {\n    const handlers = this.#aggregated.hooks.get(\"pre_tool_call\") ?? [];\n    for (const h of handlers) {\n      const decision = (await (h as (c: PreToolCallContext) => unknown)(ctx)) as\n        | PreToolCallDecision\n        | undefined;\n      if (decision !== undefined && (decision as { block?: boolean }).block === true) {\n        return decision as PreToolCallDecision;\n      }\n    }\n    return undefined;\n  }\n\n  /** Aggregated handlers for a given hook (read-only view). @internal */\n  hooksFor(name: Parameters<AggregatedPlugins[\"hooks\"][\"get\"]>[0]): ReadonlyArray<HookHandler> {\n    return this.#aggregated.hooks.get(name) ?? [];\n  }\n\n  /**\n   * Run all `pre_user_send` hooks; concatenate non-empty `recalledContext`\n   * outputs with `\\n\\n` and cap total length at `maxRecallContextBytes`\n   * (EC-A). Per-handler failures are caught + logged to stderr (EC-8) so a\n   * single broken adapter never blocks the LLM call (graceful degrade).\n   *\n   * Returns the assembled context (or undefined if empty after cap).\n   *\n   * @internal\n   */\n  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: per-handler try/catch + EC-A cap + EC-8 isolation are 3 concerns that share state (parts buffer); splitting fragments the single-pass aggregation.\n  async runPreUserSendHooks(\n    ctx: PreUserSendContext,\n    maxRecallContextBytes: number,\n  ): Promise<string | undefined> {\n    const handlers = this.#aggregated.hooks.get(\"pre_user_send\") ?? [];\n    if (handlers.length === 0) return undefined;\n    const parts: string[] = [];\n    for (const h of handlers) {\n      try {\n        const result = (await (h as (c: PreUserSendContext) => unknown)(ctx)) as\n          | PreUserSendResult\n          | undefined;\n        if (result?.recalledContext && result.recalledContext.length > 0) {\n          parts.push(result.recalledContext);\n        }\n      } catch (err) {\n        process.stderr.write(\n          `[theokit-sdk] pre_user_send hook failed: ${\n            err instanceof Error ? err.message : String(err)\n          }\\n`,\n        );\n      }\n    }\n    if (parts.length === 0) return undefined;\n    let combined = parts.join(\"\\n\\n\");\n    // EC-A: cap to prevent context-window blowout.\n    if (combined.length > maxRecallContextBytes) {\n      combined = `${combined.slice(0, maxRecallContextBytes)}\\n…[truncated]`;\n    }\n    return combined;\n  }\n\n  /**\n   * Run all `post_assistant_reply` hooks. Fire-and-forget: errors are\n   * surfaced to stderr (EC-O) so a slow/broken sync never blocks the\n   * caller's `wait()`. Returns a Promise that callers may optionally\n   * await for tests; production code typically `void`s it.\n   *\n   * @internal\n   */\n  async runPostAssistantReplyHooks(ctx: PostAssistantReplyContext): Promise<void> {\n    const handlers = this.#aggregated.hooks.get(\"post_assistant_reply\") ?? [];\n    for (const h of handlers) {\n      try {\n        await (h as (c: PostAssistantReplyContext) => unknown)(ctx);\n      } catch (err) {\n        process.stderr.write(\n          `[theokit-sdk] post_assistant_reply hook failed: ${\n            err instanceof Error ? err.message : String(err)\n          }\\n`,\n        );\n      }\n    }\n  }\n\n  async #dispatchPlugin(plugin: Plugin): Promise<void> {\n    if (plugin.kind === \"general\") {\n      const { ctx, registrations } = createPluginContext();\n      await plugin.register(ctx);\n      this.#merge(registrations);\n    } else if (plugin.kind === \"model-provider\") {\n      this.#aggregated.providerProfiles.push({\n        pluginName: plugin.name,\n        profile: plugin.profile,\n      });\n    } else if (plugin.kind === \"memory\") {\n      this.#aggregated.memoryProviders.push({\n        pluginName: plugin.name,\n        createProvider: plugin.createProvider,\n      });\n    }\n  }\n\n  #merge(r: PluginRegistrations): void {\n    this.#aggregated.tools.push(...r.tools);\n    this.#aggregated.commands.push(...r.commands);\n    for (const [hook, handlers] of r.hooks.entries()) {\n      const existing = this.#aggregated.hooks.get(hook) ?? [];\n      existing.push(...handlers);\n      this.#aggregated.hooks.set(hook, existing);\n    }\n    this.#aggregated.injected.push(...r.injected);\n  }\n}\n","/**\n * Plugin contract types (T1.1, ADRs D97-D101).\n *\n * Discriminated union by `kind`:\n *   - `\"general\"` — registers tools/hooks/commands via `register(ctx)`.\n *   - `\"model-provider\"` — declares a `ProviderProfile` consumed by router.\n *   - `\"memory\"` — supplies a memory provider factory.\n *\n * Hooks are a fixed enum (D100) to prevent sprawl; `pre_tool_call` supports\n * veto via `{ block: true, message }` (D101) so plugins can implement safety\n * guards without crashing the agent loop.\n *\n * @public\n */\n\nimport type { CustomTool } from \"../../types/agent.js\";\nimport type { MemoryAdapter } from \"../../types/memory-adapter.js\";\nimport type { ProviderProfile } from \"../providers/types.js\";\n\nexport type HookName =\n  | \"pre_tool_call\"\n  | \"post_tool_call\"\n  | \"pre_llm_call\"\n  | \"post_llm_call\"\n  | \"on_session_start\"\n  | \"on_session_end\"\n  | \"transform_tool_result\"\n  | \"transform_llm_output\"\n  // Memory adapter hooks (ADRs D141 / D145).\n  | \"pre_user_send\"\n  | \"post_assistant_reply\";\n\nexport interface PreToolCallContext {\n  name: string;\n  args: Record<string, unknown>;\n  agentId: string;\n  runId: string;\n}\n\nexport interface PreToolCallDecision {\n  block: true;\n  message: string;\n}\n\n/**\n * Context passed to `pre_user_send` hook handlers (ADR D145).\n *\n * @public\n */\nexport interface PreUserSendContext {\n  prompt: string;\n  agentId: string;\n  runId: string;\n  /** Caller-supplied memory context, flowing through from `AgentOptions.memoryContext`. */\n  memoryContext?: import(\"../../types/memory-adapter.js\").MemoryContext;\n  /** Forwarded `AbortSignal` so adapter recall HTTP can be cancelled mid-flight (EC-H). */\n  signal?: AbortSignal;\n}\n\n/**\n * Optional result returned by `pre_user_send` handlers. The agent loop\n * concatenates `recalledContext` from all handlers and injects it as a\n * `<memory-context>...</memory-context>` block before the user prompt.\n *\n * @public\n */\nexport interface PreUserSendResult {\n  recalledContext?: string;\n}\n\n/**\n * Context passed to `post_assistant_reply` hook handlers (ADR D145).\n * Fire-and-forget — exceptions are caught and surfaced to stderr; the\n * caller's `wait()` never blocks on this dispatch.\n *\n * @public\n */\nexport interface PostAssistantReplyContext {\n  prompt: string;\n  reply: string;\n  agentId: string;\n  runId: string;\n  memoryContext?: import(\"../../types/memory-adapter.js\").MemoryContext;\n}\n\nexport type HookHandler = (ctx: unknown) => unknown | Promise<unknown>;\n\nexport type CommandHandler = (args: Record<string, unknown>) => Promise<string> | string;\n\nexport interface CommandOptions {\n  description?: string;\n}\n\nexport interface PluginContext {\n  /** Register a custom tool. Equivalent to passing in `AgentOptions.tools`. */\n  registerTool(tool: CustomTool): void;\n  /** Register a slash-command-style handler. Consumed by CLI/bot wrappers; NOT used by the agent loop. */\n  registerCommand(name: string, handler: CommandHandler, opts?: CommandOptions): void;\n  /** Attach a hook handler. `pre_tool_call` supports veto via `PreToolCallDecision`. */\n  on(hook: HookName, handler: HookHandler): void;\n  /** Inject a user/system message into the next agent turn. v1 supports only `on_session_start` context. */\n  injectMessage(content: string, role?: \"user\" | \"system\"): void;\n}\n\ninterface BasePlugin {\n  name: string;\n  version: string;\n}\n\n/**\n * Memory provider factory shape (ADR D141). Returns a `MemoryAdapter`\n * (sync) or a Promise resolving to one (lazy HTTP probe / config load).\n *\n * Adapters live in `@theokit-memory-*` packages; the SDK never imports\n * them. Factory rejection is caught by the plugin manager and surfaced\n * as `ConfigurationError(code: \"plugin_factory_failed\")` (EC-F) — never\n * an unhandled rejection.\n *\n * @internal\n */\nexport type MemoryProviderFactory = (cwd: string) => MemoryAdapter | Promise<MemoryAdapter>;\n\nexport type Plugin =\n  | (BasePlugin & {\n      kind: \"general\";\n      register: (ctx: PluginContext) => void | Promise<void>;\n    })\n  | (BasePlugin & {\n      kind: \"model-provider\";\n      profile: ProviderProfile;\n    })\n  | (BasePlugin & {\n      kind: \"memory\";\n      createProvider: MemoryProviderFactory;\n    });\n\n/**\n * Identity helper for plugin authors. TS-only convenience — preserves\n * inferred type without forcing manual `Plugin` annotation.\n *\n * @public\n */\nexport function definePlugin<P extends Plugin>(p: P): P {\n  return p;\n}\n"]}

package/dist/internal/plugins/index.d.cts

@@ -0,0 +1,8 @@
+/**
+ * Barrel for the Plugin contract (ADRs D97-D101).
+ *
+ * @internal
+ */
+export { runFireAndForgetHooks, runTransformHooks } from "./lifecycle.js";
+export { type AggregatedPlugins, type MemoryEntry, PluginManager, type ProviderEntry, } from "./manager.js";
+export { type CommandHandler, type CommandOptions, definePlugin, type HookHandler, type HookName, type MemoryProviderFactory, type Plugin, type PluginContext, type PostAssistantReplyContext, type PreToolCallContext, type PreToolCallDecision, type PreUserSendContext, type PreUserSendResult, } from "./types.js";

package/dist/internal/plugins/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Barrel for the Plugin contract (ADRs D97-D101).
+ *
+ * @internal
+ */
+export { runFireAndForgetHooks, runTransformHooks } from "./lifecycle.js";
+export { type AggregatedPlugins, type MemoryEntry, PluginManager, type ProviderEntry, } from "./manager.js";
+export { type CommandHandler, type CommandOptions, definePlugin, type HookHandler, type HookName, type MemoryProviderFactory, type Plugin, type PluginContext, type PostAssistantReplyContext, type PreToolCallContext, type PreToolCallDecision, type PreUserSendContext, type PreUserSendResult, } from "./types.js";

package/dist/internal/plugins/index.js

@@ -0,0 +1,222 @@
+// src/internal/plugins/context.ts
+function createPluginContext() {
+  const registrations = {
+    tools: [],
+    commands: [],
+    hooks: /* @__PURE__ */ new Map(),
+    injected: []
+  };
+  const impl = {
+    registerTool(tool) {
+      registrations.tools.push(tool);
+    },
+    registerCommand(name, handler, opts = {}) {
+      const entry = { name, handler };
+      if (opts.description !== void 0) entry.description = opts.description;
+      registrations.commands.push(entry);
+    },
+    on(hook, handler) {
+      if (typeof handler !== "function") {
+        process.stderr.write(`[theokit-sdk] ignoring non-function handler for hook "${hook}"
+`);
+        return;
+      }
+      const existing = registrations.hooks.get(hook) ?? [];
+      existing.push(handler);
+      registrations.hooks.set(hook, existing);
+    },
+    injectMessage(content, role = "user") {
+      registrations.injected.push({ content, role });
+    }
+  };
+  const ctx = shouldSeal() ? sealContext(impl) : impl;
+  return { ctx, registrations };
+}
+function shouldSeal() {
+  return process.env.NODE_ENV !== "production";
+}
+function sealContext(impl) {
+  return new Proxy(impl, {
+    set(_target, prop) {
+      throw new Error(
+        `[theokit-sdk] PluginContext is sealed \u2014 cannot set ${String(prop)}. Plugins must use registerTool, registerCommand, on, or injectMessage.`
+      );
+    },
+    deleteProperty(_target, prop) {
+      throw new Error(`[theokit-sdk] PluginContext is sealed \u2014 cannot delete ${String(prop)}.`);
+    }
+  });
+}
+
+// src/internal/plugins/lifecycle.ts
+async function runFireAndForgetHooks(handlers, ctx) {
+  for (const h of handlers) {
+    try {
+      await h(ctx);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[theokit-sdk] plugin hook threw (continuing): ${msg}
+`);
+    }
+  }
+}
+async function runTransformHooks(handlers, initial) {
+  let current = initial;
+  for (const h of handlers) {
+    try {
+      const next = await h(current);
+      if (next !== void 0) current = next;
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`[theokit-sdk] plugin transform hook threw (continuing): ${msg}
+`);
+    }
+  }
+  return current;
+}
+
+// src/internal/plugins/manager.ts
+var PluginManager = class {
+  #aggregated = {
+    tools: [],
+    commands: [],
+    hooks: /* @__PURE__ */ new Map(),
+    injected: [],
+    providerProfiles: [],
+    memoryProviders: []
+  };
+  #initialized = false;
+  async initialize(plugins) {
+    if (this.#initialized) {
+      throw new Error("PluginManager.initialize called twice \u2014 register only once per process");
+    }
+    this.#initialized = true;
+    const seen = /* @__PURE__ */ new Set();
+    for (const plugin of plugins) {
+      if (seen.has(plugin.name)) {
+        process.stderr.write(
+          `[theokit-sdk] duplicate plugin name "${plugin.name}" \u2014 both will register independently
+`
+        );
+      }
+      seen.add(plugin.name);
+      await this.#dispatchPlugin(plugin);
+    }
+  }
+  get aggregated() {
+    return this.#aggregated;
+  }
+  /**
+   * Run all `pre_tool_call` hooks; first decision with `block: true` wins.
+   * D101: veto pattern — return `{ block: true, message }` makes the loop
+   * surface a tool_result with `isError: false, content: message` so the
+   * LLM can self-correct.
+   */
+  async runPreToolCallHooks(ctx) {
+    const handlers = this.#aggregated.hooks.get("pre_tool_call") ?? [];
+    for (const h of handlers) {
+      const decision = await h(ctx);
+      if (decision !== void 0 && decision.block === true) {
+        return decision;
+      }
+    }
+    return void 0;
+  }
+  /** Aggregated handlers for a given hook (read-only view). @internal */
+  hooksFor(name) {
+    return this.#aggregated.hooks.get(name) ?? [];
+  }
+  /**
+   * Run all `pre_user_send` hooks; concatenate non-empty `recalledContext`
+   * outputs with `\n\n` and cap total length at `maxRecallContextBytes`
+   * (EC-A). Per-handler failures are caught + logged to stderr (EC-8) so a
+   * single broken adapter never blocks the LLM call (graceful degrade).
+   *
+   * Returns the assembled context (or undefined if empty after cap).
+   *
+   * @internal
+   */
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: per-handler try/catch + EC-A cap + EC-8 isolation are 3 concerns that share state (parts buffer); splitting fragments the single-pass aggregation.
+  async runPreUserSendHooks(ctx, maxRecallContextBytes) {
+    const handlers = this.#aggregated.hooks.get("pre_user_send") ?? [];
+    if (handlers.length === 0) return void 0;
+    const parts = [];
+    for (const h of handlers) {
+      try {
+        const result = await h(ctx);
+        if (result?.recalledContext && result.recalledContext.length > 0) {
+          parts.push(result.recalledContext);
+        }
+      } catch (err) {
+        process.stderr.write(
+          `[theokit-sdk] pre_user_send hook failed: ${err instanceof Error ? err.message : String(err)}
+`
+        );
+      }
+    }
+    if (parts.length === 0) return void 0;
+    let combined = parts.join("\n\n");
+    if (combined.length > maxRecallContextBytes) {
+      combined = `${combined.slice(0, maxRecallContextBytes)}
+\u2026[truncated]`;
+    }
+    return combined;
+  }
+  /**
+   * Run all `post_assistant_reply` hooks. Fire-and-forget: errors are
+   * surfaced to stderr (EC-O) so a slow/broken sync never blocks the
+   * caller's `wait()`. Returns a Promise that callers may optionally
+   * await for tests; production code typically `void`s it.
+   *
+   * @internal
+   */
+  async runPostAssistantReplyHooks(ctx) {
+    const handlers = this.#aggregated.hooks.get("post_assistant_reply") ?? [];
+    for (const h of handlers) {
+      try {
+        await h(ctx);
+      } catch (err) {
+        process.stderr.write(
+          `[theokit-sdk] post_assistant_reply hook failed: ${err instanceof Error ? err.message : String(err)}
+`
+        );
+      }
+    }
+  }
+  async #dispatchPlugin(plugin) {
+    if (plugin.kind === "general") {
+      const { ctx, registrations } = createPluginContext();
+      await plugin.register(ctx);
+      this.#merge(registrations);
+    } else if (plugin.kind === "model-provider") {
+      this.#aggregated.providerProfiles.push({
+        pluginName: plugin.name,
+        profile: plugin.profile
+      });
+    } else if (plugin.kind === "memory") {
+      this.#aggregated.memoryProviders.push({
+        pluginName: plugin.name,
+        createProvider: plugin.createProvider
+      });
+    }
+  }
+  #merge(r) {
+    this.#aggregated.tools.push(...r.tools);
+    this.#aggregated.commands.push(...r.commands);
+    for (const [hook, handlers] of r.hooks.entries()) {
+      const existing = this.#aggregated.hooks.get(hook) ?? [];
+      existing.push(...handlers);
+      this.#aggregated.hooks.set(hook, existing);
+    }
+    this.#aggregated.injected.push(...r.injected);
+  }
+};
+
+// src/internal/plugins/types.ts
+function definePlugin(p) {
+  return p;
+}
+
+export { PluginManager, createPluginContext, definePlugin, runFireAndForgetHooks, runTransformHooks };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/internal/plugins/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/internal/plugins/context.ts","../../../src/internal/plugins/lifecycle.ts","../../../src/internal/plugins/manager.ts","../../../src/internal/plugins/types.ts"],"names":[],"mappings":";AAsCO,SAAS,mBAAA,GAGd;AACA,EAAA,MAAM,aAAA,GAAqC;AAAA,IACzC,OAAO,EAAC;AAAA,IACR,UAAU,EAAC;AAAA,IACX,KAAA,sBAAW,GAAA,EAAI;AAAA,IACf,UAAU;AAAC,GACb;AAEA,EAAA,MAAM,IAAA,GAAsB;AAAA,IAC1B,aAAa,IAAA,EAAM;AACjB,MAAA,aAAA,CAAc,KAAA,CAAM,KAAK,IAAI,CAAA;AAAA,IAC/B,CAAA;AAAA,IACA,eAAA,CAAgB,IAAA,EAAM,OAAA,EAAS,IAAA,GAAuB,EAAC,EAAG;AACxD,MAAA,MAAM,KAAA,GAAsB,EAAE,IAAA,EAAM,OAAA,EAAQ;AAC5C,MAAA,IAAI,IAAA,CAAK,WAAA,KAAgB,MAAA,EAAW,KAAA,CAAM,cAAc,IAAA,CAAK,WAAA;AAC7D,MAAA,aAAA,CAAc,QAAA,CAAS,KAAK,KAAK,CAAA;AAAA,IACnC,CAAA;AAAA,IACA,EAAA,CAAG,MAAM,OAAA,EAAS;AAIhB,MAAA,IAAI,OAAO,YAAY,UAAA,EAAY;AACjC,QAAA,OAAA,CAAQ,MAAA,CAAO,KAAA,CAAM,CAAA,sDAAA,EAAyD,IAAI,CAAA;AAAA,CAAK,CAAA;AACvF,QAAA;AAAA,MACF;AACA,MAAA,MAAM,WAAW,aAAA,CAAc,KAAA,CAAM,GAAA,CAAI,IAAI,KAAK,EAAC;AACnD,MAAA,QAAA,CAAS,KAAK,OAAO,CAAA;AACrB,MAAA,aAAA,CAAc,KAAA,CAAM,GAAA,CAAI,IAAA,EAAM,QAAQ,CAAA;AAAA,IACxC,CAAA;AAAA,IACA,aAAA,CAAc,OAAA,EAAS,IAAA,GAAO,MAAA,EAAQ;AACpC,MAAA,aAAA,CAAc,QAAA,CAAS,IAAA,CAAK,EAAE,OAAA,EAAS,MAAM,CAAA;AAAA,IAC/C;AAAA,GACF;AAEA,EAAA,MAAM,GAAA,GAAM,UAAA,EAAW,GAAI,WAAA,CAAY,IAAI,CAAA,GAAI,IAAA;AAC/C,EAAA,OAAO,EAAE,KAAK,aAAA,EAAc;AAC9B;AAEA,SAAS,UAAA,GAAsB;AAC7B,EAAA,OAAO,OAAA,CAAQ,IAAI,QAAA,KAAa,YAAA;AAClC;AAEA,SAAS,YAAY,IAAA,EAAoC;AACvD,EAAA,OAAO,IAAI,MAAM,IAAA,EAAM;AAAA,IACrB,GAAA,CAAI,SAAS,IAAA,EAAM;AACjB,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,CAAA,wDAAA,EAAsD,MAAA,CAAO,IAAI,CAAC,CAAA,uEAAA;AAAA,OAEpE;AAAA,IACF,CAAA;AAAA,IACA,cAAA,CAAe,SAAS,IAAA,EAAM;AAC5B,MAAA,MAAM,IAAI,KAAA,CAAM,CAAA,2DAAA,EAAyD,MAAA,CAAO,IAAI,CAAC,CAAA,CAAA,CAAG,CAAA;AAAA,IAC1F;AAAA,GACD,CAAA;AACH;;;AChFA,eAAsB,qBAAA,CACpB,UACA,GAAA,EACe;AACf,EAAA,KAAA,MAAW,KAAK,QAAA,EAAU;AACxB,IAAA,IAAI;AACF,MAAA,MAAO,EAAwB,GAAG,CAAA;AAAA,IACpC,SAAS,GAAA,EAAK;AACZ,MAAA,MAAM,MAAM,GAAA,YAAe,KAAA,GAAQ,GAAA,CAAI,OAAA,GAAU,OAAO,GAAG,CAAA;AAC3D,MAAA,OAAA,CAAQ,MAAA,CAAO,KAAA,CAAM,CAAA,8CAAA,EAAiD,GAAG;AAAA,CAAI,CAAA;AAAA,IAC/E;AAAA,EACF;AACF;AAEA,eAAsB,iBAAA,CACpB,UACA,OAAA,EACY;AACZ,EAAA,IAAI,OAAA,GAAU,OAAA;AACd,EAAA,KAAA,MAAW,KAAK,QAAA,EAAU;AACxB,IAAA,IAAI;AACF,MAAA,MAAM,IAAA,GAAO,MAAO,CAAA,CAA8B,OAAO,CAAA;AAGzD,MAAA,IAAI,IAAA,KAAS,QAAW,OAAA,GAAU,IAAA;AAAA,IACpC,SAAS,GAAA,EAAK;AACZ,MAAA,MAAM,MAAM,GAAA,YAAe,KAAA,GAAQ,GAAA,CAAI,OAAA,GAAU,OAAO,GAAG,CAAA;AAC3D,MAAA,OAAA,CAAQ,MAAA,CAAO,KAAA,CAAM,CAAA,wDAAA,EAA2D,GAAG;AAAA,CAAI,CAAA;AAAA,IACzF;AAAA,EACF;AACA,EAAA,OAAO,OAAA;AACT;;;ACNO,IAAM,gBAAN,MAAoB;AAAA,EACzB,WAAA,GAAiC;AAAA,IAC/B,OAAO,EAAC;AAAA,IACR,UAAU,EAAC;AAAA,IACX,KAAA,sBAAW,GAAA,EAAI;AAAA,IACf,UAAU,EAAC;AAAA,IACX,kBAAkB,EAAC;AAAA,IACnB,iBAAiB;AAAC,GACpB;AAAA,EACA,YAAA,GAAe,KAAA;AAAA,EAEf,MAAM,WAAW,OAAA,EAA+C;AAC9D,IAAA,IAAI,KAAK,YAAA,EAAc;AACrB,MAAA,MAAM,IAAI,MAAM,6EAAwE,CAAA;AAAA,IAC1F;AACA,IAAA,IAAA,CAAK,YAAA,GAAe,IAAA;AAGpB,IAAA,MAAM,IAAA,uBAAW,GAAA,EAAY;AAC7B,IAAA,KAAA,MAAW,UAAU,OAAA,EAAS;AAC5B,MAAA,IAAI,IAAA,CAAK,GAAA,CAAI,MAAA,CAAO,IAAI,CAAA,EAAG;AACzB,QAAA,OAAA,CAAQ,MAAA,CAAO,KAAA;AAAA,UACb,CAAA,qCAAA,EAAwC,OAAO,IAAI,CAAA;AAAA;AAAA,SACrD;AAAA,MACF;AACA,MAAA,IAAA,CAAK,GAAA,CAAI,OAAO,IAAI,CAAA;AACpB,MAAA,MAAM,IAAA,CAAK,gBAAgB,MAAM,CAAA;AAAA,IACnC;AAAA,EACF;AAAA,EAEA,IAAI,UAAA,GAA0C;AAC5C,IAAA,OAAO,IAAA,CAAK,WAAA;AAAA,EACd;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,oBAAoB,GAAA,EAAmE;AAC3F,IAAA,MAAM,WAAW,IAAA,CAAK,WAAA,CAAY,MAAM,GAAA,CAAI,eAAe,KAAK,EAAC;AACjE,IAAA,KAAA,MAAW,KAAK,QAAA,EAAU;AACxB,MAAA,MAAM,QAAA,GAAY,MAAO,CAAA,CAAyC,GAAG,CAAA;AAGrE,MAAA,IAAI,QAAA,KAAa,MAAA,IAAc,QAAA,CAAiC,KAAA,KAAU,IAAA,EAAM;AAC9E,QAAA,OAAO,QAAA;AAAA,MACT;AAAA,IACF;AACA,IAAA,OAAO,MAAA;AAAA,EACT;AAAA;AAAA,EAGA,SAAS,IAAA,EAAoF;AAC3F,IAAA,OAAO,KAAK,WAAA,CAAY,KAAA,CAAM,GAAA,CAAI,IAAI,KAAK,EAAC;AAAA,EAC9C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaA,MAAM,mBAAA,CACJ,GAAA,EACA,qBAAA,EAC6B;AAC7B,IAAA,MAAM,WAAW,IAAA,CAAK,WAAA,CAAY,MAAM,GAAA,CAAI,eAAe,KAAK,EAAC;AACjE,IAAA,IAAI,QAAA,CAAS,MAAA,KAAW,CAAA,EAAG,OAAO,MAAA;AAClC,IAAA,MAAM,QAAkB,EAAC;AACzB,IAAA,KAAA,MAAW,KAAK,QAAA,EAAU;AACxB,MAAA,IAAI;AACF,QAAA,MAAM,MAAA,GAAU,MAAO,CAAA,CAAyC,GAAG,CAAA;AAGnE,QAAA,IAAI,MAAA,EAAQ,eAAA,IAAmB,MAAA,CAAO,eAAA,CAAgB,SAAS,CAAA,EAAG;AAChE,UAAA,KAAA,CAAM,IAAA,CAAK,OAAO,eAAe,CAAA;AAAA,QACnC;AAAA,MACF,SAAS,GAAA,EAAK;AACZ,QAAA,OAAA,CAAQ,MAAA,CAAO,KAAA;AAAA,UACb,4CACE,GAAA,YAAe,KAAA,GAAQ,IAAI,OAAA,GAAU,MAAA,CAAO,GAAG,CACjD;AAAA;AAAA,SACF;AAAA,MACF;AAAA,IACF;AACA,IAAA,IAAI,KAAA,CAAM,MAAA,KAAW,CAAA,EAAG,OAAO,MAAA;AAC/B,IAAA,IAAI,QAAA,GAAW,KAAA,CAAM,IAAA,CAAK,MAAM,CAAA;AAEhC,IAAA,IAAI,QAAA,CAAS,SAAS,qBAAA,EAAuB;AAC3C,MAAA,QAAA,GAAW,CAAA,EAAG,QAAA,CAAS,KAAA,CAAM,CAAA,EAAG,qBAAqB,CAAC;AAAA,iBAAA,CAAA;AAAA,IACxD;AACA,IAAA,OAAO,QAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAM,2BAA2B,GAAA,EAA+C;AAC9E,IAAA,MAAM,WAAW,IAAA,CAAK,WAAA,CAAY,MAAM,GAAA,CAAI,sBAAsB,KAAK,EAAC;AACxE,IAAA,KAAA,MAAW,KAAK,QAAA,EAAU;AACxB,MAAA,IAAI;AACF,QAAA,MAAO,EAAgD,GAAG,CAAA;AAAA,MAC5D,SAAS,GAAA,EAAK;AACZ,QAAA,OAAA,CAAQ,MAAA,CAAO,KAAA;AAAA,UACb,mDACE,GAAA,YAAe,KAAA,GAAQ,IAAI,OAAA,GAAU,MAAA,CAAO,GAAG,CACjD;AAAA;AAAA,SACF;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAM,gBAAgB,MAAA,EAA+B;AACnD,IAAA,IAAI,MAAA,CAAO,SAAS,SAAA,EAAW;AAC7B,MAAA,MAAM,EAAE,GAAA,EAAK,aAAA,EAAc,GAAI,mBAAA,EAAoB;AACnD,MAAA,MAAM,MAAA,CAAO,SAAS,GAAG,CAAA;AACzB,MAAA,IAAA,CAAK,OAAO,aAAa,CAAA;AAAA,IAC3B,CAAA,MAAA,IAAW,MAAA,CAAO,IAAA,KAAS,gBAAA,EAAkB;AAC3C,MAAA,IAAA,CAAK,WAAA,CAAY,iBAAiB,IAAA,CAAK;AAAA,QACrC,YAAY,MAAA,CAAO,IAAA;AAAA,QACnB,SAAS,MAAA,CAAO;AAAA,OACjB,CAAA;AAAA,IACH,CAAA,MAAA,IAAW,MAAA,CAAO,IAAA,KAAS,QAAA,EAAU;AACnC,MAAA,IAAA,CAAK,WAAA,CAAY,gBAAgB,IAAA,CAAK;AAAA,QACpC,YAAY,MAAA,CAAO,IAAA;AAAA,QACnB,gBAAgB,MAAA,CAAO;AAAA,OACxB,CAAA;AAAA,IACH;AAAA,EACF;AAAA,EAEA,OAAO,CAAA,EAA8B;AACnC,IAAA,IAAA,CAAK,WAAA,CAAY,KAAA,CAAM,IAAA,CAAK,GAAG,EAAE,KAAK,CAAA;AACtC,IAAA,IAAA,CAAK,WAAA,CAAY,QAAA,CAAS,IAAA,CAAK,GAAG,EAAE,QAAQ,CAAA;AAC5C,IAAA,KAAA,MAAW,CAAC,IAAA,EAAM,QAAQ,KAAK,CAAA,CAAE,KAAA,CAAM,SAAQ,EAAG;AAChD,MAAA,MAAM,WAAW,IAAA,CAAK,WAAA,CAAY,MAAM,GAAA,CAAI,IAAI,KAAK,EAAC;AACtD,MAAA,QAAA,CAAS,IAAA,CAAK,GAAG,QAAQ,CAAA;AACzB,MAAA,IAAA,CAAK,WAAA,CAAY,KAAA,CAAM,GAAA,CAAI,IAAA,EAAM,QAAQ,CAAA;AAAA,IAC3C;AACA,IAAA,IAAA,CAAK,WAAA,CAAY,QAAA,CAAS,IAAA,CAAK,GAAG,EAAE,QAAQ,CAAA;AAAA,EAC9C;AACF;;;AClDO,SAAS,aAA+B,CAAA,EAAS;AACtD,EAAA,OAAO,CAAA;AACT","file":"index.js","sourcesContent":["/**\n * PluginContext implementation + dev-mode seal (T1.2, ADR D99).\n *\n * `createPluginContext()` returns a fresh `{ ctx, registrations }` pair\n * for each plugin. In dev mode (`NODE_ENV !== \"production\"`) the context\n * is wrapped in a Proxy that throws on `set`/`delete` to catch plugin\n * abuse early. In production the raw impl is returned (zero overhead).\n *\n * @internal\n */\n\nimport type { CustomTool } from \"../../types/agent.js\";\nimport type {\n  CommandHandler,\n  CommandOptions,\n  HookHandler,\n  HookName,\n  PluginContext,\n} from \"./types.js\";\n\ninterface CommandEntry {\n  name: string;\n  handler: CommandHandler;\n  description?: string;\n}\n\ninterface InjectedMessage {\n  content: string;\n  role: \"user\" | \"system\";\n}\n\nexport interface PluginRegistrations {\n  tools: CustomTool[];\n  commands: CommandEntry[];\n  hooks: Map<HookName, HookHandler[]>;\n  injected: InjectedMessage[];\n}\n\nexport function createPluginContext(): {\n  ctx: PluginContext;\n  registrations: PluginRegistrations;\n} {\n  const registrations: PluginRegistrations = {\n    tools: [],\n    commands: [],\n    hooks: new Map(),\n    injected: [],\n  };\n\n  const impl: PluginContext = {\n    registerTool(tool) {\n      registrations.tools.push(tool);\n    },\n    registerCommand(name, handler, opts: CommandOptions = {}) {\n      const entry: CommandEntry = { name, handler };\n      if (opts.description !== undefined) entry.description = opts.description;\n      registrations.commands.push(entry);\n    },\n    on(hook, handler) {\n      // EC-2 fix: defense-in-depth. Plugin author can bypass TS via `as any`\n      // and pass null/undefined; ignore + warn rather than crash the loop\n      // downstream when `runPreToolCallHooks` tries to invoke the handler.\n      if (typeof handler !== \"function\") {\n        process.stderr.write(`[theokit-sdk] ignoring non-function handler for hook \"${hook}\"\\n`);\n        return;\n      }\n      const existing = registrations.hooks.get(hook) ?? [];\n      existing.push(handler);\n      registrations.hooks.set(hook, existing);\n    },\n    injectMessage(content, role = \"user\") {\n      registrations.injected.push({ content, role });\n    },\n  };\n\n  const ctx = shouldSeal() ? sealContext(impl) : impl;\n  return { ctx, registrations };\n}\n\nfunction shouldSeal(): boolean {\n  return process.env.NODE_ENV !== \"production\";\n}\n\nfunction sealContext(impl: PluginContext): PluginContext {\n  return new Proxy(impl, {\n    set(_target, prop) {\n      throw new Error(\n        `[theokit-sdk] PluginContext is sealed — cannot set ${String(prop)}. ` +\n          `Plugins must use registerTool, registerCommand, on, or injectMessage.`,\n      );\n    },\n    deleteProperty(_target, prop) {\n      throw new Error(`[theokit-sdk] PluginContext is sealed — cannot delete ${String(prop)}.`);\n    },\n  });\n}\n","/**\n * Hook dispatch helpers (T1.4, extracted from manager to keep both modules\n * small).\n *\n *   - `runFireAndForgetHooks` — runs all handlers, swallows + logs throws,\n *     no return value (post_tool_call, on_session_start/end, etc.).\n *   - `runTransformHooks` — chains handlers, each can return a new value\n *     that replaces the input for the next handler. `undefined` keeps the\n *     current; `null` REPLACES current with null (EC-6 explicit).\n *\n * @internal\n */\n\nimport type { HookHandler } from \"./types.js\";\n\nexport async function runFireAndForgetHooks<C>(\n  handlers: ReadonlyArray<HookHandler>,\n  ctx: C,\n): Promise<void> {\n  for (const h of handlers) {\n    try {\n      await (h as (c: C) => unknown)(ctx);\n    } catch (err) {\n      const msg = err instanceof Error ? err.message : String(err);\n      process.stderr.write(`[theokit-sdk] plugin hook threw (continuing): ${msg}\\n`);\n    }\n  }\n}\n\nexport async function runTransformHooks<T>(\n  handlers: ReadonlyArray<HookHandler>,\n  initial: T,\n): Promise<T> {\n  let current = initial;\n  for (const h of handlers) {\n    try {\n      const next = await (h as (c: T) => T | undefined)(current);\n      // EC-6 explicit semantics: `undefined` = no-op; any other value\n      // (including `null`) REPLACES current.\n      if (next !== undefined) current = next;\n    } catch (err) {\n      const msg = err instanceof Error ? err.message : String(err);\n      process.stderr.write(`[theokit-sdk] plugin transform hook threw (continuing): ${msg}\\n`);\n    }\n  }\n  return current;\n}\n","/**\n * PluginManager — constructs PluginContext per plugin, invokes register()\n * once, aggregates registrations + provider profiles + memory factories\n * (T1.3, ADRs D97-D101).\n *\n * @internal\n */\n\nimport type { ProviderProfile } from \"../providers/types.js\";\nimport { createPluginContext, type PluginRegistrations } from \"./context.js\";\nimport type {\n  HookHandler,\n  MemoryProviderFactory,\n  Plugin,\n  PostAssistantReplyContext,\n  PreToolCallContext,\n  PreToolCallDecision,\n  PreUserSendContext,\n  PreUserSendResult,\n} from \"./types.js\";\n\nexport interface ProviderEntry {\n  pluginName: string;\n  profile: ProviderProfile;\n}\n\nexport interface MemoryEntry {\n  pluginName: string;\n  createProvider: MemoryProviderFactory;\n}\n\nexport interface AggregatedPlugins {\n  tools: PluginRegistrations[\"tools\"];\n  commands: PluginRegistrations[\"commands\"];\n  hooks: PluginRegistrations[\"hooks\"];\n  injected: PluginRegistrations[\"injected\"];\n  providerProfiles: ProviderEntry[];\n  memoryProviders: MemoryEntry[];\n}\n\nexport class PluginManager {\n  #aggregated: AggregatedPlugins = {\n    tools: [],\n    commands: [],\n    hooks: new Map(),\n    injected: [],\n    providerProfiles: [],\n    memoryProviders: [],\n  };\n  #initialized = false;\n\n  async initialize(plugins: ReadonlyArray<Plugin>): Promise<void> {\n    if (this.#initialized) {\n      throw new Error(\"PluginManager.initialize called twice — register only once per process\");\n    }\n    this.#initialized = true;\n    // EC-4: surface duplicate plugin names so operators notice. Two plugins\n    // with the same name are usually a mistake (npm install with override).\n    const seen = new Set<string>();\n    for (const plugin of plugins) {\n      if (seen.has(plugin.name)) {\n        process.stderr.write(\n          `[theokit-sdk] duplicate plugin name \"${plugin.name}\" — both will register independently\\n`,\n        );\n      }\n      seen.add(plugin.name);\n      await this.#dispatchPlugin(plugin);\n    }\n  }\n\n  get aggregated(): Readonly<AggregatedPlugins> {\n    return this.#aggregated;\n  }\n\n  /**\n   * Run all `pre_tool_call` hooks; first decision with `block: true` wins.\n   * D101: veto pattern — return `{ block: true, message }` makes the loop\n   * surface a tool_result with `isError: false, content: message` so the\n   * LLM can self-correct.\n   */\n  async runPreToolCallHooks(ctx: PreToolCallContext): Promise<PreToolCallDecision | undefined> {\n    const handlers = this.#aggregated.hooks.get(\"pre_tool_call\") ?? [];\n    for (const h of handlers) {\n      const decision = (await (h as (c: PreToolCallContext) => unknown)(ctx)) as\n        | PreToolCallDecision\n        | undefined;\n      if (decision !== undefined && (decision as { block?: boolean }).block === true) {\n        return decision as PreToolCallDecision;\n      }\n    }\n    return undefined;\n  }\n\n  /** Aggregated handlers for a given hook (read-only view). @internal */\n  hooksFor(name: Parameters<AggregatedPlugins[\"hooks\"][\"get\"]>[0]): ReadonlyArray<HookHandler> {\n    return this.#aggregated.hooks.get(name) ?? [];\n  }\n\n  /**\n   * Run all `pre_user_send` hooks; concatenate non-empty `recalledContext`\n   * outputs with `\\n\\n` and cap total length at `maxRecallContextBytes`\n   * (EC-A). Per-handler failures are caught + logged to stderr (EC-8) so a\n   * single broken adapter never blocks the LLM call (graceful degrade).\n   *\n   * Returns the assembled context (or undefined if empty after cap).\n   *\n   * @internal\n   */\n  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: per-handler try/catch + EC-A cap + EC-8 isolation are 3 concerns that share state (parts buffer); splitting fragments the single-pass aggregation.\n  async runPreUserSendHooks(\n    ctx: PreUserSendContext,\n    maxRecallContextBytes: number,\n  ): Promise<string | undefined> {\n    const handlers = this.#aggregated.hooks.get(\"pre_user_send\") ?? [];\n    if (handlers.length === 0) return undefined;\n    const parts: string[] = [];\n    for (const h of handlers) {\n      try {\n        const result = (await (h as (c: PreUserSendContext) => unknown)(ctx)) as\n          | PreUserSendResult\n          | undefined;\n        if (result?.recalledContext && result.recalledContext.length > 0) {\n          parts.push(result.recalledContext);\n        }\n      } catch (err) {\n        process.stderr.write(\n          `[theokit-sdk] pre_user_send hook failed: ${\n            err instanceof Error ? err.message : String(err)\n          }\\n`,\n        );\n      }\n    }\n    if (parts.length === 0) return undefined;\n    let combined = parts.join(\"\\n\\n\");\n    // EC-A: cap to prevent context-window blowout.\n    if (combined.length > maxRecallContextBytes) {\n      combined = `${combined.slice(0, maxRecallContextBytes)}\\n…[truncated]`;\n    }\n    return combined;\n  }\n\n  /**\n   * Run all `post_assistant_reply` hooks. Fire-and-forget: errors are\n   * surfaced to stderr (EC-O) so a slow/broken sync never blocks the\n   * caller's `wait()`. Returns a Promise that callers may optionally\n   * await for tests; production code typically `void`s it.\n   *\n   * @internal\n   */\n  async runPostAssistantReplyHooks(ctx: PostAssistantReplyContext): Promise<void> {\n    const handlers = this.#aggregated.hooks.get(\"post_assistant_reply\") ?? [];\n    for (const h of handlers) {\n      try {\n        await (h as (c: PostAssistantReplyContext) => unknown)(ctx);\n      } catch (err) {\n        process.stderr.write(\n          `[theokit-sdk] post_assistant_reply hook failed: ${\n            err instanceof Error ? err.message : String(err)\n          }\\n`,\n        );\n      }\n    }\n  }\n\n  async #dispatchPlugin(plugin: Plugin): Promise<void> {\n    if (plugin.kind === \"general\") {\n      const { ctx, registrations } = createPluginContext();\n      await plugin.register(ctx);\n      this.#merge(registrations);\n    } else if (plugin.kind === \"model-provider\") {\n      this.#aggregated.providerProfiles.push({\n        pluginName: plugin.name,\n        profile: plugin.profile,\n      });\n    } else if (plugin.kind === \"memory\") {\n      this.#aggregated.memoryProviders.push({\n        pluginName: plugin.name,\n        createProvider: plugin.createProvider,\n      });\n    }\n  }\n\n  #merge(r: PluginRegistrations): void {\n    this.#aggregated.tools.push(...r.tools);\n    this.#aggregated.commands.push(...r.commands);\n    for (const [hook, handlers] of r.hooks.entries()) {\n      const existing = this.#aggregated.hooks.get(hook) ?? [];\n      existing.push(...handlers);\n      this.#aggregated.hooks.set(hook, existing);\n    }\n    this.#aggregated.injected.push(...r.injected);\n  }\n}\n","/**\n * Plugin contract types (T1.1, ADRs D97-D101).\n *\n * Discriminated union by `kind`:\n *   - `\"general\"` — registers tools/hooks/commands via `register(ctx)`.\n *   - `\"model-provider\"` — declares a `ProviderProfile` consumed by router.\n *   - `\"memory\"` — supplies a memory provider factory.\n *\n * Hooks are a fixed enum (D100) to prevent sprawl; `pre_tool_call` supports\n * veto via `{ block: true, message }` (D101) so plugins can implement safety\n * guards without crashing the agent loop.\n *\n * @public\n */\n\nimport type { CustomTool } from \"../../types/agent.js\";\nimport type { MemoryAdapter } from \"../../types/memory-adapter.js\";\nimport type { ProviderProfile } from \"../providers/types.js\";\n\nexport type HookName =\n  | \"pre_tool_call\"\n  | \"post_tool_call\"\n  | \"pre_llm_call\"\n  | \"post_llm_call\"\n  | \"on_session_start\"\n  | \"on_session_end\"\n  | \"transform_tool_result\"\n  | \"transform_llm_output\"\n  // Memory adapter hooks (ADRs D141 / D145).\n  | \"pre_user_send\"\n  | \"post_assistant_reply\";\n\nexport interface PreToolCallContext {\n  name: string;\n  args: Record<string, unknown>;\n  agentId: string;\n  runId: string;\n}\n\nexport interface PreToolCallDecision {\n  block: true;\n  message: string;\n}\n\n/**\n * Context passed to `pre_user_send` hook handlers (ADR D145).\n *\n * @public\n */\nexport interface PreUserSendContext {\n  prompt: string;\n  agentId: string;\n  runId: string;\n  /** Caller-supplied memory context, flowing through from `AgentOptions.memoryContext`. */\n  memoryContext?: import(\"../../types/memory-adapter.js\").MemoryContext;\n  /** Forwarded `AbortSignal` so adapter recall HTTP can be cancelled mid-flight (EC-H). */\n  signal?: AbortSignal;\n}\n\n/**\n * Optional result returned by `pre_user_send` handlers. The agent loop\n * concatenates `recalledContext` from all handlers and injects it as a\n * `<memory-context>...</memory-context>` block before the user prompt.\n *\n * @public\n */\nexport interface PreUserSendResult {\n  recalledContext?: string;\n}\n\n/**\n * Context passed to `post_assistant_reply` hook handlers (ADR D145).\n * Fire-and-forget — exceptions are caught and surfaced to stderr; the\n * caller's `wait()` never blocks on this dispatch.\n *\n * @public\n */\nexport interface PostAssistantReplyContext {\n  prompt: string;\n  reply: string;\n  agentId: string;\n  runId: string;\n  memoryContext?: import(\"../../types/memory-adapter.js\").MemoryContext;\n}\n\nexport type HookHandler = (ctx: unknown) => unknown | Promise<unknown>;\n\nexport type CommandHandler = (args: Record<string, unknown>) => Promise<string> | string;\n\nexport interface CommandOptions {\n  description?: string;\n}\n\nexport interface PluginContext {\n  /** Register a custom tool. Equivalent to passing in `AgentOptions.tools`. */\n  registerTool(tool: CustomTool): void;\n  /** Register a slash-command-style handler. Consumed by CLI/bot wrappers; NOT used by the agent loop. */\n  registerCommand(name: string, handler: CommandHandler, opts?: CommandOptions): void;\n  /** Attach a hook handler. `pre_tool_call` supports veto via `PreToolCallDecision`. */\n  on(hook: HookName, handler: HookHandler): void;\n  /** Inject a user/system message into the next agent turn. v1 supports only `on_session_start` context. */\n  injectMessage(content: string, role?: \"user\" | \"system\"): void;\n}\n\ninterface BasePlugin {\n  name: string;\n  version: string;\n}\n\n/**\n * Memory provider factory shape (ADR D141). Returns a `MemoryAdapter`\n * (sync) or a Promise resolving to one (lazy HTTP probe / config load).\n *\n * Adapters live in `@theokit-memory-*` packages; the SDK never imports\n * them. Factory rejection is caught by the plugin manager and surfaced\n * as `ConfigurationError(code: \"plugin_factory_failed\")` (EC-F) — never\n * an unhandled rejection.\n *\n * @internal\n */\nexport type MemoryProviderFactory = (cwd: string) => MemoryAdapter | Promise<MemoryAdapter>;\n\nexport type Plugin =\n  | (BasePlugin & {\n      kind: \"general\";\n      register: (ctx: PluginContext) => void | Promise<void>;\n    })\n  | (BasePlugin & {\n      kind: \"model-provider\";\n      profile: ProviderProfile;\n    })\n  | (BasePlugin & {\n      kind: \"memory\";\n      createProvider: MemoryProviderFactory;\n    });\n\n/**\n * Identity helper for plugin authors. TS-only convenience — preserves\n * inferred type without forcing manual `Plugin` annotation.\n *\n * @public\n */\nexport function definePlugin<P extends Plugin>(p: P): P {\n  return p;\n}\n"]}

package/dist/internal/plugins/lifecycle.d.cts

@@ -0,0 +1,14 @@
+/**
+ * Hook dispatch helpers (T1.4, extracted from manager to keep both modules
+ * small).
+ *
+ *   - `runFireAndForgetHooks` — runs all handlers, swallows + logs throws,
+ *     no return value (post_tool_call, on_session_start/end, etc.).
+ *   - `runTransformHooks` — chains handlers, each can return a new value
+ *     that replaces the input for the next handler. `undefined` keeps the
+ *     current; `null` REPLACES current with null (EC-6 explicit).
+ *
+ * @internal
+ */
+export declare function runFireAndForgetHooks<C>(handlers: ReadonlyArray<HookHandler>, ctx: C): Promise<void>;
+export declare function runTransformHooks<T>(handlers: ReadonlyArray<HookHandler>, initial: T): Promise<T>;

package/dist/internal/plugins/lifecycle.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Hook dispatch helpers (T1.4, extracted from manager to keep both modules
+ * small).
+ *
+ *   - `runFireAndForgetHooks` — runs all handlers, swallows + logs throws,
+ *     no return value (post_tool_call, on_session_start/end, etc.).
+ *   - `runTransformHooks` — chains handlers, each can return a new value
+ *     that replaces the input for the next handler. `undefined` keeps the
+ *     current; `null` REPLACES current with null (EC-6 explicit).
+ *
+ * @internal
+ */
+export declare function runFireAndForgetHooks<C>(handlers: ReadonlyArray<HookHandler>, ctx: C): Promise<void>;
+export declare function runTransformHooks<T>(handlers: ReadonlyArray<HookHandler>, initial: T): Promise<T>;

package/dist/internal/plugins/manager.d.cts

@@ -0,0 +1,37 @@
+/**
+ * PluginManager — constructs PluginContext per plugin, invokes register()
+ * once, aggregates registrations + provider profiles + memory factories
+ * (T1.3, ADRs D97-D101).
+ *
+ * @internal
+ */
+import { type PluginRegistrations } from "./context.js";
+import type { MemoryProviderFactory, Plugin, PreToolCallContext, PreToolCallDecision } from "./types.js";
+export interface ProviderEntry {
+    pluginName: string;
+    profile: ProviderProfile;
+}
+export interface MemoryEntry {
+    pluginName: string;
+    createProvider: MemoryProviderFactory;
+}
+export interface AggregatedPlugins {
+    tools: PluginRegistrations["tools"];
+    commands: PluginRegistrations["commands"];
+    hooks: PluginRegistrations["hooks"];
+    injected: PluginRegistrations["injected"];
+    providerProfiles: ProviderEntry[];
+    memoryProviders: MemoryEntry[];
+}
+export declare class PluginManager {
+    #private;
+    initialize(plugins: ReadonlyArray<Plugin>): Promise<void>;
+    get aggregated(): Readonly<AggregatedPlugins>;
+    /**
+     * Run all `pre_tool_call` hooks; first decision with `block: true` wins.
+     * D101: veto pattern — return `{ block: true, message }` makes the loop
+     * surface a tool_result with `isError: false, content: message` so the
+     * LLM can self-correct.
+     */
+    runPreToolCallHooks(ctx: PreToolCallContext): Promise<PreToolCallDecision | undefined>;
+}