@theokit/sdk 2.20.0 → 2.21.0

package/dist/cron.js

@@ -1,10 +1,10 @@
+import { z, toJSONSchema } from 'zod';
+import { createRequire } from 'module';
 import { randomUUID, randomBytes, createHash } from 'crypto';
-import { readFile, unlink, mkdir, open, rename, statfs, stat, rm, readdir, appendFile, access } from 'fs/promises';
+import { readFile, unlink, mkdir, open, rename, statfs, stat, rm, readdir, writeFile, appendFile, access } from 'fs/promises';
 import { join, dirname, resolve, sep, relative, isAbsolute } from 'path';
-import { z, toJSONSchema } from 'zod';
 import { mkdirSync, readdirSync, existsSync, realpathSync, lstatSync, readlinkSync, readFileSync } from 'fs';
 import { AsyncLocalStorage } from 'async_hooks';
-import { createRequire } from 'module';
 import { homedir } from 'os';
 import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
@@ -510,6 +510,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 z6 = requireZod();
+  const jsonSchema = toJsonSchema(schema, { unrepresentable: "any" });
+  return {
+    z: z6,
+    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 [key, fieldSchema] of Object.entries(shape)) {
+    if (typeof fieldSchema?.safeParse !== "function") continue;
+    const parsed = fieldSchema.safeParse(rawObj[key]);
+    if (parsed.success) out[key] = 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(key, fn) {
@@ -1427,29 +1677,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, {
@@ -1614,14 +1841,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 };
   }
@@ -2054,345 +2281,118 @@ async function runWorkAndFinalize(taskId, aborter, work) {
     emit(payload) {
       void checkCancelRequestedAt(taskId, aborter);
       emitToSubscribers(taskId, {
-        type: "progress",
-        taskId,
-        at: Date.now(),
-        payload
-      });
-    }
-  };
-  try {
-    const result = await reentryAls.run(true, () => Promise.resolve().then(() => work(ctx)));
-    if (aborter.signal.aborted) {
-      const cancelledAt = Date.now();
-      await transition(taskId, "cancelled", { cancelledAt });
-      emitToSubscribers(taskId, { type: "cancelled", taskId, cancelledAt });
-      return;
-    }
-    const finishedAt = Date.now();
-    await transition(taskId, "finished", { finishedAt, result });
-    emitToSubscribers(taskId, { type: "finished", taskId, finishedAt, result });
-  } catch (err) {
-    if (aborter.signal.aborted) {
-      const cancelledAt = Date.now();
-      await transition(taskId, "cancelled", { cancelledAt });
-      emitToSubscribers(taskId, { type: "cancelled", taskId, cancelledAt });
-      return;
-    }
-    const erroredAt = Date.now();
-    const error = err instanceof Error ? { code: err.code ?? "work_threw", message: err.message } : { code: "work_threw", message: String(err) };
-    await transition(taskId, "error", { erroredAt, error });
-    emitToSubscribers(taskId, { type: "errored", taskId, erroredAt, error });
-  }
-}
-async function checkCancelRequestedAt(taskId, aborter) {
-  if (aborter.signal.aborted) return;
-  try {
-    const handle = await state.store.get(taskId);
-    if (handle?.cancelRequested === true) {
-      aborter.abort("cancelRequested");
-    }
-  } catch {
-  }
-}
-async function acquireSlot() {
-  if (reentryAls.getStore() === true) {
-    return () => {
-    };
-  }
-  return state.semaphore.acquire();
-}
-async function submit(internal) {
-  state.firstSubmitSeen = true;
-  startEvictTimerIfNeeded();
-  const resolvedId = resolveIdInternal(internal);
-  const submitSpan = startTaskSubmitSpan({ taskId: resolvedId, kind: internal.kind });
-  const existing = await state.store.get(resolvedId);
-  if (existing !== void 0) {
-    submitSpan.end();
-    return existing;
-  }
-  const queuedHandle = await buildAndInsertQueued(internal, resolvedId);
-  submitSpan.end();
-  if (internal.signal?.aborted === true) {
-    return shortCircuitAborted(queuedHandle, internal.signal);
-  }
-  const aborter = new AbortController();
-  state.aborters.set(resolvedId, aborter);
-  if (internal.signal !== void 0) {
-    internal.signal.addEventListener("abort", () => aborter.abort(internal.signal?.reason), {
-      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 get(id) {
-  if (!isValidTaskId(id, true)) return void 0;
-  return state.store.get(id);
-}
-var DEFAULT_CONCURRENCY, DEFAULT_RETENTION_MS, EVICTION_INTERVAL_MS, RING_CAP, reentryAls, state;
-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({});
-  }
-});
-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 z6 = requireZod();
-  const jsonSchema = toJsonSchema(schema, { unrepresentable: "any" });
-  return {
-    z: z6,
-    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 [key, fieldSchema] of Object.entries(shape)) {
-    if (typeof fieldSchema?.safeParse !== "function") continue;
-    const parsed = fieldSchema.safeParse(rawObj[key]);
-    if (parsed.success) out[key] = 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);
+        type: "progress",
+        taskId,
+        at: Date.now(),
+        payload
+      });
+    }
+  };
   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"
-        };
-      }
-      lastParseError = parsed.error;
+    const result = await reentryAls.run(true, () => Promise.resolve().then(() => work(ctx)));
+    if (aborter.signal.aborted) {
+      const cancelledAt = Date.now();
+      await transition(taskId, "cancelled", { cancelledAt });
+      emitToSubscribers(taskId, { type: "cancelled", taskId, cancelledAt });
+      return;
     }
