@foldrun/core 2.3.0 → 2.5.0

package/src/trace-tree.ts

@@ -0,0 +1,187 @@
+// A run as one tree (FOL-72 step 5): run → step → model call → tool call,
+// each with when it started and ended, what it cost in tokens and how it
+// ended — the waterfall every agent-tracing tool opens on. Built from the
+// run record alone (steps, step.calls, the paired tool events), so the run
+// page, GET …/runs/<id>/trace and `foldrun report --tree` read one function.
+//
+// A tool call nests under the model call that asked for it: its event names
+// the call (`inCall`) since 19 Oct 2026; older records are matched by time,
+// to the last model call that answered before the tool started. Pure: no
+// node imports, so the browser can use it.
+
+import type { RunRecord, StepRecord, RunEvent, ModelCall } from "./store.ts";
+
+export type SpanKind = "run" | "step" | "model" | "tool" | "error";
+export type SpanStatus = "ok" | "error" | "running" | "waiting" | "skipped" | "pending";
+
+export interface TraceSpan {
+  /** Stable within the run: "run", "s2", "s2/m3", "s2/t:<call>", "s2/e5". */
+  id: string;
+  kind: SpanKind;
+  /** What the line says: the flow, the agent, the model, the tool. */
+  label: string;
+  /** Epoch ms; null when the record does not say. */
+  start: number | null;
+  end: number | null;
+  status: SpanStatus;
+  /** Model and step spans: tokens (input is all input, as on the record). */
+  tokens?: { input: number; output: number; cacheRead: number; cacheWrite: number };
+  /** Step spans: the provider's token cost, USD. */
+  costUsd?: number | null;
+  model?: string;
+  /** Model spans: why it stopped. */
+  stop?: string;
+  /** Tool spans: the call id, and whether its input and output were recorded. */
+  call?: string;
+  captured?: boolean;
+  /** Error spans and failed tools: the words. */
+  text?: string;
+  subagent?: string;
+  /** Index into run.steps, on a step and everything under it. */
+  step?: number;
+  children: TraceSpan[];
+}
+
+const ms = (iso: string | null | undefined) => {
+  if (!iso) return null;
+  const t = Date.parse(iso);
+  return Number.isNaN(t) ? null : t;
+};
+
+function stepStatus(s: StepRecord): SpanStatus {
+  if (s.status === "completed") return "ok";
+  if (s.status === "failed") return "error";
+  if (s.status === "running") return "running";
+  if (s.status === "awaiting-approval") return "waiting";
+  if (s.status === "skipped") return "skipped";
+  return "pending";
+}
+
+/** Tool events paired: the call's start, its duration, whether it erred. */
+function toolCalls(events: RunEvent[]): { e: RunEvent; start: number | null; end: number | null; err: boolean; captured: boolean }[] {
+  const byCall = new Map<string, { e: RunEvent; start: number | null; end: number | null; err: boolean; captured: boolean }>();
+  const out: { e: RunEvent; start: number | null; end: number | null; err: boolean; captured: boolean }[] = [];
+  for (const e of events) {
+    if (e.type !== "tool") continue;
+    if (e.call && e.ms != null && byCall.has(e.call)) {
+      const open = byCall.get(e.call)!;
+      open.end = (open.start ?? ms(e.t) ?? 0) + e.ms;
+      open.err ||= e.err === true;
+      open.captured ||= e.captured === true;
+      continue;
+    }
+    const c = { e, start: ms(e.t), end: null as number | null, err: e.err === true, captured: e.captured === true };
+    if (e.call) byCall.set(e.call, c);
+    out.push(c);
+  }
+  return out;
+}
+
+function modelSpan(c: ModelCall, step: number): TraceSpan {
+  const at = ms(c.at);
+  return {
+    id: `s${step}/m${c.attempt && c.attempt > 1 ? `${c.attempt}.` : ""}${c.n}`,
+    kind: "model",
+    label: c.model ?? "model",
+    // The request went out `ms` before the response began arriving.
+    start: at !== null ? at - c.ms : null,
+    end: at,
+    status: "ok",
+    tokens: c.tokens,
+    ...(c.model ? { model: c.model } : {}),
+    ...(c.stop ? { stop: c.stop } : {}),
+    ...(c.subagent ? { subagent: c.subagent } : {}),
+    step,
+    children: [],
+  };
+}
+
+function stepSpan(s: StepRecord, i: number, now: number): TraceSpan {
+  const first = s.events[0] ? ms(s.events[0].t) : null;
+  const last = s.events.length ? ms(s.events[s.events.length - 1]!.t) : null;
+  const status = stepStatus(s);
+  const span: TraceSpan = {
+    id: `s${i}`,
+    kind: "step",
+    label: s.agent,
+    start: ms(s.startedAt) ?? first,
+    end: ms(s.finishedAt) ?? (status === "running" ? now : last),
+    status,
+    ...(s.tokens ? { tokens: { input: s.tokens.input, output: s.tokens.output, cacheRead: s.tokens.cacheRead ?? 0, cacheWrite: s.tokens.cacheWrite ?? 0 } } : {}),
+    costUsd: s.costUsd ?? null,
+    ...(s.model ? { model: s.model } : {}),
+    step: i,
+    children: [],
+  };
+
+  const models = (s.calls ?? []).map((c) => ({ c, span: modelSpan(c, i) }));
+  const byId = new Map(models.map((m) => [m.c.id, m.span]));
+  const homeOf = (e: RunEvent, start: number | null): TraceSpan => {
+    if (e.inCall && byId.has(e.inCall)) return byId.get(e.inCall)!;
+    // Older records: the last model call (of the same agent) that answered
+    // before the tool started.
+    const same = models.filter((m) => (m.c.subagent ?? null) === (e.subagent ?? null) && m.span.end !== null && start !== null && m.span.end <= start + 50);
+    return same.length ? same[same.length - 1]!.span : span;
+  };
+
+  for (const t of toolCalls(s.events)) {
+    const home = homeOf(t.e, t.start);
+    const tool: TraceSpan = {
+      id: `s${i}/t:${t.e.call ?? `${t.start}`}`,
+      kind: "tool",
+      label: t.e.text,
+      start: t.start,
+      end: t.end ?? (status === "running" ? now : t.start),
+      status: t.err ? "error" : t.end === null && status === "running" ? "running" : "ok",
+      ...(t.e.call ? { call: t.e.call } : {}),
+      ...(t.captured ? { captured: true } : {}),
+      ...(t.e.subagent ? { subagent: t.e.subagent } : {}),
+      step: i,
+      children: [],
+    };
+    home.children.push(tool);
+  }
+  // A model call lasts until the last tool it asked for has finished.
+  for (const m of models) {
+    const ends = m.span.children.map((c) => c.end).filter((x): x is number => x !== null);
+    if (ends.length && m.span.end !== null) m.span.end = Math.max(m.span.end, ...ends);
+  }
+  span.children.push(...models.map((m) => m.span));
+
+  // Errors, as leaves: why the step failed, read without opening the trace.
+  s.events.forEach((e, k) => {
+    if (e.type !== "error") return;
+    span.children.push({ id: `s${i}/e${k}`, kind: "error", label: "error", start: ms(e.t), end: ms(e.t), status: "error", text: e.text, step: i, children: [] });
+  });
+  span.children.sort((a, b) => (a.start ?? Infinity) - (b.start ?? Infinity));
+  return span;
+}
+
+export function buildTraceTree(run: RunRecord, now = Date.now()): TraceSpan {
+  const status: SpanStatus =
+    run.status === "completed" ? "ok" : run.status === "failed" ? "error" : run.status === "awaiting-approval" ? "waiting" : run.status === "queued" ? "pending" : "running";
+  return {
+    id: "run",
+    kind: "run",
+    label: run.flow,
+    start: ms(run.startedAt),
+    end: ms(run.finishedAt) ?? (status === "running" || status === "waiting" ? now : null),
+    status,
+    children: run.steps.map((s, i) => stepSpan(s, i, now)),
+  };
+}
+
+/** The ids from the root to the first thing that went wrong — what the
+ *  view opens on; [] when nothing did. A failed tool beats the step's error
+ *  line, which beats the failed step itself. */
+export function failurePath(root: TraceSpan): string[] {
+  let best: { path: string[]; rank: number } | null = null;
+  const rank = (s: TraceSpan) => (s.kind === "tool" ? 3 : s.kind === "error" ? 2 : s.kind === "step" ? 1 : 0);
+  const walk = (s: TraceSpan, path: string[]) => {
+    const here = [...path, s.id];
+    if (s.status === "error" && s.kind !== "run" && (!best || rank(s) > best.rank)) best = { path: here, rank: rank(s) };
+    for (const c of s.children) walk(c, here);
+  };
+  walk(root, []);
+  return best ? (best as { path: string[] }).path : [];
+}

