@foldrun/core 0.6.0 → 0.7.0

package/dist/src/run-container.js

@@ -25,7 +25,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { isPlatformPath } from "./store.js";
 import { divertedSummary, isDivertedPath, overlayTestWrites } from "./test-mode.js";
 import { isFileValue, fileContent } from "./secrets.js";
-import { safeTenantSegment } from "./runtime.js";
+import { safeTenantSegment, systemInstallSh, SYSTEM_FROM_INPUT_SH, INSTALL_SOCKET } from "./runtime.js";
 import { isOperatorEvent } from "./operator.js";
 import { parseBrowserPod } from "./browser-pod.js";
 /**
@@ -173,19 +173,39 @@ export function mergeAppends(was, host, next) {
     const max = Math.min(h.length, n.length);
     while (common < max && h.charCodeAt(common) === n.charCodeAt(common))
         common++;
-    for (let end = common; end >= 0; end--) {
-        if (end > 0 && h[end - 1] !== "\n")
-            continue;
-        const prefix = h.slice(0, end);
-        const matches = typeof was === "string" ? sha(Buffer.from(prefix, "utf8")) === was : Buffer.from(prefix, "utf8").equals(was);
-        if (!matches)
-            continue;
-        const hostAdded = h.slice(end);
-        const stepAdded = n.slice(end);
-        const joined = hostAdded && !hostAdded.endsWith("\n") ? hostAdded + "\n" : hostAdded;
-        return Buffer.from(prefix + joined + stepAdded, "utf8");
+    // One pass over the shared prefix. Rebuilding and hashing the prefix at
+    // every line boundary, from the longest down, was quadratic: on 6 Oct 2026
+    // a conflicted file of a few MB held the worker's event loop for minutes,
+    // the liveness probe killed it every 4.5 minutes, and every step on the box
+    // lost its model connection.
+    let end = -1;
+    if (typeof was === "string") {
+        const run = crypto.createHash("sha256");
+        if (run.copy().digest("hex") === was)
+            end = 0;
+        let from = 0;
+        for (let nl = h.indexOf("\n"); nl !== -1 && nl < common; nl = h.indexOf("\n", nl + 1)) {
+            run.update(h.slice(from, nl + 1), "utf8");
+            from = nl + 1;
+            if (run.copy().digest("hex") === was)
+                end = from;
+        }
     }
-    return null;
+    else {
+        // The base's bytes are known, so it can only end at their length.
+        const base = was.toString("utf8");
+        if (base.length <= common &&
+            (base.length === 0 || base.endsWith("\n")) &&
+            h.startsWith(base) &&
+            Buffer.from(base, "utf8").equals(was))
+            end = base.length;
+    }
+    if (end < 0)
+        return null;
+    const hostAdded = h.slice(end);
+    const stepAdded = n.slice(end);
+    const joined = hostAdded && !hostAdded.endsWith("\n") ? hostAdded + "\n" : hostAdded;
+    return Buffer.from(h.slice(0, end) + joined + stepAdded, "utf8");
 }
 export function applyContainerChanges(hostWs, containerWs, baseline, note, divert) {
     const applied = [];
@@ -283,6 +303,12 @@ export function applyContainerChanges(hostWs, containerWs, baseline, note, diver
  * that fills it.
  */
 export const RUNTIME_CACHE = "/home/agent/.foldrun/runner/.runtimes";
