@theokit/agents 7.5.0 → 8.0.0

package/dist/bridge.d.ts

@@ -1,7 +1,10 @@
-export { i as AGENT_BRAND, j as AfterToolCallContext, k as AgentBuilder, l as AgentDefinition, m as AgentDefinitionError, n as AgentExecutionContext, o as AgentManifest, f as AgentManifestEntry, p as AgentManifestSource, q as AgentManifestTool, t as AgentRoute, u as AgentRouteContext, v as AgentRunInfo, w as AgentStreamEvent, x as AgentTurnMetadata, y as AgentsPluginOptions, z as ApiErrorContext, B as ApiErrorDecision, E as ApiErrorPolicy, h as ApprovalPosture, F as ApprovalRequiredEvent, I as ArtifactChunkEvent, J as ArtifactStartEvent, K as BackgroundDelegation, N as BeforeToolCallContext, O as BudgetExceededError, Q as CheckpointSavedEvent, C as CompiledAgentOptions, U as CompiledContextWindow, a as CompiledTool, V as ContextualTool, Y as DefineAgentConfig, Z as DefinitionOrThunk, _ as DelegateFn, $ as DelegateOptions, a0 as DelegationBudgetExceededError, a1 as DelegationError, D as DelegationResult, a2 as DoneEvent, a3 as ErrorEvent, a4 as FileEditEvent, aa as InferAgentInput, ab as InferAgentToolNames, ac as IterationEvent, ad as LLMCallContext, ai as McpApprovalSpec, aj as McpFileError, ak as McpRegistryConfig, al as McpRequestContext, am as McpSelection, ao as PartialToolCallEvent, aq as ProcessInputContext, au as RunStartedEvent, av as ScoreVerdict, aw as ScoredDelegation, ax as Scorer, ay as SdkAgentHandle, az as SdkMessage, aA as SdkSendOptions, aB as SdkTurnHandle, aC as Segment, aF as StateUpdateEvent, S as StreamEvent, aG as TextDeltaEvent, aH as ThinkingEvent, aJ as ToolCallEvent, aK as ToolCallVeto, aL as ToolHooks, aM as ToolHooksPlugin, aN as ToolResultEvent, aO as ToolWalkResult, aQ as ToolboxWalkResult, aR as agentsPlugin, aS as buildModelSelection, aT as compileAgentDefinition, aU as compileAgentModule, aV as compileContextWindow, aW as compileProjectContext, aX as compileSkills, aY as compileTools, aZ as createAgentExecutionContext, a_ as createApiErrorHandler, a$ as createSdkAgentStream, b0 as createThinkTagExtractor, b1 as createToolHooksPlugin, b2 as delegate, b3 as delegateBackground, b4 as delegateWithScoring, b5 as extractThinkTagStream, b6 as generateAgentManifest, b7 as generateAgentRoutes, b8 as isAgentContext, b9 as isAgentDefinition, ba as isApprovalRequired, bb as isDone, bc as isError, bd as isPartialToolCall, be as isTextDelta, bf as isToolCall, bg as isToolResult, bi as loadMcpJson, bk as mcpRegistry, bl as mcpToolApprovals, bn as presentUIMessageStream, bo as projectContextMetadataOnlyKnobs, bp as reasoningEffortOf, bt as resolveMcpServers, bu as runWithApiErrorHandling, bv as streamAgentResponse, s as streamAgentUIMessages, bw as toAgentFactory, bx as translateSdkEvent } from './bridge-entry-Z8GjrwH4.js';
+export { d as AfterToolCallContext, e as AgentBuilder, f as AgentDefinitionError, g as AgentExecutionContext, h as AgentManifest, A as AgentManifestEntry, i as AgentManifestSource, j as AgentManifestTool, k as AgentRoute, l as AgentRouteContext, m as AgentRunInfo, n as AgentStreamEvent, o as AgentTurnMetadata, p as AgentsPluginOptions, q as ApiErrorContext, r as ApiErrorDecision, t as ApiErrorPolicy, c as ApprovalPosture, u as ApprovalRequiredEvent, v as ArtifactChunkEvent, w as ArtifactStartEvent, B as BackgroundDelegation, x as BeforeToolCallContext, y as BudgetExceededError, z as CheckpointSavedEvent, E as CompiledContextWindow, F as ContextualTool, I as DefinitionOrThunk, J as DelegateFn, K as DelegateOptions, M as DelegationBudgetExceededError, N as DelegationError, O as DelegationPort, D as DelegationResult, P as DelegationTarget, Q as DelegationTimeoutError, T as DoneEvent, U as EphemeralAgent, V as ErrorEvent, W as FileEditEvent, X as IterationEvent, Y as LLMCallContext, a0 as McpApprovalSpec, a1 as McpFileError, a2 as McpRegistryConfig, a3 as McpRequestContext, a4 as McpSelection, a5 as PartialToolCallEvent, a6 as ProcessInputContext, aa as RunStartedEvent, ab as ScoreVerdict, ac as ScoredDelegation, ad as Scorer, ae as SdkAgentHandle, af as SdkMessage, ag as SdkSendOptions, ah as SdkTurnHandle, ai as Segment, aj as StateUpdateEvent, S as StreamEvent, ak as TextDeltaEvent, al as ThinkingEvent, am as ToolCallEvent, an as ToolCallVeto, ao as ToolHooks, ap as ToolHooksPlugin, aq as ToolResultEvent, ar as agentsPlugin, as as buildModelSelection, at as compileAgentModule, au as compileContextWindow, av as compileProjectContext, aw as compileSkills, ax as createAgentExecutionContext, ay as createApiErrorHandler, az as createSdkAgentStream, aA as createThinkTagExtractor, aB as createToolHooksPlugin, aC as delegate, aD as delegateBackground, aE as delegateWithScoring, aF as extractThinkTagStream, aG as generateAgentManifest, aH as generateAgentRoutes, aI as isAgentContext, aJ as isApprovalRequired, aK as isDone, aL as isError, aM as isPartialToolCall, aN as isTextDelta, aO as isToolCall, aP as isToolResult, aR as loadMcpJson, aT as mcpRegistry, aU as mcpToolApprovals, aW as presentUIMessageStream, aX as projectContextMetadataOnlyKnobs, aY as reasoningEffortOf, a$ as resolveMcpServers, b0 as runWithApiErrorHandling, b1 as streamAgentResponse, s as streamAgentUIMessages, b2 as toAgentFactory, b3 as translateSdkEvent, b4 as withClockCap, b5 as withEphemeralAgent } from './bridge-entry-BEniSXWE.js';
+export { c as AGENT_BRAND, A as AgentDefinition, C as CompiledAgentOptions, a as CompiledTool, D as DefineAgentConfig, I as InferAgentInput, j as InferAgentToolNames, m as ProjectSettingsGrant, n as SettingSourceCapability, S as SettingSourcesSelection, r as ToolWalkResult, t as ToolboxWalkResult, U as UntrustedSettingSourceError, u as compileAgentDefinition, v as compileTools, w as isAgentDefinition, y as resolveSettingSources } from './define-agent-3Kuf6iKM.js';
 import '@theokit/http';
 import '@theokit/sdk';
