@tangle-network/agent-runtime 0.45.0 → 0.47.0

package/dist/{chunk-KEWO4KI6.js → chunk-72JQCHOZ.js}

@@ -3,22 +3,120 @@ import {
   PlannerError,
   RuntimeRunStateError,
   ValidationError,
-  addTokenUsage,
-  deleteBoxSafe,
-  extractLlmCallEvent,
-  mapWithConcurrency,
-  randomSuffix,
-  randomUuid,
-  sleep,
-  stringifySafe,
-  throwAbort,
-  throwIfAborted,
-  withTimeout,
-  zeroTokenUsage
-} from "./chunk-PRX45WE2.js";
+  extractLlmCallEvent
+} from "./chunk-GSUO5QS6.js";
 
 // src/durable/spawn-journal.ts
 import { createHash } from "crypto";
+
+// src/runtime/util.ts
+async function deleteBoxSafe(box) {
+  if (!box || typeof box.delete !== "function") return true;
+  try {
+    await box.delete();
+    return true;
+  } catch {
+    return false;
+  }
+}
+function randomSuffix(len = 8) {
+  return Math.random().toString(36).slice(2, 2 + len);
+}
+function randomUuid() {
+  return crypto.randomUUID();
+}
+function abortError() {
+  const err = new Error("aborted");
+  err.name = "AbortError";
+  return err;
+}
+function throwAbort() {
+  throw abortError();
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw abortError();
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+    let onAbort;
+    const timer = setTimeout(() => {
+      if (onAbort && signal) signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    if (signal) {
+      onAbort = () => {
+        clearTimeout(timer);
+        resolve();
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+function withTimeout(promise, ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(void 0), ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      () => {
+        clearTimeout(timer);
+        resolve(void 0);
+      }
+    );
+  });
+}
+function stringifySafe(value, opts = {}) {
+  let s;
+  try {
+    if (typeof value === "string") {
+      s = value;
+    } else {
+      const json = opts.pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value);
+      s = json ?? String(value);
+    }
+  } catch {
+    s = String(value);
+  }
+  if (opts.max !== void 0 && s.length > opts.max) return `${s.slice(0, opts.max)}\u2026`;
+  return s;
+}
+function zeroTokenUsage() {
+  return { input: 0, output: 0 };
+}
+function addTokenUsage(acc, delta) {
+  acc.input += delta.input ?? 0;
+  acc.output += delta.output ?? 0;
+}
+async function mapWithConcurrency(items, limit, fn) {
+  const bound = Math.max(1, Math.floor(limit));
+  const results = new Array(items.length);
+  let next = 0;
+  let failed = false;
+  const worker = async () => {
+    while (!failed) {
+      const i = next;
+      next += 1;
+      if (i >= items.length) return;
+      try {
+        results[i] = await fn(items[i], i);
+      } catch (err) {
+        failed = true;
+        throw err;
+      }
+    }
+  };
+  const workerCount = Math.min(bound, items.length);
+  await Promise.all(Array.from({ length: workerCount }, () => worker()));
+  return results;
+}
+
+// src/durable/spawn-journal.ts
 function contentAddress(artifact) {
   const hex = createHash("sha256").update(stableStringify(artifact), "utf-8").digest("hex");
   return `sha256:${hex}`;
@@ -376,18 +474,100 @@ function deterministicCompletion(check) {
   };
 }
 
-// src/runtime/dynamic.ts
-function createDynamicDriver(options) {
+// src/runtime/personify/analyst.ts
+var judgeEvidenceUri = /^(verdict|judge|score)\b/i;
+var assertTraceDerivedFindings = (findings) => {
+  for (const f of findings) {
+    for (const ref of f.evidence_refs ?? []) {
+      if (ref.kind === "metric" && judgeEvidenceUri.test(ref.uri)) {
+        throw new PlannerError(
+          `steer-firewall: finding ${stringifySafe(f.finding_id)} cites judge-derived evidence (${stringifySafe(ref.uri)}); findings fed to a combinator's steer decision must be trace-derived, not judge-derived (selector \u2260 judge)`
+        );
+      }
+    }
+  }
+};
+function createScopeAnalyst(scope, options) {
+  if (!options.analyst || typeof options.analyst.act !== "function") {
+    throw new AnalystError("createScopeAnalyst: analyst must be an Agent with an act() method");
+  }
+  const label = options.label ?? "analyst";
+  return {
+    async analyze(input) {
+      const task = options.buildTask(input);
+      const spawned = scope.spawn(options.analyst, task, {
+        budget: options.budget,
+        label
+      });
+      if (!spawned.ok) {
+        throw new AnalystError(
+          `createScopeAnalyst: analyst spawn refused by the conserved pool (${spawned.reason}); cannot steer node ${stringifySafe(input.nodeId)} on an unrun analyst`
+        );
+      }
+      const settled = await drainAnalystSettlement(scope, spawned.handle.id);
+      const findings = readAnalystFindings(settled);
+      assertTraceDerivedFindings(findings);
+      return findings;
+    }
+  };
+}
+async function drainAnalystSettlement(scope, analystId) {
+  for (; ; ) {
+    const settled = await scope.next();
+    if (settled === null) {
+      throw new AnalystError(
+        `createScopeAnalyst: scope drained before analyst ${stringifySafe(analystId)} settled`
+      );
+    }
+    if (settled.handle.id === analystId) return settled;
+  }
+}
+function readAnalystFindings(settled) {
+  if (settled.kind === "down") {
+    throw new AnalystError(
+      `createScopeAnalyst: analyst ${stringifySafe(settled.handle.id)} settled down (${settled.infra ? "infra" : "result"}): ${stringifySafe(settled.reason)}`
+    );
+  }
+  const out = settled.out;
+  if (!Array.isArray(out)) {
+    throw new PlannerError(
+      `createScopeAnalyst: analyst ${stringifySafe(settled.handle.id)} must return AnalystFinding[], got ${stringifySafe(out)}`
+    );
+  }
+  return out;
+}
+function buildSteerContext(findings, settledSoFar) {
+  assertTraceDerivedFindings(findings);
+  const lastValidScore = observedBestScore(settledSoFar);
+  return {
+    findings,
+    settledSoFar,
+    ...lastValidScore !== void 0 ? { lastValidScore } : {}
+  };
+}
+function observedBestScore(settledSoFar) {
+  let best;
+  for (const s of settledSoFar) {
+    if (s.kind !== "done") continue;
+    const v = s.verdict;
+    if (!v || v.valid !== true || typeof v.score !== "number") continue;
+    if (best === void 0 || v.score > best) best = v.score;
+  }
+  return best;
+}
+
+// src/runtime/driver.ts
+function createDriver(options) {
   if (typeof options.planner !== "function") {
-    throw new ValidationError("createDynamicDriver: planner must be a function");
+    throw new ValidationError("createDriver: planner must be a function");
   }
   const maxIterations = options.maxIterations ?? 8;
   if (!Number.isFinite(maxIterations) || maxIterations <= 0) {
-    throw new ValidationError("createDynamicDriver: maxIterations must be > 0");
+    throw new ValidationError("createDriver: maxIterations must be > 0");
   }
   const maxFanout = options.maxFanout ?? 4;
   if (!Number.isFinite(maxFanout) || maxFanout < 1) {
-    throw new ValidationError("createDynamicDriver: maxFanout must be >= 1");
+    throw new ValidationError("createDriver: maxFanout must be >= 1");
   }
   let pending;
   return {
@@ -498,7 +678,7 @@ async function runAnalyze(analyze, task, history) {
   const findings = await analyze({ task, history });
   if (!Array.isArray(findings)) {
     throw new PlannerError(
-      `createDynamicDriver: analyze hook must return AnalystFinding[], got ${stringifySafe(findings)}`
+      `createDriver: analyze hook must return AnalystFinding[], got ${stringifySafe(findings)}`
     );
   }
   assertTraceDerivedFindings(findings);
@@ -508,23 +688,11 @@ async function runComplete(complete, task, history) {
   const verdict = await complete.assess({ task, history });
   if (!verdict || typeof verdict.done !== "boolean" || verdict.determinism !== "deterministic" && verdict.determinism !== "probabilistic") {
     throw new PlannerError(
-      `createDynamicDriver: complete.assess must return a CompletionVerdict {done, determinism}, got ${stringifySafe(verdict)}`
+      `createDriver: complete.assess must return a CompletionVerdict {done, determinism}, got ${stringifySafe(verdict)}`
     );
   }
   return verdict;
 }
-var JUDGE_EVIDENCE_URI = /^(verdict|judge|score)\b/i;
-function assertTraceDerivedFindings(findings) {
-  for (const f of findings) {
-    for (const ref of f.evidence_refs ?? []) {
-      if (ref.kind === "metric" && JUDGE_EVIDENCE_URI.test(ref.uri)) {
-        throw new PlannerError(
-          `steer-firewall: finding ${stringifySafe(f.finding_id)} cites judge-derived evidence (${stringifySafe(ref.uri)}); analyses fed to the driver must be trace-derived, not judge-derived (selector \u2260 judge)`
-        );
-      }
-    }
-  }
-}
 function renderAnalyses(findings) {
   if (findings.length === 0) return "";
   const rows = findings.map((f) => {
@@ -535,6 +703,56 @@ function renderAnalyses(findings) {
 ${rows.join("\n")}`;
 }
 
+// src/runtime/inline-sandbox-client.ts
+function isAsyncIterable(v) {
+  return typeof v === "object" && v !== null && Symbol.asyncIterator in v;
+}
+async function settle(exec, task, signal) {
+  const r = exec.execute(task, signal);
+  if (isAsyncIterable(r)) {
+    for await (const _ of r) {
+    }
+    return exec.resultArtifact();
+  }
+  return r;
+}
+function inlineSandboxClient(factory) {
+  let seq = 0;
+  return {
+    async create(_options) {
+      const id = `inline-${seq++}`;
+      return {
+        id,
+        async *streamPrompt(message) {
+          const controller = new AbortController();
+          const spec = { profile: { name: id }, harness: null };
+          const exec = factory(spec, { signal: controller.signal, seams: {} });
+          try {
+            const artifact = await settle(exec, message, controller.signal);
+            const out = artifact.out;
+            yield {
+              type: "result",
+              data: {
+                finalText: out?.content ?? "",
+                tokenUsage: {
+                  inputTokens: artifact.spent.tokens.input,
+                  outputTokens: artifact.spent.tokens.output
+                },
+                costUsd: artifact.spent.usd
+              }
+            };
+          } finally {
+            await exec.teardown("brutalKill").catch(() => {
+            });
+          }
+        },
+        async delete() {
+        }
+      };
+    }
+  };
+}
+
 // src/runtime/report-usage.ts
 function reportLoopUsage(cost, result, source = "loop") {
   cost.observe(result.costUsd, source);
@@ -648,6 +866,7 @@ async function acquireSandbox(client, options, acquire = {}) {
   const sleep2 = acquire.sleep ?? ((ms) => sleep(ms, acquire.signal));
   const pollMs = acquire.pollIntervalMs ?? 3e3;
   const deadline = now() + (acquire.readyTimeoutMs ?? 6e5);
+  const appearScans = 5;
   const name = options.name ?? acquire.name ?? `loop-sbx-${randomUuid()}`;
   const createOpts = { ...options, name };
   const c = client;
@@ -663,9 +882,12 @@ async function acquireSandbox(client, options, acquire = {}) {
       if (!isRetryable(err)) throw err;
       lastErr = err;
       if (typeof c.list === "function") {
-        const found = (await c.list().catch(() => []))?.find((b) => b.name === name);
-        if (found)
-          return await waitReadyOrDestroy(found, deadline, pollMs, acquire.signal, now, sleep2);
+        for (let scan = 0; scan < appearScans && now() < deadline; scan += 1) {
+          const found = (await c.list().catch(() => []))?.find((b) => b.name === name);
+          if (found)
+            return await waitReadyOrDestroy(found, deadline, pollMs, acquire.signal, now, sleep2);
+          if (scan < appearScans - 1) await sleep2(pollMs);
+        }
       }
       attempt += 1;
       await sleep2(Math.min(pollMs * attempt, 15e3));
@@ -714,9 +936,13 @@ function isRetryable(err) {
   if (typeof status === "number" && RETRYABLE_HTTP.has(status)) return true;
   const name = e.name ?? "";
   if (name === "TimeoutError" || name === "ServerError" || name === "NetworkError") return true;
-  return /\b(timed out|timeout|gateway|temporarily unavailable|ECONNRESET|ETIMEDOUT|EAI_AGAIN)\b/i.test(
-    e.message ?? ""
-  );
+  const msg = e.message ?? "";
+  if (/\b(timed out|timeout|gateway|temporarily unavailable|too many requests|ECONNRESET|ETIMEDOUT|EAI_AGAIN)\b/i.test(
+    msg
+  )) {
+    return true;
+  }
+  return /provision failed|edge data plane|not reachable|failed to create sandbox/i.test(msg);
 }
 
 // src/runtime/sandbox-backend.ts
@@ -764,10 +990,31 @@ async function resolveCapabilities(client) {
 // src/runtime/sandbox-lineage.ts
 var TEARDOWN_TIMEOUT_MS = 15e3;
 var DEFAULT_FORK_CONCURRENCY = 4;
+async function* pollPromptEvents(box, prompt, sessionId, signal) {
+  if (signal.aborted) throwAbort();
+  const dispatched = await box.dispatchPrompt(prompt, { sessionId, signal });
+  const activeSessionId = dispatched.sessionId;
+  const result = await box.session(activeSessionId).result();
+  if (signal.aborted) throwAbort();
+  yield {
+    type: "result",
+    id: activeSessionId,
+    data: {
+      finalText: result.response ?? "",
+      success: result.success,
+      ...result.error ? { error: result.error } : {},
+      ...result.usage ? { usage: result.usage } : {}
+    }
+  };
+}
+function promptEvents(streaming, box, prompt, sessionId, signal) {
+  return streaming === "poll" ? pollPromptEvents(box, prompt, sessionId, signal) : box.streamPrompt(prompt, { sessionId, signal });
+}
 function createSandboxLineage(client, capabilities, options = {}) {
   if (!client || typeof client.create !== "function") {
     throw new ValidationError("createSandboxLineage: client.create is required");
   }
+  const streaming = options.streaming ?? "sse";
   const forkConcurrency = Math.max(
     1,
     Math.floor(options.maxConcurrency ?? DEFAULT_FORK_CONCURRENCY)
@@ -777,6 +1024,7 @@ function createSandboxLineage(client, capabilities, options = {}) {
     if (signal.aborted) throwAbort();
     const opts = buildBackendOptions(spec.profile, spec.sandboxOverrides);
     const box = await acquireSandbox(client, opts, { signal });
+    await spec.prepareBox?.(box, { signal });
     owned.push(box);
     return box;
   };
@@ -784,13 +1032,13 @@ function createSandboxLineage(client, capabilities, options = {}) {
     async start(spec, prompt, signal) {
       const box = await acquireFresh(spec, signal);
       const sessionId = mintSessionId();
-      const events = box.streamPrompt(prompt, { sessionId, signal });
+      const events = promptEvents(streaming, box, prompt, sessionId, signal);
       return { handle: { box, sessionId }, events };
     },
     async continue(handle, prompt, signal) {
       if (signal.aborted) throwAbort();
       await assertSessionLive(handle.box, handle.sessionId);
-      return handle.box.streamPrompt(prompt, { sessionId: handle.sessionId, signal });
+      return promptEvents(streaming, handle.box, prompt, handle.sessionId, signal);
     },
     async fork(parent, prompts, specs, signal) {
       if (prompts.length === 0) {
@@ -805,17 +1053,18 @@ function createSandboxLineage(client, capabilities, options = {}) {
         if (checkpointId !== void 0) {
           const box2 = await forkFromCheckpoint(parent.box, checkpointId, signal);
           owned.push(box2);
+          await spec.prepareBox?.(box2, { signal });
           const sessionId2 = mintSessionId();
           return {
             handle: { box: box2, sessionId: sessionId2 },
-            events: box2.streamPrompt(prompt, { sessionId: sessionId2, signal })
+            events: promptEvents(streaming, box2, prompt, sessionId2, signal)
           };
         }
         const box = await acquireFresh(spec, signal);
         const sessionId = mintSessionId();
         return {
           handle: { box, sessionId },
-          events: box.streamPrompt(prompt, { sessionId, signal })
+          events: promptEvents(streaming, box, prompt, sessionId, signal)
         };
       });
     },
@@ -884,6 +1133,7 @@ async function runLoop(options) {
   if (!Number.isFinite(maxConcurrency) || maxConcurrency <= 0) {
     throw new ValidationError("runLoop: maxConcurrency must be > 0");
   }
+  const sandboxStreaming = options.lineage?.streaming ?? "sse";
   if (!options.ctx?.sandboxClient || typeof options.ctx.sandboxClient.create !== "function") {
     throw new ValidationError("runLoop: ctx.sandboxClient.create is required");
   }
@@ -1000,6 +1250,7 @@ async function runLoop(options) {
         output: options.output,
         validator: options.validator,
         maxConcurrency,
+        streaming: sandboxStreaming,
         signal: controller.signal,
         ctx: options.ctx,
         runId,
@@ -1059,7 +1310,10 @@ async function setUpLineage(options, maxConcurrency) {
   }
   const capabilities = await probeSandboxCapabilities(options.ctx.sandboxClient);
   return {
-    lineage: createSandboxLineage(options.ctx.sandboxClient, capabilities, { maxConcurrency }),
+    lineage: createSandboxLineage(options.ctx.sandboxClient, capabilities, {
+      maxConcurrency,
+      streaming: lineageOpts.streaming
+    }),
     options: lineageOpts,
     handles: /* @__PURE__ */ new Map(),
     canPrune: typeof options.driver.describePlan !== "function"
@@ -1189,7 +1443,8 @@ async function executeIteration(args) {
       stream = acquired.events;
     } else {
       box = await createSandboxForSpec(args.ctx.sandboxClient, spec, args.signal);
-      stream = box.streamPrompt(spec.taskToPrompt(args.item.task), { signal: args.signal });
+      const prompt = spec.taskToPrompt(args.item.task);
+      stream = args.streaming === "poll" ? promptEvents("poll", box, prompt, `${args.runId}-i${args.item.index}`, args.signal) : box.streamPrompt(prompt, { signal: args.signal });
     }
     const placement = describeSandboxPlacement(args.ctx.sandboxClient, box);
     await emitTrace(args.ctx.traceEmitter, {
@@ -1222,6 +1477,7 @@ async function executeIteration(args) {
     if (args.validator) {
       slot.verdict = await args.validator.validate(slot.output, {
         iteration: args.item.index,
+        ...box ? { box } : {},
         signal: args.signal,
         traceEmitter: args.ctx.traceEmitter
       });
@@ -1318,7 +1574,9 @@ function readSandboxId(box) {
 async function createSandboxForSpec(client, spec, signal) {
   const opts = buildBackendOptions(spec.profile, spec.sandboxOverrides);
   if (signal.aborted) throwAbort();
-  return acquireSandbox(client, opts, { signal });
+  const box = await acquireSandbox(client, opts, { signal });
+  await spec.prepareBox?.(box, { signal });
+  return box;
 }
 function finalize(args) {
   const winner = args.options.selectWinner ? args.options.selectWinner(args.iterations) : args.options.driver.selectWinner?.(args.iterations) ?? defaultSelectWinner(args.iterations);
@@ -1479,86 +1737,160 @@ function loopDispatch(opts) {
   return (profile, scenario, ctx) => runLoopForCell(opts, scenario, profile, ctx);
 }
 
-// src/runtime/personify/analyst.ts
-var judgeEvidenceUri = /^(verdict|judge|score)\b/i;
-var assertTraceDerivedFindings2 = (findings) => {
-  for (const f of findings) {
-    for (const ref of f.evidence_refs ?? []) {
-      if (ref.kind === "metric" && judgeEvidenceUri.test(ref.uri)) {
-        throw new PlannerError(
-          `steer-firewall: finding ${stringifySafe(f.finding_id)} cites judge-derived evidence (${stringifySafe(ref.uri)}); findings fed to a combinator's steer decision must be trace-derived, not judge-derived (selector \u2260 judge)`
-        );
+// src/runtime/observe.ts
+import { makeFinding } from "@tangle-network/agent-eval";
+var observerId = "observe/trace";
+function summarizeTrace(trace, maxLines) {
+  const lines = [];
+  for (const ev of trace) {
+    const e = ev;
+    const t = (e.type ?? "").toLowerCase();
+    const d = e.data ?? {};
+    const part = d.part ?? {};
+    if (part.type === "tool")
+      lines.push(`tool:${part.tool}${part.state?.status ? `(${part.state.status})` : ""}`);
+    else if (t.includes("error"))
+      lines.push(`ERROR: ${String(d.message ?? d.detail ?? "").slice(0, 200)}`);
+    else if (t === "status" && typeof d.status === "string") lines.push(`status:${d.status}`);
+    else if (t.includes("tool")) lines.push(`tool-event:${t}`);
+  }
+  const out = [];
+  for (const ln of lines) {
+    const prev = out[out.length - 1];
+    const m = prev?.match(/^(.*?)(?: x(\d+))?$/);
+    if (m && m[1] === ln) out[out.length - 1] = `${ln} x${(Number(m[2]) || 1) + 1}`;
+    else out.push(ln);
+  }
+  return out.slice(0, maxLines).join("\n") || "(no tool/error events in trace)";
+}
+var findingsSchema = {
+  name: "observer_findings",
+  schema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      findings: {
+        type: "array",
+        items: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            area: {
+              type: "string",
+              description: "tool-use | cost | verification | process | failure | latency"
+            },
+            severity: { type: "string", enum: ["critical", "high", "medium", "low", "info"] },
+            claim: {
+              type: "string",
+              description: "what you OBSERVED in the trace (a fact, with the evidence)"
+            },
+            recommended_action: {
+              type: "string",
+              description: "the concrete change for the agent or operator"
+            },
+            audience: {
+              type: "string",
+              enum: ["agent", "operator"],
+              description: "who should act on this"
+            },
+            confidence: { type: "number" }
+          },
+          required: ["area", "severity", "claim", "recommended_action", "audience", "confidence"]
+        }
       }
-    }
+    },
+    required: ["findings"]
   }
 };
-function createScopeAnalyst(scope, options) {
-  if (!options.analyst || typeof options.analyst.act !== "function") {
-    throw new AnalystError("createScopeAnalyst: analyst must be an Agent with an act() method");
-  }
-  const label = options.label ?? "analyst";
-  return {
-    async analyze(input) {
-      const task = options.buildTask(input);
-      const spawned = scope.spawn(options.analyst, task, {
-        budget: options.budget,
-        label
-      });
-      if (!spawned.ok) {
-        throw new AnalystError(
-          `createScopeAnalyst: analyst spawn refused by the conserved pool (${spawned.reason}); cannot steer node ${stringifySafe(input.nodeId)} on an unrun analyst`
-        );
-      }
-      const settled = await drainAnalystSettlement(scope, spawned.handle.id);
-      const findings = readAnalystFindings(settled);
-      assertTraceDerivedFindings2(findings);
-      return findings;
-    }
-  };
-}
-async function drainAnalystSettlement(scope, analystId) {
-  for (; ; ) {
-    const settled = await scope.next();
-    if (settled === null) {
-      throw new AnalystError(
-        `createScopeAnalyst: scope drained before analyst ${stringifySafe(analystId)} settled`
-      );
+async function observe(input, opts) {
+  const traceSummary = summarizeTrace(input.trace, opts.maxTraceLines ?? 80);
+  const res = await opts.chat.chat(
+    {
+      ...opts.model ? { model: opts.model } : {},
+      jsonSchema: findingsSchema,
+      messages: [
+        {
+          role: "system",
+          content: "You are a third-person OBSERVER watching an AI agent work. You see its TRACE (what it did), not its grader. From the trace, name SPECIFIC, behavior-grounded findings: wasted/duplicated tool calls, thrash/retries, token/cost waste, missing verification, failure patterns. For each, a concrete recommended_action, and whether the AGENT (fix its skills/prompt/tools) or the OPERATOR (fix framing/decomposition/config) should act. Only claim what the trace shows. No findings if the run was clean."
+        },
+        {
+          role: "user",
+          content: `TASK: ${input.task}
+
+OUTCOME: ${input.outcome ?? "unknown"}
+
+FINAL OUTPUT (truncated):
+${input.output.slice(0, 1200)}
+
+TRACE (in order; "xN" = repeated):
+${traceSummary}`
+        }
+      ]
+    },
+    { ...opts.signal ? { signal: opts.signal } : {} }
+  );
+  const parsed = parseFindings(res.content);
+  const producedAt = input.runId ? `${input.runId}` : observerId;
+  const findings = parsed.map(
+    (f) => makeFinding({
+      analyst_id: observerId,
+      area: `${f.area}`,
+      severity: f.severity,
+      claim: f.claim,
+      recommended_action: f.recommended_action,
+      confidence: typeof f.confidence === "number" ? f.confidence : 0.5,
+      evidence_refs: [],
+      // The observer reads BEHAVIOR, never the judge verdict — firewall provenance.
+      derived_from_judge: false,
+      metadata: { audience: f.audience },
+      ...input.runId ? { subject: input.runId } : {}
+    })
+  );
+  const learned = [];
+  if (opts.corpus) {
+    for (const f of findings) {
+      const record = {
+        schemaVersion: "1.0.0",
+        id: f.finding_id,
+        runId: input.runId ?? observerId,
+        producedAt: f.produced_at ?? producedAt,
+        area: f.area,
+        claim: f.recommended_action ?? f.claim,
+        ...f.claim ? { rationale: f.claim } : {},
+        tags: [...opts.tags ?? [], `audience:${f.metadata?.audience ?? "agent"}`],
+        confidence: f.confidence,
+        evidence: [{ kind: "finding", uri: f.finding_id }]
+      };
+      const r = await opts.corpus.append(record);
+      if (r.succeeded) learned.push(record);
     }
-    if (settled.handle.id === analystId) return settled;
-  }
-}
-function readAnalystFindings(settled) {
-  if (settled.kind === "down") {
-    throw new AnalystError(
-      `createScopeAnalyst: analyst ${stringifySafe(settled.handle.id)} settled down (${settled.infra ? "infra" : "result"}): ${stringifySafe(settled.reason)}`
-    );
-  }
-  const out = settled.out;
-  if (!Array.isArray(out)) {
-    throw new PlannerError(
-      `createScopeAnalyst: analyst ${stringifySafe(settled.handle.id)} must return AnalystFinding[], got ${stringifySafe(out)}`
-    );
   }
-  return out;
+  return { findings, learned, report: renderReport(findings) };
 }
-function buildSteerContext(findings, settledSoFar) {
-  assertTraceDerivedFindings2(findings);
-  const lastValidScore = observedBestScore(settledSoFar);
-  return {
-    findings,
-    settledSoFar,
-    ...lastValidScore !== void 0 ? { lastValidScore } : {}
-  };
-}
-function observedBestScore(settledSoFar) {
-  let best;
-  for (const s of settledSoFar) {
-    if (s.kind !== "done") continue;
-    const v = s.verdict;
-    if (!v || v.valid !== true || typeof v.score !== "number") continue;
-    if (best === void 0 || v.score > best) best = v.score;
-  }
-  return best;
+function parseFindings(content) {
+  let obj;
+  try {
+    obj = JSON.parse(content);
+  } catch {
+    const m = content.match(/\{[\s\S]*\}/);
+    obj = m ? JSON.parse(m[0]) : { findings: [] };
+  }
+  const arr = obj.findings;
+  return Array.isArray(arr) ? arr : [];
+}
+function renderReport(findings) {
+  if (findings.length === 0) return "\u2713 clean run \u2014 the observer found nothing to change.";
+  const audience = (f) => f.metadata?.audience ?? "agent";
+  const forAgent = findings.filter((f) => audience(f) === "agent");
+  const forOperator = findings.filter((f) => audience(f) === "operator");
+  const block = (title, fs) => fs.length === 0 ? "" : `**${title}**
+${fs.map((f) => `- [${f.severity}] ${f.claim}
+  \u2192 ${f.recommended_action ?? ""}`).join("\n")}
+`;
+  return [
+    block("For the agent (fix skills / prompt / tools)", forAgent),
+    block("For you (the operator)", forOperator)
+  ].filter(Boolean).join("\n");
 }
 
 // src/runtime/supervise/scope.ts
@@ -1574,7 +1906,7 @@ function createScope(args) {
     const spec = agent.executorSpec;
     if (!isAgentSpec(spec)) {
       throw new ValidationError(
-        `scope.spawn: agent "${agent.name}" exposes no \`executorSpec\` (AgentSpec) to resolve a LeafExecutor`
+        `scope.spawn: agent "${agent.name}" exposes no \`executorSpec\` (AgentSpec) to resolve a Executor`
       );
     }
     const resolved = args.executors.resolve(spec);
@@ -1802,7 +2134,7 @@ async function runChild(live, executor, childAbort, task, opts, pool, ticket, bl
     live.status = "running";
     const ran = executor.execute(task, childAbort.signal);
     let artifact;
-    if (isAsyncIterable(ran)) {
+    if (isAsyncIterable2(ran)) {
       const spend = await foldStream(ran);
       live.spent = spend;
       artifact = executor.resultArtifact();
@@ -1924,7 +2256,7 @@ function downRecord(reason, infra) {
 function zeroSpend2() {
   return { iterations: 0, tokens: { input: 0, output: 0 }, usd: 0, ms: 0 };
 }
-function isAsyncIterable(value) {
+function isAsyncIterable2(value) {
   return typeof value === "object" && value !== null && typeof value[Symbol.asyncIterator] === "function";
 }
 function isAgentSpec(value) {
@@ -2463,6 +2795,7 @@ import { estimateCost, isModelPriced } from "@tangle-network/agent-eval";
 var routerSeamKey = "router";
 var sandboxSeamKey = "sandbox";
 var cliSeamKey = "cli";
+var bridgeSeamKey = "bridge";
 function contentRef(prefix, value) {
   let str;
   try {
@@ -2756,6 +3089,96 @@ function killWithGrace(proc, grace) {
     }, grace);
   });
 }
+var bridgeExecutor = (spec, ctx) => {
+  const seam = readSeam(ctx, bridgeSeamKey, "bridge");
+  if (!seam.bridgeUrl || !seam.bridgeBearer || !seam.model) {
+    throw new ValidationError(
+      "bridgeExecutor: BridgeSeam.bridgeUrl + bridgeBearer + model required"
+    );
+  }
+  const controller = new AbortController();
+  const abortIfSignalled = () => {
+    if (ctx.signal.aborted) controller.abort();
+  };
+  abortIfSignalled();
+  if (!ctx.signal.aborted) ctx.signal.addEventListener("abort", abortIfSignalled, { once: true });
+  let artifact;
+  return {
+    runtime: "cli",
+    async execute(task, signal) {
+      const messages = taskToMessages(task, spec);
+      const started = Date.now();
+      const linked = linkSignals(signal, controller.signal);
+      const timer = seam.timeoutMs ? setTimeout(() => controller.abort(), seam.timeoutMs) : void 0;
+      try {
+        const res = await fetch(`${seam.bridgeUrl.replace(/\/$/, "")}/v1/chat/completions`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${seam.bridgeBearer}`
+          },
+          body: JSON.stringify({
+            model: seam.model,
+            stream: false,
+            ...seam.agentProfile ? { agent_profile: seam.agentProfile } : {},
+            messages
+          }),
+          ...linked ? { signal: linked } : {}
+        });
+        if (!res.ok) {
+          throw new ValidationError(
+            `bridgeExecutor: bridge ${res.status}: ${(await res.text()).slice(0, 300)}`
+          );
+        }
+        const data = await res.json();
+        const u = data.usage;
+        const usage = u && typeof u.prompt_tokens === "number" && typeof u.completion_tokens === "number" ? { input: u.prompt_tokens, output: u.completion_tokens } : void 0;
+        const msg = data.choices?.[0]?.message;
+        const content = msg?.content ?? "";
+        const toolCalls = (msg?.tool_calls ?? []).map((t) => t.function?.name ?? "unknown");
+        const spent = {
+          iterations: 1,
+          tokens: usage ? { input: usage.input, output: usage.output } : zeroTokenUsage(),
+          usd: typeof u?.cost === "number" ? u.cost : 0,
+          ms: Date.now() - started
+        };
+        const out = { content, toolCalls };
+        artifact = { outRef: contentRef("bridge", { model: seam.model, content }), out, spent };
+        return artifact;
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+    },
+    teardown(_grace) {
+      controller.abort();
+      return Promise.resolve({ destroyed: true });
+    },
+    resultArtifact() {
+      if (!artifact) {
+        throw new ValidationError("bridgeExecutor: resultArtifact() read before execute()");
+      }
+      return { ...artifact, spent: artifact.spent };
+    }
+  };
+};
+function createExecutor(config) {
+  return (spec, ctx) => {
+    const { backend, ...seam } = config;
+    const seamed = { ...ctx, seams: { ...ctx.seams, [backend]: seam } };
+    switch (config.backend) {
+      case "router":
+        return routerInlineExecutor(spec, seamed);
+      case "bridge":
+        return bridgeExecutor(spec, seamed);
+      case "cli":
+        return cliExecutor(spec, seamed);
+      case "sandbox": {
+        const harness = spec.harness ?? config.harness ?? null;
+        return sandboxExecutor({ ...spec, harness }, seamed);
+      }
+    }
+  };
+}
 function createExecutorRegistry() {
   const factories = /* @__PURE__ */ new Map();
   factories.set("router", routerInlineExecutor);
@@ -3538,6 +3961,298 @@ function requireSpend(rolled, id, root) {
   return spend;
 }
 
+// src/runtime/sandbox-run.ts
+async function openSandboxRun(client, options, deliverable) {
+  const runId = options.runId ?? `sandbox-run-${randomSuffix()}`;
+  const now = options.now ?? Date.now;
+  const capabilities = await probeSandboxCapabilities(client);
+  const lineage = createSandboxLineage(client, capabilities, {
+    ...options.maxConcurrency !== void 0 ? { maxConcurrency: options.maxConcurrency } : {}
+  });
+  let handle;
+  let started = false;
+  let runStartedAt;
+  let failed = false;
+  let turnCount = 0;
+  function emit(event) {
+    notifyRuntimeHookEvent(
+      options.hooks,
+      {
+        id: `${runId}:${event.target}:${event.phase}${event.stepIndex === void 0 ? "" : `:${event.stepIndex}`}`,
+        runId,
+        scenarioId: options.scenarioId,
+        target: event.target,
+        phase: event.phase,
+        timestamp: event.timestamp,
+        stepIndex: event.stepIndex,
+        payload: event.payload,
+        metadata: { producer: "openSandboxRun" }
+      },
+      { signal: options.signal }
+    );
+  }
+  const runPayload = () => ({
+    agentName: options.agentRun.name ?? options.agentRun.profile.name ?? "agent",
+    profileName: options.agentRun.profile.name,
+    backendType: backendType(options.agentRun),
+    deliverableKind: deliverable.kind,
+    ...deliverable.kind === "artifact" ? { deliverablePath: deliverable.path } : {},
+    ...handle ? { sessionId: handle.sessionId, sandboxId: handle.box.id } : {}
+  });
+  const turnPayload = (prompt, turnKind, startedAt, result, error) => ({
+    ...runPayload(),
+    turnKind,
+    promptChars: prompt.length,
+    promptHash: hashText(prompt),
+    ...result !== void 0 || error !== void 0 ? { durationMs: Math.max(0, now() - startedAt) } : {},
+    ...result ? {
+      eventCount: result.events.length,
+      eventTypes: eventTypeCounts(result.events),
+      ...result.readError !== void 0 ? { readError: result.readError } : {}
+    } : {},
+    ...error !== void 0 ? { error: errorMessage(error) } : {}
+  });
+  async function settle2(box, events) {
+    const collected = [];
+    for await (const ev of events) collected.push(ev);
+    if (deliverable.kind === "events") {
+      return { out: deliverable.fromEvents(collected), events: collected };
+    }
+    throwIfAborted(options.signal);
+    let raw = "";
+    let readError;
+    const readAttempts = 4;
+    const readDelayMs = options.readRetryDelayMs ?? 1e3;
+    for (let attempt = 0; attempt < readAttempts; attempt += 1) {
+      throwIfAborted(options.signal);
+      try {
+        raw = await box.fs.read(deliverable.path);
+        readError = void 0;
+        break;
+      } catch (err) {
+        readError = err instanceof Error ? err.message : String(err);
+        if (attempt < readAttempts - 1 && readDelayMs > 0)
+          await sleep(readDelayMs * (attempt + 1), options.signal);
+      }
+    }
+    return {
+      out: deliverable.fromArtifact(raw, collected),
+      events: collected,
+      ...readError !== void 0 ? { readError } : {}
+    };
+  }
+  return {
+    get box() {
+      if (!handle) throw new Error("openSandboxRun: box unavailable before start()");
+      return handle.box;
+    },
+    get sessionId() {
+      if (!handle) throw new Error("openSandboxRun: sessionId unavailable before start()");
+      return handle.sessionId;
+    },
+    async start(prompt) {
+      if (started)
+        throw new Error(
+          "openSandboxRun: start() already called \u2014 use resume() to continue the session"
+        );
+      started = true;
+      runStartedAt = now();
+      emit({
+        target: "agent.run",
+        phase: "before",
+        timestamp: runStartedAt,
+        payload: { ...runPayload(), turnCount: 0 }
+      });
+      const stepIndex = turnCount;
+      const turnStartedAt = now();
+      emit({
+        target: "agent.turn",
+        phase: "before",
+        timestamp: turnStartedAt,
+        stepIndex,
+        payload: turnPayload(prompt, "start", turnStartedAt)
+      });
+      try {
+        const r = await lineage.start(
+          options.agentRun,
+          prompt,
+          options.signal
+        );
+        handle = r.handle;
+        const result = await settle2(handle.box, r.events);
+        turnCount += 1;
+        emit({
+          target: "agent.turn",
+          phase: "after",
+          timestamp: now(),
+          stepIndex,
+          payload: turnPayload(prompt, "start", turnStartedAt, result)
+        });
+        return result;
+      } catch (error) {
+        failed = true;
+        emit({
+          target: "agent.turn",
+          phase: "error",
+          timestamp: now(),
+          stepIndex,
+          payload: turnPayload(prompt, "start", turnStartedAt, void 0, error)
+        });
+        emit({
+          target: "agent.run",
+          phase: "error",
+          timestamp: now(),
+          payload: { ...runPayload(), turnCount, error: errorMessage(error) }
+        });
+        throw error;
+      }
+    },
+    async resume(prompt) {
+      if (!handle) throw new Error("openSandboxRun: resume() called before start()");
+      const stepIndex = turnCount;
+      const turnStartedAt = now();
+      emit({
+        target: "agent.turn",
+        phase: "before",
+        timestamp: turnStartedAt,
+        stepIndex,
+        payload: turnPayload(prompt, "resume", turnStartedAt)
+      });
+      try {
+        const result = await settle2(
+          handle.box,
+          await lineage.continue(handle, prompt, options.signal)
+        );
+        turnCount += 1;
+        emit({
+          target: "agent.turn",
+          phase: "after",
+          timestamp: now(),
+          stepIndex,
+          payload: turnPayload(prompt, "resume", turnStartedAt, result)
+        });
+        return result;
+      } catch (error) {
+        failed = true;
+        emit({
+          target: "agent.turn",
+          phase: "error",
+          timestamp: now(),
+          stepIndex,
+          payload: turnPayload(prompt, "resume", turnStartedAt, void 0, error)
+        });
+        emit({
+          target: "agent.run",
+          phase: "error",
+          timestamp: now(),
+          payload: { ...runPayload(), turnCount, error: errorMessage(error) }
+        });
+        throw error;
+      }
+    },
+    async close() {
+      await lineage.teardown();
+      if (runStartedAt !== void 0) {
+        emit({
+          target: "agent.run",
+          phase: "after",
+          timestamp: now(),
+          payload: {
+            ...runPayload(),
+            turnCount,
+            status: failed ? "error" : "completed",
+            durationMs: Math.max(0, now() - runStartedAt)
+          }
+        });
+      }
+    }
+  };
+}
+function backendType(spec) {
+  const backend = spec.sandboxOverrides?.backend;
+  return backend?.type;
+}
+function eventTypeCounts(events) {
+  const counts = {};
+  for (const event of events) counts[event.type] = (counts[event.type] ?? 0) + 1;
+  return counts;
+}
+function hashText(value) {
+  let hash = 2166136261;
+  for (let i = 0; i < value.length; i += 1) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/runtime/workspace.ts
+function localShell() {
+  return async (args, cwd) => {
+    const { execFile } = await import("child_process");
+    const [bin, ...rest] = args;
+    return new Promise((resolve) => {
+      execFile(
+        bin ?? "",
+        rest,
+        { cwd, encoding: "utf-8", maxBuffer: 64 * 1024 * 1024 },
+        (err, stdout, stderr) => {
+          resolve({
+            stdout: stdout ?? "",
+            stderr: stderr ?? "",
+            code: err ? err.code ?? 1 : 0
+          });
+        }
+      );
+    });
+  };
+}
+function gitWorkspace(opts) {
+  const shell = opts.shell ?? localShell();
+  const branch = opts.branch ?? "main";
+  const cfg = opts.noHooks === false ? [] : ["-c", "core.hooksPath=/dev/null"];
+  const ident = ["-c", "user.email=workspace@tangle.local", "-c", "user.name=workspace"];
+  const run = async (args, cwd) => {
+    const res = await shell(["git", ...cfg, ...ident, ...args], cwd);
+    if (res.code !== 0) {
+      throw new Error(
+        `git ${args.join(" ")} failed (${res.code}): ${tail(res.stderr || res.stdout)}`
+      );
+    }
+    return res.stdout;
+  };
+  return {
+    ref: opts.ref,
+    materialize: (dir) => run(["clone", "--branch", branch, opts.ref, dir]).then(() => {
+    }),
+    async commit(dir, message) {
+      await run(["add", "-A"], dir);
+      const status = await run(["status", "--porcelain"], dir);
+      if (!status.trim()) return { ok: true, rev: (await run(["rev-parse", "HEAD"], dir)).trim() };
+      await run(["commit", "-m", message], dir);
+      const pull = await shell(["git", ...cfg, ...ident, "pull", "--rebase", "origin", branch], dir);
+      if (pull.code !== 0) {
+        await shell(["git", ...cfg, "rebase", "--abort"], dir).catch(() => {
+        });
+        return { ok: false, conflict: tail(pull.stderr || pull.stdout) };
+      }
+      const push = await shell(["git", ...cfg, ...ident, "push", "origin", branch], dir);
+      if (push.code !== 0) return { ok: false, conflict: tail(push.stderr || push.stdout) };
+      return { ok: true, rev: (await run(["rev-parse", "HEAD"], dir)).trim() };
+    },
+    async head() {
+      const out = await run(["ls-remote", opts.ref, `refs/heads/${branch}`]);
+      return out.split(/\s+/)[0] ?? "";
+    }
+  };
+}
+function tail(s) {
+  return s.slice(-400);
+}
+
 export {
   contentAddress,
   InMemoryResultBlobStore,
@@ -3550,8 +4265,12 @@ export {
   stopSentinel,
   sentinelCompletion,
   deterministicCompletion,
-  createDynamicDriver,
+  assertTraceDerivedFindings,
+  createScopeAnalyst,
+  buildSteerContext,
+  createDriver,
   renderAnalyses,
+  inlineSandboxClient,
   reportLoopUsage,
   defineRuntimeHooks,
   composeRuntimeHooks,
@@ -3565,9 +4284,8 @@ export {
   createSandboxForSpec,
   defaultSelectWinner,
   loopDispatch,
-  assertTraceDerivedFindings2 as assertTraceDerivedFindings,
-  createScopeAnalyst,
-  buildSteerContext,
+  observe,
+  renderReport,
   createScope,
   settledToIteration,
   pipeline,
@@ -3580,9 +4298,7 @@ export {
   InMemoryCorpus,
   FileCorpus,
   renderCorpusToInstructions,
-  routerInlineExecutor,
-  sandboxExecutor,
-  cliExecutor,
+  createExecutor,
   createExecutorRegistry,
   spendFromUsageEvents,
   createBudgetPool,
@@ -3594,6 +4310,9 @@ export {
   definePersona,
   runPersonified,
   trajectoryReport,
-  equalKOnCost
+  equalKOnCost,
+  openSandboxRun,
+  localShell,
+  gitWorkspace
 };
-//# sourceMappingURL=chunk-KEWO4KI6.js.map
+//# sourceMappingURL=chunk-72JQCHOZ.js.map