@theokit/sdk 2.20.0 → 2.22.0

package/dist/index.js

@@ -1,10 +1,10 @@
+import { z, toJSONSchema } from 'zod';
+import { createRequire } from 'module';
 import { createHash, randomUUID, randomBytes } from 'crypto';
 import { existsSync, rmSync, mkdirSync, renameSync, readFileSync, realpathSync, lstatSync, readlinkSync, readdirSync } from 'fs';
 import { join, dirname, relative, resolve, sep, isAbsolute } from 'path';
-import { readFile, stat, rm, readdir, mkdir, rename, open, unlink, statfs, access, appendFile } from 'fs/promises';
-import { z, toJSONSchema } from 'zod';
+import { readFile, stat, rm, readdir, mkdir, appendFile, rename, open, unlink, statfs, access, writeFile } from 'fs/promises';
 import { AsyncLocalStorage } from 'async_hooks';
-import { createRequire } from 'module';
 import { homedir } from 'os';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
@@ -516,6 +516,256 @@ var init_errors = __esm({
     };
   }
 });
+function toJsonSchema(schema, options = { unrepresentable: "any" }) {
+  return toJSONSchema(schema, options);
+}
+var init_to_json_schema = __esm({
+  "src/internal/zod/to-json-schema.ts"() {
+  }
+});
+function requireZod() {
+  if (cachedZ !== void 0) return cachedZ;
+  const r = createRequire(import.meta.url);
+  let mod;
+  try {
+    mod = r("zod");
+  } catch (cause) {
+    throw new ConfigurationError(
+      'Structured output requires the optional peer dependency `zod`. Add `"zod": "^3.25.0 || ^4.0.0"` to your package.json and reinstall.',
+      { code: "zod_not_installed", cause }
+    );
+  }
+  cachedZ = mod.z ?? mod;
+  return cachedZ;
+}
+function makeOutputTool(jsonSchema, onCapture) {
+  return {
+    name: "output",
+    description: "Call this tool with your final structured answer. Match the JSON schema exactly.",
+    inputSchema: jsonSchema,
+    handler: (input) => {
+      const out = onCapture(input);
+      if (typeof out === "string") return out;
+      if (out instanceof Promise) return out;
+      return "";
+    }
+  };
+}
+function buildTransientAgentOptions(params) {
+  return {
+    model: params.model,
+    local: params.local,
+    tools: [params.outputTool],
+    systemPrompt: params.systemPrompt ?? "You produce structured output by calling the `output` tool exactly once. Match the JSON schema.",
+    ...params.apiKey !== void 0 ? { apiKey: params.apiKey } : {},
+    ...params.providers !== void 0 ? { providers: params.providers } : {}
+  };
+}
+function extractUsage(result) {
+  const u = result.usage;
+  if (u === void 0) return { inputTokens: 0, outputTokens: 0 };
+  return { inputTokens: u.inputTokens ?? 0, outputTokens: u.outputTokens ?? 0 };
+}
+function buildToolPrompt(prompt) {
+  return `${prompt}
+
+Respond by calling the \`output\` tool with the structured answer that matches the schema.`;
+}
+function setupStructuredOutput(schema, maxRetries) {
+  const z8 = requireZod();
+  const jsonSchema = toJsonSchema(schema, { unrepresentable: "any" });
+  return {
+    z: z8,
+    jsonSchema,
+    maxRetries: maxRetries ?? 1,
+    initialUsage: { inputTokens: 0, outputTokens: 0 }
+  };
+}
+async function disposeAndDeleteTransient(agent, deletor) {
+  await agent.dispose();
+  try {
+    await deletor(agent.agentId);
+  } catch {
+  }
+}
+var cachedZ;
+var init_structured_output_helpers = __esm({
+  "src/internal/structured-output-helpers.ts"() {
+    init_errors();
+    init_to_json_schema();
+  }
+});
+
+// src/generate-object.ts
+var generate_object_exports = {};
+__export(generate_object_exports, {
+  GenerateObjectError: () => GenerateObjectError,
+  generateObjectImpl: () => generateObjectImpl
+});
+function salvagePartial(schema, raw) {
+  if (typeof raw !== "object" || raw === null) return raw;
+  const shape = schema.shape;
+  if (shape === void 0 || typeof shape !== "object") return raw;
+  const rawObj = raw;
+  const out = {};
+  for (const [key2, fieldSchema] of Object.entries(shape)) {
+    if (typeof fieldSchema?.safeParse !== "function") continue;
+    const parsed = fieldSchema.safeParse(rawObj[key2]);
+    if (parsed.success) out[key2] = parsed.data;
+  }
+  return out;
+}
+async function runReasoningPhase(options, deps) {
+  const reasoningOptions = {
+    model: options.model,
+    local: options.local,
+    ...options.systemPrompt !== void 0 ? { systemPrompt: options.systemPrompt } : {},
+    ...options.apiKey !== void 0 ? { apiKey: options.apiKey } : {},
+    ...options.providers !== void 0 ? { providers: options.providers } : {}
+  };
+  const reasoningAgent = await deps.create(reasoningOptions);
+  try {
+    const run = await reasoningAgent.send(options.prompt);
+    const result = await run.wait();
+    const text = result.result;
+    return typeof text === "string" ? text : options.prompt;
+  } finally {
+    await disposeAndDeleteTransient(reasoningAgent, deps.delete);
+  }
+}
+async function generateObjectImpl(options, deps) {
+  const { jsonSchema, maxRetries, initialUsage } = setupStructuredOutput(
+    options.schema,
+    options.maxRetries
+  );
+  let capturedRaw;
+  let lastUsage = initialUsage;
+  const sentinel = /* @__PURE__ */ Symbol("generate-object-sentinel");
+  class CaptureSentinel extends Error {
+    constructor(captured) {
+      super("generate-object-capture");
+      this.captured = captured;
+    }
+    captured;
+    [sentinel] = true;
+  }
+  const outputTool = makeOutputTool(jsonSchema, (input) => {
+    if (capturedRaw === void 0) {
+      capturedRaw = input;
+    }
+    throw new CaptureSentinel(input);
+  });
+  const reasoningText = options.structuringModel !== void 0 ? await runReasoningPhase(options, deps) : void 0;
+  const structuringModel = options.structuringModel ?? options.model;
+  const structuringPrompt = reasoningText ?? options.prompt;
+  const agentOptions = buildTransientAgentOptions({
+    model: structuringModel,
+    local: options.local,
+    outputTool,
+    ...options.systemPrompt !== void 0 ? { systemPrompt: options.systemPrompt } : {},
+    ...options.apiKey !== void 0 ? { apiKey: options.apiKey } : {},
+    ...options.providers !== void 0 ? { providers: options.providers } : {}
+  });
+  const agent = await deps.create(agentOptions);
+  try {
+    const userMessage = buildToolPrompt(structuringPrompt);
+    let lastParseError;
+    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+      capturedRaw = void 0;
+      const run = await agent.send(userMessage);
+      const result = await run.wait();
+      lastUsage = extractUsage(result);
+      if (capturedRaw === void 0) {
+        if (result.status === "error" && result.error !== void 0) {
+          throw new GenerateObjectError(
+            "no_tool_call",
+            `Agent run failed before the model could reply: ${result.error.message ?? "unknown error"} [${result.error.code ?? "?"}]`,
+            result.error
+          );
+        }
+        if (attempt === maxRetries) {
+          throw new GenerateObjectError(
+            "no_tool_call",
+            "The model returned text instead of calling the `output` tool."
+          );
+        }
+        continue;
+      }
+      const parsed = options.schema.safeParse(capturedRaw);
+      if (parsed.success) {
+        return {
+          object: parsed.data,
+          raw: capturedRaw,
+          usage: lastUsage,
+          finishReason: "tool_use"
+        };
+      }
+      lastParseError = parsed.error;
+    }
+    if (options.errorStrategy === "return-raw") {
+      return {
+        object: capturedRaw,
+        raw: capturedRaw,
+        usage: lastUsage,
+        finishReason: "tool_use"
+      };
+    }
+    if (options.errorStrategy === "return-partial") {
+      return {
+        object: salvagePartial(options.schema, capturedRaw),
+        raw: capturedRaw,
+        usage: lastUsage,
+        finishReason: "tool_use"
+      };
+    }
+    throw new GenerateObjectError(
+      "parse_failed",
+      "Schema parse failed after all retries.",
+      lastParseError
+    );
+  } finally {
+    await disposeAndDeleteTransient(agent, deps.delete);
+  }
+}
+var GenerateObjectError;
+var init_generate_object = __esm({
+  "src/generate-object.ts"() {
+    init_structured_output_helpers();
+    GenerateObjectError = class extends Error {
+      name = "GenerateObjectError";
+      code;
+      cause;
+      constructor(code, message, cause) {
+        super(message);
+        this.code = code;
+        if (cause !== void 0) this.cause = cause;
+      }
+    };
+  }
+});
+
+// src/internal/runtime/registry/agent-factory-registry.ts
+var agent_factory_registry_exports = {};
+__export(agent_factory_registry_exports, {
+  getAgentFacade: () => getAgentFacade,
+  setAgentFacade: () => setAgentFacade
+});
+function setAgentFacade(facade) {
+  registered = facade;
+}
+function getAgentFacade() {
+  if (registered === void 0) {
+    throw new Error(
+      "internal: Agent facade not registered. The `agent.ts` module must be loaded before internal subsystems (LocalAgent.runUntil/fork, eval, scorers, cron) invoke it."
+    );
+  }
+  return registered;
+}
+var registered;
+var init_agent_factory_registry = __esm({
+  "src/internal/runtime/registry/agent-factory-registry.ts"() {
+  }
+});
 
 // src/internal/persistence/cwd-mutex.ts
 function withCwdMutex(key2, fn) {
@@ -2786,29 +3036,6 @@ var init_judge_call = __esm({
   }
 });
 
