@theokit/agents 0.28.0 → 0.30.0

package/dist/{chunk-DA7HHFL5.js → chunk-AUOCWGPS.js}

@@ -9,9 +9,11 @@ import {
   TOOL_METHODS,
   Trace,
   getAgentConfig,
+  getCheckpointConfig,
   getCompactionConfig,
   getContextWindowConfig,
   getGatewayConfig,
+  getHumanInTheLoopConfig,
   getMcpConfig,
   getMemoryConfig,
   getMeta,
@@ -19,7 +21,7 @@ import {
   getProjectContextConfig,
   getSkillsConfig,
   getSubAgents
-} from "./chunk-GVPUUKKE.js";
+} from "./chunk-FI6ZG2YP.js";
 import {
   __name
 } from "./chunk-7QVYU63E.js";
@@ -117,7 +119,8 @@ var AgentWarningCode = {
   FILTER_METADATA_ONLY: "THEO_AGENT_FILTER_METADATA_ONLY",
   BUDGET_TOP_LEVEL_METADATA_ONLY: "THEO_AGENT_BUDGET_TOP_LEVEL_METADATA_ONLY",
   CONTEXT_STRATEGY_METADATA_ONLY: "THEO_AGENT_CONTEXT_STRATEGY_METADATA_ONLY",
-  PROJECT_CONTEXT_KNOB_METADATA_ONLY: "THEO_AGENT_PROJECT_CONTEXT_KNOB_METADATA_ONLY"
+  PROJECT_CONTEXT_KNOB_METADATA_ONLY: "THEO_AGENT_PROJECT_CONTEXT_KNOB_METADATA_ONLY",
+  CHECKPOINT_STORAGE_METADATA_ONLY: "THEO_AGENT_CHECKPOINT_STORAGE_METADATA_ONLY"
 };
 var reflectorInstance = new Reflector();
 function walkToolbox(ToolboxClass) {
@@ -145,7 +148,8 @@ function walkToolbox(ToolboxClass) {
       capabilities: void 0,
       budget: void 0,
       trace: traceVal ?? false,
-      audit: auditVal ?? false
+      audit: auditVal ?? false,
+      hitl: getHumanInTheLoopConfig(ToolboxClass, propertyKey)
     };
   });
   return {
@@ -171,6 +175,12 @@ function warnUnmappedDecoratorKnobs(agentName, contextWindow, projectContext) {
   }
 }
 __name(warnUnmappedDecoratorKnobs, "warnUnmappedDecoratorKnobs");
