@theokit/sdk 2.20.0 → 2.22.0

package/dist/a2a/index.js

@@ -1,10 +1,10 @@
 import { existsSync, realpathSync, mkdirSync, lstatSync, readlinkSync, readFileSync, readdirSync } from 'fs';
 import { randomUUID, createHash, randomBytes } from 'crypto';
-import { join, dirname, resolve, sep, relative, isAbsolute } from 'path';
-import { stat, mkdir, readFile, rename, rm, readdir, open, unlink, appendFile, statfs, access } from 'fs/promises';
-import { homedir } from 'os';
 import { z, toJSONSchema } from 'zod';
 import { createRequire } from 'module';
+import { join, dirname, resolve, sep, relative, isAbsolute } from 'path';
+import { stat, mkdir, readFile, rename, rm, readdir, writeFile, open, unlink, appendFile, statfs, access } from 'fs/promises';
+import { homedir } from 'os';
 import { spawn } from 'child_process';
 import { AsyncLocalStorage } from 'async_hooks';
 import { fileURLToPath } from 'url';
@@ -29,6 +29,7 @@ var init_agent_builder = __esm({
       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;
@@ -895,6 +896,329 @@ var init_ids = __esm({
   }
 });
 
+// src/internal/runtime/config/default-model.ts
+var DEFAULT_AGENTIC_MODEL_ID;
+var init_default_model = __esm({
+  "src/internal/runtime/config/default-model.ts"() {
+    DEFAULT_AGENTIC_MODEL_ID = "google/gemini-2.0-flash-001";
+  }
+});
+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 z7 = requireZod();
+  const jsonSchema = toJsonSchema(schema, { unrepresentable: "any" });
+  return {
+    z: z7,
+    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/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;
+}
+var init_agent_generate = __esm({
+  "src/agent-generate.ts"() {
+    init_default_model();
+  }
+});
+
 // src/internal/persistence/cwd-mutex.ts
 function withCwdMutex(key, fn) {
   const prev = tails.get(key) ?? Promise.resolve();
@@ -1064,11 +1388,21 @@ var init_path_guard = __esm({
   }
 });
 
-// src/internal/runtime/config/default-model.ts
-var DEFAULT_AGENTIC_MODEL_ID;
-var init_default_model = __esm({
-  "src/internal/runtime/config/default-model.ts"() {
-    DEFAULT_AGENTIC_MODEL_ID = "google/gemini-2.0-flash-001";
+// src/internal/runtime/model-selection.ts
+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 };
+}
+var init_model_selection = __esm({
+  "src/internal/runtime/model-selection.ts"() {
+    init_errors();
   }
 });
 function detectNetworkFsName(typeMagic) {
@@ -1208,7 +1542,10 @@ var init_enabled_names = __esm({
 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),
@@ -1379,6 +1716,7 @@ var init_agent_registry_store = __esm({
     init_cwd_mutex();
     init_schema_version();
     init_enabled_names();
+    init_model_selection();
     SCHEMA_VERSION = 1;
     LEGACY_SCHEMA_VERSION_STRING = "1.0";
     REGISTRY_RELATIVE_PATH = join(".theokit", "agents", "registry.json");
@@ -1514,7 +1852,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;
@@ -1624,6 +1963,7 @@ function serializeMemory2(memory) {
 var init_cloud_config_serializer = __esm({
   "src/internal/runtime/cloud/cloud-config-serializer.ts"() {
     init_enabled_names();
+    init_model_selection();
   }
 });
 
@@ -2334,6 +2674,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;
 }
 var FixtureRunBase;
 var init_fixture_run_base = __esm({
@@ -2841,6 +3182,7 @@ function buildFixtureArtifacts() {
 var CloudAgent;
 var init_cloud_agent = __esm({
   "src/internal/runtime/cloud/cloud-agent.ts"() {
+    init_agent_generate();
     init_errors();
     init_env();
     init_fixture_mode();
@@ -2848,6 +3190,7 @@ var init_cloud_agent = __esm({
     init_cwd_mutex();
     init_path_guard();
     init_default_model();
+    init_model_selection();
     init_agent_registry();
     init_system_prompt();
     init_cloud_config_serializer();
@@ -2867,7 +3210,7 @@ var init_cloud_agent = __esm({
       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);
@@ -2897,6 +3240,17 @@ var init_cloud_agent = __esm({
         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(
@@ -2927,7 +3281,7 @@ var init_cloud_agent = __esm({
         });
       }
       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 });
@@ -4121,12 +4475,12 @@ function tryAutoRegisterAdapters(settings) {
   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) {
@@ -4138,7 +4492,7 @@ function tryAutoRegisterAdapters(settings) {
     }
   }
 }
-var ALL_ADAPTERS, registered;
+var ALL_ADAPTERS, registered2;
 var init_adapter_registry = __esm({
   "src/internal/telemetry/adapter-registry.ts"() {
     init_arize();
@@ -4157,7 +4511,7 @@ var init_adapter_registry = __esm({
       arizeAdapter,
       braintrustAdapter
     ];
-    registered = /* @__PURE__ */ new Set();
+    registered2 = /* @__PURE__ */ new Set();
   }
 });
 function loadOtel() {
@@ -4748,6 +5102,30 @@ var init_pagination = __esm({
   "src/internal/persistence/pagination.ts"() {
   }
 });
+
+// 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;
+}
+var init_session_meta = __esm({
+  "src/internal/persistence/session-meta.ts"() {
+  }
+});
 function toStoredMessage(record) {
   return {
     role: record.role,
@@ -4763,7 +5141,9 @@ var init_conversation_storage_fs = __esm({
   "src/internal/persistence/conversation-storage-fs.ts"() {
     init_agent_session_store();
     init_security();
+    init_file_lock();
     init_pagination();
+    init_session_meta();
     FileSystemConversationStorage = class {
       #root;
       constructor(opts = {}) {
@@ -4813,6 +5193,37 @@ var init_conversation_storage_fs = __esm({
       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() {
       }
     };
@@ -6876,7 +7287,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
     );
@@ -6913,6 +7324,7 @@ var init_local_agent_bootstrap = __esm({
     init_enabled_names();
     init_providers_manager();
     init_context_manager();
+    init_model_selection();
     init_plugins_manager();
     init_agent_registry();
     init_skills_manager();
@@ -6961,6 +7373,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,
@@ -7661,6 +8074,19 @@ var init_loop_llm_stream = __esm({
     init_message_builders();
   }
 });
+
+// src/types/run-events.ts
+function emitRunEvent(sink, event) {
+  if (sink === void 0) return;
+  try {
+    sink(event);
+  } catch {
+  }
+}
+var init_run_events = __esm({
+  "src/types/run-events.ts"() {
+  }
+});
 async function withToolWhitelist(whitelist, fn) {
   return toolWhitelistStore.run(whitelist, fn);
 }
@@ -7832,6 +8258,27 @@ var init_repair_middleware = __esm({
   }
 });
 
+// src/tool-error.ts
+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");
+}
+var ToolError;
+var init_tool_error = __esm({
+  "src/tool-error.ts"() {
+    init_errors();
+    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;
+      }
+    };
+  }
+});
+
 // src/internal/runtime/tools/shell-tool.ts
 async function runShell(options) {
   if (options.sandbox === true && isObviouslyUnsafe(options.command)) {
@@ -7876,23 +8323,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 };
   }
@@ -7937,6 +8388,7 @@ ${result.stderr}`.trim();
 }
 var init_tool_executors = __esm({
   "src/internal/agent-loop/tool-executors.ts"() {
+    init_tool_error();
     init_shell_tool();
   }
 });
@@ -8021,6 +8473,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,
@@ -8047,6 +8504,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, {
@@ -8083,6 +8547,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: "",
@@ -8105,6 +8576,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: "",
@@ -8148,7 +8626,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
@@ -8170,7 +8650,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
@@ -8183,7 +8666,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 } : {}
   };
 }
@@ -8233,6 +8718,7 @@ function buildToolUseCompleted(inputs, callId, call, result) {
 }
 var init_tool_dispatch = __esm({
   "src/internal/agent-loop/tool-dispatch.ts"() {
+    init_run_events();
     init_ids();
     init_async_local_storage();
     init_map_with_concurrency();
@@ -8243,6 +8729,33 @@ var init_tool_dispatch = __esm({
   }
 });
 
+// src/internal/llm/tool-result-content.ts
+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
+  );
+}
+var init_tool_result_content = __esm({
+  "src/internal/llm/tool-result-content.ts"() {
+    init_errors();
+  }
+});
+
 // src/internal/agent-loop/tool-result-guard.ts
 function guardText(content, opts) {
   let out = content;
@@ -8260,12 +8773,17 @@ ${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
+    )
   );
 }
 var OPEN, CLOSE, PII_PATTERNS;
 var init_tool_result_guard = __esm({
   "src/internal/agent-loop/tool-result-guard.ts"() {
+    init_tool_result_content();
     OPEN = "<untrusted-tool-output>";
     CLOSE = "</untrusted-tool-output>";
     PII_PATTERNS = [
@@ -8644,6 +9162,14 @@ var init_usage_and_cost = __esm({
 });
 
 // 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;
+}
 async function runAgentLoop(inputs) {
   const sendSpan = inputs.telemetry?.startSpan("agent.send", {
     agentId: inputs.agentId,
@@ -8884,7 +9410,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,
@@ -9298,8 +9826,8 @@ var init_vertex = __esm({
 
 // src/internal/providers/builtin/index.ts
 function registerBuiltins() {
-  if (registered2) return;
-  registered2 = true;
+  if (registered3) return;
+  registered3 = true;
   registerProvider(ANTHROPIC);
   registerProvider(OPENAI);
   registerProvider(OPENROUTER);
@@ -9311,7 +9839,7 @@ function registerBuiltins() {
   registerProvider(VERTEX);
   registerCatalogProviders();
 }
-var registered2;
+var registered3;
 var init_builtin = __esm({
   "src/internal/providers/builtin/index.ts"() {
     init_catalog_loader();
@@ -9325,7 +9853,7 @@ var init_builtin = __esm({
     init_openai();
     init_openrouter();
     init_vertex();
-    registered2 = false;
+    registered3 = false;
   }
 });
 
@@ -9570,7 +10098,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 } : {}
     };
   });
@@ -9647,6 +10177,7 @@ function encodeAnthropicSystem(system) {
 var init_anthropic_shared = __esm({
   "src/internal/llm/anthropic-shared.ts"() {
     init_finish();
+    init_tool_result_content();
   }
 });
 
@@ -10601,7 +11132,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
         });
       }
@@ -10642,6 +11174,7 @@ var init_ollama_native = __esm({
   "src/internal/llm/ollama-native.ts"() {
     init_ollama2();
     init_finish();
+    init_tool_result_content();
     OllamaNativeClient = class {
       constructor(options) {
         this.options = options;
@@ -11006,7 +11539,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")
       });
     }
   }
@@ -11037,6 +11572,7 @@ var init_openai2 = __esm({
     init_finish();
     init_hermes_tool_extract();
     init_sse();
+    init_tool_result_content();
     OpenAIClient = class {
       constructor(options) {
         this.options = options;
@@ -12276,18 +12812,20 @@ var init_personality_filter = __esm({
 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
     },
@@ -12398,6 +12936,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 } : {},
@@ -15458,39 +15998,16 @@ Goal: ${ctx.goal}
 Subgoals: ${subgoals}
 Last agent response: ${ctx.lastResponse}
 
-Respond with EXACTLY one of:
-- DONE: <reason>
-- CONTINUE: <what's left>
-- SKIPPED: <why not applicable>
-
-Be strict. If unclear, prefer CONTINUE.`;
-}
-var init_judge_call = __esm({
-  "src/internal/judge/judge-call.ts"() {
-    init_parse_verdict();
-  }
-});
-
-// 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;
+Respond with EXACTLY one of:
+- DONE: <reason>
+- CONTINUE: <what's left>
+- SKIPPED: <why not applicable>
+
+Be strict. If unclear, prefer CONTINUE.`;
 }
-var registered3;
-var init_agent_factory_registry = __esm({
-  "src/internal/runtime/registry/agent-factory-registry.ts"() {
+var init_judge_call = __esm({
+  "src/internal/judge/judge-call.ts"() {
+    init_parse_verdict();
   }
 });
 
@@ -15658,14 +16175,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 };
   }
@@ -15824,7 +16341,7 @@ var init_local_agent_memory_hooks = __esm({
 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({
@@ -15893,6 +16410,7 @@ var init_local_agent_send = __esm({
     init_abort_utils();
     init_memory_path_selector();
     init_memory_store();
+    init_model_selection();
     init_agent_session();
     init_safe_call();
     init_local_agent_invalidate();
@@ -16472,6 +16990,7 @@ function includesSetting(options, source) {
 var LocalAgent;
 var init_local_agent = __esm({
   "src/internal/runtime/local-agent/local-agent.ts"() {
+    init_agent_generate();
     init_errors();
     init_ids();
     init_cwd_mutex();
@@ -16482,6 +17001,7 @@ var init_local_agent = __esm({
     init_hooks_executor();
     init_post_run_lifecycle();
     init_memory_path_selector();
+    init_model_selection();
     init_agent_registry();
     init_live_agent_registry();
     init_agent_session();
@@ -16558,7 +17078,7 @@ var init_local_agent = __esm({
       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;
@@ -16625,6 +17145,11 @@ var init_local_agent = __esm({
       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);
@@ -16857,6 +17382,7 @@ var init_local_agent = __esm({
   }
 });
 async function runCreateUnderSpan(options, span) {
+  options = { ...options, model: normalizeModel(options.model) };
   validateAgentOptions(options);
   validateCloudToolParity(options);
   await guardAgainstIdCollision(options);
@@ -16930,7 +17456,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" });
@@ -16996,6 +17525,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
   };
@@ -17078,237 +17611,11 @@ var init_agent_helpers = __esm({
     init_cloud_agent();
     init_cloud_tool_parity();
     init_local_agent();
+    init_model_selection();
     init_agent_registry();
     init_validate_agent_options();
   }
 });
-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 z7 = requireZod();
-  const jsonSchema = toJsonSchema(schema, { unrepresentable: "any" });
-  return {
-    z: z7,
-    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 = 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;
-    }
-    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/stream-object.ts
 var stream_object_exports = {};
@@ -17364,7 +17671,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(
@@ -18011,6 +18318,7 @@ var init_agent = __esm({
     };
     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),
@@ -18067,7 +18375,9 @@ var MessageBus = class {
       ...partial,
       from,
       to,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      // SE3 — provenance projection of the sender address (thin view over `from`).
+      origin: { kind: "peer", from }
     };
     handler(message);
   }
@@ -18081,7 +18391,9 @@ var MessageBus = class {
       ...partial,
       from,
       to,
-      timestamp: Date.now()
+      timestamp: Date.now(),
+      // SE3 — provenance projection of the sender address (thin view over `from`).
+      origin: { kind: "peer", from }
     };
     return Promise.race([
       Promise.resolve(handler(message)),
@@ -18111,6 +18423,52 @@ var MaxDelegationDepthError = class extends Error {
   maxDepth;
   code = "max_delegation_depth";
 };
+async function applyDelegationStart(spec, input) {
+  if (spec.onDelegationStart === void 0) return { input };
+  const decision = await spec.onDelegationStart({ input, name: spec.name });
+  if (decision === void 0) return { input };
+  if (decision.proceed === false)
+    return { reject: decision.rejectionReason ?? "(delegation rejected)" };
+  return { input: decision.modifiedInput ?? input };
+}
+async function runChildAgent(spec, input, signal) {
+  const { Agent: Agent2 } = await Promise.resolve().then(() => (init_agent(), agent_exports));
+  const agent = await Agent2.create({
+    ...spec.model ? { model: { id: spec.model } } : {},
+    systemPrompt: spec.instructions,
+    tools: spec.tools ?? []
+  });
+  try {
+    const run = signal !== void 0 ? await agent.send(input, { signal }) : await agent.send(input);
+    const result = await run.wait();
+    return result.result ?? "(no response)";
+  } finally {
+    agent.dispose();
+  }
+}
+async function notifyDelegationError(spec, input, error) {
+  if (spec.onDelegationComplete === void 0) return;
+  try {
+    await spec.onDelegationComplete({ input, name: spec.name, error });
+  } catch {
+  }
+}
+function applyMessageFilter(spec, input, messages) {
+  if (spec.messageFilter === void 0 || messages === void 0) return input;
+  const filtered = spec.messageFilter({ messages, input, name: spec.name });
+  if (filtered.length === 0) return input;
+  const preamble = filtered.map((m) => `${m.role}: ${m.content}`).join("\n");
+  return `Prior conversation:
+${preamble}
+
+Task:
+${input}`;
+}
+async function applyDelegationComplete(spec, input, result) {
+  if (spec.onDelegationComplete === void 0) return result;
+  const completion = await spec.onDelegationComplete({ input, name: spec.name, result });
+  return completion?.feedback !== void 0 ? result + completion.feedback : result;
+}
 function defineSubAgent(spec, _parentDepth = 0) {
   const currentDepth = _parentDepth + 1;
   const maxDepth = spec.maxDelegationDepth ?? 3;
@@ -18124,21 +18482,19 @@ function defineSubAgent(spec, _parentDepth = 0) {
     name: spec.name,
     description: spec.description,
     inputSchema,
-    handler: async (rawInput) => {
-      const { input } = inputSchema.parse(rawInput);
-      const { Agent: Agent2 } = await Promise.resolve().then(() => (init_agent(), agent_exports));
-      const agent = await Agent2.create({
-        ...spec.model ? { model: { id: spec.model } } : {},
-        systemPrompt: spec.instructions,
-        tools: spec.tools ?? []
-      });
+    handler: async (rawInput, ctx) => {
+      const { input: parsed } = inputSchema.parse(rawInput);
+      const start = await applyDelegationStart(spec, parsed);
+      if ("reject" in start) return start.reject;
+      const input = applyMessageFilter(spec, start.input, ctx?.messages);
+      let result;
       try {
-        const run = await agent.send(input);
-        const result = await run.wait();
-        return result.result ?? "(no response)";
-      } finally {
-        agent.dispose();
+        result = await runChildAgent(spec, input, ctx?.signal);
+      } catch (error) {
+        await notifyDelegationError(spec, input, error);
+        throw error;
       }
+      return applyDelegationComplete(spec, input, result);
     }
   };
 }