-// src/internal/runtime/registry/agent-factory-registry.ts
-var agent_factory_registry_exports = {};
-__export(agent_factory_registry_exports, {
-  getAgentFacade: () => getAgentFacade,
-  setAgentFacade: () => setAgentFacade
-});
-function setAgentFacade(facade) {
-  registered3 = facade;
-}
-function getAgentFacade() {
-  if (registered3 === void 0) {
-    throw new Error(
-      "internal: Agent facade not registered. The `agent.ts` module must be loaded before internal subsystems (LocalAgent.runUntil/fork, eval, scorers, cron) invoke it."
-    );
-  }
-  return registered3;
-}
-var registered3;
-var init_agent_factory_registry = __esm({
-  "src/internal/runtime/registry/agent-factory-registry.ts"() {
-  }
-});
-
 // src/internal/runtime/lifecycle/run-to-completion.ts
 var run_to_completion_exports = {};
 __export(run_to_completion_exports, {
@@ -2973,14 +3200,14 @@ async function forkAgentImpl(parent, options, deps) {
       return {
         result: result.result,
         toolCalls: [],
-        usage: extractUsage(result)
+        usage: extractUsage2(result)
       };
     });
   } finally {
     await fork.dispose();
   }
 }
-function extractUsage(result) {
+function extractUsage2(result) {
   if (typeof result !== "object" || result === null) {
     return { inputTokens: 0, outputTokens: 0 };
   }
@@ -3611,331 +3838,104 @@ async function submit(internal) {
       once: true
     });
   }