+/** Starts the install helper as root, in the background, before the drop to
+ *  the agent user: the root half of the `install` tool (install-helper.ts).
+ *  The agent reaches it only through the socket; it installs only validated
+ *  Debian package names, and dies with the container. */
+export const INSTALL_HELPER_SH = `FOLDRUN_INSTALL_SOCKET=${INSTALL_SOCKET}; export FOLDRUN_INSTALL_SOCKET
+node /opt/runner/node_modules/@foldrun/core/dist/src/install-helper.js "$FOLDRUN_INSTALL_SOCKET" ${RUNTIME_CACHE} >/dev/null 2>&1 &`;
 /**
  * Where the platform's shared runtime layer is mounted, read-only, in a run
  * pod — and read-write, one entry at a time, in the pod that builds an entry
@@ -420,6 +446,25 @@ try {
   // meet the packages its runtime declared, not the image's bare python.
   Object.assign(env, runtime.env);
 
+  // install: what the agent finds it needs mid-step. apt goes through the
+  // root start-up's helper (install-helper.ts); pip and npm land in a
+  // directory of this container's own, on the paths from the first turn.
+  const { buildInstallTool, INSTALL_TOOL } = await import("@foldrun/core/install-tool");
+  const { stepInstallEnv, INSTALL_SOCKET } = await import("@foldrun/core/runtime");
+  const installDir = "/home/agent/.foldrun/step";
+  const installing = (input.allowed ?? []).includes(INSTALL_TOOL);
+  if (installing) Object.assign(env, stepInstallEnv(installDir, env));
+  const install = installing
+    ? buildInstallTool({
+        dir: installDir,
+        socket: env.FOLDRUN_INSTALL_SOCKET || INSTALL_SOCKET,
+        cacheRoot: "${RUNTIME_CACHE}",
+        python: env.VIRTUAL_ENV ? env.VIRTUAL_ENV + "/bin/python" : "python3",
+        env,
+        emit,
+      })
+    : { server: null };
+
   // API and script tools, rebuilt in here from their specs. Secrets were
   // substituted into API headers before the input crossed the boundary, so
   // buildApiTools gets an already-resolved environment. verify: gets the
@@ -470,6 +515,7 @@ try {
       ...(history.server ? { foldrun_history: history.server } : {}),
       ...(desks.server ? { foldrun_desks: desks.server } : {}),
       ...(ask.server ? { foldrun_ask: ask.server } : {}),
+      ...(install.server ? { foldrun_install: install.server } : {}),
       ...input.mcpServers,
     },
     ...(inbox ? { inbox } : {}),
@@ -757,7 +803,14 @@ RUN node -e ' \\
 
 FROM browsers AS full
 ${CORE_INSTALL}`;
+// runtime: system: — apt as root, before the drop (runtime.ts systemInstallSh).
+// set -e is off around it: a failed install is reported by the driver, which
+// reads the status file and fails the step with apt's own words.
 const ENTRY = `#!/bin/sh
+set +e
+${SYSTEM_FROM_INPUT_SH}
+${systemInstallSh(RUNTIME_CACHE)}
+${INSTALL_HELPER_SH}
 set -e
 chown -R agent:agent /workspace /library /opt/runner/job
 # The runtime cache, when one is mounted. NOT recursive: a warm cache is tens

package/dist/src/runner.d.ts

@@ -1,8 +1,10 @@
 import { type SubagentSpec } from "./subagents.ts";
 import { type FlowStep, type RunRecord, type StepRecord } from "./store.ts";
 import { type Catalog } from "./catalog.ts";
+import { type SearchRoot, type RunDigest } from "./context-tools.ts";
 import { type ScriptSpec } from "./script-tools.ts";
 import { type RuntimeSpec } from "./runtime.ts";
+import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import { type LanguageChoice } from "./language.ts";
 import { type RegionChoice } from "./locale.ts";
 import { type ClockChoice } from "./clock.ts";
@@ -191,6 +193,163 @@ export declare function applicableSkills<T extends {
  */
 export declare function saysUntilMarker(result: string | null, until: string): boolean;
 export declare function resolveDocLinks(text: string, workspaceRoot: string): string;
