@foldrun/core 9.1.0 → 9.2.0

package/dist/src/runner.js

@@ -35,20 +35,22 @@ const isolatedRun = () => {
     return mode === "container" || (!!mode && mode in platform.isolation);
 };
 import { gatherConsults, buildConsultTools } from "./agent-tools.js";
-import { DELEGATE_TOOL, gatherSubagents, ownSandbox, subagentPrompt, subagentTools } from "./subagents.js";
+import { DELEGATE_TOOL, gatherSubagents, ownSandbox, subagentPrompt, subagentTools, SUBAGENT_NO_REMOTES } from "./subagents.js";
 import { DELEGATE_SERVER, buildDelegateTools, delegatePromptLine, delegateToolNames, localDelegateChannel, readCopyBack } from "./delegate-tools.js";
 import { ASK_TOOL, PEER_TOOLS, applyOperatorEvent, askPromptLine, askTimeoutSec, buildAskTool, buildPeerTools, inboxReader, localPeerBus, peersPromptLine } from "./operator.js";
 import { sendPlainNotification } from "./notify.js";
 import { TOOL_MAP, BUILTIN_TOOLS, ownToolNames, toolRefs, legacyUseNames, legacyUseError, retiredToolNames, retiredToolError } from "./tool-names.js";
 import { refNames } from "./refs.js";
-import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowledgeIndex, workspaceKnowledgeIndex, workspaceTools, brokenToolReport, listWorkspaces, listTenants, listRuns, liveRuns, syncBundleFor, parseToolDef, readFlow, markerPresent, whenRowsPath, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, isSplicedRecord, runSummary, verdictOf, sumAttempts, tokensOf, parseSchemaText, STORAGE_DIR, adoptLegacyVersionKey, listAgents, isOneSegment, } from "./store.js";
+import { accountDir, workspaceDir, buildMemoryIndex, workspaceMemoryIndex, knowledgeIndex, workspaceKnowledgeIndex, workspaceTools, brokenToolReport, listWorkspaces, listTenants, listRuns, liveRuns, syncBundleFor, parseToolDef, readFlow, markerPresent, whenRowsPath, parseApis, resolveModel, parseProvider, providerEnvFor, resolveEffort, isEffortWord, EFFORT_LEVELS, checkFormatVersion, readRun, writeRun, isSplicedRecord, runSummary, verdictOf, sumAttempts, tokensOf, parseSchemaText, STORAGE_DIR, adoptLegacyVersionKey, listAgents, isOneSegment, stoppedByText, } from "./store.js";
 import { canReadBack } from "./tool-output.js";
 import { PromptLayers, promptCacheKey } from "./prompt-layers.js";
 import { loadCatalog, checkModel, clampEffort, catalogCost, findModel, tokenPriceOf } from "./catalog.js";
 import { resolveSecrets, getSecret, materializeSecrets, secretSites, isClientCertValue, clientCertOf, withoutHeldCerts, isIdentityValue, identityOf } from "./secrets.js";
-import { resolveNetwork, networkLine, networkEnforceWanted, proxyEnv, EGRESS_CA_ENV } from "./network.js";
+import { resolveNetwork, networkLine, networkEnforceWanted, proxyEnv, siteCovers, EGRESS_CA_ENV } from "./network.js";
 import { materializeFileSecrets, cleanupFileSecrets } from "./secret-files.js";
 import { buildApiTools, secretsUsedByApi } from "./api-tools.js";
+import { buildA2ATools } from "./a2a-tools.js";
+import { parseRemotes, remoteSecretNames, remoteGrantHost, remoteNetworkHosts, remotesPromptLines, A2A_TOOLS } from "./a2a-remotes.js";
 import { attachOperations, prefetchOpenApi } from "./openapi.js";
 import { buildSearchTools, buildHistoryTools, buildDeskTools, digestRuns } from "./context-tools.js";
 import { startTranslator, translatorSpecFor } from "./translator.js";