+function warnNonDurableCheckpoint(agentName, checkpoint) {
+  if (checkpoint && checkpoint.storage !== "filesystem") {
+    console.warn(`[${AgentWarningCode.CHECKPOINT_STORAGE_METADATA_ONLY}] Agent ${agentName}: @Checkpoint({ storage: '${checkpoint.storage ?? "memory"}' }) does NOT resume across requests \u2014 only 'filesystem' selects the SDK's durable conversation store. Use @Checkpoint({ storage: 'filesystem' }) for cross-request resume.`);
+  }
+}
+__name(warnNonDurableCheckpoint, "warnNonDurableCheckpoint");
 var agentWalkCache = /* @__PURE__ */ new WeakMap();
 function walkAgentMetadata(AgentClass, toolboxClasses = []) {
   if (toolboxClasses.length === 0) {
@@ -208,6 +218,8 @@ function walkAgentMetadata(AgentClass, toolboxClasses = []) {
   const projectContext = getProjectContextConfig(AgentClass);
   warnUnmappedDecoratorKnobs(AgentClass.name, contextWindow, projectContext);
   const compaction = getCompactionConfig(AgentClass);
+  const checkpoint = getCheckpointConfig(AgentClass);
+  warnNonDurableCheckpoint(AgentClass.name, checkpoint);
   const result = {
     agentConfig,
     mainLoop,
@@ -223,7 +235,8 @@ function walkAgentMetadata(AgentClass, toolboxClasses = []) {
     contextWindow,
     projectContext,
     mcpServers,
-    compaction
+    compaction,
+    checkpoint
   };
   if (toolboxClasses.length === 0) {
     agentWalkCache.set(AgentClass, result);
@@ -258,6 +271,22 @@ function compileSkills(options) {
 __name(compileSkills, "compileSkills");
 
 // src/bridge/agent-compiler.ts
+function toolRuntimeName(namespace, toolName) {
+  return namespace ? `${namespace}.${toolName}` : toolName;
+}
+__name(toolRuntimeName, "toolRuntimeName");
+function compileHitlGates(toolboxes) {
+  const gates = /* @__PURE__ */ new Map();
+  for (const tb of toolboxes) {
+    for (const tool of tb.tools) {
+      if (tool.hitl) {
+        gates.set(toolRuntimeName(tb.namespace, tool.config.name), tool.hitl);
+      }
+    }
+  }
+  return gates;
+}
+__name(compileHitlGates, "compileHitlGates");
 function compileTools(toolboxes, toolboxInstances) {
   const tools = [];
   for (const tb of toolboxes) {
@@ -270,7 +299,7 @@ function compileTools(toolboxes, toolboxInstances) {
       if (typeof handler !== "function") {
         throw new Error(`[@theokit/agents] Toolbox ${tb.class.name}: '${String(tool.propertyKey)}' is not a function.`);
       }
-      const name = tb.namespace ? `${tb.namespace}.${tool.config.name}` : tool.config.name;
+      const name = toolRuntimeName(tb.namespace, tool.config.name);
       tools.push({
         name,
         description: tool.config.description,
@@ -298,6 +327,7 @@ __name(compileSubAgents, "compileSubAgents");
 function compileAgent(walkResult, toolboxInstances = /* @__PURE__ */ new Map()) {
   const tools = compileTools(walkResult.toolboxes, toolboxInstances);
   const agents = compileSubAgents(walkResult.subAgentClasses);
+  const hitl = compileHitlGates(walkResult.toolboxes);
   return {
     model: walkResult.agentConfig.model,
     reasoningEffort: walkResult.agentConfig.reasoningEffort,
@@ -314,7 +344,9 @@ function compileAgent(walkResult, toolboxInstances = /* @__PURE__ */ new Map())
     mcpServers: walkResult.mcpServers,
     maxIterations: walkResult.mainLoop.maxIterations ?? walkResult.agentConfig.maxIterations,
     timeoutMs: walkResult.mainLoop.timeoutMs ?? walkResult.agentConfig.timeoutMs,
-    stream: walkResult.agentConfig.stream ?? true
+    stream: walkResult.agentConfig.stream ?? true,
+    hitl: hitl.size > 0 ? hitl : void 0,
+    checkpoint: walkResult.checkpoint
   };
 }
 __name(compileAgent, "compileAgent");
@@ -940,6 +972,25 @@ function buildExtraCreateOptions(overrides, compiled) {
   return extra;
 }
 __name(buildExtraCreateOptions, "buildExtraCreateOptions");
+async function loadSdkRuntime() {
+  try {
+    const sdk = await import("@theokit/sdk");
+    const InMemory = sdk.InMemoryConversationStorage;
+    return {
+      Agent: sdk.Agent,
+      defineTool: sdk.defineTool,
+      InMemoryConversationStorage: InMemory,
+      FileSystemConversationStorage: "FileSystemConversationStorage" in sdk ? sdk.FileSystemConversationStorage : InMemory
+    };
+  } catch {
+    return null;
+  }
+}
+__name(loadSdkRuntime, "loadSdkRuntime");
+function newConversationStorage(compiled, InMemory, FileSystem) {
+  return compiled.checkpoint?.storage === "filesystem" ? new FileSystem() : new InMemory();
+}
+__name(newConversationStorage, "newConversationStorage");
 function createAsyncQueue() {
   const items = [];
   let wake = null;
@@ -1090,15 +1141,8 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
     async *[Symbol.asyncIterator]() {
       const runId = `run-${Date.now()}`;
       const t0 = Date.now();
-      let Agent;
-      let defineTool;
-      let InMemoryConversationStorage;
-      try {
-        const sdk = await import("@theokit/sdk");
-        Agent = sdk.Agent;
-        defineTool = sdk.defineTool;
-        InMemoryConversationStorage = sdk.InMemoryConversationStorage;
-      } catch {
+      const rt = await loadSdkRuntime();
+      if (!rt) {
         yield {
           type: "error",
           code: "SDK_NOT_INSTALLED",
@@ -1107,6 +1151,7 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
         };
         return;
       }
+      const { Agent, defineTool, InMemoryConversationStorage, FileSystemConversationStorage } = rt;
       const sdkTools = buildSdkTools(compiledTools, defineTool, overrides.sdkTools);
       let agent;
       try {
@@ -1116,7 +1161,7 @@ function createSdkAgentStream(compiled, compiledTools, apiKey, overrides = {}) {
           cwd: overrides.cwd
         };
         const extra = buildExtraCreateOptions(overrides, compiled);
-        storage ??= new InMemoryConversationStorage();
+        storage ??= newConversationStorage(compiled, InMemoryConversationStorage, FileSystemConversationStorage);
         if (applied.length > 0) {
           console.debug("[THEO_AGENT_M8_RUNTIME_APPLIED]", {
             skills: applied.includes("skills"),
@@ -1220,6 +1265,36 @@ function* emitToolResult(event, seen) {
   }
 }
 __name(emitToolResult, "emitToolResult");
+function* emitApprovalRequest(event, seen) {
+  if (!seen.has(event.callId)) {
+    seen.add(event.callId);
+    yield {
+      type: "tool-input-available",
+      toolCallId: event.callId,
+      toolName: event.toolName,
+      input: event.input ?? {},
+      dynamic: true
+    };
+  }
+  yield {
+    type: "tool-approval-request",
+    approvalId: event.callId,
+    toolCallId: event.callId
+  };
+}
+__name(emitApprovalRequest, "emitApprovalRequest");
+function* emitCheckpointSaved(event) {
+  yield {
+    type: "data-checkpoint",
+    data: {
+      checkpointId: event.checkpointId,
+      resumeToken: event.resumeToken,
+      step: event.step
+    },
+    transient: true
+  };
+}
+__name(emitCheckpointSaved, "emitCheckpointSaved");
 async function* translateToUIMessageStream(events, opts) {
   yield {
     type: "start"
@@ -1265,9 +1340,15 @@ async function* translateToUIMessageStream(events, opts) {
       } else if (event.type === "tool_call") {
         yield* closeOpenBlock(state, opts.textId);
         yield* emitToolCall(event, seenToolCallIds);
+      } else if (event.type === "approval_required") {
+        yield* closeOpenBlock(state, opts.textId);
+        yield* emitApprovalRequest(event, seenToolCallIds);
       } else if (event.type === "tool_result") {
         yield* closeOpenBlock(state, opts.textId);
         yield* emitToolResult(event, seenToolCallIds);
+      } else if (event.type === "checkpoint_saved") {
+        yield* closeOpenBlock(state, opts.textId);
+        yield* emitCheckpointSaved(event);
       } else if (event.type === "error") {
         yield {
           type: "error",
@@ -1291,6 +1372,201 @@ async function* translateToUIMessageStream(events, opts) {
 }
 __name(translateToUIMessageStream, "translateToUIMessageStream");
 
+// 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 compileAgentDefinition(def) {
+  return {
+    model: def.model,
+    reasoningEffort: def.reasoningEffort,
+    systemPrompt: def.system,
+    tools: def.tools ?? [],
+    agents: {},
+    stream: true
+  };
+}
+__name(compileAgentDefinition, "compileAgentDefinition");
+
+// src/bridge/hitl-plugin.ts
+function createHitlPlugin(wiring) {
+  return {
+    name: "theokit-hitl",
+    register(ctx) {
+      ctx.on("pre_tool_call", async (c) => {
+        const opts = wiring.gated.get(c.name);
+        if (!opts) return void 0;
+        const approvalId = crypto.randomUUID();
+        wiring.emit({
+          type: "approval_required",
+          callId: approvalId,
+          toolName: c.name,
+          question: opts.question,
+          input: c.args,
+          callbackUrl: `approve/${approvalId}`,
+          timeoutMs: opts.timeout ?? 3e5
+        });
+        const approved = await wiring.awaitApproval(approvalId, opts);
+        return approved ? void 0 : {
+          block: true,
+          message: `Tool '${c.name}' denied by human approver`
+        };
+      });
+    }
+  };
+}
+__name(createHitlPlugin, "createHitlPlugin");
+
+// src/bridge/agent-endpoint.ts
+var AgentDefinitionError = class extends Error {
+  static {
+    __name(this, "AgentDefinitionError");
+  }
+  constructor(source) {
+    super(`[@theokit/agents] ${source}: an agents/ file must default-export a defineAgent(...) value or an @Agent-decorated class.`);
+    this.name = "AgentDefinitionError";
+  }
+};
+function extractDefaultExport(mod) {
+  if (typeof mod === "object" && mod !== null && "default" in mod) {
+    return mod.default;
+  }
+  return mod;
+}
+__name(extractDefaultExport, "extractDefaultExport");
+function compileAgentModule(mod, source = "agent module") {
+  const def = extractDefaultExport(mod);
+  if (isAgentDefinition(def)) {
+    return compileAgentDefinition(def);
+  }
+  if (typeof def === "function" && getAgentConfig(def) !== void 0) {
+    const walk = walkAgentMetadata(def, getMixins(def));
+    const instances = /* @__PURE__ */ new Map();
+    for (const tb of walk.toolboxes) {
+      instances.set(tb.class, new tb.class());
+    }
+    return compileAgent(walk, instances);
+  }
+  throw new AgentDefinitionError(source);
+}
+__name(compileAgentModule, "compileAgentModule");
+async function* asAgentStream(events) {
+  for await (const e of events) yield e;
+}
+__name(asAgentStream, "asAgentStream");
+var EventQueue = class EventQueue2 {
+  static {
+    __name(this, "EventQueue");
+  }
+  #items = [];
+  #resolvers = [];
+  #closed = false;
+  push(item) {
+    if (this.#closed) return;
+    const r = this.#resolvers.shift();
+    if (r) r({
+      value: item,
+      done: false
+    });
+    else this.#items.push(item);
+  }
+  close() {
+    this.#closed = true;
+    for (const r of this.#resolvers.splice(0)) r({
+      value: void 0,
+      done: true
+    });
+  }
+  async *drain() {
+    for (; ; ) {
+      if (this.#items.length > 0) {
+        yield this.#items.shift();
+        continue;
+      }
+      if (this.#closed) return;
+      const next = await new Promise((resolve) => this.#resolvers.push(resolve));
+      if (next.done) return;
+      yield next.value;
+    }
+  }
+};
+async function* appendCheckpointSaved(source, sessionId) {
+  let emitted = false;
+  const checkpoint = /* @__PURE__ */ __name(() => ({
+    type: "checkpoint_saved",
+    checkpointId: crypto.randomUUID(),
+    step: 0,
+    resumeToken: sessionId
+  }), "checkpoint");
+  for await (const ev of source) {
+    if (ev.type === "done" && !emitted) {
+      emitted = true;
+      yield checkpoint();
+    }
+    yield ev;
+  }
+  if (!emitted) yield checkpoint();
+}
+__name(appendCheckpointSaved, "appendCheckpointSaved");
+function streamAgentUIMessages(compiled, apiKey, input) {
+  const textId = crypto.randomUUID();
+  const overrides = {};
+  if (input.conversationStorage) overrides.conversationStorage = input.conversationStorage;
+  let source;
+  if (!input.hitl || input.hitl.gated.size === 0) {
+    const events2 = createSdkAgentStream(compiled, compiled.tools, apiKey, overrides)(input.message, input.sessionId);
+    source = asAgentStream(events2);
+  } else {
+    const queue = new EventQueue();
+    input.signal?.addEventListener("abort", () => queue.close(), {
+      once: true
+    });
+    const plugin = createHitlPlugin({
+      gated: input.hitl.gated,
+      emit: /* @__PURE__ */ __name((e) => queue.push(e), "emit"),
+      awaitApproval: input.hitl.awaitApproval
+    });
+    const sdkStream = createSdkAgentStream(compiled, compiled.tools, apiKey, {
+      ...overrides,
+      // The HITL plugin is a structural @theokit/sdk Plugin (createHitlPlugin returns the
+      // { name, register } shape); the RuntimeOverrides.plugins union is widened at the SDK edge.
+      plugins: [
+        plugin
+      ]
+    })(input.message, input.sessionId);
+    void (async () => {
+      try {
+        for await (const e of sdkStream) queue.push(e);
+      } catch (err) {
+        queue.push({
+          type: "error",
+          code: "SDK_STREAM_ERROR",
+          message: err instanceof Error ? err.message : String(err),
+          retryable: false
+        });
+      } finally {
+        queue.close();
+      }
+    })();
+    source = queue.drain();
+  }
+  const durableCheckpoint = compiled.checkpoint?.storage === "filesystem";
+  const events = durableCheckpoint ? appendCheckpointSaved(source, input.sessionId) : source;
+  return translateToUIMessageStream(events, {
+    textId
+  });
+}
+__name(streamAgentUIMessages, "streamAgentUIMessages");
+
 // src/loop/compaction-strategy.ts
 import { compactTranscript } from "@theokit/sdk/compaction";
 import { z } from "zod";
@@ -2011,6 +2287,13 @@ export {
   extractThinkTagStream,
   createSdkAgentStream,
   translateToUIMessageStream,
+  AGENT_BRAND,
+  defineAgent,
+  isAgentDefinition,
+  compileAgentDefinition,
+  AgentDefinitionError,
+  compileAgentModule,
+  streamAgentUIMessages,
   DEFAULT_KEEP_TOKENS,
   compactionStrategyConfigSchema,
   resolveCompactionStrategy,
@@ -2029,4 +2312,4 @@ export {
   generateAgentManifest,
   agentsPlugin
 };
-//# sourceMappingURL=chunk-DA7HHFL5.js.map
+//# sourceMappingURL=chunk-AUOCWGPS.js.map