@theokit/agents 0.44.1 → 0.44.3

package/dist/{bridge-entry-BW1ifbWg.d.ts → bridge-entry-BtFJdaCe.d.ts}

@@ -196,6 +196,8 @@ interface CompiledAgentOptions {
      * (merged with `cwd`, decoupled from inline skills). Absent ⇒ inline (code) config only.
      */
     settingSources?: readonly SettingSource[];
+    /** Code `Plugin` objects forwarded to `Agent.create({ plugins })` (lifecycle-hook seam). */
+    plugins?: readonly unknown[];
     tools: CompiledTool[];
     agents: Record<string, CompiledSubAgent>;
     memory?: MemoryOptions;
@@ -585,6 +587,17 @@ interface DefineAgentConfig<TInput extends z.ZodType = z.ZodType> {
      * + execution (G2 / ADR-0040); theokit only wires this into `Agent.create({ local.settingSources })`.
      */
     settingSources?: readonly SettingSource[];
+    /**
+     * Code `Plugin` objects forwarded to `Agent.create({ plugins })` — EXTENSION units (tools,
+     * commands, model providers, memory adapters). For lifecycle interception use {@link hooks}.
+     */
+    plugins?: readonly unknown[];
+    /**
+     * Lifecycle hooks keyed by `HookName` (`pre_tool_call` may veto via `{ block, message }`). Set by
+     * the builder's `hooks()`; converted into a code plugin at `build()` and never reaching the SDK
+     * under this name — the plugin is the TRANSPORT, this is the contract callers write against.
+     */
+    hooks?: Readonly<Record<string, unknown>>;
     /**
      * MCP servers available to the agent — the builder-chain equivalent of the `@MCP` class
      * decorator. Each key is a server name; the value is the server configuration. Forwarded
@@ -927,6 +940,34 @@ interface AgentBuilder<TInput extends z.ZodType | UnsetMarker = UnsetMarker, TMo
      * shell-executing hooks from `.theokit/hooks.json` — opt-in because `.theokit/` is your own repo.
      */
     settingSources(sources: readonly SettingSource[]): AgentBuilder<TInput, TModel, TContext, TTools>;
+    /**
+     * Attach LIFECYCLE HOOKS in code, keyed by `HookName` — the builder-chain seam for intercepting
+     * the agent loop. `pre_tool_call` may VETO a tool by returning `{ block: true, message }` before
+     * it runs; the other events are observational.
+     *
+     * ```ts
+     * agent().hooks({
+     *   pre_tool_call: (c) => guard(c.name) ? undefined : { block: true, message: 'not allowed' },
+     *   on_session_start: () => log('session up'),
+     * })
+     * ```
+     *
+     * A hook is delivered internally as a code plugin, but that is TRANSPORT, not the contract — use
+     * this instead of hand-wrapping a plugin, so the caller expresses interception rather than
+     * assembling plumbing. Call once — a later call replaces the map. Composes with
+     * {@link AgentBuilder.plugins}: hooks and plugins are additive, not exclusive.
+     */
+    hooks(map: Readonly<Record<string, unknown>>): AgentBuilder<TInput, TModel, TContext, TTools>;
+    /**
+     * Register code `Plugin` objects for this agent — the builder-chain equivalent of
+     * `Agent.create({ plugins })`. A plugin is an EXTENSION UNIT: it can register tools and commands,
+     * or supply a model provider / memory adapter (`kind: 'general' | 'model-provider' | 'memory'`).
+     *
+     * For lifecycle interception prefer {@link AgentBuilder.hooks} — a hook needs a plugin only as its
+     * transport, and `plugins()` makes the caller assemble that transport by hand. Reach for this when
+     * you genuinely have a plugin (a provider, a memory adapter, a tool-registering extension).
+     */
+    plugins(list: readonly unknown[]): AgentBuilder<TInput, TModel, TContext, TTools>;
     /**
      * Declare MCP (Model Context Protocol) servers available to this agent — the builder-chain
      * equivalent of the `@MCP` class decorator. Each key is a server name; the value is its config

package/dist/bridge.d.ts

@@ -1,4 +1,4 @@
-export { c as AGENT_BRAND, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinition, g as AgentDefinitionError, h as AgentExecutionContext, i as AgentManifest, A as AgentManifestEntry, 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, C as CompiledAgentOptions, F as CompiledContextWindow, a as CompiledTool, G as ContextualTool, I as DefineAgentConfig, J as DelegateFn, K as DelegateOptions, M as DelegationError, D as DelegationResult, N as DoneEvent, O as ErrorEvent, P as FileEditEvent, T as InferAgentInput, U as InferAgentToolNames, V as IterationEvent, W as LLMCallContext, _ as McpApprovalSpec, $ as McpRegistryConfig, a0 as McpRequestContext, a1 as McpSelection, a2 as PartialToolCallEvent, a3 as ProcessInputContext, a7 as RunStartedEvent, a8 as ScoreVerdict, a9 as ScoredDelegation, aa as Scorer, ab as SdkAgentHandle, ac as SdkMessage, ad as Segment, ag as StateUpdateEvent, S as StreamEvent, 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, aX as mcpRegistry, aY as mcpToolApprovals, a_ as projectContextMetadataOnlyKnobs, 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';
+export { c as AGENT_BRAND, d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinition, g as AgentDefinitionError, h as AgentExecutionContext, i as AgentManifest, A as AgentManifestEntry, 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, C as CompiledAgentOptions, F as CompiledContextWindow, a as CompiledTool, G as ContextualTool, I as DefineAgentConfig, J as DelegateFn, K as DelegateOptions, M as DelegationError, D as DelegationResult, N as DoneEvent, O as ErrorEvent, P as FileEditEvent, T as InferAgentInput, U as InferAgentToolNames, V as IterationEvent, W as LLMCallContext, _ as McpApprovalSpec, $ as McpRegistryConfig, a0 as McpRequestContext, a1 as McpSelection, a2 as PartialToolCallEvent, a3 as ProcessInputContext, a7 as RunStartedEvent, a8 as ScoreVerdict, a9 as ScoredDelegation, aa as Scorer, ab as SdkAgentHandle, ac as SdkMessage, ad as Segment, ag as StateUpdateEvent, S as StreamEvent, 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, aX as mcpRegistry, aY as mcpToolApprovals, a_ as projectContextMetadataOnlyKnobs, 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-BtFJdaCe.js';
 import '@theokit/http';
 import './types-DVA4LQsA.js';
 import '@theokit/sdk';

package/dist/bridge.js

@@ -47,7 +47,7 @@ import {
   translateToUIMessageStream,
   validateUniqueRoutes,
   walkAgentMetadata
-} from "./chunk-6WOLHCZB.js";
+} from "./chunk-KWQWD277.js";
 import "./chunk-NERDIS45.js";
 import "./chunk-7QVYU63E.js";
 export {

package/dist/{chunk-6WOLHCZB.js → chunk-KWQWD277.js}

@@ -562,6 +562,9 @@ function compileAgentDefinition(def) {
     ...def.settingSources !== void 0 ? {
       settingSources: def.settingSources
     } : {},
+    ...def.plugins !== void 0 ? {
+      plugins: def.plugins
+    } : {},
     // MCP — builder/`defineAgent` servers converge on the same `mcpServers` field the `@MCP`
     // decorator path populates; the SDK adapter forwards it to `Agent.create({ mcpServers })`.
     ...def.mcpServers !== void 0 ? {
@@ -923,6 +926,10 @@ function assembleM8CreateOptions(compiled) {
     options.skills = compiled.skills;
     applied.push("skills");
   }
+  if (compiled.plugins) {
+    options.plugins = compiled.plugins;
+    applied.push("plugins");
+  }
   const settingSources = resolveSettingSources(compiled);
   if (settingSources) {
     options.local = {
@@ -1097,7 +1104,12 @@ __name(withLeakedDialectRecovery, "withLeakedDialectRecovery");
 function buildExtraCreateOptions(overrides, compiled) {
   const recoverLeakedToolCalls = overrides.recoverLeakedToolCalls ?? compiled.recoverLeakedToolCalls ?? false;
   const extra = {};
-  if (overrides.plugins !== void 0) extra.plugins = overrides.plugins;
+  if (overrides.plugins !== void 0) {
+    extra.plugins = Array.isArray(overrides.plugins) && Array.isArray(compiled.plugins) ? [
+      ...compiled.plugins,
+      ...overrides.plugins
+    ] : overrides.plugins;
+  }
   if (overrides.providers !== void 0) {
     extra.providers = recoverLeakedToolCalls ? withLeakedDialectRecovery(overrides.providers) : overrides.providers;
   }
@@ -1630,6 +1642,32 @@ function contextualTool(tool, _requiredContext) {
   return tool;
 }
 __name(contextualTool, "contextualTool");
+function withHooksPlugin(config) {
+  const map = config.hooks;
+  if (map === void 0) return config;
+  const entries = Object.entries(map).filter(([, h]) => typeof h === "function");
+  const { hooks: _dropped, ...rest } = config;
+  if (entries.length === 0) return rest;
+  const plugin = {
+    name: "theokit-builder-hooks",
+    version: "1.0.0",
+    kind: "general",
+    register(ctx) {
+      for (const [hookName, handler] of entries) {
+        ctx.on(hookName, handler);
+      }
+    }
+  };
+  const existing = rest.plugins ?? [];
+  return {
+    ...rest,
+    plugins: [
+      ...existing,
+      plugin
+    ]
+  };
+}
+__name(withHooksPlugin, "withHooksPlugin");
 function makeBuilder(config) {
   const runtime = {
     input: /* @__PURE__ */ __name((schema) => makeBuilder({
@@ -1689,12 +1727,20 @@ function makeBuilder(config) {
       ...config,
       settingSources: sources
     }), "settingSources"),
+    hooks: /* @__PURE__ */ __name((map) => makeBuilder({
+      ...config,
+      hooks: map
+    }), "hooks"),
+    plugins: /* @__PURE__ */ __name((list) => makeBuilder({
+      ...config,
+      plugins: list
+    }), "plugins"),
     mcp: /* @__PURE__ */ __name((servers) => makeBuilder({
       ...config,
       mcpServers: servers
     }), "mcp"),
     use: /* @__PURE__ */ __name((preset) => preset(runtime), "use"),
-    build: /* @__PURE__ */ __name(() => defineAgent(config), "build")
+    build: /* @__PURE__ */ __name(() => defineAgent(withHooksPlugin(config)), "build")
   };
   return runtime;
 }
@@ -3069,4 +3115,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-6WOLHCZB.js.map
+//# sourceMappingURL=chunk-KWQWD277.js.map