@@ -539,6 +541,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)`);
             }
@@ -552,7 +560,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",
@@ -995,6 +1003,10 @@ grantsOnly = false) {
     // 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);
@@ -1075,6 +1087,10 @@ grantsOnly = false) {
     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.
     //
     // Plus the credentials its API tools reference. An agent that opted into
@@ -1152,7 +1168,21 @@ grantsOnly = false) {
     // 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
     // promise, and three of each is a menu while ten is a support queue. Default
@@ -1560,6 +1590,8 @@ grantsOnly = false) {
         }
     }
     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
     // workspace's finished runs, minus the one being driven. Both are values
@@ -1656,8 +1688,18 @@ grantsOnly = false) {
         // 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,
@@ -1704,7 +1746,7 @@ grantsOnly = false) {
         // 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))])],
     };
 }
 /**
@@ -2113,7 +2155,7 @@ mayDefer) {
         // step: the generic HTTP tool still works without the typed ones.
         for (const w of await prefetchOpenApi(tenant, openApiSources(agentDir, tenant)))
             push("error", `openapi: ${w}`);
-        const { front, clockEnv, clock, systemPrompt, promptLayers, allowed, disabled, apiTools, scriptTools, secretEnv, secretScopes, missingSecrets, missingTools, runtime, unknownTools, shadowed, legacyUse, retiredTools, mcpServers, mcpNames, apiSpecs, scriptSpecs, brokenTools, size: agentSize, providerEnv, providerLabel, providerSecrets, providerWarnings, formatWarning, searchChoice, fetchChoice, actionChoices, web, language, region, fallbackEnv, apiWarnings, searchRoots, historyDigest, deskDigest, searchTools, historyTools, deskTools, ask, peers, translator, fallbackTranslator, outward, } = agentContext(agentDir, tenant, tags, { runId, agent: step.agent }, flowTimezone);
+        const { front, clockEnv, clock, systemPrompt, promptLayers, allowed, disabled, apiTools, scriptTools, 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, ask, peers, translator, fallbackTranslator, outward, } = agentContext(agentDir, tenant, tags, { runId, agent: step.agent }, flowTimezone);
         disposeRuntime = runtime.dispose;
         canActOutward = outward;
         // Sent again on every turn; with turns and the tools' result sizes, what
@@ -2150,7 +2192,52 @@ mayDefer) {
         // 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) => 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 = 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();
+        for (const r of remotes) {
+            const why = await platform.checkUntrustedUrl(r.card);
+            if (why)
+                cardProblems.set(r.name, why);
+        }
+        const stepRemotes = 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.
         push("info", `clock: ${clock.timezone} (${clock.source}) — today is ${clockEnv.FOLDRUN_DATE}`);
@@ -2581,6 +2668,17 @@ mayDefer) {
                 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)
@@ -2615,6 +2713,8 @@ mayDefer) {
                     ...Object.values(mcpServers).map((m) => ("url" in m && typeof m.url === "string" ? hostOf(m.url) : null)).filter((h) => !!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 };
@@ -2701,7 +2801,10 @@ mayDefer) {
             ];
             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` : "";
