@foldrun/core 9.1.0 → 9.2.0

package/src/runner.ts

@@ -38,7 +38,7 @@ const isolatedRun = () => {
   return mode === "container" || (!!mode && mode in platform.isolation);
 };
 import { gatherConsults, buildConsultTools } from "./agent-tools.ts";
-import { DELEGATE_TOOL, gatherSubagents, ownSandbox, subagentPrompt, subagentTools, type DelegateSpec, type SubagentSpec } from "./subagents.ts";
+import { DELEGATE_TOOL, gatherSubagents, ownSandbox, subagentPrompt, subagentTools, SUBAGENT_NO_REMOTES, type DelegateSpec, type SubagentSpec } from "./subagents.ts";
 import { DELEGATE_SERVER, buildDelegateTools, delegatePromptLine, delegateToolNames, localDelegateChannel, readCopyBack } from "./delegate-tools.ts";
 import type { DelegationResult } from "./operator.ts";
 import type { StepDelegation } from "./store.ts";
@@ -91,14 +91,17 @@ import {
   adoptLegacyVersionKey,
   listAgents,
   isOneSegment,
+  stoppedByText,
 } from "./store.ts";
 import { canReadBack } from "./tool-output.ts";
 import { PromptLayers, promptCacheKey } from "./prompt-layers.ts";
 import { loadCatalog, checkModel, clampEffort, catalogCost, findModel, tokenPriceOf, type Catalog, type TokenPrice } from "./catalog.ts";
 import { resolveSecrets, getSecret, materializeSecrets, secretSites, isClientCertValue, clientCertOf, withoutHeldCerts, isIdentityValue, identityOf } from "./secrets.ts";
-import { resolveNetwork, networkLine, networkEnforceWanted, proxyEnv, EGRESS_CA_ENV } from "./network.ts";
+import { resolveNetwork, networkLine, networkEnforceWanted, proxyEnv, siteCovers, EGRESS_CA_ENV } from "./network.ts";
 import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.ts";
 import { buildApiTools, secretsUsedByApi } from "./api-tools.ts";
+import { buildA2ATools } from "./a2a-tools.ts";
+import { parseRemotes, remoteSecretNames, remoteGrantHost, remoteNetworkHosts, remotesPromptLines, A2A_TOOLS, type RemoteSpec } from "./a2a-remotes.ts";
 import { attachOperations, prefetchOpenApi } from "./openapi.ts";
 import { buildSearchTools, buildHistoryTools, buildDeskTools, digestRuns, type SearchRoot, type RunDigest } from "./context-tools.ts";
 import { startTranslator, translatorSpecFor, type TranslatorSpec } from "./translator.ts";
@@ -632,6 +635,12 @@ export function buildSubagentSpecs(o: {
         continue;
       }
       const tools = subagentTools(own.allowed, o.parentAllowed);
+      // remotes: are the parent's server and credentials; withheld here
+      // (subagents.ts isA2aTool), and the sub-agent and the step are told.
+      const remotesWithheld = own.remotes.length > 0;
+      if (remotesWithheld) {
+        o.push("info", `subagents: "${sub.name}" declares remotes: (${own.remotes.map((r) => r.name).join(", ")}), which it does not get inside this step — ${SUBAGENT_NO_REMOTES}`);
+      }
       if (!tools.length) {
         o.push("error", `subagents: "${sub.name}" holds none of its tools inside this step — it can only answer from its prompt (use agents: for that)`);
       }
@@ -645,7 +654,7 @@ export function buildSubagentSpecs(o: {
           parent: o.self,
           workspace: path.basename(o.workspaceRoot),
           shared: sharedInstructions(sub.dir, o.tenant),
-        }),
+        }, { remotesWithheld }),
         tools,
         disallowedTools: refNames(own.front.disallowedTools),
         model: own.front.model ? resolveModel(own.front.model) : "inherit",