package/src/translator.ts

@@ -85,6 +85,11 @@ export interface TranslatorSpec {
   /** The provider block's `params:` — merged into the outgoing body after
    *  the translation, so a file can set what this format does not model. */
   params?: Record<string, unknown>;
+  /** `prompt_cache_key` for an endpoint that routes its prompt cache by
+   *  one (OpenAI, Mistral): the same key for every request that shares a
+   *  prefix — one per agent (prompt-layers.ts). Unset where the preset
+   *  does not say the parameter is understood. */
+  cacheKey?: string;
   /** How the endpoint is named in the trace. */
   label?: string;
   /** The step's egress lease, when the sandbox must not hold the key: the
@@ -185,12 +190,14 @@ export function toChatCompletions(
     maxTokensParam?: "max_tokens" | "max_completion_tokens";
     reasoningEffort?: boolean;
     stream: boolean;
+    cacheKey?: string;
     /** Merged in last, so the file wins over the translation. */
     params?: Record<string, unknown>;
   },
   drop: Dropped = dropped(),
 ): Json {
   const out: Json = { model: req.model, stream: opts.stream };
+  if (opts.cacheKey) out.prompt_cache_key = opts.cacheKey;
   const messages: Json[] = [];
 
   const system = textOf(req.system);
@@ -335,11 +342,13 @@ export function toResponses(
   opts: {
     reasoningEffort?: boolean;
     stream: boolean;
+    cacheKey?: string;
     params?: Record<string, unknown>;
   },
   drop: Dropped = dropped(),
 ): Json {
   const out: Json = { model: req.model, stream: opts.stream, store: false };
+  if (opts.cacheKey) out.prompt_cache_key = opts.cacheKey;
   const system = textOf(req.system);
   if (system) out.instructions = system;
 
@@ -948,8 +957,8 @@ export async function startTranslator(spec: TranslatorSpec): Promise<RunningTran
       const drop = dropped();
       const responses = spec.wire === "responses";
       const outbound = responses
-        ? toResponses(body, { reasoningEffort: spec.reasoningEffort, params: spec.params, stream }, drop)
-        : toChatCompletions(body, { maxTokensParam: spec.maxTokensParam, reasoningEffort: spec.reasoningEffort, params: spec.params, stream }, drop);
+        ? toResponses(body, { reasoningEffort: spec.reasoningEffort, params: spec.params, cacheKey: spec.cacheKey, stream }, drop)
+        : toChatCompletions(body, { maxTokensParam: spec.maxTokensParam, reasoningEffort: spec.reasoningEffort, params: spec.params, cacheKey: spec.cacheKey, stream }, drop);
       for (const line of drop.lines()) if (!log.includes(line)) log.push(line);
 
       let upstream: Response;
@@ -1089,6 +1098,7 @@ export function translatorSpecFor(spec: {
   name?: string | null;
   maxTokensParam?: "max_tokens" | "max_completion_tokens";
   reasoningEffort?: boolean;
+  cacheKey?: string;
 }): TranslatorSpec | null {
   if (spec.format !== "openai" && spec.format !== "responses") return null;
   return {
@@ -1099,6 +1109,7 @@ export function translatorSpecFor(spec: {
     params: spec.params,
     maxTokensParam: spec.maxTokensParam,
     reasoningEffort: spec.reasoningEffort,
+    ...(spec.cacheKey ? { cacheKey: spec.cacheKey } : {}),
     label: spec.name ? `${spec.name} (${spec.baseUrl})` : spec.baseUrl,
   };
 }

package/src/trigger-log.ts

@@ -39,6 +39,7 @@ export type TriggerOutcome =
   | "debounced"
   | "quarantined"
   | "paused"
+  | "halted"
   | "overlap-skipped"
   | "missed"
   | "failed";

package/src/workspace-check.ts

@@ -0,0 +1,41 @@
+// One workspace's findings, as the Checks page, `GET …/check` and the daily
+// rescan see them (FOL-58): the deploy's checks and the whole scanner, with
+// what the files alone do not carry — the account's network: and the
+// outward tools of the library and the workspace, nearest wins.
+
+import { accountDir, workspaceDir, workspaceTools, type OutwardMark } from "./store.ts";
+import { readAgentsMdKeys } from "./agents-md.ts";
+import { libraryTools } from "./library.ts";
+import { checkFiles, readTree } from "./deploy.ts";
+import type { DeployFile } from "./store.ts";
+import type { ScanFinding, ScanOptions } from "./scan.ts";
+
+/** What the checks read of a workspace, at most. Data (state/ and memory/,
+ *  what agents write) past these is left out and named; the rest past its
+ *  budget is not read at all (TreeTooLarge). On 20 Oct 2026 the daily
+ *  rescan read 1.2 GB of one desk's state/ into a 2 GB heap and crash-looped
+ *  the worker. The rest is 64 MiB because a deploy is 10 MiB a push. */
+export const CHECK_LIMITS = {
+  maxDataFileBytes: 5 * 1024 * 1024,
+  maxDataBytes: 32 * 1024 * 1024,
+  maxDataFiles: 5000,
+  maxSourceBytes: 64 * 1024 * 1024,
+} as const;
+
+/** A workspace as the checks read it: the deploy's tree within CHECK_LIMITS.
+ *  Read once and hand it to everything that checks. */
+export function checkTree(dir: string, onSkip?: (path: string, bytes: number) => void): DeployFile[] {
+  return readTree(dir, { ...CHECK_LIMITS, onSkip });
+}
+
+export function checkOptions(tenant: string, workspace: string): ScanOptions {
+  const tools = { ...libraryTools(tenant), ...workspaceTools(tenant, workspace) };
+  const outwardTools = Object.entries(tools).filter(([, d]) => (d as OutwardMark).outward === true).map(([n]) => n);
+  // AGENTS.md, or the older project.md, as the runner reads it (Codex review).
+  const accountNetwork = readAgentsMdKeys(accountDir(tenant)).network;
+  return { outwardTools, accountNetwork };
+}
+
+export function checkWorkspace(tenant: string, workspace: string, tree: DeployFile[] = checkTree(workspaceDir(tenant, workspace))): ScanFinding[] {
+  return checkFiles(tree, checkOptions(tenant, workspace));
+}