@@ -2741,6 +2844,20 @@ mayDefer) {
             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 = 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` } });
             }
@@ -2837,6 +2954,7 @@ mayDefer) {
                     // 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.
@@ -3286,6 +3404,18 @@ mayDefer) {
             }
             // @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
@@ -3329,6 +3459,7 @@ mayDefer) {
                     ...(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,
                 },
@@ -3445,6 +3576,8 @@ mayDefer) {
                 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) {
@@ -3978,7 +4111,10 @@ export function readSchemaFile(workspaceRoot, rel) {
     }
     return null;
 }
-export function createFlowRun(tenant, workspace, steps, flowName, status, tags = [], startedBy = null, opts = {}) {
+export function createFlowRun(tenant, workspace, steps, flowName, status, tags = [], startedBy = null, opts = {}, 
+/** An A2A task's correlation (foldrun-platform flow-admission.ts) — its
+ *  own trailing argument, so the signature only widened. */
+a2a) {
     const run = {
         id: `run-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
         flow: flowName,
@@ -3986,6 +4122,8 @@ export function createFlowRun(tenant, workspace, steps, flowName, status, tags =
         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", a2a: { task: a2a.task, key: a2a.key } } : {}),
         startedAt: new Date().toISOString(),
         finishedAt: null,
         steps: steps.map((s) => ({
@@ -4205,8 +4343,12 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
      */
     const save = () => {
         const disk = run.stopRequested ? null : readRun(tenant, workspace, run.id);
-        if (disk?.stopRequested)
+        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";
@@ -4659,6 +4801,8 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                 // 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") {
@@ -4676,7 +4820,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                     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;
@@ -5136,7 +5280,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                             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;
@@ -5232,7 +5376,7 @@ function driveRunInner(tenant, workspace, run, modelOverride, tags, opts) {
                             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/dist/src/scan.js

@@ -30,6 +30,9 @@ import matter, { frontmatterErrorLine, frontmatterErrorText, parseLenient, confi
 import { refNames } from "./refs.js";
 import { resolveNetwork } from "./network.js";
 import { frontmatterProblems, schemaKindOf } from "./frontmatter-schema.js";
+import { parseRemotes } from "./a2a-remotes.js";
+import { isA2aPublished } from "./a2a-publish.js";
+import { parseFlow } from "./store.js";
 export const OWASP_URL = "https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026";
 export const SCAN_RULES = [
     {
@@ -81,6 +84,29 @@ export const SCAN_RULES = [
             "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",
@@ -649,6 +675,7 @@ function docKind(p) {
 const WRITE_METHODS = /\b(?:POST|PUT|PATCH|DELETE)\b/i;
 function scanAgents(agents, outward, toolDefs, push, networks) {
     const byName = new Map(agents.map((a) => [a.name, a]));
+    const legs = new Map();
     for (const a of agents) {
         const d = a.data;
         const tools = refNames(d.tools);
@@ -657,6 +684,11 @@ function scanAgents(agents, outward, toolDefs, push, networks) {
         // 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 : [];
@@ -669,11 +701,13 @@ function scanAgents(agents, outward, toolDefs, push, networks) {
         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) => WRITE_METHODS.test(JSON.stringify(x?.methods ?? x?.method ?? "")));
-        const outLeg = [...(openNet ? ["an open network"] : []), ...outwardTools.map((t) => `outward tool ${t}`), ...writeApis.map((x) => `writes to api ${x?.name ?? "?"}`)];
+        const writes = [...outwardTools.map((t) => `outward tool ${t}`), ...writeApis.map((x) => `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";
-        if (readsWeb && 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`);
+        legs.set(a.name, { privateLeg, outLeg, writes, gated });
+        if (untrusted.length && privateLeg.length && outLeg.length && !gated) {
+            push("security/lethal-trifecta", a.file, a.line, `trifecta ${a.name}`, `${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`);
         }
         // Sub-agents declaring tools the parent lacks.
         for (const s of refNames(d.subagents)) {
@@ -705,6 +739,63 @@ function scanAgents(agents, outward, toolDefs, push, networks) {
             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;
+}
+/** The agents a step may run: its own, a rescuer, the ones it delegates to. */
+function stepAgents(s) {
+    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, legs, push) {
+    for (const fl of flows) {
+        let info;
+        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();
+        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, file, lines, push) {
     if (!runtime || typeof runtime !== "object")
@@ -819,6 +910,7 @@ export function scanFiles(files, options = {}) {
     };
     const outward = new Set(options.outwardTools ?? []);
     const agents = [];
+    const flows = [];
     const toolDefs = new Map();
     for (const f of files.filter(isText)) {
         const lines = f.content.split(/\r?\n/);
@@ -876,6 +968,10 @@ export function scanFiles(files, options = {}) {
             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)
@@ -885,7 +981,8 @@ export function scanFiles(files, options = {}) {
     }
     // 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/dist/src/secrets.d.ts

@@ -44,6 +44,14 @@ interface StoredSecret {
 }
 type SecretsFile = Record<string, StoredSecret>;
 declare const writeBound: () => boolean;
+/**
+ * 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 declare function lockFileExclusive(file: string, busy?: string): () => void;
 /**
  * Change one vault file safely: `change` gets what is stored now and returns
  * the new contents, or null to leave the file untouched. Returns what is
@@ -275,6 +283,28 @@ ctx?: {
      *  the stored value with the new refresh token. */
     onRotate?: (name: string, usedValue: string, next: string) => unknown;
 }): Promise<Record<string, string>>;
+/**
+ * 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 declare function materializeCurrent(env: Record<string, string>, scope?: {
+    tenant: string;
+    workspace?: string;
+} | null): Promise<Record<string, string>>;
 export interface ServiceAccountConfig {
     token_url: string;
     issuer: string;

package/dist/src/secrets.js

@@ -221,6 +221,16 @@ function readFile(file) {
     }
 }
 function lockVault(file) {
+    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, busy = `${path.basename(file)} is busy — another writer holds it; try again`) {
     const lock = `${file}.lock`;
     const deadline = Date.now() + LOCK_WAIT_MS;
     for (;;) {
@@ -243,7 +253,7 @@ function lockVault(file) {
                 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");
+                throw new Error(busy);
             sleep(25);
         }
     }
@@ -1019,6 +1029,36 @@ ctx) {
     }
     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, scope) {
+    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
 // token by self-signing a JWT with a private key and exchanging it. No user,