-import 'zod';
+import '@theokit/sdk/sandbox';
 import '@theokit/presenter/wire';
-import '@theokit/sdk/retry';
+import 'zod';
+import './hook-handlers-Cw2FsnE5.js';
 import '@theokit/sdk/errors';
+import '@theokit/sdk/retry';

package/dist/bridge.js

@@ -1,15 +1,14 @@
 import {
-  AGENT_BRAND,
   AgentBuilder,
   AgentDefinitionError,
   BudgetExceededError,
   ContextualTool,
   DelegationBudgetExceededError,
   DelegationError,
+  DelegationTimeoutError,
   McpFileError,
   agentsPlugin,
   buildModelSelection,
-  compileAgentDefinition,
   compileAgentModule,
   compileContextWindow,
   compileProjectContext,
@@ -27,7 +26,6 @@ import {
   generateAgentManifest,
   generateAgentRoutes,
   isAgentContext,
-  isAgentDefinition,
   isApprovalRequired,
   isDone,
   isError,
@@ -46,8 +44,17 @@ import {
   streamAgentResponse,
   streamAgentUIMessages,
   toAgentFactory,
-  translateSdkEvent
-} from "./chunk-WKBZZQBO.js";
+  translateSdkEvent,
+  withClockCap,
+  withEphemeralAgent
+} from "./chunk-C7UXZWVY.js";
+import {
+  AGENT_BRAND,
+  UntrustedSettingSourceError,
+  compileAgentDefinition,
+  isAgentDefinition,
+  resolveSettingSources
+} from "./chunk-4VHCH6IZ.js";
 import "./chunk-Z4QWC7IK.js";
 export {
   AGENT_BRAND,
@@ -57,7 +64,9 @@ export {
   ContextualTool,
   DelegationBudgetExceededError,
   DelegationError,
+  DelegationTimeoutError,
   McpFileError,
+  UntrustedSettingSourceError,
   agentsPlugin,
   buildModelSelection,
   compileAgentDefinition,
@@ -93,10 +102,13 @@ export {
   projectContextMetadataOnlyKnobs,
   reasoningEffortOf,
   resolveMcpServers,
+  resolveSettingSources,
   runWithApiErrorHandling,
   streamAgentResponse,
   streamAgentUIMessages,
   toAgentFactory,
-  translateSdkEvent
+  translateSdkEvent,
+  withClockCap,
+  withEphemeralAgent
 };
 //# sourceMappingURL=bridge.js.map

package/dist/chunk-4VHCH6IZ.js

@@ -0,0 +1,181 @@
+import {
+  __name
+} from "./chunk-Z4QWC7IK.js";
+
+// src/bridge/setting-sources-gate.ts
+import { TheokitAgentError } from "@theokit/sdk/errors";
+var UntrustedSettingSourceError = class extends TheokitAgentError {
+  static {
+    __name(this, "UntrustedSettingSourceError");
+  }
+  trustSource;
+  capability;
+  name = "UntrustedSettingSourceError";
+  constructor(message, trustSource, capability) {
+    super(message), this.trustSource = trustSource, this.capability = capability;
+  }
+};
+function resolveSettingSources(selection) {
+  if (selection === void 0) return [];
+  const sources = [];
+  if (selection.user === true) sources.push("user");
+  const grant = selection.project;
+  if (grant !== void 0) {
+    const posture = grant.trustedBy;
+    if (!posture.allows.projectSettings) {
+      throw new UntrustedSettingSourceError(`the \`project\` setting source reads <cwd>/.theokit/ \u2014 including shell-executing hooks \u2014 and the posture does not grant \`projectSettings\` (level: ${posture.level}, decided by: ${posture.source}). Grant it with a trusted posture, or omit \`project\` to read only the operator's own ~/.theokit/.`, posture.source, "projectSettings");
+    }
+    sources.push("project");
+  }
+  return sources;
+}
+__name(resolveSettingSources, "resolveSettingSources");
+
+// src/bridge/define-agent.ts
+var AGENT_BRAND = /* @__PURE__ */ Symbol.for("theokit.agent.definition");
+function defineAgent(config) {
+  return {
+    ...config,
+    [AGENT_BRAND]: true
+  };
+}
+__name(defineAgent, "defineAgent");
+function isAgentDefinition(value) {
+  return typeof value === "object" && value !== null && value[AGENT_BRAND] === true;
+}
+__name(isAgentDefinition, "isAgentDefinition");
+function toCompiledTool(tool) {
+  const handler = tool.handler;
+  const compiled = {
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    handler: /* @__PURE__ */ __name((input, ctx) => handler(input, ctx), "handler")
+  };
+  for (const sym of Object.getOwnPropertySymbols(tool)) {
+    ;
+    compiled[sym] = tool[sym];
+  }
+  return compiled;
+}
+__name(toCompiledTool, "toCompiledTool");
+function compileAgentDefinition(def) {
+  return {
+    model: def.model,
+    reasoningEffort: def.reasoningEffort,
+    systemPrompt: def.system,
+    tools: (def.tools ?? []).map(toCompiledTool),
+    agents: {},
+    stream: true,
+    // M7 — run-context flows to CompiledAgentOptions.runContext (distinct from the
+    // context-window `context` field the decorator path uses); absent ⇒ no key.
+    ...def.context !== void 0 ? {
+      runContext: def.context
+    } : {},
+    // M9 — guardrails flow through unchanged; the runner applies them at the input boundary.
+    ...def.guardrails !== void 0 ? {
+      guardrails: def.guardrails
+    } : {},
+    // M14 — HITL approvals compile into the same `hitl` map the decorator path produces.
+    ...def.approvals !== void 0 ? {
+      hitl: compileApprovals(def)
+    } : {},
+    // M13 — skills: a static list → SDK skills.enabled; a resolver → carried for the request path.
+    ...compileSkillsSelection(def.skills),
+    // theokit-file-based-config + M68 — the selection is resolved HERE, at the earliest point every
+    // authoring path converges on, so `CompiledAgentOptions.settingSources` can only ever hold
+    // roots that some posture authorized. Refusing at compile time rather than at run assembly is
+    // `error-handling.md` § 3: validate at the entry, fail before the value travels.
+    ...def.settingSources !== void 0 ? {
+      settingSources: resolveSettingSources(def.settingSources)
+    } : {},
+    // M49 — memory flows to the projection layer; `assembleM8CreateOptions` forwards it to Agent.create.
+    ...def.memory !== void 0 ? {
+      memory: def.memory
+    } : {},
+    // Hooks are converted here — the layer EVERY path converges on — rather than on the builder, so
+    // `defineAgent({ hooks })` cannot type-check and silently no-op. A lifecycle hook that is
+    // declared but never registered is a security gate that does not gate.
+    ...compileHooksAndPlugins(def),
+    // 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 ? {
+      mcpServers: def.mcpServers
+    } : {}
+  };
+}
+__name(compileAgentDefinition, "compileAgentDefinition");
+function compileHooksAndPlugins(def) {
+  const map = def.hooks;
+  const entries = Object.entries(map ?? {}).filter(([, h]) => typeof h === "function");
+  const explicit = def.plugins ?? [];
+  if (entries.length === 0) {
+    return def.plugins !== void 0 ? {
+      plugins: def.plugins
+    } : {};
+  }
+  const plugin = {
+    name: "theokit-builder-hooks",
+    version: "1.0.0",
+    kind: "general",
+    register(ctx) {
+      for (const [hookName, handler] of entries) {
+        ctx.on(hookName, handler);
+      }
+    }
+  };
+  return {
+    plugins: [
+      ...explicit,
+      plugin
+    ]
+  };
+}
+__name(compileHooksAndPlugins, "compileHooksAndPlugins");
+function compileSkillsSelection(skills) {
+  if (skills === void 0) return {};
+  if (typeof skills === "function") return {
+    skillsResolver: skills
+  };
+  const enabled = [];
+  const inline = [];
+  for (const entry of skills) {
+    if (typeof entry === "string") enabled.push(entry);
+    else inline.push(entry);
+  }
+  return {
+    skills: {
+      enabled,
+      autoInject: true,
+      ...inline.length > 0 ? {
+        inline
+      } : {}
+    }
+  };
+}
+__name(compileSkillsSelection, "compileSkillsSelection");
+function compileApprovals(def) {
+  const toolNames = new Set((def.tools ?? []).map((t) => t.name));
+  const gates = /* @__PURE__ */ new Map();
+  for (const [toolName, options] of Object.entries(def.approvals ?? {})) {
+    if (!toolNames.has(toolName)) {
+      throw new Error(`[@theokit/agents] defineAgent approval references unknown tool "${toolName}". Declared tools: ${[
+        ...toolNames
+      ].join(", ") || "(none)"}.`);
+    }
+    gates.set(toolName, options);
+  }
+  return gates;
+}
+__name(compileApprovals, "compileApprovals");
+
+export {
+  UntrustedSettingSourceError,
+  resolveSettingSources,
+  AGENT_BRAND,
+  defineAgent,
+  isAgentDefinition,
+  compileAgentDefinition,
+  compileSkillsSelection
+};
+//# sourceMappingURL=chunk-4VHCH6IZ.js.map

package/dist/chunk-4VHCH6IZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bridge/setting-sources-gate.ts","../src/bridge/define-agent.ts"],"mappings":"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","names":["TheokitAgentError","UntrustedSettingSourceError","TheokitAgentError","name","message","trustSource","capability","resolveSettingSources","selection","undefined","sources","user","push","grant","project","posture","trustedBy","allows","projectSettings","level","source","AGENT_BRAND","Symbol","for","defineAgent","config","isAgentDefinition","value","toCompiledTool","tool","handler","compiled","name","description","inputSchema","input","ctx","sym","Object","getOwnPropertySymbols","compileAgentDefinition","def","model","reasoningEffort","systemPrompt","system","tools","map","agents","stream","context","undefined","runContext","guardrails","approvals","hitl","compileApprovals","compileSkillsSelection","skills","settingSources","resolveSettingSources","memory","compileHooksAndPlugins","mcpServers","hooks","entries","filter","h","explicit","plugins","length","plugin","version","kind","register","hookName","on","skillsResolver","enabled","inline","entry","push","autoInject","toolNames","Set","t","gates","Map","toolName","options","has","Error","join","set"]}