-  const release = await acquireSlot();
-  void (async () => {
-    try {
-      await checkCancelRequestedAt(resolvedId, aborter);
-      if (aborter.signal.aborted) {
-        const cancelledAt = Date.now();
-        await transition(resolvedId, "cancelled", { cancelledAt });
-        emitToSubscribers(resolvedId, { type: "cancelled", taskId: resolvedId, cancelledAt });
-        return;
-      }
-      const startedAt = Date.now();
-      await transition(resolvedId, "running", { startedAt });
-      emitToSubscribers(resolvedId, { type: "started", taskId: resolvedId, startedAt });
-      await runWorkAndFinalize(resolvedId, aborter, internal.work);
-    } finally {
-      release();
-      state.aborters.delete(resolvedId);
-    }
-  })();
-  return queuedHandle;
-}
-async function list(filter = {}) {
-  return state.store.list(filter);
-}
-async function get(id) {
-  if (!isValidTaskId(id, true)) return void 0;
-  return state.store.get(id);
-}
-async function cancel(id, reason) {
-  if (!isValidTaskId(id, true)) return { cancelled: false, alreadyTerminal: false };
-  const handle = await state.store.get(id);
-  if (handle === void 0) return { cancelled: false, alreadyTerminal: false };
-  if (handle.state === "finished" || handle.state === "error" || handle.state === "cancelled") {
-    return { cancelled: false, alreadyTerminal: true };
-  }
-  const span = startTaskCancelSpan({
-    taskId: id,
-    ...reason !== void 0 ? { reason } : {},
-    via: "api"
-  });
-  try {
-    return await cancelInternal(id, handle.state, reason);
-  } finally {
-    span.end();
-  }
-}
-async function cancelInternal(id, currentState, reason) {
-  if (currentState === "queued") {
-    const cancelledAt = Date.now();
-    await transition(id, "cancelled", { cancelledAt });
-    emitToSubscribers(id, {
-      type: "cancelled",
-      taskId: id,
-      cancelledAt,
-      ...reason !== void 0 ? { reason } : {}
-    });
-    state.aborters.delete(id);
-    return { cancelled: true, alreadyTerminal: false };
-  }
-  const aborter = state.aborters.get(id);
-  if (aborter !== void 0) aborter.abort(reason ?? "cancelled");
-  return { cancelled: true, alreadyTerminal: false };
-}
-async function evictNow(now = Date.now()) {
-  return state.store.evictTerminalOlderThan(now - state.retentionMs);
-}
-var DEFAULT_CONCURRENCY, DEFAULT_RETENTION_MS, EVICTION_INTERVAL_MS, RING_CAP, reentryAls, state, subscribe;
-var init_registry = __esm({
-  "src/internal/task/registry.ts"() {
-    init_errors();
-    init_task();
-    init_async_semaphore();
-    init_ring_buffer();
-    init_store();
-    init_subscribe();
-    init_telemetry();
-    DEFAULT_CONCURRENCY = 8;
-    DEFAULT_RETENTION_MS = 60 * 60 * 1e3;
-    EVICTION_INTERVAL_MS = 5 * 60 * 1e3;
-    RING_CAP = 64;
-    reentryAls = new AsyncLocalStorage();
-    state = buildState({});
-    subscribe = buildSubscribe({
-      getBuffer: (id) => state.buffers.get(id),
-      getOrCreateSubscriberSet: (id) => {
-        let subs = state.subscribers.get(id);
-        if (subs === void 0) {
-          subs = /* @__PURE__ */ new Set();
-          state.subscribers.set(id, subs);
-        }
-        return subs;
-      },
-      removeSubscriber: (id, cb) => {
-        const set = state.subscribers.get(id);
-        set?.delete(cb);
-        if (set !== void 0 && set.size === 0) state.subscribers.delete(id);
-      }
-    });
-  }
-});
-function toJsonSchema(schema, options = { unrepresentable: "any" }) {
-  return toJSONSchema(schema, options);
-}
-var init_to_json_schema = __esm({
-  "src/internal/zod/to-json-schema.ts"() {
-  }
-});
-function requireZod() {
-  if (cachedZ !== void 0) return cachedZ;
-  const r = createRequire(import.meta.url);
-  let mod;
-  try {
-    mod = r("zod");
-  } catch (cause) {
-    throw new ConfigurationError(
-      'Structured output requires the optional peer dependency `zod`. Add `"zod": "^3.25.0 || ^4.0.0"` to your package.json and reinstall.',
-      { code: "zod_not_installed", cause }
-    );
-  }
-  cachedZ = mod.z ?? mod;
-  return cachedZ;
-}
-function makeOutputTool(jsonSchema, onCapture) {
-  return {
-    name: "output",
-    description: "Call this tool with your final structured answer. Match the JSON schema exactly.",
-    inputSchema: jsonSchema,
-    handler: (input) => {
-      const out = onCapture(input);
-      if (typeof out === "string") return out;
-      if (out instanceof Promise) return out;
-      return "";
-    }
-  };
-}
-function buildTransientAgentOptions(params) {
-  return {
-    model: params.model,
-    local: params.local,
-    tools: [params.outputTool],
-    systemPrompt: params.systemPrompt ?? "You produce structured output by calling the `output` tool exactly once. Match the JSON schema.",
-    ...params.apiKey !== void 0 ? { apiKey: params.apiKey } : {},
-    ...params.providers !== void 0 ? { providers: params.providers } : {}
-  };
-}
-function extractUsage2(result) {
-  const u = result.usage;
-  if (u === void 0) return { inputTokens: 0, outputTokens: 0 };
-  return { inputTokens: u.inputTokens ?? 0, outputTokens: u.outputTokens ?? 0 };
-}
-function buildToolPrompt(prompt) {
-  return `${prompt}
-
-Respond by calling the \`output\` tool with the structured answer that matches the schema.`;
-}
-function setupStructuredOutput(schema, maxRetries) {
-  const z8 = requireZod();
-  const jsonSchema = toJsonSchema(schema, { unrepresentable: "any" });
-  return {
-    z: z8,
-    jsonSchema,
-    maxRetries: maxRetries ?? 1,
-    initialUsage: { inputTokens: 0, outputTokens: 0 }
-  };
-}
-async function disposeAndDeleteTransient(agent, deletor) {
-  await agent.dispose();
-  try {
-    await deletor(agent.agentId);
-  } catch {
-  }
-}
-var cachedZ;
-var init_structured_output_helpers = __esm({
-  "src/internal/structured-output-helpers.ts"() {
-    init_errors();
-    init_to_json_schema();
-  }
-});
-
-// src/generate-object.ts
-var generate_object_exports = {};
-__export(generate_object_exports, {
-  GenerateObjectError: () => GenerateObjectError,
-  generateObjectImpl: () => generateObjectImpl
-});
-function salvagePartial(schema, raw) {
-  if (typeof raw !== "object" || raw === null) return raw;
-  const shape = schema.shape;
-  if (shape === void 0 || typeof shape !== "object") return raw;
-  const rawObj = raw;
-  const out = {};
-  for (const [key2, fieldSchema] of Object.entries(shape)) {
-    if (typeof fieldSchema?.safeParse !== "function") continue;
-    const parsed = fieldSchema.safeParse(rawObj[key2]);
-    if (parsed.success) out[key2] = parsed.data;
-  }
-  return out;
-}
-async function runReasoningPhase(options, deps) {
-  const reasoningOptions = {
-    model: options.model,
-    local: options.local,
-    ...options.systemPrompt !== void 0 ? { systemPrompt: options.systemPrompt } : {},
-    ...options.apiKey !== void 0 ? { apiKey: options.apiKey } : {},
-    ...options.providers !== void 0 ? { providers: options.providers } : {}
-  };
-  const reasoningAgent = await deps.create(reasoningOptions);
-  try {
-    const run = await reasoningAgent.send(options.prompt);
-    const result = await run.wait();
-    const text = result.result;
-    return typeof text === "string" ? text : options.prompt;
-  } finally {
-    await disposeAndDeleteTransient(reasoningAgent, deps.delete);
-  }
-}
-async function generateObjectImpl(options, deps) {
-  const { jsonSchema, maxRetries, initialUsage } = setupStructuredOutput(
-    options.schema,
-    options.maxRetries
-  );
-  let capturedRaw;
-  let lastUsage = initialUsage;
-  const sentinel = /* @__PURE__ */ Symbol("generate-object-sentinel");
-  class CaptureSentinel extends Error {
-    constructor(captured) {
-      super("generate-object-capture");
-      this.captured = captured;
-    }
-    captured;
-    [sentinel] = true;
-  }
-  const outputTool = makeOutputTool(jsonSchema, (input) => {
-    if (capturedRaw === void 0) {
-      capturedRaw = input;
-    }
-    throw new CaptureSentinel(input);
-  });
-  const reasoningText = options.structuringModel !== void 0 ? await runReasoningPhase(options, deps) : void 0;
-  const structuringModel = options.structuringModel ?? options.model;
-  const structuringPrompt = reasoningText ?? options.prompt;
-  const agentOptions = buildTransientAgentOptions({
-    model: structuringModel,
-    local: options.local,
-    outputTool,
-    ...options.systemPrompt !== void 0 ? { systemPrompt: options.systemPrompt } : {},
-    ...options.apiKey !== void 0 ? { apiKey: options.apiKey } : {},
-    ...options.providers !== void 0 ? { providers: options.providers } : {}
-  });
-  const agent = await deps.create(agentOptions);
-  try {
-    const userMessage = buildToolPrompt(structuringPrompt);
-    let lastParseError;
-    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
-      capturedRaw = void 0;
-      const run = await agent.send(userMessage);
-      const result = await run.wait();
-      lastUsage = extractUsage2(result);
-      if (capturedRaw === void 0) {
-        if (result.status === "error" && result.error !== void 0) {
-          throw new GenerateObjectError(
-            "no_tool_call",
-            `Agent run failed before the model could reply: ${result.error.message ?? "unknown error"} [${result.error.code ?? "?"}]`,
-            result.error
-          );
-        }
-        if (attempt === maxRetries) {
-          throw new GenerateObjectError(
-            "no_tool_call",
-            "The model returned text instead of calling the `output` tool."
-          );
-        }
-        continue;
-      }
-      const parsed = options.schema.safeParse(capturedRaw);
-      if (parsed.success) {
-        return {
-          object: parsed.data,
-          raw: capturedRaw,
-          usage: lastUsage,
-          finishReason: "tool_use"
-        };
+  const release = await acquireSlot();
+  void (async () => {
+    try {
+      await checkCancelRequestedAt(resolvedId, aborter);
+      if (aborter.signal.aborted) {
+        const cancelledAt = Date.now();
+        await transition(resolvedId, "cancelled", { cancelledAt });
+        emitToSubscribers(resolvedId, { type: "cancelled", taskId: resolvedId, cancelledAt });
+        return;
       }
-      lastParseError = parsed.error;
-    }
-    if (options.errorStrategy === "return-raw") {
-      return {
-        object: capturedRaw,
-        raw: capturedRaw,
-        usage: lastUsage,
-        finishReason: "tool_use"
-      };
-    }
-    if (options.errorStrategy === "return-partial") {
-      return {
-        object: salvagePartial(options.schema, capturedRaw),
-        raw: capturedRaw,
-        usage: lastUsage,
-        finishReason: "tool_use"
-      };
+      const startedAt = Date.now();
+      await transition(resolvedId, "running", { startedAt });
+      emitToSubscribers(resolvedId, { type: "started", taskId: resolvedId, startedAt });
+      await runWorkAndFinalize(resolvedId, aborter, internal.work);
+    } finally {
+      release();
+      state.aborters.delete(resolvedId);
     }
-    throw new GenerateObjectError(
-      "parse_failed",
-      "Schema parse failed after all retries.",
-      lastParseError
-    );
+  })();
+  return queuedHandle;
+}
+async function list(filter = {}) {
+  return state.store.list(filter);
+}
+async function get(id) {
+  if (!isValidTaskId(id, true)) return void 0;
+  return state.store.get(id);
+}
+async function cancel(id, reason) {
+  if (!isValidTaskId(id, true)) return { cancelled: false, alreadyTerminal: false };
+  const handle = await state.store.get(id);
+  if (handle === void 0) return { cancelled: false, alreadyTerminal: false };
+  if (handle.state === "finished" || handle.state === "error" || handle.state === "cancelled") {
+    return { cancelled: false, alreadyTerminal: true };
+  }
+  const span = startTaskCancelSpan({
+    taskId: id,
+    ...reason !== void 0 ? { reason } : {},
+    via: "api"
+  });
+  try {
+    return await cancelInternal(id, handle.state, reason);
   } finally {
-    await disposeAndDeleteTransient(agent, deps.delete);
+    span.end();
   }
 }
-var GenerateObjectError;
-var init_generate_object = __esm({
-  "src/generate-object.ts"() {
-    init_structured_output_helpers();
-    GenerateObjectError = class extends Error {
-      name = "GenerateObjectError";
-      code;
-      cause;
-      constructor(code, message, cause) {
-        super(message);
-        this.code = code;
-        if (cause !== void 0) this.cause = cause;
+async function cancelInternal(id, currentState, reason) {
+  if (currentState === "queued") {
+    const cancelledAt = Date.now();
+    await transition(id, "cancelled", { cancelledAt });
+    emitToSubscribers(id, {
+      type: "cancelled",
+      taskId: id,
+      cancelledAt,
+      ...reason !== void 0 ? { reason } : {}
+    });
+    state.aborters.delete(id);
+    return { cancelled: true, alreadyTerminal: false };
+  }
+  const aborter = state.aborters.get(id);
+  if (aborter !== void 0) aborter.abort(reason ?? "cancelled");
+  return { cancelled: true, alreadyTerminal: false };
+}
+async function evictNow(now = Date.now()) {
+  return state.store.evictTerminalOlderThan(now - state.retentionMs);
+}
+var DEFAULT_CONCURRENCY, DEFAULT_RETENTION_MS, EVICTION_INTERVAL_MS, RING_CAP, reentryAls, state, subscribe;
+var init_registry = __esm({
+  "src/internal/task/registry.ts"() {
+    init_errors();
+    init_task();
+    init_async_semaphore();
+    init_ring_buffer();
+    init_store();
+    init_subscribe();
+    init_telemetry();
+    DEFAULT_CONCURRENCY = 8;
+    DEFAULT_RETENTION_MS = 60 * 60 * 1e3;
+    EVICTION_INTERVAL_MS = 5 * 60 * 1e3;
+    RING_CAP = 64;
+    reentryAls = new AsyncLocalStorage();
+    state = buildState({});
+    subscribe = buildSubscribe({
+      getBuffer: (id) => state.buffers.get(id),
+      getOrCreateSubscriberSet: (id) => {
+        let subs = state.subscribers.get(id);
+        if (subs === void 0) {
+          subs = /* @__PURE__ */ new Set();
+          state.subscribers.set(id, subs);
+        }
+        return subs;
+      },
+      removeSubscriber: (id, cb) => {
+        const set = state.subscribers.get(id);
+        set?.delete(cb);
+        if (set !== void 0 && set.size === 0) state.subscribers.delete(id);
       }
-    };
+    });
   }
 });
 
@@ -3993,7 +3993,7 @@ async function* streamObjectImpl(options, deps) {
         }
       }
       const result = await run.wait();
-      lastUsage = extractUsage2(result);
+      lastUsage = extractUsage(result);
       if (capturedRaw === void 0) {
         if (result.status === "error" && result.error !== void 0) {
           throw new StreamObjectError(
@@ -4745,7 +4745,10 @@ async function runAgentStep(step, input, ctx) {
     };
   }
   const exec = async () => {
-    const run = await step.agent.send(prompt);
+    const run = await step.agent.send(
+      prompt,
+      step.origin !== void 0 ? { origin: step.origin } : void 0
+    );
     const result = await run.wait();
     if (result.status === "finished") {
       return result.result ?? "";
@@ -5517,6 +5520,7 @@ var AgentBuilder = class {
   constructor(deps) {
     this.deps = deps;
   }
+  /** SE8 — accepts a bare-string id shorthand (`"openai/gpt-4o-mini"`) or a {@link ModelSelection}. */
   model(m) {
     this.opts.model = m;
     return this;
@@ -5874,13 +5878,87 @@ function isLocalAgentId(id) {
   return id.startsWith(PREFIX.localAgent);
 }
 
+// src/internal/runtime/config/default-model.ts
+var DEFAULT_AGENTIC_MODEL_ID = "google/gemini-2.0-flash-001";
+
+// src/agent-generate.ts
+async function agentGenerate(agent, agentModel, agentApiKey, agentLocal, input, options) {
+  const { output, maxRetries, errorStrategy, ...sendOptions } = options;
+  const run = await agent.send(input, sendOptions);
+  const result = await run.wait();
+  const { generateObjectImpl: generateObjectImpl2, GenerateObjectError: GenerateObjectError2 } = await Promise.resolve().then(() => (init_generate_object(), generate_object_exports));
+  const answer = structurableAnswerOrThrow(result, GenerateObjectError2);
+  const { getAgentFacade: getAgentFacade2 } = await Promise.resolve().then(() => (init_agent_factory_registry(), agent_factory_registry_exports));
+  const facade = getAgentFacade2();
+  const structured = await generateObjectImpl2(
+    {
+      prompt: answer,
+      schema: output,
+      // `agentModel` arrives already normalized (`this.model` passed through
+      // `normalizeModel` in the LocalAgent/CloudAgent constructor), so the widened
+      // `string | ModelSelection` field only ever receives a `ModelSelection` here.
+      model: agentModel ?? { id: DEFAULT_AGENTIC_MODEL_ID },
+      // `local` is required to keep the transient structuring agent local-only;
+      // default to the process cwd when the agent had no explicit local config.
+      local: agentLocal ?? { cwd: process.cwd() },
+      ...agentApiKey !== void 0 ? { apiKey: agentApiKey } : {},
+      ...maxRetries !== void 0 ? { maxRetries } : {},
+      ...errorStrategy !== void 0 ? { errorStrategy } : {}
+    },
+    {
+      create: (opts) => facade.create(opts),
+      delete: (agentId) => facade.delete(agentId)
+    }
+  );
+  return {
+    object: structured.object,
+    result,
+    raw: structured.raw,
+    usage: structured.usage
+  };
+}
+function structurableAnswerOrThrow(result, GenerateObjectError2) {
+  if (result.status === "error") {
+    throw new GenerateObjectError2(
+      "no_tool_call",
+      `Agent run failed before an answer could be structured: ${result.error?.message ?? "unknown error"} [${result.error?.code ?? "?"}]`,
+      result.error
+    );
+  }
+  if (result.status === "cancelled") {
+    throw new GenerateObjectError2(
+      "no_tool_call",
+      "Agent run was cancelled before an answer could be structured."
+    );
+  }
+  const answer = result.result;
+  if (answer === void 0 || answer.length === 0) {
+    throw new GenerateObjectError2(
+      "no_tool_call",
+      "The tool loop finished with no text answer (tool-only completion) \u2014 there is nothing to structure."
+    );
+  }
+  return answer;
+}
+
 // src/internal/runtime/cloud/cloud-agent.ts
 init_errors();
 init_cwd_mutex();
 init_path_guard();
 
-// src/internal/runtime/config/default-model.ts
-var DEFAULT_AGENTIC_MODEL_ID = "google/gemini-2.0-flash-001";
+// src/internal/runtime/model-selection.ts
+init_errors();
+function normalizeModel(m) {
+  if (m === void 0 || typeof m !== "string") return m;
+  const id = m.trim();
+  if (id.length === 0) {
+    throw new ConfigurationError(
+      'model must be a non-empty "provider/model" id string or a ModelSelection object',
+      { code: "invalid_model_selection" }
+    );
+  }
+  return { id };
+}
 
 // src/internal/runtime/registry/agent-registry-store.ts
 init_cwd_mutex();
@@ -5957,7 +6035,10 @@ var REGISTRY_RELATIVE_PATH = join(".theokit", "agents", "registry.json");
 function stripSecretsFromOptions(options) {
   return assignDefined({
     name: options.name,
-    model: options.model !== void 0 ? { id: options.model.id } : void 0,
+    model: (() => {
+      const m = normalizeModel(options.model);
+      return m !== void 0 ? { id: m.id } : void 0;
+    })(),
     systemPrompt: typeof options.systemPrompt === "string" ? options.systemPrompt : void 0,
     local: serializeLocal(options.local),
     cloud: serializeCloud(options.cloud),
@@ -6242,7 +6323,8 @@ function serializeCloudAgentConfig(options) {
     cloud: serializeCloud2(options.cloud)
   };
   if (typeof options.agentId === "string") payload.agentId = options.agentId;
-  if (options.model !== void 0) payload.model = { id: options.model.id };
+  const cfgModel = normalizeModel(options.model);
+  if (cfgModel !== void 0) payload.model = { id: cfgModel.id };
   if (typeof options.systemPrompt === "string") payload.systemPrompt = options.systemPrompt;
   const skills = serializeSkills(options.skills);
   if (skills !== void 0) payload.skills = skills;
@@ -7047,6 +7129,7 @@ function applyScriptMetrics(base, script) {
   if (script.cost !== void 0) base.cost = script.cost;
   if (script.stoppedAtIterationLimit === true) base.stoppedAtIterationLimit = true;
   if (script.stoppedByDoomLoop === true) base.stoppedByDoomLoop = true;
+  if (script.origin !== void 0) base.origin = script.origin;
 }
 
 // src/internal/runtime/cloud/cloud-run.ts
@@ -7402,7 +7485,7 @@ var CloudAgent = class {
   disposed = false;
   constructor(options, providedAgentId) {
     this.agentId = providedAgentId ?? options.agentId ?? generateCloudAgentId();
-    this.model = options.model;
+    this.model = normalizeModel(options.model);
     this.options = options;
     this.cloudPayload = serializeCloudAgentConfig({ ...options, agentId: this.agentId });
     const repoUrls = (options.cloud?.repos ?? []).map((repo) => repo.url);
@@ -7432,6 +7515,17 @@ var CloudAgent = class {
     const apiKey = resolveApiKey(this.options.apiKey);
     return isFixtureApiKey(apiKey) && getConfiguredBaseUrl() === void 0;
   }
+  // SE9 — integrated structured output; delegates to the shared helper.
+  generate(message, options) {
+    return agentGenerate(
+      this,
+      this.model,
+      this.options.apiKey,
+      this.options.local,
+      message,
+      options
+    );
+  }
   async send(message, options = {}) {
     if (options.tools !== void 0 && options.tools.length > 0) {
       throw new ConfigurationError(
@@ -7462,7 +7556,7 @@ var CloudAgent = class {
     });
   }
   async sendLocked(message, options) {
-    const overrideModel = options.model;
+    const overrideModel = normalizeModel(options.model);
     if (overrideModel !== void 0) {
       this.model = overrideModel;
       updateRegisteredAgent(this.agentId, { model: overrideModel });
@@ -8379,18 +8473,18 @@ var ALL_ADAPTERS = [
   arizeAdapter,
   braintrustAdapter
 ];
-var registered = /* @__PURE__ */ new Set();
+var registered2 = /* @__PURE__ */ new Set();
 function tryAutoRegisterAdapters(settings) {
   if (settings?.enabled !== true) return;
   if (settings.autoDetect === false) return;
   const disabled = new Set(settings.disable ?? []);
   for (const adapter of ALL_ADAPTERS) {
-    if (registered.has(adapter.moduleName)) continue;
+    if (registered2.has(adapter.moduleName)) continue;
     if (disabled.has(adapter.displayName.toLowerCase())) continue;
     if (!adapter.detect()) continue;
     try {
       adapter.register();
-      registered.add(adapter.moduleName);
+      registered2.add(adapter.moduleName);
       process.stderr.write(`[theokit-sdk] telemetry: ${adapter.displayName} auto-instrumented.
 `);
     } catch (cause) {
@@ -8920,6 +9014,26 @@ function paginate(items, opts) {
   return items.slice(start, end);
 }
 
+// src/internal/persistence/session-meta.ts
+function applyMetaPatch(current, patch) {
+  const next = {};
+  if (current.title !== void 0) next.title = current.title;
+  if (current.tag !== void 0) next.tag = current.tag;
+  if (patch.title === null) delete next.title;
+  else if (patch.title !== void 0) next.title = patch.title;
+  if (patch.tag === null) delete next.tag;
+  else if (patch.tag !== void 0) next.tag = patch.tag;
+  return next;
+}
+function coerceSessionMeta(raw) {
+  if (typeof raw !== "object" || raw === null) return void 0;
+  const obj = raw;
+  const meta = {};
+  if (typeof obj.title === "string") meta.title = obj.title;
+  if (typeof obj.tag === "string") meta.tag = obj.tag;
+  return meta.title === void 0 && meta.tag === void 0 ? void 0 : meta;
+}
+
 // src/internal/persistence/conversation-storage-fs.ts
 var FileSystemConversationStorage = class {
   #root;
@@ -8970,6 +9084,37 @@ var FileSystemConversationStorage = class {
   async compact(conversationId, maxTurns) {
     await compactSessionFile(this.#root, conversationId, maxTurns);
   }
+  // SE4 — session metadata persisted as a per-conversation sidecar
+  // `<root>/.theokit/agents/<safeId>/session.json` (same sanitized perimeter as
+  // the transcript). Kept separate from messages.jsonl so a title/tag write does
+  // not rewrite the append-only log.
+  #metaPath(conversationId) {
+    const safe2 = sanitizeIdentifier(conversationId, { maxLen: 128 });
+    return safePathJoin(this.#root, ".theokit", "agents", safe2, "session.json");
+  }
+  async getSessionMeta(conversationId) {
+    try {
+      const raw = await readFile(this.#metaPath(conversationId), "utf8");
+      return coerceSessionMeta(JSON.parse(raw));
+    } catch (cause) {
+      if (cause.code === "ENOENT") return void 0;
+      throw cause;
+    }
+  }
+  async setSessionMeta(conversationId, patch) {
+    const metaPath = this.#metaPath(conversationId);
+    await mkdir(dirname(metaPath), { recursive: true });
+    await withFileLock(metaPath, async () => {
+      let current = {};
+      try {
+        current = coerceSessionMeta(JSON.parse(await readFile(metaPath, "utf8"))) ?? {};
+      } catch (cause) {
+        if (cause.code !== "ENOENT") throw cause;
+      }
+      const next = applyMetaPatch(current, patch);
+      await writeFile(metaPath, redactSecrets(JSON.stringify(next)), "utf8");
+    });
+  }
   async dispose() {
   }
 };
@@ -10891,7 +11036,7 @@ function bootstrapSubmanagers(args) {
   const providerCount = (args.options.providers?.routes?.length ?? 0) + enabledPluginNames(args.options.plugins).length;
   if (providerCount > 0 || args.options.providers !== void 0) {
     out.providers = new ProvidersManagerImpl(
-      args.options.model,
+      normalizeModel(args.options.model),
       args.options.providers,
       args.options.plugins
     );
@@ -10961,6 +11106,7 @@ function createLocalRun(options) {
     projectMcpServers: options.projectMcpServers,
     ...options.persistMemoryFact !== void 0 ? { persistMemoryFact: options.persistMemoryFact } : {}
   });
+  if (options.sendOptions.origin !== void 0) script.origin = options.sendOptions.origin;
   const handle = new LocalRun({
     id,
     agentId: options.agentId,
@@ -11609,6 +11755,15 @@ async function emitReasoningDeltaCallback(inputs, text) {
   );
 }
 
+// src/types/run-events.ts
+function emitRunEvent(sink, event) {
+  if (sink === void 0) return;
+  try {
+    sink(event);
+  } catch {
+  }
+}
+
 // src/internal/agent-loop/tool-dispatch.ts
 init_async_local_storage();
 
@@ -11706,6 +11861,22 @@ function coerceArgsToSchema(args, schema) {
   return { value: out, changed };
 }
 
+// src/tool-error.ts
+init_errors();
+var ToolError = class extends TheokitAgentError {
+  name = "ToolError";
+  /** The error content surfaced to the model: a string, or text/image blocks. */
+  content;
+  constructor(content, options = {}) {
+    super(renderToolErrorMessage(content), { ...options, isRetryable: false });
+    this.content = content;
+  }
+};
+function renderToolErrorMessage(content) {
+  if (typeof content === "string") return content;
+  return content.map((block) => block.type === "text" ? block.text : `[${block.source.media_type} image]`).join("\n");
+}
+
 // src/internal/runtime/tools/shell-tool.ts
 async function runShell(options) {
   if (options.sandbox === true && isObviouslyUnsafe(options.command)) {
@@ -11745,23 +11916,27 @@ async function executeTool(inputs, resolved, call) {
   if (resolved.origin === "shell") return runShellTool(inputs, call);
   if (resolved.origin === "memory") return runMemoryTool(resolved, call, inputs.context);
   if (resolved.origin === "custom")
-    return runCustomTool(resolved, call, inputs.signal, inputs.context);
+    return runCustomTool(resolved, call, inputs.signal, inputs.context, inputs.messages);
   return runMcpTool(inputs, resolved, call);
 }
 async function runMemoryTool(resolved, call, context) {
   return runHandlerTool("memory", resolved.memoryHandler, call, void 0, context);
 }
-async function runCustomTool(resolved, call, signal, context) {
-  return runHandlerTool("custom", resolved.customHandler, call, signal, context);
+async function runCustomTool(resolved, call, signal, context, messages) {
+  return runHandlerTool("custom", resolved.customHandler, call, signal, context, messages);
 }
-async function runHandlerTool(kind, handler, call, signal, context) {
+async function runHandlerTool(kind, handler, call, signal, context, messages) {
   if (handler === void 0) {
     return { stdout: "", stderr: `${kind} tool ${call.name} has no handler`, exitCode: 127 };
   }
   try {
-    const stdout = await handler(call.input, { signal, context });
-    return { stdout, stderr: "", exitCode: 0 };
+    const out = await handler(call.input, { signal, context, messages });
+    if (typeof out !== "string") return { stdout: "", stderr: "", exitCode: 0, content: out };
+    return { stdout: out, stderr: "", exitCode: 0 };
   } catch (cause) {
+    if (cause instanceof ToolError) {
+      return { stdout: "", stderr: cause.message, exitCode: 1, content: cause.content };
+    }
     const message = cause instanceof Error ? cause.message : String(cause);
     return { stdout: "", stderr: message, exitCode: 1 };
   }
@@ -11880,6 +12055,11 @@ async function dispatchSingleCall(inputs, tools, call, events, parentSpan) {
     toolSpan?.end();
     return fileVeto;
   }
+  emitRunEvent(inputs.runEventSink, {
+    type: "tool_progress",
+    toolName: workingCall.name,
+    toolCallId: callId
+  });
   const result = await runToolWithLifecycle(inputs, resolved, workingCall, callId);
   await inputs.pluginManager?.runPostToolCallHooks({
     name: workingCall.name,
@@ -11906,6 +12086,13 @@ function applyRepairAndExtractCall(tools, call) {
 function vetoFromForkWhitelist(inputs, call, callId, events) {
   const whitelistDecision = checkToolWhitelist(call.name);
   if (whitelistDecision.allowed) return void 0;
+  emitRunEvent(inputs.runEventSink, {
+    type: "permission_denied",
+    toolName: call.name,
+    toolCallId: callId,
+    source: "fork_whitelist",
+    message: whitelistDecision.reason ?? "tool not available in fork"
+  });
   events.push(buildToolUseRunning(inputs, callId, call));
   events.push(
     buildToolUseCompleted(inputs, callId, call, {
@@ -11942,6 +12129,13 @@ async function vetoFromPluginPreHook(inputs, call, callId, events) {
     runId: inputs.runId
   });
   if (pluginVeto === void 0) return void 0;
+  emitRunEvent(inputs.runEventSink, {
+    type: "permission_denied",
+    toolName: call.name,
+    toolCallId: callId,
+    source: "plugin",
+    message: pluginVeto.message
+  });
   events.push(
     buildToolUseCompleted(inputs, callId, call, {
       stdout: "",
@@ -11964,6 +12158,13 @@ async function vetoFromFileHookPreDecision(inputs, call, callId, events) {
     runId: inputs.runId
   });
   if (!preDecision.blocked) return void 0;
+  emitRunEvent(inputs.runEventSink, {
+    type: "permission_denied",
+    toolName: call.name,
+    toolCallId: callId,
+    source: "file_hook",
+    message: preDecision.reason ?? "blocked by hook"
+  });
   events.push(
     buildToolUseCompleted(inputs, callId, call, {
       stdout: "",
@@ -12007,7 +12208,9 @@ async function runToolWithLifecycle(inputs, resolved, call, callId) {
     await safeEmitToolHook(inputs.onToolEnd, {
       toolName: call.name,
       args: call.input,
-      result: result.stdout,
+      // SE7 — a block-returning handler has empty `stdout`; surface its structured
+      // content to the hook instead of an empty string.
+      result: result.content !== void 0 ? result.content : result.stdout,
       conversationId: inputs.agentId,
       callId,
       durationMs
@@ -12029,7 +12232,10 @@ function finalizeSpanAndPostHook(inputs, call, callId, result, events, toolSpan)
     output: {
       stdout: result.stdout,
       stderr: result.stderr,
-      exitCode: result.exitCode ?? 0
+      exitCode: result.exitCode ?? 0,
+      // SE7 — structured content (text + image blocks) when the handler
+      // returned/threw blocks; absent for the string path.
+      ...result.content !== void 0 ? { content: result.content } : {}
     },
     agentId: inputs.agentId,
     runId: inputs.runId
@@ -12042,7 +12248,9 @@ function finalizeSpanAndPostHook(inputs, call, callId, result, events, toolSpan)
   return {
     type: "tool_result",
     toolUseId: call.id,
-    content: renderToolResult(result),
+    // SE7 — structured content blocks (handler-returned or ToolError-carried)
+    // are authoritative; otherwise the legacy string rendering.
+    content: result.content !== void 0 ? result.content : renderToolResult(result),
     ...result.exitCode !== 0 && result.exitCode !== void 0 ? { isError: true } : {}
   };
 }
@@ -12091,6 +12299,29 @@ function buildToolUseCompleted(inputs, callId, call, result) {
   };
 }
 
+// src/internal/llm/tool-result-content.ts
+init_errors();
+function toBlockToolResultContent(content) {
+  return content;
+}
+function toStringToolResultContent(content, providerName) {
+  if (typeof content === "string") return content;
+  if (content.some((block) => block.type === "image")) {
+    throw new ConfigurationError(
+      `provider "${providerName}" does not support image content in tool results`
+    );
+  }
+  return content.filter(
+    (block) => block.type === "text"
+  ).map((block) => block.text).join("\n");
+}
+function renderToolResultContentText(content, fn) {
+  if (typeof content === "string") return fn(content);
+  return content.map(
+    (block) => block.type === "text" ? { type: "text", text: fn(block.text) } : block
+  );
+}
+
 // src/internal/agent-loop/tool-result-guard.ts
 var OPEN = "<untrusted-tool-output>";
 var CLOSE = "</untrusted-tool-output>";
@@ -12116,7 +12347,11 @@ ${CLOSE}`;
 function applyToolResultGuard(parts, opts) {
   if (opts.delimit !== true && opts.redactPii !== true) return parts;
   return parts.map(
-    (p) => p.type === "tool_result" ? { ...p, content: guardText(p.content, opts) } : p
+    (p) => (
+      // SE7 — guard the TEXT of a tool result (string or the text blocks of a
+      // structured content); image blocks pass through untouched.
+      p.type === "tool_result" ? { ...p, content: renderToolResultContentText(p.content, (t) => guardText(t, opts)) } : p
+    )
   );
 }
 
@@ -12455,6 +12690,14 @@ function computeUsageCost(inputs, usage) {
 }
 
 // src/internal/agent-loop/loop.ts
+function projectToolContextMessages(messages) {
+  const projected = [];
+  for (const m of messages) {
+    const content = m.content.flatMap((p) => p.type === "text" ? [p.text] : []).join("");
+    if (content !== "") projected.push({ role: m.role, content });
+  }
+  return projected;
+}
 var MAX_NUDGE_ATTEMPTS = 2;
 var MAX_STOP_FEEDBACK_ATTEMPTS = 2;
 async function runAgentLoop(inputs) {
@@ -12697,7 +12940,9 @@ async function continueOrTerminate(inputs, ctx, llmOutput) {
   const outText = await transformLlmOutputText(inputs, llmOutput.text, tCtx);
   ctx.messages.push(buildAssistantTurn(outText, llmOutput.toolCalls));
   const rawResults = await dispatchTools(
-    inputs,
+    // SE12 — forward a read-only text projection of the transcript-so-far to tool
+    // handlers via `ctx.messages` (consumed by defineSubAgent's messageFilter).
+    { ...inputs, messages: projectToolContextMessages(ctx.messages) },
     ctx.tools,
     llmOutput.toolCalls,
     ctx.events,
@@ -13047,10 +13292,10 @@ function stripVertexPrefix(modelId) {
 }
 
 // src/internal/providers/builtin/index.ts
-var registered2 = false;
+var registered3 = false;
 function registerBuiltins() {
-  if (registered2) return;
-  registered2 = true;
+  if (registered3) return;
+  registered3 = true;
   registerProvider(ANTHROPIC);
   registerProvider(OPENAI);
   registerProvider(OPENROUTER);
@@ -13279,7 +13524,9 @@ function toAnthropicWireMessage(message) {
     return {
       type: "tool_result",
       tool_use_id: part.toolUseId,
-      content: part.content,
+      // SE7 — this wire is block-capable: strings pass through, structured
+      // text/image blocks are forwarded natively.
+      content: toBlockToolResultContent(part.content),
       ...part.isError === true ? { is_error: true } : {}
     };
   });
@@ -14071,7 +14318,8 @@ function toOllamaMessages(message) {
       if (part.type === "tool_result") {
         out.push({
           role: "tool",
-          content: part.content,
+          // SE7 — string-only tool role: text blocks flatten; image fails fast.
+          content: toStringToolResultContent(part.content, "ollama"),
           tool_name: part.toolUseId
         });
       }
@@ -14608,7 +14856,9 @@ function userOrToolMessages(message) {
       out.push({
         role: "tool",
         tool_call_id: part.toolUseId,
-        content: part.content
+        // SE7 — this wire's tool role is string-only: text blocks flatten; an
+        // image block fails fast (ConfigurationError).
+        content: toStringToolResultContent(part.content, "openai")
       });
     }
   }
@@ -15538,18 +15788,20 @@ function levenshtein(a, b) {
 function createRealLocalRun(options) {
   const { userText, id, startTime } = prepareRunContext(options.message);
   const supported = /* @__PURE__ */ new Set(["stream", "wait", "cancel", "conversation"]);
-  const unusedFixtureScript = {
+  const runScript = {
     events: [],
     finalStatus: "running",
     cancellable: false,
-    conversation: []
+    conversation: [],
+    // SE3 — carry the turn's provenance so buildResult forwards it onto RunResult.origin.
+    ...options.sendOptions.origin !== void 0 ? { origin: options.sendOptions.origin } : {}
   };
   const handle = new RealLocalRun(
     {
       id,
       agentId: options.agentId,
       model: options.model,
-      script: unusedFixtureScript,
+      script: runScript,
       supportedOps: supported,
       startTime
     },
@@ -15661,6 +15913,8 @@ function buildLoopInputs(options, runId, userText) {
     // M7 — forward SendOptions.context to the loop so every tool handler receives
     // it on `ctx.context` (shared run config set once, e.g. projectRoot).
     ...options.sendOptions.context !== void 0 ? { context: options.sendOptions.context } : {},
+    // SE2 — forward the opt-in typed runtime-event sink to the loop.
+    ...options.sendOptions.onRunEvent !== void 0 ? { runEventSink: options.sendOptions.onRunEvent } : {},
     // #58 / #57 — forward the per-tool timeout + tool-result guard so a consumer
     // can enable them via SendOptions (not only internal AgentLoopInputs).
     ...options.sendOptions.perToolTimeoutMs !== void 0 ? { perToolTimeoutMs: options.sendOptions.perToolTimeoutMs } : {},
@@ -17405,7 +17659,7 @@ function wrapRunWithPostReplyHook(args) {
 async function executeSendLocked(inputs, message, options) {
   if (inputs.disposed) throw new AgentDisposedError(inputs.agentId);
   await consumePending(inputs.agentId, inputs.invalidationPending, inputs.clearInvalidation, inputs.reload);
-  inputs.applyModelOverride(options.model);
+  inputs.applyModelOverride(normalizeModel(options.model));
   const userText = typeof message === "string" ? message : message.text;
   if (inputs.options.onBeforeSend !== void 0) {
     await inputs.options.onBeforeSend({
@@ -17557,7 +17811,7 @@ var LocalAgent = class {
   constructor(options) {
     this.agentId = options.agentId ?? generateLocalAgentId();
     this._telemetry = createTelemetry(options.telemetry);
-    this.model = options.model;
+    this.model = normalizeModel(options.model);
     this.options = options;
     this.workspaceCwd = resolveCwd(options.local?.cwd);
     this.conversationStorage = options.conversationStorage;
@@ -17624,6 +17878,11 @@ var LocalAgent = class {
   hooks() {
     return this.hooksExecutor;
   }
+  // SE9 — integrated structured output; delegates to the shared helper.
+  generate(message, options) {
+    const { apiKey, local } = this.options;
+    return agentGenerate(this, this.model, apiKey, local, message, options);
+  }
   async send(message, options = {}) {
     if (options.tools !== void 0 && options.tools.length > 0) {
       validateToolCatalog(options.tools);
@@ -17863,6 +18122,7 @@ function includesSetting(options, source) {
 
 // src/agent-helpers.ts
 async function runCreateUnderSpan(options, span) {
+  options = { ...options, model: normalizeModel(options.model) };
   validateAgentOptions(options);
   validateCloudToolParity(options);
   await guardAgainstIdCollision(options);
@@ -17936,7 +18196,10 @@ async function createLocalAgent(options) {
   const willFlowToProvider = !isFixtureApiKey(apiKey) && !shouldUseRealLocalRuntime(apiKey);
   const shape = validateApiKeyShape(apiKey, {
     strict: willFlowToProvider,
-    ...willFlowToProvider ? { provider: providerFromModelId(options.model?.id) } : {}
+    // `options.model` is already normalized by `runCreateUnderSpan`; `normalizeModel`
+    // here is the idempotent narrowing of the widened public type (`{id}` passes
+    // through by reference) — cleaner than an `as` cast.
+    ...willFlowToProvider ? { provider: providerFromModelId(normalizeModel(options.model)?.id) } : {}
   });
   if (shape.malformed) {
     throw new AuthenticationError(shape.message, { code: "malformed_api_key" });
@@ -18002,6 +18265,10 @@ async function rehydrateExistingAgent(agentId, existing, options) {
     ...existing.options,
     ...options,
     ...mergedLocal !== void 0 ? { local: mergedLocal } : {},
+    // SE8 — normalize a caller-supplied bare-string model override at this resume
+    // boundary (Agent.resume never flows through runCreateUnderSpan). Cloud resume
+    // honors it; local resume forces the persisted model below.
+    model: normalizeModel(options.model ?? existing.options.model),
     mcpServers: void 0,
     agentId
   };
@@ -18368,6 +18635,7 @@ async function getOrCreateUncached(agentId, options) {
 }
 setAgentFacade({
   create: (options) => Agent.create(options),
+  delete: (agentId) => Agent.delete(agentId),
   prompt: (message, options) => Agent.prompt(message, options),
   get: (agentId) => Agent.get(agentId),
   resume: (agentId, options) => Agent.resume(agentId, options),
@@ -19328,6 +19596,8 @@ init_generate_object();
 // src/internal/persistence/conversation-storage-memory.ts
 var InMemoryConversationStorage = class {
   #store = /* @__PURE__ */ new Map();
+  // SE4 — session-level metadata (title/tag), kept beside the transcript.
+  #meta = /* @__PURE__ */ new Map();
   async getMessages(conversationId, opts) {
     const existing = this.#store.get(conversationId);
     return existing === void 0 ? [] : paginate(existing.slice(), opts);
@@ -19356,15 +19626,20 @@ var InMemoryConversationStorage = class {
   }
   async deleteConversation(conversationId) {
     this.#store.delete(conversationId);
+    this.#meta.delete(conversationId);
   }
   async deleteScope(prefix) {
     let n = 0;
     for (const id of [...this.#store.keys()]) {
       if (id.startsWith(prefix)) {
         this.#store.delete(id);
+        this.#meta.delete(id);
         n += 1;
       }
     }
+    for (const id of [...this.#meta.keys()]) {
+      if (id.startsWith(prefix)) this.#meta.delete(id);
+    }
     return n;
   }
   async listConversationIds(opts) {
@@ -19372,8 +19647,17 @@ var InMemoryConversationStorage = class {
     if (opts?.limit !== void 0) return all.slice(0, opts.limit);
     return all;
   }
+  async getSessionMeta(conversationId) {
+    const meta = this.#meta.get(conversationId);
+    return meta === void 0 ? void 0 : { ...meta };
+  }
+  async setSessionMeta(conversationId, patch) {
+    const current = this.#meta.get(conversationId) ?? {};
+    this.#meta.set(conversationId, applyMetaPatch(current, patch));
+  }
   async dispose() {
     this.#store.clear();
+    this.#meta.clear();
   }
 };
 
@@ -20113,6 +20397,21 @@ async function migrateSqliteToLance2(options) {
 }
 
 // src/permission-engine.ts
+function applyMode(verdict, mode, explicit) {
+  if (verdict === "deny") return "deny";
+  switch (mode) {
+    case "default":
+      return verdict;
+    case "plan":
+      return verdict === "allow" ? "allow" : "deny";
+    case "acceptEdits":
+      if (verdict === "ask") return explicit ? "ask" : "allow";
+      return verdict;
+    // allow stays allow
+    case "bypass":
+      return "allow";
+  }
+}
 function argMatches(matcher, value) {
   if (typeof matcher === "function") return matcher(value);
   if (value === void 0) return false;
@@ -20133,14 +20432,14 @@ var PermissionEngine = class {
    * argument values, so the same tool name can resolve to different actions
    * depending on what it is asked to do.
    */
-  evaluate(toolName, args) {
+  evaluate(toolName, args, mode = "default") {
     for (const rule of this.rules) {
       const nameMatches = typeof rule.tool === "string" ? rule.tool === toolName : rule.tool.test(toolName);
       if (!nameMatches) continue;
       if (rule.args !== void 0 && !this.#argsMatch(rule.args, args)) continue;
-      return rule.action;
+      return applyMode(rule.action, mode, true);
     }
-    return this.defaultAction;
+    return applyMode(this.defaultAction, mode, false);
   }
   #argsMatch(matchers, args) {
     const call = args ?? {};
@@ -20152,21 +20451,32 @@ var PermissionEngine = class {
 };
 
 // src/permission-plugin.ts
+async function resolveAsk(opts, name, args, mode) {
+  if (opts.canUseTool !== void 0) {
+    let decision;
+    try {
+      decision = await opts.canUseTool(name, args, { toolName: name, mode });
+    } catch {
+      return { block: true, message: `permission gate error (fail-closed): ${name}` };
+    }
+    return decision.behavior === "deny" ? { block: true, message: decision.message ?? `denied: ${name}` } : void 0;
+  }
+  return opts.onAsk ? opts.onAsk(name) : { block: true, message: `requires approval: ${name}` };
+}
 function createPermissionPlugin(engine, opts = {}) {
+  const mode = opts.mode ?? "default";
   return definePlugin({
     name: opts.name ?? "permission-engine",
     version: "1.0.0",
     kind: "general",
     register(ctx) {
-      ctx.on("pre_tool_call", (rawCtx) => {
+      ctx.on("pre_tool_call", async (rawCtx) => {
         const { name, args } = rawCtx;
-        const action = engine.evaluate(name, args);
+        const action = engine.evaluate(name, args, mode);
         if (action === "deny") {
           return { block: true, message: `denied by permission engine: ${name}` };
         }
-        if (action === "ask") {
-          return opts.onAsk ? opts.onAsk(name) : { block: true, message: `requires approval: ${name}` };
-        }
+        if (action === "ask") return resolveAsk(opts, name, args, mode);
         return void 0;
       });
     }
@@ -20272,6 +20582,96 @@ var Security = class {
   }
 };
 
+// src/session-manager.ts
+var SUMMARY_PREVIEW_MAX = 80;
+function createSessionManager(storage2) {
+  return {
+    async listSessions(opts) {
+      if (typeof storage2.listConversationIds !== "function") {
+        return {
+          supported: false,
+          reason: "storage adapter does not support listing conversations (listConversationIds)"
+        };
+      }
+      const ids = await storage2.listConversationIds();
+      if (ids === void 0) {
+        return {
+          supported: false,
+          reason: "storage adapter reported listing as unsupported (listConversationIds \u2192 undefined)"
+        };
+      }
+      const windowed = windowIds(ids, opts);
+      const summaries = [];
+      for (const id of windowed) {
+        summaries.push(await buildSummary(storage2, id));
+      }
+      return { supported: true, value: summaries };
+    },
+    getSessionMessages(id, opts) {
+      return storage2.getMessages(id, opts);
+    },
+    async renameSession(id, title) {
+      if (typeof storage2.setSessionMeta !== "function") {
+        return unsupportedWrite();
+      }
+      await storage2.setSessionMeta(id, { title });
+      return { supported: true, value: void 0 };
+    },
+    async tagSession(id, tag) {
+      if (typeof storage2.setSessionMeta !== "function") {
+        return unsupportedWrite();
+      }
+      await storage2.setSessionMeta(id, { tag });
+      return { supported: true, value: void 0 };
+    }
+  };
+}
+function unsupportedWrite() {
+  return {
+    supported: false,
+    reason: "storage adapter does not support writing session metadata (setSessionMeta)"
+  };
+}
+function windowIds(ids, opts) {
+  const start = opts?.offset !== void 0 && opts.offset > 0 ? opts.offset : 0;
+  const rawLimit = opts?.limit;
+  if (rawLimit !== void 0 && rawLimit <= 0) return [];
+  const end = rawLimit !== void 0 ? start + rawLimit : void 0;
+  return ids.slice(start, end);
+}
+async function buildSummary(storage2, id) {
+  const messages = await storage2.getMessages(id);
+  const firstUser = messages.find((m) => m.role === "user")?.content;
+  const firstPrompt = firstUser !== void 0 && firstUser.length > 0 ? firstUser : void 0;
+  const lastModified = deriveLastModified(messages);
+  const meta = typeof storage2.getSessionMeta === "function" ? await storage2.getSessionMeta(id) : void 0;
+  const title = meta?.title;
+  const tag = meta?.tag;
+  const summary = title ?? previewOf(firstPrompt);
+  return {
+    id,
+    messageCount: messages.length,
+    ...firstPrompt !== void 0 ? { firstPrompt } : {},
+    ...lastModified !== void 0 ? { lastModified } : {},
+    ...title !== void 0 ? { title } : {},
+    ...tag !== void 0 ? { tag } : {},
+    ...summary !== void 0 ? { summary } : {}
+  };
+}
+function deriveLastModified(messages) {
+  let last;
+  for (const m of messages) {
+    if (m.at !== void 0 && (last === void 0 || m.at > last)) last = m.at;
+  }
+  return last;
+}
+function previewOf(text) {
+  if (text === void 0) return void 0;
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  if (oneLine.length === 0) return void 0;
+  return oneLine.length > SUMMARY_PREVIEW_MAX ? `${oneLine.slice(0, SUMMARY_PREVIEW_MAX - 1)}\u2026` : oneLine;
+}
+
 // src/session-scope.ts
 function scopedConversationId(scope, id) {
   return `${scope}__${id}`;
@@ -20292,7 +20692,7 @@ var PersistenceSchema = z.object({
 // src/workflow.ts
 init_path_guard();
 init_workflow();
-z.object({
+var RetryPolicySchema = z.object({
   // EC-3 absorbed: maxAttempts MUST be a finite int in [1, 20].
   maxAttempts: z.number().int("retry.maxAttempts must be integer").min(1, "retry.maxAttempts must be >= 1").max(20, "retry.maxAttempts must be <= 20"),
   initialBackoffMs: z.number().int().min(0).optional(),
@@ -20490,12 +20890,15 @@ var Workflow = class {
 };
 function agentStep(id, agent, promptTemplate, opts) {
   validateStepId(id);
+  if (opts?.retry !== void 0) RetryPolicySchema.parse(opts.retry);
   return {
     kind: "agent",
     id,
     agent,
     promptTemplate,
-    ...{}
+    ...opts?.retry !== void 0 ? { retry: opts.retry } : {},
+    // SE3 — carry the turn's provenance down to `agent.send()` (metadata-only).
+    ...opts?.origin !== void 0 ? { origin: opts.origin } : {}
   };
 }
 function validateStepId(id) {
@@ -20543,7 +20946,8 @@ function createSquad(options) {
       for (let i = 0; i < agents2.length; i++) {
         const agent = agents2[i];
         if (agent === void 0) continue;
-        builder = builder.then(agentStep(`agent-${i}`, agent, (prev) => String(prev)));
+        const opts = i > 0 ? { origin: { kind: "peer", from: `agent-${i - 1}` } } : void 0;
+        builder = builder.then(agentStep(`agent-${i}`, agent, (prev) => String(prev), opts));
       }
       const run = await builder.commit().run(input);
       return { result: run.output, status: run.status, steps: run.stepResults };
@@ -20997,6 +21401,6 @@ function safeStringify2(v) {
   }
 }
 
-export { Agent, AgentBuilder, AgentDisposedError, AgentRunError, AuthenticationError, Budget, BudgetExceededError, ConfigurationError, Cron, EventBus, FileSystemConversationStorage, GenerateObjectError, InMemoryConversationStorage, IntegrationNotConnectedError, InvalidTaskIdError, JobQueue, Memory, MemoryAdapterError, NetworkError, PermissionEngine, RateLimitError, Security, StreamObjectError, Task, TaskNotFoundError, Theokit, TheokitAgentError, UnknownAgentError, UnsupportedBudgetOperationError, UnsupportedRunOperationError, UnsupportedTaskOperationError, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createPermissionPlugin, createSkill, createSquad, definePlugin, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isTransientError, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDisposedError, AgentRunError, AuthenticationError, Budget, BudgetExceededError, ConfigurationError, Cron, EventBus, FileSystemConversationStorage, GenerateObjectError, InMemoryConversationStorage, IntegrationNotConnectedError, InvalidTaskIdError, JobQueue, Memory, MemoryAdapterError, NetworkError, PermissionEngine, RateLimitError, Security, StreamObjectError, Task, TaskNotFoundError, Theokit, TheokitAgentError, ToolError, UnknownAgentError, UnsupportedBudgetOperationError, UnsupportedRunOperationError, UnsupportedTaskOperationError, UsageAccumulator, applyMode, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createPermissionPlugin, createSessionManager, createSkill, createSquad, definePlugin, defineProvider, defineTool, emitRunEvent, extractRawId, getPricingEntry, inferApiMode, isTransientError, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, scopedConversationId, sessionScopePrefix, toShareGptTrajectory, withCwdMutex };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map