@@ -1134,6 +1143,10 @@ export function agentContext(
   // APIs — the agent's own definitions, plus workspace tools it granted by
   // name. Library tools are defined once and reused.
   const apis = parseApis(front.apis);
+  // remotes: — outside A2A agents (a2a-remotes.ts). The tools are built
+  // where the step runs (runStep, run-container.ts), like ask's: they keep
+  // handles under the run and the step, which only the step knows.
+  const remotes = parseRemotes(front.remotes);
   // Scripts declared inline on the agent, plus any script-type tool it
   // granted — one list grants both kinds.
   const scriptSpecs = parseScripts(front.scripts);
@@ -1212,6 +1225,10 @@ export function agentContext(
   if (apiTools.promptLines.length) {
     parts.add("apis", `# APIs you can call\n\n${apiTools.promptLines.join("\n")}`);
   }
+  // Read-only (permissionMode: plan) holds no tool that sends; nor the line.
+  if (remotes.length && front.permissionMode !== "plan") {
+    parts.add("remotes", `# Outside agents you can call (A2A)\n\n${remotesPromptLines(remotes).join("\n")}`);
+  }
 
   // Secrets an agent declared become env vars for its scripts and bash.
   //
@@ -1286,10 +1303,24 @@ export function agentContext(
   // One name once, however many places asked for it.
   declared.splice(0, declared.length, ...new Set(declared));
   const referenced = [...new Set(apis.flatMap(secretsUsedByApi))];
+  // A remote's secret travels with the remote, as an API's does: naming it
+  // under remotes: is enough. One nothing else in the step uses is resolved
+  // apart, into remoteSecretEnv, and reaches the a2a tools alone — never
+  // secretEnv, which every script, Bash, consult and the sandbox's
+  // environment are built from, on either path. On the isolated path it is
+  // then the egress proxy's to fill for the card's origin (runStep). A
+  // secret the agent also declares, or an API also uses, is the agent's own
+  // choice to expose, and stays where it was.
+  const remoteSecrets = remoteSecretNames(remotes);
+  const remoteOnlySecrets = remoteSecrets.filter((n) => !declared.includes(n) && !referenced.includes(n));
   const {
     env: secretEnv,
     from: secretScopes,
   } = resolveSecrets(tenant, [...new Set([...declared, ...referenced])], workspace);
+  const { env: remoteSecretEnv, from: remoteScopes } = resolveSecrets(tenant, remoteOnlySecrets, workspace);
+  // Which store each came from, for the trace's "secret X ← scope" lines and
+  // the proxy's health keys.
+  Object.assign(secretScopes, remoteScopes);
   const { missing: missingDeclared } = resolveSecrets(tenant, declared, workspace);
 
   // The step's pod size. Three classes, not a dial: a size is a price and a
@@ -1716,6 +1747,7 @@ export function agentContext(
     }
   }
   allowed.push(...apiTools.toolNames, ...scriptTools.toolNames);
+  if (remotes.length) allowed.push(...A2A_TOOLS);
 
   // tools: [search] — every place a fact of this agent's could be, in the
   // same nearest-wins order the prompt lists them. tools: [history] — the
@@ -1813,8 +1845,18 @@ export function agentContext(
     // path, which serialises specs across the container boundary rather
     // than using the servers built here.
     apiSpecs: apis,
+    // remotes: — the specs, and the secrets only they use (runStep binds
+    // those to each card's origin).
+    remotes,
+    remoteOnlySecrets,
+    // Never spread into an environment: the a2a tools' alone.
+    remoteSecretEnv,
     scriptSpecs,
-    outward: outward || scriptSpecs.some((sc) => sc.outward),
+    // A message to an outside agent acts outside the workspace as surely as
+    // an outward tool: a retry after a failed check could have the same work
+    // done twice, reworded past a2a_send's same-request guard. Granted only
+    // (permissionMode: plan withholds the tools), so only then.
+    outward: outward || scriptSpecs.some((sc) => sc.outward) || (remotes.length > 0 && finalAllowed.some((t) => A2A_TOOLS.includes(t))),
     searchRoots,
     historyDigest,
     deskDigest,
@@ -1861,7 +1903,7 @@ export function agentContext(
     // missing ones so the step can tell "you never made this" apart from
     // "it's right there with a typo in it".
     brokenTools: brokenToolReport(tenant, workspace),
-    missingSecrets: [...new Set([...missingDeclared, ...apiTools.missingSecrets])],
+    missingSecrets: [...new Set([...missingDeclared, ...apiTools.missingSecrets, ...remoteSecrets.filter((n) => !(n in secretEnv) && !(n in remoteSecretEnv))])],
   };
 }
 
@@ -2299,6 +2341,7 @@ async function runStep(
       secretEnv, secretScopes, missingSecrets, missingTools, runtime,
       unknownTools, shadowed, legacyUse, retiredTools, mcpServers, mcpNames,
       apiSpecs, scriptSpecs, brokenTools, size: agentSize,
+      remotes, remoteOnlySecrets, remoteSecretEnv,
       providerEnv, providerLabel, providerSecrets, providerWarnings, formatWarning,
       searchChoice, fetchChoice, actionChoices, web, language, region,
       fallbackEnv, apiWarnings, searchRoots, historyDigest, deskDigest, searchTools, historyTools, deskTools,
@@ -2344,7 +2387,50 @@ async function runStep(
     // Populate before the first push: everything after this point may quote a
     // credential. Short values are skipped — a two-character secret would
     // redact half the English language, and anything that short is not one.
-    redactions = redactionsFor({ ...liveSecrets, ...providerSecrets, ...providerEnv });
+    // remotes: — the credentials only they use, made live apart and never
+    // merged into liveSecrets, which the scripts' and the sandbox's
+    // environments are built from.
+    const remoteLive = await materializeSecrets(remoteSecretEnv, { tenant, workspace: path.basename(workspaceRootOf(agentDir)) });
+    const remoteValue = (name: string): string | undefined => remoteLive[name] ?? liveSecrets[name];
+    redactions = redactionsFor({ ...liveSecrets, ...remoteLive, ...providerSecrets, ...providerEnv });
+
+    // remotes: a secret the vault binds to sites of its own is sent only to
+    // them (egress.ts). A remote whose card is on none of them is not sent
+    // it — not called at all — and the trace says why.
+    const remoteBindings: Record<string, string[]> = remotes.length
+      ? secretSites(tenant, remotes.flatMap((r) => (r.secret ? [r.secret] : [])), path.basename(workspaceRootOf(agentDir)))
+      : {};
+    // And the install's rule for a URL a tenant chose, decided here on the
+    // host, which knows the install (a sandbox does not): https only where
+    // untrusted fetches are guarded (platform.ts checkUntrustedUrl). A card a
+    // hosted install would not call is not called from its sandbox either.
+    const cardProblems = new Map<string, string>();
+    for (const r of remotes) {
+      const why = await platform.checkUntrustedUrl(r.card);
+      if (why) cardProblems.set(r.name, why);
+    }
+    const stepRemotes: RemoteSpec[] = remotes.map((r) => {
+      const refused = cardProblems.get(r.name);
+      if (refused) {
+        const why = `${r.name} cannot be called: ${refused}`;
+        push("error", `remotes: ${why}`);
+        return { ...r, unavailable: why };
+      }
+      const sites = r.secret ? remoteBindings[r.secret] : undefined;
+      let hostname = "";
+      try {
+        hostname = new URL(r.card).hostname;
+      } catch {
+        // parseRemotes kept only readable URLs
+      }
+      if (!sites?.length || sites.some((site) => siteCovers(site, hostname))) return r;
+      const why = `${r.name} cannot be called: its secret ${r.secret} is bound in the vault to ${sites.join(", ")}, not to ${hostname}. Bind it there too (\`foldrun secrets sites ${r.secret} …\`), or give the remote its own secret`;
+      push("error", `remotes: ${why}`);
+      return { ...r, unavailable: why };
+    });
+    if (stepRemotes.length) {
+      push("info", `remotes: ${stepRemotes.map((r) => `${r.name} (${r.origin})`).join(", ")} — A2A 1.0 over JSON-RPC; only these origins, and a card naming another is refused`);
+    }
 
     // One line for the clock: which zone this step works to, and which level
     // set it. "Why is this dated yesterday" should be answerable from the run.
@@ -2778,6 +2864,20 @@ async function runStep(
       for (const c of actionChoices) {
         if (c.provider && c.secret in liveSecrets) addGrant(grant, c.secret, liveSecrets[c.secret], c.host);
       }
+      // remotes: each secret granted to its card's host and no other — the
+      // origin the owner wrote. A card cannot move the call elsewhere
+      // (a2a-client.ts validateCard), so the token can only go there.
+      for (const r of stepRemotes) {
+        const host = remoteGrantHost(r);
+        const value = r.secret ? remoteValue(r.secret) : undefined;
+        if (!host || !r.secret || r.unavailable || value === undefined) continue;
+        addGrant(grant, r.secret, value, host);
+        (grant.healthKeys ??= {})[r.secret] = healthKey(
+          r.secret,
+          secretScopes[r.secret] === "workspace" ? "workspace" : "account",
+          path.basename(path.resolve(agentDir, "..", "..")),
+        );
+      }
       for (const api of apiSpecs) {
         const host = hostOf(api.base);
         if (!host) continue;
@@ -2814,6 +2914,8 @@ async function runStep(
           ...Object.values(mcpServers).map((m) => ("url" in m && typeof m.url === "string" ? hostOf(m.url) : null)).filter((h): h is string => !!h),
           ...Object.values(grant.secrets).flatMap((g) => g.hosts),
           ...Object.values(boundSites).flat(),
+          // remotes: each card's own host — never one its card names.
+          ...remoteNetworkHosts(stepRemotes),
         ],
       });
       grant.network = { level: network.level, hosts: network.hosts };
@@ -2904,7 +3006,10 @@ async function runStep(
       ];
       const declared = Object.keys(liveSecrets);
       // A bound secret is never materialised, whatever the step grants.
-      const unbound = declared.filter((name) => !bound.includes(name));
+      // A secret only remotes: use is the proxy's to fill for the card's
+      // origin, or crosses inside the remote's spec when there is no proxy —
+      // never as an environment variable every program in the sandbox reads.
+      const unbound = declared.filter((name) => !bound.includes(name) && !remoteOnlySecrets.includes(name));
       const materialise = (!lease || materialisers.length > 0) && unbound.length > 0;
       if (lease) {
         const boundNote = bound.length ? `${bound.join(", ")} bound to sites — filled by the egress proxy, never in the sandbox` : "";
@@ -2946,6 +3051,17 @@ async function runStep(
       // /identity door. Without a lease there is no door, and so no token.
       const identityDeclared = declared.filter((name) => typeof liveSecrets[name] === "string" && isIdentityValue(liveSecrets[name]!));
       for (const name of identityDeclared) delete sandboxSecrets[name];
+      for (const name of remoteOnlySecrets) delete sandboxSecrets[name];
+      // The remotes as they cross: with a lease the token is its `${NAME}`,
+      // which the proxy fills for the card's host alone; without one (no
+      // proxy configured) the value rides in the spec, as an API header's
+      // does. A test run with no proxy carries none: it sends nothing.
+      const remoteSpecs: RemoteSpec[] = stepRemotes.map((r) => {
+        const value = r.secret ? remoteValue(r.secret) : undefined;
+        if (!r.secret || r.unavailable || value === undefined) return r;
+        if (lease) return { ...r, token: `\${${r.secret}}` };
+        return testRun ? r : { ...r, token: value };
+      });
       for (const name of identitiesHeld) {
         push("info", `test: ${name} withheld — no identity token on a test run`, { effect: { kind: "withheld", summary: `${name} withheld from the sandbox` } });
       }
@@ -3047,6 +3163,7 @@ async function runStep(
           // a bound one goes back to its ${NAME} for the proxy to fill.
           mcpServers: bound.length ? unbindMcpHeaders(mcpServers, bound, liveSecrets, grant) : mcpServers,
           apis: substitutedApis,
+          ...(remoteSpecs.length && allowed.some((t) => A2A_TOOLS.includes(t)) ? { a2a: { remotes: remoteSpecs, runId: runId ?? null, step: stepIndex ?? null } } : {}),
           scripts: scriptSpecs,
           // The merged spec, not `front.runtime` — see the plan's `runtime`
           // field. A tool's own `runtime:` is part of what this step needs.
@@ -3495,6 +3612,18 @@ async function runStep(
       }
       // @file secrets become 0600 paths here (host run), cleaned up in the
       // finally — once, however many attempts follow.
+      // remotes: the four tools, here in this process. No proxy: the token
+      // goes straight to the card's origin, made live per request.
+      const a2aTools = stepRemotes.length && allowed.some((t) => A2A_TOOLS.includes(t))
+        ? buildA2ATools(tenant, stepRemotes, path.basename(workspaceRoot), { env: { ...secretEnv, ...remoteSecretEnv }, missing: [] }, {
+            stateDir: path.join(workspaceRoot, "state", "a2a", step.agent),
+            runId: runId ?? null,
+            step: stepIndex ?? null,
+            test: testRun,
+            keepIn: { dir: agentDir, readable: () => canReadBack(allowed) },
+            emit: (type, text) => push(type, text),
+          })
+        : null;
       const mat = materializeFileSecrets(agentDir, stepSecrets);
       fileDir = mat.dir;
       // install: pip and npm land in a directory of this step's own, gone in
@@ -3538,6 +3667,7 @@ async function runStep(
           ...(askTools ? { foldrun_ask: askTools.server } : {}),
           ...(peerTools ? { foldrun_peers: peerTools.server } : {}),
           ...(delegateTools?.server ? { foldrun_delegate: delegateTools.server } : {}),
+          ...(a2aTools?.server ? { foldrun_a2a: a2aTools.server } : {}),
           ...(installTools ? { foldrun_install: installTools.server } : {}),
           ...mcpServers,
         },
@@ -3651,6 +3781,7 @@ async function runStep(
       step.stopReason = outcome.stopReason ?? null;
       for (const line of apiTools.drainLog()) push("info", `api: ${line}`);
       for (const line of scriptTools.drainLog()) push("info", `script: ${line}`);
+      for (const line of a2aTools?.drainLog() ?? []) push("info", `a2a: ${line}`);
     }
   } catch (err) {
     step.status = "failed";
@@ -4196,6 +4327,9 @@ export function createFlowRun(
   tags: string[] = [],
   startedBy: string | null = null,
   opts: { test?: boolean } = {},
+  /** An A2A task's correlation (foldrun-platform flow-admission.ts) — its
+   *  own trailing argument, so the signature only widened. */
+  a2a?: { task: string; key: string },
 ): RunRecord {
   const run: RunRecord = {
     id: `run-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
@@ -4204,6 +4338,8 @@ export function createFlowRun(
     status,
     ...(startedBy ? { startedBy: startedBy.trim().toLowerCase() } : {}),
     ...(opts.test ? { test: true } : {}),
+    // An outside agent asked, over A2A: the task it serves, and whose key.
+    ...(a2a ? { trigger: "a2a" as const, a2a: { task: a2a.task, key: a2a.key } } : {}),
     startedAt: new Date().toISOString(),
     finishedAt: null,
     steps: steps.map((s) => ({
@@ -4439,7 +4575,11 @@ function driveRunInner(
    */
   const save = () => {
     const disk = run.stopRequested ? null : readRun(tenant, workspace, run.id);
-    if (disk?.stopRequested) run.stopRequested = true;
+    if (disk?.stopRequested) {
+      run.stopRequested = true;
+      // Who stopped it (an A2A caller's cancel, say) travels with the flag.
+      if (disk.stoppedBy) run.stoppedBy ??= disk.stoppedBy;
+    }
     if (run.stopRequested) {
       if (run.status !== "completed" && run.status !== "failed") {
         run.status = "failed";
@@ -4891,6 +5031,7 @@ function driveRunInner(
         // this is what keeps the *next* group from starting.
         const stopCheck = readRun(tenant, workspace, run.id);
         if (stopCheck?.stopRequested) {
+          if (stopCheck.stoppedBy) run.stoppedBy ??= stopCheck.stoppedBy;
           let skipped = 0;
           for (const s of run.steps) {
             if (s.status === "pending" || s.status === "running") {
@@ -4908,7 +5049,7 @@ function driveRunInner(
           witness?.events.push({
             t: new Date().toISOString(),
             type: "info",
-            text: `run stopped by a person between groups — ${skipped} remaining step${skipped === 1 ? "" : "s"} skipped`,
+            text: `run stopped by ${stoppedByText(run)} between groups — ${skipped} remaining step${skipped === 1 ? "" : "s"} skipped`,
           });
           run.status = "failed";
           run.stopRequested = true;
@@ -5380,7 +5521,7 @@ function driveRunInner(
                   if (run.stopRequested) {
                     step.status = "skipped";
                     step.skipReason = "run stopped";
-                    step.events.push({ t: new Date().toISOString(), type: "info", text: "run stopped by a person while this step waited to start — skipped" });
+                    step.events.push({ t: new Date().toISOString(), type: "info", text: `run stopped by ${stoppedByText(run)} while this step waited to start — skipped` });
                     save();
                     gate.release(step);
                     return;
@@ -5497,7 +5638,7 @@ function driveRunInner(
                   step.events.push({
                     t: new Date().toISOString(),
                     type: "info",
-                    text: "stopped by a person mid-step — its sandbox was destroyed, which is what ended this attempt; not retried",
+                    text: `stopped by ${stoppedByText(run)} mid-step — its sandbox was destroyed, which is what ended this attempt; not retried`,
                   });
                   save();
                   break;

package/src/scan.ts

@@ -31,6 +31,9 @@ import matter, { frontmatterErrorLine, frontmatterErrorText, parseLenient, confi
 import { refNames } from "./refs.ts";
 import { resolveNetwork } from "./network.ts";
 import { frontmatterProblems, schemaKindOf } from "./frontmatter-schema.ts";
+import { parseRemotes } from "./a2a-remotes.ts";
+import { isA2aPublished } from "./a2a-publish.ts";
+import { parseFlow, type FlowStep } from "./store.ts";
 
 export type ScanLevel = "error" | "warn" | "info";
 export type ScanCategory = "secret" | "security" | "content" | "supply-chain" | "config";
@@ -137,6 +140,31 @@ export const SCAN_RULES: readonly ScanRule[] = [
       "or guard its calls with a `hooks:` gate. An approval (`!`) on every outward step is the other answer.",
     owasp: ["ASI01", "ASI02", "ASI03"],
   },
+  {
+    // 1 Nov 2026, with A2A: a published flow's first input is whatever an
+    // outside caller sends. Shipped as a warning, like every new rule.
+    id: "security/published-flow-trifecta",
+    category: "security",
+    level: "warn",
+    title: "A flow published over A2A runs an agent that holds private data and can send it out",
+    help:
+      "An outside agent's message is untrusted input to every step of a published flow. A step whose agent also holds a secret, " +
+      "an API or an MCP server, and can reach an open network, an outward tool or an API it may write to, can be told by the caller " +
+      "where to send what it holds. Take a leg away from that agent (network: { level: trusted, allow: [...] }, split it, a hooks: gate), " +
+      "or do not publish the flow.",
+    owasp: ["ASI01", "ASI02", "ASI03"],
+  },
+  {
+    id: "security/published-flow-ungated",
+    category: "security",
+    level: "warn",
+    title: "A flow published over A2A acts outside the workspace with no person in the way",
+    help:
+      "An outside caller can start a published flow as often as its key allows. A step that posts, sends, writes to an API or calls " +
+      "another outside agent, with no approval (`!`) or `ask:` before it or on it, does what any caller asked. Put a gate before the " +
+      "first such step — an approval is a person reading what it will do.",
+    owasp: ["ASI02", "ASI09"],
+  },
   {
     id: "security/subagent-wider",
     category: "security",
@@ -720,8 +748,20 @@ interface ToolFacts {
   lines: string[];
 }
 
-function scanAgents(agents: AgentFacts[], outward: Set<string>, toolDefs: Map<string, ToolFacts>, push: Push, networks: { account?: unknown; workspace?: unknown }) {
+/** What one agent can reach, as the trifecta and the published-flow rules
+ *  read it: each leg's items, for a message. */
+interface AgentLegs {
+  privateLeg: string[];
+  outLeg: string[];
+  /** What it can do outside the workspace: outward tools, API writes, sends
+   *  to outside agents. */
+  writes: string[];
+  gated: boolean;
+}
+
+function scanAgents(agents: AgentFacts[], outward: Set<string>, toolDefs: Map<string, ToolFacts>, push: Push, networks: { account?: unknown; workspace?: unknown }): Map<string, AgentLegs> {
   const byName = new Map(agents.map((a) => [a.name, a]));
+  const legs = new Map<string, AgentLegs>();
   for (const a of agents) {
     const d = a.data;
     const tools = refNames(d.tools);
@@ -731,6 +771,11 @@ function scanAgents(agents: AgentFacts[], outward: Set<string>, toolDefs: Map<st
     // Untrusted: it reads the open web. (A webhook body is the other source;
     // that is a flow's trigger, and the flow-level rule is a later one.)
     const readsWeb = has("web") || tools.some((t) => /browse|fetch|scrape|crawl/i.test(t) && has(t));
+    // An outside agent's reply is untrusted too, and a message to one is a
+    // way out (remotes:). Its own token is not private data the agent holds:
+    // the proxy fills it, for that remote's origin alone.
+    const remotes = parseRemotes(d.remotes);
+    const untrusted = [...(readsWeb ? ["reads the web"] : []), ...(remotes.length ? [`reads replies from outside agents (${remotes.slice(0, 3).map((r) => r.name).join(", ")}${remotes.length > 3 ? ", …" : ""})`] : [])];
     // Private: a secret it spends itself, an API or MCP server it holds.
     const secrets = Array.isArray(d.secrets) ? d.secrets.map(String) : [];
     const apis = Array.isArray(d.apis) ? d.apis : [];
@@ -743,14 +788,16 @@ function scanAgents(agents: AgentFacts[], outward: Set<string>, toolDefs: Map<st
     const openNet = resolveNetwork({ account: networks.account, workspace: networks.workspace, agent: d.network, readsWeb }).level === "open";
     const outwardTools = tools.filter((t) => outward.has(t) && !denied.has(t));
     const writeApis = apis.filter((x: any) => WRITE_METHODS.test(JSON.stringify(x?.methods ?? x?.method ?? "")));
-    const outLeg = [...(openNet ? ["an open network"] : []), ...outwardTools.map((t) => `outward tool ${t}`), ...writeApis.map((x: any) => `writes to api ${x?.name ?? "?"}`)];
+    const writes = [...outwardTools.map((t) => `outward tool ${t}`), ...writeApis.map((x: any) => `writes to api ${x?.name ?? "?"}`), ...remotes.map((r) => `outside agent ${r.name}`)];
+    const outLeg = [...(openNet ? ["an open network"] : []), ...writes];
     const gated = refNames(d.hooks).length > 0 || d.permissionMode === "plan";
+    legs.set(a.name, { privateLeg, outLeg, writes, gated });
 
-    if (readsWeb && privateLeg.length && outLeg.length && !gated) {
+    if (untrusted.length && privateLeg.length && outLeg.length && !gated) {
       push(
         "security/lethal-trifecta", a.file, a.line, `trifecta ${a.name}`,
-        `${a.name} reads the web, holds ${privateLeg.slice(0, 3).join(", ")}${privateLeg.length > 3 ? ", …" : ""} and can reach ${outLeg.slice(0, 2).join(" and ")} — ` +
-          `a page it reads can tell it where to send what it holds. Take it off the open network (network: { level: trusted, allow: [...] }), split it, or add a hooks: gate`,
+        `${a.name} ${untrusted.join(" and ")}, holds ${privateLeg.slice(0, 3).join(", ")}${privateLeg.length > 3 ? ", …" : ""} and can reach ${outLeg.slice(0, 2).join(" and ")} — ` +
+          `${readsWeb ? "a page it reads" : "a reply it reads"} can tell it where to send what it holds. Take it off the open network (network: { level: trusted, allow: [...] }), split it, or add a hooks: gate`,
       );
     }
 
@@ -784,6 +831,72 @@ function scanAgents(agents: AgentFacts[], outward: Set<string>, toolDefs: Map<st
     if (pkg) push("supply-chain/unpinned-mcp", file, keyLine(lines, "command"), `mcp ${pkg}`, `command runs \`${pkg}\` — whatever was published last; pin a version`);
     runtimePackages(def.runtime, file, lines, push);
   }
+  return legs;
+}
+
+// ── flows published over A2A ───────────────────────────────────────────────
+
+interface FlowFacts {
+  file: string;
+  content: string;
+  lines: string[];
+}
+
+/** The agents a step may run: its own, a rescuer, the ones it delegates to. */
+function stepAgents(s: FlowStep): string[] {
+  if (s.subflow) return [];
+  return [...new Set([s.agent, ...(s.onFail ? [s.onFail] : []), ...(s.delegate ?? [])].filter(Boolean))];
+}
+
+/**
+ * A flow with `a2a: {publish: true}` takes its first input from an outside
+ * caller. Two findings: a step agent the caller could steer into sending
+ * what it holds (the trifecta, with the caller as the untrusted leg), and a
+ * step that acts outside the workspace with no person before it.
+ */
+function scanPublishedFlows(flows: FlowFacts[], legs: Map<string, AgentLegs>, push: Push) {
+  for (const fl of flows) {
+    let info: ReturnType<typeof parseFlow>;
+    try {
+      info = parseFlow(fl.file, fl.content);
+    } catch {
+      continue; // a flow that does not parse is check's finding
+    }
+    if (!isA2aPublished(info.a2a)) continue;
+    const at = keyLine(fl.lines, "a2a");
+    const said = new Set<string>();
+    for (const step of info.steps) {
+      for (const name of stepAgents(step)) {
+        const l = legs.get(name);
+        if (!l || said.has(name) || l.gated || !l.privateLeg.length || !l.outLeg.length) continue;
+        said.add(name);
+        push(
+          "security/published-flow-trifecta", fl.file, step.line ?? at, `published trifecta ${name}`,
+          `${info.name} is published over A2A, so what an outside caller sends reaches ${name}, which holds ${l.privateLeg.slice(0, 3).join(", ")}${l.privateLeg.length > 3 ? ", …" : ""} ` +
+            `and can reach ${l.outLeg.slice(0, 2).join(" and ")} — a caller can tell it where to send what it holds. Take a leg away from ${name}, or do not publish the flow`,
+        );
+      }
+    }
+    // Groups in order. A gate (an approval, or ask:, which is one with a
+    // question) on any step of a group parks the run before ANY step of that
+    // group launches (runner.ts driveRunInner), so it holds its parallel
+    // siblings as well as every group after.
+    let gated = false;
+    for (const g of [...new Set(info.steps.map((s) => s.group))].sort((a, b) => a - b)) {
+      const group = info.steps.filter((s) => s.group === g);
+      if (group.some((s) => s.approve || s.ask)) gated = true;
+      for (const s of group) {
+        if (gated) continue;
+        const writes = [...new Set(stepAgents(s).flatMap((n) => legs.get(n)?.writes ?? []))];
+        if (!writes.length) continue;
+        push(
+          "security/published-flow-ungated", fl.file, s.line ?? at, `published ungated ${g} ${s.agent}`,
+          `step ${g} ([[${s.agent}]]) can act outside the workspace (${writes.slice(0, 2).join(", ")}${writes.length > 2 ? ", …" : ""}) and ${info.name} is published over A2A, ` +
+            `with no approval or ask: before it — any caller with a key starts it. Put a gate (\`${g}!.\`) on it or before it`,
+        );
+      }
+    }
+  }
 }
 
 function runtimePackages(runtime: unknown, file: string, lines: string[], push: Push) {
@@ -916,6 +1029,7 @@ export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFin
 
   const outward = new Set(options.outwardTools ?? []);
   const agents: AgentFacts[] = [];
+  const flows: FlowFacts[] = [];
   const toolDefs = new Map<string, ToolFacts>();
 
   for (const f of files.filter(isText)) {
@@ -970,6 +1084,8 @@ export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFin
       const rel = f.path.replace(/^library\//, "");
       const name = /^agents\/([^/]+)\//.exec(rel)?.[1] ?? rel.replace(/^.*\/|\.md$/g, "");
       agents.push({ name, file: f.path, line: 1, data, lines });
+    } else if (kind === "flow") {
+      if (!f.path.startsWith("library/")) flows.push({ file: f.path, content: f.content, lines });
     } else if (kind === "tool") {
       const name = typeof data.name === "string" ? data.name : f.path.replace(/^(?:library\/)?tools\//, "").replace(/(?:\/tool)?\.md$/, "");
       if (data.outward === true) outward.add(name);
@@ -978,7 +1094,8 @@ export function scanFiles(files: ScanFile[], options: ScanOptions = {}): ScanFin
   }
   // project.md is the older name the runtime still reads (Codex review, FOL-58).
   const workspaceMd = files.find((f) => f.path === "AGENTS.md") ?? files.find((f) => f.path === "project.md");
-  scanAgents(agents, outward, toolDefs, push, { account: options.accountNetwork, workspace: workspaceMd ? frontOf(workspaceMd.content, "AGENTS.md")?.network : undefined });
+  const legs = scanAgents(agents, outward, toolDefs, push, { account: options.accountNetwork, workspace: workspaceMd ? frontOf(workspaceMd.content, "AGENTS.md")?.network : undefined });
+  scanPublishedFlows(flows, legs, push);
   for (const m of more.values()) {
     findings.push({ rule: m.rule, level: m.level ?? scanRule(m.rule)?.level ?? "warn", file: m.file, message: `and ${m.n} more like this in this file, not listed`, fingerprint: m.hash.digest("hex").slice(0, 16), truncated: true });
   }

package/src/secrets.ts

@@ -278,6 +278,17 @@ function readFile(file: string): SecretsFile {
 }
 
 function lockVault(file: string): () => void {
+  return lockFileExclusive(file, "the vault is busy — another change is being saved; try again");
+}
+
+/**
+ * An exclusive lock on `file` for a read-change-write, across processes and
+ * pods: `<file>.lock` opened O_EXCL (NFS 4.1 and EFS honour it), taken over
+ * when older than LOCK_STALE_MS (a holder that died), waited for up to
+ * LOCK_WAIT_MS, then `busy` is thrown. Returns the release. The vault's,
+ * and any other small state file several runs write (a2a-tools' handles).
+ */
+export function lockFileExclusive(file: string, busy = `${path.basename(file)} is busy — another writer holds it; try again`): () => void {
   const lock = `${file}.lock`;
   const deadline = Date.now() + LOCK_WAIT_MS;
   for (;;) {
@@ -296,7 +307,7 @@ function lockVault(file: string): () => void {
       } catch {
         continue; // released between the open and the stat
       }
-      if (Date.now() > deadline) throw new Error("the vault is busy — another change is being saved; try again");
+      if (Date.now() > deadline) throw new Error(busy);
       sleep(25);
     }
   }
@@ -1176,6 +1187,37 @@ export async function materializeSecrets(
   return out;
 }
 
+/**
+ * materializeSecrets for a tool that holds secrets for a whole step and
+ * makes them live per call (the API tools, the a2a tools), on a host with
+ * the vault.
+ *
+ * Two things the step's copy of a recipe cannot do alone. A provider that
+ * rotates refresh tokens has spent the refresh token the step started with —
+ * the runner materialised it at step start, and any refresh since spent its
+ * successor — so an oauth2 recipe is read again from the vault as it is now
+ * (and `env` updated in place, for the next call). And it is made live in
+ * the account's scope, as the runner and the egress proxy do: the cached
+ * access token is keyed by account, and a rotation is written back to the
+ * vault by the compare-and-set above. Refreshing the starting recipe outside
+ * that scope missed the cache and sent a spent refresh token: invalid_grant.
+ *
+ * No `scope` (inside a sandbox, where there is no vault and the values
+ * crossed already made live): materializeSecrets as it was.
+ */
+export async function materializeCurrent(
+  env: Record<string, string>,
+  scope?: { tenant: string; workspace?: string } | null,
+): Promise<Record<string, string>> {
+  if (!scope?.tenant) return materializeSecrets(env);
+  for (const [name, value] of Object.entries(env)) {
+    if (typeof value !== "string" || !isOAuth2Value(value)) continue;
+    const current = getSecret(scope.tenant, name, scope.workspace)?.value;
+    if (current && isOAuth2Value(current)) env[name] = current;
+  }
+  return materializeSecrets(env, { tenant: scope.tenant, ...(scope.workspace ? { workspace: scope.workspace } : {}) });
+}
+
 // ---------------------------------------------------------------- service account
 
 // Signed-key credentials: a Google service account, or anything that mints a

package/src/starter.ts

@@ -389,6 +389,7 @@ All of it, \`/api/workspaces/<workspace>\` unless noted:
 | \`/export\` · \`/import\` | GET · POST | the workspace, a flow (\`?kind=flow&name=\`) or an agent as a .zip; take one in (\`?dryRun=1\` first, \`?overwrite=1\` to replace) |
 | \`/restore\` | POST | the workspace's source back to a point in its history — \`dryRun\` first, then \`confirm\` |
 | \`/vocabulary\` | GET | what this workspace's documents may say |
+| \`/a2a\` | GET | what it serves to outside agents over A2A: flows that say \`a2a:\`, card URLs, recent tasks |
 | \`/check\` | GET | what \`foldrun check\` says about the deployed copy, as findings with rule ids (\`?security=1\`) |
 | \`/assistant\` | POST | ask the assistant, or have it write agents, flows, tools and skills — from the docs only; proposals come back, nothing is written |
 
@@ -398,7 +399,8 @@ Account-level, outside \`/workspaces\`: \`/api/secrets\`, \`/api/keys\`, \`/api/
 \`/api/me/inbox\` (what waits on you: gates, questions, issues, proposed fixes, your failed runs),
 \`/api/account/backups\` (snapshots, restore requests), \`/api/me/onboarding\` (getting started),
 \`/api/healthz\` and \`/api/version\` (open), \`/api/changelog\` (release notes)
-and \`/api/metrics\` (Prometheus).
+and \`/api/metrics\` (Prometheus). Outside \`/api\`: \`/a2a/<account>/<ws>/flows/<flow>\`
+(a published flow's agent card and A2A 1.0 JSON-RPC endpoint — an A2A key only, \`foldrun docs a2a\`).
 
 Every call answers — and the CLI sends — \`Foldrun-Version: YYYY-MM-DD\` (dated API
 versions; an account pin in Settings → API), \`X-RateLimit-*\` headers (a \`429\`
@@ -434,6 +436,7 @@ effort: low
 overlap: skip            # skip | queue — what a second run does while one is live
 priority: normal         # high | normal | low — where its runs stand in the queue
 compute: { vcpu: 4, memory: 8Gi, disk: 40Gi }  # optional: what one run may hold at once
+a2a: { publish: false }  # true: outside agents may call it over A2A (admin only; callers need an A2A key)
 ---
 
 1. [[researcher]] — Find three sources on {{topic}}.
@@ -499,6 +502,7 @@ hooks: [no-force-push]      # from hooks/ or the library: code at every tool cal
 scripts: [summarise.py]     # from scripts/, each becomes a callable tool
 apis: [{ name: crm }]       # an HTTP API, as a tool
 mcpServers: {}              # an MCP server, as a tool
+remotes: []                 # outside A2A agents [{name, card, secret?}] — the a2a_send/status/reply/cancel tools
 agents: [writer]            # colleagues this one may consult (an answer, no tools)
 subagents: [researcher]     # colleagues it may delegate a job to (own context, own tools ≤ its own)
 sandbox: own                # delegated to: run each job in its own sandbox (own tools, secrets, network)