@foldrun/core 2.6.0 → 2.8.0

package/src/delegate-tools.ts

@@ -0,0 +1,175 @@
+// Isolated sub-agents: a colleague that does a job in ITS OWN sandbox.
+//
+//   subagents: [reader]       # on the delegating agent, unchanged
+//   sandbox: own              # on reader's own agent.md
+//
+// A sub-agent delegated to the ordinary way (subagents.ts) runs inside the
+// parent's SDK session: the parent's pod, secrets, lease and network, its
+// tools cut to the parent's. That protects the parent's context and nothing
+// else — an injected page read by the sub-agent is read in a sandbox the
+// parent's secrets are in.
+//
+// An agent marked `sandbox: own` is instead offered to the parent as a tool,
+// `delegate_<name>(job)`. The call leaves the parent's sandbox through the
+// one door it has (the egress proxy, at its lease — operator.ts), and the
+// worker runs the job as a step of its own: its own pod, its own `tools:`,
+// `secrets:` and `network:` from its own file, NOT cut to the parent's — the
+// parent may hold less. The parent waits and gets the reply text, nothing
+// else. What the sub-agent wrote reaches the workspace when it finishes, so
+// the next step sees it; the reply names the paths.
+//
+// Depth one, as for every sub-agent: the job's own `subagents:` are not
+// offered to it. Its record sits in the run after the parent's, marked
+// `subagentOf` (store.ts), with its own cost and trace.
+//
+// With no channel (a container step on an install without a proxy) the tools
+// are not granted at all; the runner says so on the step.
+
+import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
+import { z } from "zod";
+import type { DelegationResult, OperatorChannel } from "./operator.ts";
+import type { EventExtra } from "./step-exec.ts";
+import { delegateToolName, type DelegateSpec } from "./subagents.ts";
+
+export const DELEGATE_SERVER = "foldrun_delegate";
+/** A job handed over is at most this long — the sub-agent's prompt. */
+export const JOB_MAX = 20_000;
+/** What comes back is cut here: the reply is the parent's context. */
+export const REPLY_MAX = 40_000;
+
+type Emit = (type: "text" | "tool" | "info" | "error", text: string, extra?: EventExtra) => void;
+
+/** The granted names, the same on every path. */
+export function delegateToolNames(specs: DelegateSpec[]): string[] {
+  return specs.map((s) => `mcp__${DELEGATE_SERVER}__${delegateToolName(s.name)}`);
+}
+
+/** The reply as the parent reads it: the sub-agent's words, then what it changed. */
+export function replyText(name: string, r: DelegationResult): string {
+  const body = r.result.trim() || "(no reply)";
+  const cut = body.length > REPLY_MAX ? `${body.slice(0, REPLY_MAX)}\n…(cut at ${REPLY_MAX} characters)` : body;
+  const wrote = r.wrote?.length
+    ? `\n\nFiles ${name} changed (in the workspace from the next step on — not in your sandbox):\n${r.wrote.slice(0, 200).map((w) => `- ${w}`).join("\n")}`
+    : "";
+  const head = r.status === "completed" ? "" : `${name} did not finish (${r.status}). What it said:\n`;
+  return head + cut + wrote;
+}
+
+export function buildDelegateTools(opts: {
+  specs: DelegateSpec[];
+  channel: OperatorChannel | null;
+  emit: Emit;
+  /** The most one job may run; the step's own timeout bounds it anyway. */
+  timeoutSec?: number;
+  now?: () => number;
+}) {
+  const now = opts.now ?? Date.now;
+  const channel = opts.channel;
+  if (!opts.specs.length || !channel?.delegate || !channel.delegation) {
+    return { server: null, toolNames: [] as string[], calls: {} as Record<string, (job: string) => Promise<unknown>> };
+  }
+  const text = (t: string, isError = false) => ({ content: [{ type: "text" as const, text: t }], ...(isError ? { isError: true } : {}) });
+  const run = async (s: DelegateSpec, rawJob: string) => {
+    const job = String(rawJob ?? "").trim().slice(0, JOB_MAX);
+    if (!job) return text(`${delegateToolName(s.name)} needs the job, written out in full.`, true);
+    let id: string;
+    try {
+      ({ id } = await channel.delegate!(s.name, job));
+    } catch (err) {
+      return text(`Could not hand ${s.name} the job: ${err instanceof Error ? err.message : String(err)}`, true);
+    }
+    opts.emit("info", `delegating to ${s.name} (own sandbox): ${job.split("\n")[0].slice(0, 160)}`, { subagent: s.name });
+    const deadline = opts.timeoutSec ? now() + opts.timeoutSec * 1000 : Infinity;
+    while (now() < deadline) {
+      let got: DelegationResult | null = null;
+      try {
+        got = await channel.delegation!(id, Math.min(deadline - now(), 25_000));
+      } catch {
+        // A dropped long-poll is retried; the job goes on meanwhile.
+        await new Promise((r) => setTimeout(r, 2_000));
+        continue;
+      }
+      if (got) {
+        opts.emit(got.status === "completed" ? "info" : "error", `${s.name} ${got.status}${got.wrote?.length ? ` — changed ${got.wrote.length} file(s)` : ""}`, { subagent: s.name });
+        return text(replyText(s.name, got), got.status !== "completed");
+      }
+    }
+    try {
+      await channel.cancelDelegation?.(id);
+    } catch {
+      /* the worker ends it with the step */
+    }
+    return text(`${s.name} did not finish in time; its job was stopped.`, true);
+  };
+  const tools = opts.specs.map((s) =>
+    tool(
+      delegateToolName(s.name),
+      `Hand ${s.name} a whole job: ${s.description} It works in its own sandbox with its own tools and returns its reply — ` +
+        `it has not read your conversation, so write the job out in full: what to do, what to return, where to put files.`,
+      { job: z.string().describe("The complete, self-contained job") },
+      async ({ job }) => run(s, job),
+    ),
+  );
+  return {
+    server: createSdkMcpServer({ name: DELEGATE_SERVER, version: "1.0.0", tools }),
+    toolNames: delegateToolNames(opts.specs),
+    /** Each tool's own function, by agent name, for tests. */
+    calls: Object.fromEntries(opts.specs.map((s) => [s.name, (job: string) => run(s, job)])),
+  };
+}
+
+/** The channel for a step that runs in this process (`foldrun run`): no
+ *  proxy between it and the drive loop, so a job is handed over directly. */
+export function localDelegateChannel(
+  run: (agent: string, job: string, cancelled: () => boolean) => Promise<DelegationResult>,
+): OperatorChannel {
+  const jobs = new Map<string, { done: Promise<DelegationResult>; result?: DelegationResult; cancelled: boolean }>();
+  let n = 0;
+  const none = async () => {
+    throw new Error("nobody can answer here");
+  };
+  return {
+    ask: none,
+    poll: async () => null,
+    inbox: async () => [],
+    async delegate(agent, job) {
+      const id = `local-${++n}`;
+      const entry: { done: Promise<DelegationResult>; result?: DelegationResult; cancelled: boolean } = {
+        cancelled: false,
+        done: Promise.resolve(),
+      } as never;
+      entry.done = run(agent, job, () => entry.cancelled)
+        .catch((err): DelegationResult => ({ status: "failed", result: err instanceof Error ? err.message : String(err) }))
+        .then((r) => (entry.result = r));
+      jobs.set(id, entry);
+      return { id };
+    },
+    async delegation(id, maxMs) {
+      const entry = jobs.get(id);
+      if (!entry) return { status: "skipped", result: "no such job" };
+      if (entry.result) return entry.result;
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      const r = await Promise.race([
+        entry.done,
+        new Promise<null>((res) => (timer = setTimeout(() => res(null), Math.max(0, maxMs)))),
+      ]);
+      clearTimeout(timer);
+      return r;
+    },
+    async cancelDelegation(id) {
+      const entry = jobs.get(id);
+      if (entry) entry.cancelled = true;
+    },
+  };
+}
+
+/** The line the delegating step's prompt carries, so the model knows who
+ *  works where. */
+export function delegatePromptLine(specs: DelegateSpec[]): string {
+  return (
+    `<isolated-subagents>\nThese colleagues work in their own sandbox, with their own tools; call the tool to hand one a job ` +
+    `and you get back its reply and the paths of any files it changed:\n` +
+    specs.map((s) => `- ${delegateToolName(s.name)}: ${s.description}`).join("\n") +
+    `\n</isolated-subagents>`
+  );
+}