-    if (options.errorStrategy === "return-raw") {
-      return {
-        object: capturedRaw,
-        raw: capturedRaw,
-        usage: lastUsage,
-        finishReason: "tool_use"
-      };
+    const finishedAt = Date.now();
+    await transition(taskId, "finished", { finishedAt, result });
+    emitToSubscribers(taskId, { type: "finished", taskId, finishedAt, result });
+  } catch (err) {
+    if (aborter.signal.aborted) {
+      const cancelledAt = Date.now();
+      await transition(taskId, "cancelled", { cancelledAt });
+      emitToSubscribers(taskId, { type: "cancelled", taskId, cancelledAt });
+      return;
     }
-    if (options.errorStrategy === "return-partial") {
-      return {
-        object: salvagePartial(options.schema, capturedRaw),
-        raw: capturedRaw,
-        usage: lastUsage,
-        finishReason: "tool_use"
-      };
+    const erroredAt = Date.now();
+    const error = err instanceof Error ? { code: err.code ?? "work_threw", message: err.message } : { code: "work_threw", message: String(err) };
+    await transition(taskId, "error", { erroredAt, error });
+    emitToSubscribers(taskId, { type: "errored", taskId, erroredAt, error });
+  }
+}
+async function checkCancelRequestedAt(taskId, aborter) {
+  if (aborter.signal.aborted) return;
+  try {
+    const handle = await state.store.get(taskId);
+    if (handle?.cancelRequested === true) {
+      aborter.abort("cancelRequested");
     }
-    throw new GenerateObjectError(
-      "parse_failed",
-      "Schema parse failed after all retries.",
-      lastParseError
-    );
-  } finally {
-    await disposeAndDeleteTransient(agent, deps.delete);
+  } catch {
   }
 }
-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 acquireSlot() {
+  if (reentryAls.getStore() === true) {
+    return () => {
     };
   }
+  return state.semaphore.acquire();
+}
+async function submit(internal) {
+  state.firstSubmitSeen = true;
+  startEvictTimerIfNeeded();
+  const resolvedId = resolveIdInternal(internal);
+  const submitSpan = startTaskSubmitSpan({ taskId: resolvedId, kind: internal.kind });
+  const existing = await state.store.get(resolvedId);
+  if (existing !== void 0) {
+    submitSpan.end();
+    return existing;
+  }
+  const queuedHandle = await buildAndInsertQueued(internal, resolvedId);
+  submitSpan.end();
+  if (internal.signal?.aborted === true) {
+    return shortCircuitAborted(queuedHandle, internal.signal);
+  }
+  const aborter = new AbortController();
+  state.aborters.set(resolvedId, aborter);
+  if (internal.signal !== void 0) {
+    internal.signal.addEventListener("abort", () => aborter.abort(internal.signal?.reason), {
+      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 get(id) {
+  if (!isValidTaskId(id, true)) return void 0;
+  return state.store.get(id);
+}
+var DEFAULT_CONCURRENCY, DEFAULT_RETENTION_MS, EVICTION_INTERVAL_MS, RING_CAP, reentryAls, state;
+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({});
+  }
 });
 
 // src/stream-object.ts
@@ -2449,7 +2449,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(
@@ -2795,6 +2795,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;
@@ -3148,6 +3149,69 @@ 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();
@@ -3298,8 +3362,19 @@ function safeFilenameForId(id, options) {
   return `h-${createHash("sha256").update(id).digest("hex").slice(0, 16)}`;
 }
 
-// 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();
@@ -3376,7 +3451,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),
@@ -3661,7 +3739,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;
@@ -4557,6 +4636,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
@@ -4912,7 +4992,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);
@@ -4942,6 +5022,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(
@@ -4972,7 +5063,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 });
@@ -5886,18 +5977,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) {
@@ -6460,6 +6551,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;
@@ -6510,6 +6621,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() {
   }
 };
@@ -8429,7 +8571,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
     );
@@ -8499,6 +8641,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,
@@ -9147,6 +9290,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();
 
@@ -9244,6 +9396,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)) {
@@ -9297,9 +9465,13 @@ async function runHandlerTool(kind, handler, call, signal, context) {
     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 });
+    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 };
   }
@@ -9418,6 +9590,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,
@@ -9444,6 +9621,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, {
@@ -9480,6 +9664,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: "",
@@ -9502,6 +9693,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: "",
@@ -9545,7 +9743,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
@@ -9567,7 +9767,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
@@ -9580,7 +9783,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 } : {}
   };
 }
@@ -9629,6 +9834,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>";
@@ -9654,7 +9882,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
+    )
   );
 }
 
@@ -10571,10 +10803,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);
@@ -10802,7 +11034,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 } : {}
     };
   });
@@ -11594,7 +11828,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
         });
       }
@@ -12131,7 +12366,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")
       });
     }
   }
@@ -13060,18 +13297,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
     },
@@ -13183,6 +13422,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 } : {},
@@ -15875,7 +16116,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({
@@ -16027,7 +16268,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;
@@ -16094,6 +16335,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);
@@ -16333,6 +16579,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);
@@ -16406,7 +16653,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" });
@@ -16472,6 +16722,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
   };
@@ -16838,6 +17092,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),