+export declare function agentContext(agentDir: string, tenant: string, tags?: string[], 
+/** Who is running, so scripts can stamp what they write with its provenance. */
+identity?: {
+    runId?: string;
+    agent?: string;
+}, 
+/** The flow's own `timezone:`, when this step belongs to one. Between the
+ *  agent's frontmatter and the workspace's AGENTS.md in the cascade. */
+flowTimezone?: string | null, 
+/** Only what the agent is granted — no runtime prepared. For a sub-agent,
+ *  whose tools are cut to its parent's and run in the parent's runtime. */
+grantsOnly?: boolean): {
+    front: {
+        [key: string]: any;
+    };
+    clockEnv: {
+        FOLDRUN_LANGUAGE: string;
+        FOLDRUN_REGION?: string | undefined;
+        FOLDRUN_CURRENCY?: string | undefined;
+        FOLDRUN_UNITS: import("./locale.ts").Units;
+        FOLDRUN_CALENDAR: string;
+        FOLDRUN_DATE_LOCAL?: string | undefined;
+        FOLDRUN_RTL: string;
+        TZ: string;
+        FOLDRUN_DATE: string;
+        FOLDRUN_SEARCH_URL?: string | undefined;
+        FOLDRUN_API_URL?: string | undefined;
+        FOLDRUN_WEB_SEARCH_VIA?: string | undefined;
+        FOLDRUN_WEB_SEARCH_SECRET?: string | undefined;
+        FOLDRUN_WEB_FETCH_VIA?: string | undefined;
+        FOLDRUN_WEB_FETCH_SECRET?: string | undefined;
+        FOLDRUN_WEB_ACTIONS?: string | undefined;
+        FOLDRUN_BROWSER_VENDOR?: string | undefined;
+        FOLDRUN_BROWSER_SECRET?: string | undefined;
+        FOLDRUN_BROWSER_VENDOR_SESSION?: string | undefined;
+        FOLDRUN_BROWSER_SESSION?: string | undefined;
+        FOLDRUN_BROWSER_ENGINE?: "chrome" | "chromium" | "firefox" | "lightpanda" | "obscura" | "webkit" | undefined;
+        FOLDRUN_BROWSER_USER_AGENT?: string | undefined;
+        FOLDRUN_BROWSER_DEVICE?: string | undefined;
+        FOLDRUN_BROWSER_LOCALE?: string | undefined;
+        FOLDRUN_BROWSER_TIMEZONE?: string | undefined;
+        FOLDRUN_BROWSER_COOKIES?: string | undefined;
+        FOLDRUN_BROWSER_COOKIE_DOMAIN?: string | undefined;
+        FOLDRUN_BROWSER_STORAGE?: string | undefined;
+        FOLDRUN_BROWSER_STORAGE_ORIGIN?: string | undefined;
+        FOLDRUN_BROWSER_IDENTITIES?: string | undefined;
+        FOLDRUN_BROWSER_HEADLESS?: string | undefined;
+        FOLDRUN_BROWSER_VERSION?: string | undefined;
+        FOLDRUN_BROWSER_LIVE?: string | undefined;
+        FOLDRUN_BROWSER_ALLOWED_DOMAINS?: string | undefined;
+        FOLDRUN_BROWSER_DENY?: string | undefined;
+        FOLDRUN_BROWSER_BOUNDARIES?: string | undefined;
+        FOLDRUN_BROWSER_INIT?: string | undefined;
+        FOLDRUN_BROWSER_EXTENSIONS?: string | undefined;
+        FOLDRUN_BROWSER_WEBGPU?: string | undefined;
+        FOLDRUN_BROWSER_IGNORE_HTTPS_ERRORS?: string | undefined;
+        FOLDRUN_BROWSER_STATE_KEY?: string | undefined;
+        FOLDRUN_BROWSER_VIDEO?: string | undefined;
+        FOLDRUN_BROWSER_LIVE_VIEW?: string | undefined;
+    };
+    /** The zone, where it came from, and anything unreadable on the way —
+     *  reported by the step, not here, so it lands in the run's trace. */
+    clock: ClockChoice;
+    systemPrompt: string;
+    allowed: string[];
+    disabled: string[];
+    unknownTools: string[];
+    shadowed: string[];
+    legacyUse: string[];
+    retiredTools: string[];
+    mcpServers: Record<string, McpServerConfig>;
+    mcpNames: string[];
+    apiTools: import("./api-tools.ts").ApiToolResult;
+    scriptTools: import("./script-tools.ts").ScriptToolResult;
+    apiSpecs: import("./store.ts").ApiSpec[];
+    scriptSpecs: ScriptSpec[];
+    outward: boolean;
+    searchRoots: SearchRoot[];
+    historyDigest: RunDigest[];
+    deskDigest: RunDigest[];
+    searchTools: import("./context-tools.ts").ContextToolResult;
+    historyTools: import("./context-tools.ts").ContextToolResult;
+    deskTools: import("./context-tools.ts").ContextToolResult;
+    ask: {
+        timeoutSec: number;
+    } | null;
+    runtime: {
+        log: string[];
+        error: string | null;
+        executor: import("./container.ts").Executor;
+        spec: RuntimeSpec | null;
+        dispose: (() => void) | undefined;
+    };
+    secretEnv: {
+        [x: string]: string;
+    };
+    formatWarning: string | null;
+    providerEnv: Record<string, string>;
+    providerLabel: string | null;
+    providerSecrets: Record<string, string>;
+    providerWarnings: string[];
+    fallbackEnv: Record<string, string> | null;
+    region: RegionChoice;
+    searchChoice: import("./providers.ts").SearchChoice;
+    fetchChoice: import("./providers.ts").SearchChoice;
+    actionChoices: ({
+        provider: null;
+        error?: undefined;
+        action: "answer" | "crawl" | "extract" | "map" | "monitor";
+    } | {
+        provider: string;
+        secret: string;
+        host: string;
+        error?: undefined;
+        action: "answer" | "crawl" | "extract" | "map" | "monitor";
+    } | {
+        provider: null;
+        error: string;
+        action: "answer" | "crawl" | "extract" | "map" | "monitor";
+    })[];
+    web: {
+        actions: import("./providers.ts").WebAction[] | null;
+        raw: Record<import("./providers.ts").WebAction, unknown>;
+        problems: string[];
+    };
+    language: LanguageChoice;
+    translator: {
+        upstreamBase: string;
+        wire?: import("./translator.ts").TranslatorWire;
+        upstreamKey: string;
+        headers?: Record<string, string>;
+        maxTokensParam?: "max_tokens" | "max_completion_tokens";
+        reasoningEffort?: boolean;
+        params?: Record<string, unknown>;
+        label?: string;
+        egress?: string;
+        timezone: string;
+    } | null;
+    fallbackTranslator: {
+        upstreamBase: string;
+        wire?: import("./translator.ts").TranslatorWire;
+        upstreamKey: string;
+        headers?: Record<string, string>;
+        maxTokensParam?: "max_tokens" | "max_completion_tokens";
+        reasoningEffort?: boolean;
+        params?: Record<string, unknown>;
+        label?: string;
+        egress?: string;
+        timezone: string;
+    } | null;
+    apiWarnings: string[];
+    secretScopes: Record<string, import("./secrets.ts").SecretScope>;
+    missingTools: string[];
+    size: "heavy" | "large" | "small";
+    brokenTools: string[];
+    missingSecrets: string[];
+};
 export declare function repriced(catalog: Catalog | null, model: string, usage: {
     inputTokens: number;
     outputTokens: number;
@@ -215,6 +374,28 @@ attempt: number, status: "completed" | "failed", startedAt: string, eventsBefore
 /** The attempt re-attached to a sandbox a previous driver left: same
  *  attempt, so its row is replaced rather than repeated. */
 reattach?: boolean): void;
+/**
+ * What the person at the gate said, framed for the step's prompt — or "".
+ *
+ * The note is the freshest instruction the step has — later than the flow
+ * file, aimed at this exact run. When the gate asked a question (ask:), the
+ * note IS the answer and is framed as one.
+ *
+ * Both halves go through resolveDocLinks for the same reason the
+ * instruction does: this is authored text on its way to becoming a prompt,
+ * and the rule is that ALL of it expands. A person answering "which list?"
+ * with [[dead-ends]] was sending the model two literal brackets — the one
+ * reference syntax the workspace teaches, and the one place it silently did
+ * nothing. The previous step's results are NOT resolved, deliberately: that
+ * is model output, and a model that happens to emit [[brackets]] must not
+ * thereby name a file.
+ *
+ * An ask: gate approved with no note still says so. It used to add nothing,
+ * so the step never learned its question had been answered: gbp-desk's
+ * rivals sender, told "a plain approval means all offices", saw no answer
+ * at all and stopped BLOCKED (run-muu6r18y-417e, 2026-10-05).
+ */
+export declare function operatorBlock(step: Pick<StepRecord, "ask" | "approvalNote" | "approvedAt">, workspaceRoot: string): string;
 /**
  * Did this attempt call its tools and then fail only on the check after —
  * `verify:`, `output: json`, a schema? For a step whose tools act outward
@@ -245,6 +426,11 @@ export declare function actedThenFailedCheck(events: {
  * happened to create it.
  */
 export declare function copyTreeBytes(from: string, to: string): void;
+/** A refusal of the credential itself, in any of the wordings Claude Code
+ *  has used. "Failed to authenticate: OAuth token revoked" (9 Oct 2026, a
+ *  step started one second before the 09:07:52Z refresh) matched none of the
+ *  older two, so the step failed instead of waiting for the new token. */
+export declare function isAuthRefusal(text: string): boolean;
 /**
  * Wait, briefly, for the mounted credential to become one we have not
  * already been refused on. Returns the new value, or null when the window
@@ -252,6 +438,24 @@ export declare function copyTreeBytes(from: string, to: string): void;
  * wrong", not "this key is stale".
  */
 export declare function awaitRotatedCredential(before: string | undefined, now?: () => number, read?: () => string | undefined, waitMs?: number, pollMs?: number): Promise<string | null>;
+/** A step's own model connection cut: the egress proxy or the worker it
+ *  runs through went away. Only the run's final error, never a tool's — a
+ *  WebFetch that could not connect is the step's business, not ours. */
+export declare function isModelConnectionLost(text: string): boolean;
+/** A tool call written out as text rather than made: the model's last
+ *  message holds `<invoke name=…>` / `<function_calls>` markup. Only the tail
+ *  counts — a reply that quotes such markup mid-way and goes on is fine. */
+export declare function wroteToolCallAsText(text: string): boolean;
+/** Runs again after a tool call written as text. */
+export declare const TEXT_CALL_RETRIES = 1;
+export declare const TEXT_CALL_NOTE: string;
+/** How many times a step whose model connection was cut runs again. */
+export declare const DROP_RETRIES = 2;
+/** May a step whose connection dropped run again? Yes, unless its tools can
+ *  act outward and one ran in this attempt (actedThenFailedCheck's rule). */
+export declare function dropRetrySafe(canActOutward: boolean, attemptEvents: {
+    type: string;
+}[]): boolean;
 /** How many times a busy provider is given another moment, and the longest
  *  any one wait may be. Three is the industry's habit and the point where
  *  waiting longer stops being kinder than failing. */