package/src/egress.ts

@@ -43,7 +43,7 @@
 // platform's (it needs a long-lived process and a Service); the pod side is
 // here in core, because it is what the runner image runs.
 
-import type { PeerInfo } from "./operator.ts";
+import type { DelegationResult, PeerInfo } from "./operator.ts";
 import { trimSlashes } from "./paths.ts";
 import type { TestEffect } from "./test-mode.ts";
 import type { NetworkLevel } from "./network.ts";
@@ -96,6 +96,14 @@ export function hostOf(url: string): string | null {
  * from the step's declared secrets and the hosts its tools and provider
  * name; the proxy enforces it per request.
  */
+/** Which workload a lease is for — the runner's word, never the pod's: what
+ *  an identity token's subject is built from (oidc-issuer.ts). */
+export interface LeaseWho {
+  workspace: string;
+  agent: string;
+  flow?: string;
+}
+
 export interface EgressGrant {
   /** Secret name → the hosts that secret may be substituted for. */
   secrets: Record<string, { value: string; hosts: string[] }>;
@@ -116,6 +124,9 @@ export interface EgressGrant {
   /** Refuse a site off the list (true), or allow it and name it in the
    *  trace (false: report only). Set by the platform when it leases. */
   enforce?: boolean;
+  /** Identity name → the audience its tokens are for: the only identities
+   *  this step may ask the proxy's /identity door to mint (oidc-issuer.ts). */
+  identities?: Record<string, { audience: string }>;
 }
 
 export interface EgressLease {
@@ -160,13 +171,37 @@ export interface EgressHooks {
   /** `step` — the step's index in run.steps; keys that step's operator inbox.
    *  `agent` and `peers` — this step's agent and the other steps of its
    *  parallel group (tools: [peers]): the proxy serves the roster and
-   *  addresses a colleague's message to the right inbox. */
-  lease(args: { tenant: string; runId: string; grant: EgressGrant; test?: boolean; step?: number; agent?: string; peers?: PeerInfo[] }): Promise<EgressLease | null>;
+   *  addresses a colleague's message to the right inbox.
+   *  `delegates` — the `sandbox: own` sub-agents this step may hand a job
+   *  to over the delegate door (delegate-tools.ts); the proxy refuses any
+   *  other name. */
+  lease(args: { tenant: string; runId: string; grant: EgressGrant; test?: boolean; step?: number; agent?: string; peers?: PeerInfo[]; who?: LeaseWho; delegates?: string[] }): Promise<EgressLease | null>;
+  /** The run is still being driven: renew its leases' heartbeat. Optional —
+   *  an install without leases has nothing to renew. */
+  renew?(runId: string): Promise<number>;
   /** The step is over — every attempt, however it ended (tools: [peers]).
    *  A lease comes and goes per attempt, so it cannot say this: a sibling
    *  between retries, or waiting for a slot, holds none and is not done.
    *  Optional: a platform without it keeps every sibling reachable. */
   stepEnded?(args: { tenant: string; runId: string; step: number }): Promise<void>;
+  /** Serve the jobs a step posts to the delegate door while it runs
+   *  (`sandbox: own` sub-agents): each is handed to `run`, whose result the
+   *  door then answers the step's long-poll with. `close()` stops serving
+   *  and settles anything unfinished as skipped. Optional: a platform
+   *  without it offers no delegate tools, and the runner says so. */
+  delegations?(
+    args: { tenant: string; runId: string; step: number; resuming?: boolean },
+    run: (job: DelegationJob) => Promise<DelegationResult>,
+  ): { close(): Promise<void> };
+}
+
+/** One job posted to the delegate door. */
+export interface DelegationJob {
+  id: string;
+  agent: string;
+  job: string;
+  /** Set when the step cancelled it (the delegate tool timed out). */
+  cancelled?: () => boolean;
 }
 
 /** Strip a header set of the proxy's own and hop-by-hop headers. */

package/src/frontmatter-fields.ts

@@ -89,6 +89,7 @@ const AGENT: FieldSpec[] = [
   { key: "mcpServers", type: "object", help: "MCP servers, name → {command | url, args, env, headers}" },
   { key: "agents", type: ["list", "string"], help: "colleagues it may consult" },
   { key: "subagents", type: ["list", "string"], help: "colleagues it may delegate to" },
+  { key: "sandbox", type: "string", values: ["own", "parent"], help: "when delegated to as a sub-agent: own = its own sandbox, tools, secrets and network; parent (default) = inside the delegating step's" },
   { key: "secrets", type: ["list", "string"], help: "keys it spends itself" },
   { key: "budget", type: ["number", "string"], help: "USD per run" },
   { key: "limits", type: "object", validated: true, help: "per-step call limits" },
@@ -240,7 +241,7 @@ const SAID_WHAT_IT_IS: FieldSpec[] = [
 const JOB_FIELDS: Partial<Record<SchemaKind, Partial<Record<Job, readonly string[]>>>> = {
   agent: {
     governance: ["owner", "budget"],
-    guardrail: ["limits", "network", "hooks", "disallowedTools", "permissionMode", "secrets"],
+    guardrail: ["limits", "network", "hooks", "disallowedTools", "permissionMode", "secrets", "sandbox"],
   },
   flow: {
     governance: ["owner", "approvers", "approve_within", "budget", "priority"],

package/src/oauth-presets.ts

@@ -19,6 +19,12 @@ export interface OAuthPreset {
   hint: string;
 }
 
+/**
+ * @deprecated foldrun is a runner and keeps no list of providers: the
+ * dashboard and CLI take the provider's own URLs and an `authorize_extra`
+ * map (`--authorize-param`) instead. Kept for apps saved from a preset and
+ * the CLI's deprecated `--provider`; to be removed in a major.
+ */
 export const OAUTH_PRESETS: Record<string, OAuthPreset> = {
   google: {
     authorize_url: "https://accounts.google.com/o/oauth2/v2/auth",
@@ -51,4 +57,5 @@ export const OAUTH_PRESETS: Record<string, OAuthPreset> = {
   },
 };
 
+/** @deprecated see OAUTH_PRESETS. */
 export const OAUTH_PRESET_NAMES = Object.keys(OAUTH_PRESETS);

package/src/operator.ts

@@ -99,6 +99,24 @@ export interface OperatorChannel {
   /** Leave `text` in the inbox of the sibling named `to` (or of every
    *  sibling, `"all"`). Resolves with the agents it reached. */
   tell?(to: string, text: string): Promise<{ to: string[] }>;
+  /** `sandbox: own` sub-agents (delegate-tools.ts): hand `agent` a job. The
+   *  worker runs it in its own sandbox; only the reply comes back. Optional:
+   *  an older proxy has no delegate door. */
+  delegate?(agent: string, job: string): Promise<{ id: string }>;
+  /** Waits up to `maxMs` for that job to finish; null while it still runs. */
+  delegation?(id: string, maxMs: number): Promise<DelegationResult | null>;
+  /** The parent stopped waiting (its step ended): stop the job. Best effort. */
+  cancelDelegation?(id: string): Promise<void>;
+}
+
+/** How an isolated sub-agent's job ended, as the delegating step hears it. */
+export interface DelegationResult {
+  status: "completed" | "failed" | "skipped";
+  /** Its reply — all the parent sees of its work. */
+  result: string;
+  /** Workspace paths it changed. They reach the workspace when it ends, so
+   *  the next step sees them; the delegating step's own sandbox does not. */
+  wrote?: string[];
 }
 
 export const QUESTION_MAX = 2_000;
@@ -175,6 +193,40 @@ export function httpChannel(egress: string | undefined | null, fetchImpl: typeof
       );
       return { to: Array.isArray(body.to) ? (body.to as string[]) : [] };
     },
+    async delegate(agent, job) {
+      const body = await json(
+        await fetchImpl(`${ep.base}/delegate/${ep.token}`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ agent, job }),
+          signal: AbortSignal.timeout(15_000),
+        }),
+      );
+      return { id: String(body.id) };
+    },
+    async delegation(id, maxMs) {
+      const wait = Math.max(0, Math.min(maxMs, POLL_MS));
+      const body = await json(
+        await fetchImpl(`${ep.base}/delegate/${ep.token}/${encodeURIComponent(id)}?wait=${wait}`, {
+          signal: AbortSignal.timeout(wait + 15_000),
+        }),
+      );
+      const status = body.status;
+      if (status !== "completed" && status !== "failed" && status !== "skipped") return null;
+      return {
+        status,
+        result: typeof body.result === "string" ? body.result : "",
+        wrote: Array.isArray(body.wrote) ? (body.wrote as unknown[]).filter((w): w is string => typeof w === "string") : [],
+      };
+    },
+    async cancelDelegation(id) {
+      await json(
+        await fetchImpl(`${ep.base}/delegate/${ep.token}/${encodeURIComponent(id)}`, {
+          method: "DELETE",
+          signal: AbortSignal.timeout(5_000),
+        }),
+      );
+    },
   };
 }
 

package/src/platform.ts

@@ -107,6 +107,11 @@ export interface PlatformHooks {
   isolation: Record<string, IsolatedStepRunner>;
   /** Destroy whatever sandboxes a stopped run still has. Default: nothing to destroy. */
   killRunSandboxes(runId: string): void;
+  /** Destroy ONE step's sandbox, by the ref on its record — a sandbox: own
+   *  job orphaned by a restart while its parent re-attaches, where killing
+   *  the whole run's would take the parent too. Optional: an executor that
+   *  cannot re-attach never needs it (the whole run's are killed instead). */
+  killSandbox?(sandbox: { kind: string; ref: string }): void;
   /** Publish storage/public/ as share links after a run. Default: no links. */
   syncPublicShares(tenant: string, workspace: string): Promise<{ added: string[] }>;
   /** This account's own data key, or null to use the install key. */

package/src/run-container.ts

@@ -35,7 +35,7 @@ import { safeTenantSegment, systemInstallSh, SYSTEM_FROM_INPUT_SH, INSTALL_SOCKE
 import { egressCaSh, type NetworkLevel } from "./network.ts";
 import type { ScriptSpec } from "./script-tools.ts";
 import type { ConsultSpec } from "./agent-tools.ts";
-import type { SubagentSpec } from "./subagents.ts";
+import type { DelegateSpec, SubagentSpec } from "./subagents.ts";
 import { isOperatorEvent, type OperatorEvent } from "./operator.ts";
 import type { SearchRoot, RunDigest } from "./context-tools.ts";
 import type { TranslatorSpec } from "./translator.ts";
@@ -66,6 +66,9 @@ export interface ContainerStepInput {
   consults: ConsultSpec[];
   /** `subagents:` — built host-side (runner.ts), plain JSON. */
   subagents?: SubagentSpec[];
+  /** `sandbox: own` sub-agents — offered as delegate_<name> tools; their
+   *  jobs run on the worker in sandboxes of their own (delegate-tools.ts). */
+  delegates?: DelegateSpec[];
   timeoutSec?: number;
   /** The step's spend ceiling and the model's per-token price — see
    *  step-exec.ts. Values, so the driver can enforce them in the pod. */
@@ -214,6 +217,10 @@ export interface ContainerStepOutcome {
   /** The pod's reconnects and, when it was lost, what the step had written —
    *  see ExecOutcome.browserPod. */
   browserPod?: BrowserPodOutcome;
+  /** Workspace paths the step's changes were applied to on the host — what
+   *  applyContainerChanges returned. An isolated sub-agent's reply names
+   *  them to the step that delegated (delegate-tools.ts). */
+  applied?: string[];
 }
 
 /**
@@ -626,6 +633,7 @@ try {
   const { buildConsultTools } = await import("@foldrun/core/agent-tools");
   const { buildSearchTools, buildHistoryTools, buildDeskTools } = await import("@foldrun/core/context-tools");
   const { httpChannel, buildAskTool, buildPeerTools, inboxReader } = await import("@foldrun/core/operator");
+  const { buildDelegateTools } = await import("@foldrun/core/delegate-tools");
   const { startTranslator } = await import("@foldrun/core/translator");
   const { prepareRuntime } = await import("@foldrun/core/runtime");
   const { materializeFileSecrets } = await import("@foldrun/core/secret-files");
@@ -725,6 +733,39 @@ try {
   const ask = input.ask ? buildAskTool({ channel, timeoutSec: input.ask.timeoutSec, emit }) : { server: null };
   const peers = input.peers ? buildPeerTools({ channel, self: input.peers.self, siblings: input.peers.siblings, emit }) : { server: null };
   const inbox = channel ? inboxReader(channel, emit) : undefined;
+  // sandbox: own sub-agents: a tool each, whose job runs in its own sandbox
+  // on the worker, reached over the same proxy door.
+  const delegate = input.delegates?.length ? buildDelegateTools({ specs: input.delegates, channel, emit, timeoutSec: input.timeoutSec }) : { server: null };
+
+  // Keyless cloud identities (FOLDRUN_IDENTITIES): each token file kept
+  // fresh through the proxy's /identity door, which mints only what this
+  // step's lease was granted. Fetched before the step starts, renewed five
+  // minutes before it expires (with jitter); a failure is said and retried.
+  // Plain JS: this text is the driver, not TypeScript.
+  const identityNames = (env.FOLDRUN_IDENTITIES || "").split(",").filter(Boolean);
+  if (identityNames.length) {
+    // No backslashes: this sits inside a template literal, which eats them.
+    const ep = new RegExp("^(https?://[^/]+)/e/([A-Za-z0-9_-]{16,})/?$").exec(env.FOLDRUN_EGRESS || "");
+    const dir = env.FOLDRUN_IDENTITY_DIR || "/tmp/foldrun-identity";
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const keepFresh = async (name) => {
+      let wait = 30000;
+      try {
+        if (!ep) throw new Error("no egress proxy to ask");
+        const res = await fetch(ep[1] + "/identity/" + ep[2] + "/" + name, { signal: AbortSignal.timeout(15000) });
+        const body = await res.json().catch(() => ({}));
+        if (!res.ok || !body.token) throw new Error((body.error && body.error.message) || ("proxy answered " + res.status));
+        const file = dir + "/" + name.toLowerCase() + ".jwt";
+        fs.writeFileSync(file + ".tmp", body.token, { mode: 0o600 });
+        fs.renameSync(file + ".tmp", file);
+        wait = Math.max(30000, body.expiresAt - Date.now() - 300000 + Math.floor(Math.random() * 60000) - 30000);
+      } catch (err) {
+        emit("error", "identity " + name + ": " + (err && err.message ? err.message : String(err)) + " — trying again in 30s");
+      }
+      setTimeout(() => { void keepFresh(name); }, wait).unref();
+    };
+    await Promise.all(identityNames.map(keepFresh));
+  }
 
   mark("tools");
   const outcome = await executeStep({
@@ -746,6 +787,7 @@ try {
       ...(desks.server ? { foldrun_desks: desks.server } : {}),
       ...(ask.server ? { foldrun_ask: ask.server } : {}),
       ...(peers.server ? { foldrun_peers: peers.server } : {}),
+      ...(delegate.server ? { foldrun_delegate: delegate.server } : {}),
       ...(install.server ? { foldrun_install: install.server } : {}),
       ...input.mcpServers,
     },
@@ -1687,8 +1729,9 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
     const wsOut = path.join(staging, "out");
     fs.mkdirSync(wsOut);
     const back = spawnSync(cli(), ["cp", `${containerId}:/workspace/.`, wsOut], { encoding: "utf8" });
+    let applied: string[] = [];
     if (back.status === 0) {
-      applyContainerChanges(args.workspaceRoot, wsOut, wsIn, (m) => args.emit("error", m), args.divert);
+      applied = applyContainerChanges(args.workspaceRoot, wsOut, wsIn, (m) => args.emit("error", m), args.divert);
     } else {
       args.emit("error", `copy-out failed — the step's file changes were lost:\n${back.stderr.slice(0, 500)}`);
     }
@@ -1702,7 +1745,7 @@ export async function runStepInContainer(args: RunInContainerArgs): Promise<Cont
       phases,
     };
     args.emit("info", timingLine(timing));
-    return { ...outcome, timing };
+    return { ...outcome, timing, applied };
   } finally {
     if (containerId) spawnSync(cli(), ["rm", "-f", containerId], { stdio: "ignore" });
     fs.rmSync(staging, { recursive: true, force: true });