@foldrun/core 9.0.0 → 9.2.0

package/dist/src/store.js

@@ -45,6 +45,8 @@ export function readFrontmatter(file) {
 import { ownToolNames, legacyUseNames, retiredToolNames } from "./tool-names.js";
 import { refNames } from "./refs.js";
 import { checkFilter } from "./trigger-filter.js";
+import { parseA2aPublish } from "./a2a-publish.js";
+import { parseRemotes, remoteNetworkHosts, A2A_LIMIT_KEY } from "./a2a-remotes.js";
 import { parseBudget, budgetProblem } from "./budget.js";
 import { timezoneProblem } from "./clock.js";
 import { parseStepLimits, readLimits } from "./limits.js";
@@ -1115,6 +1117,9 @@ function inlineToolNames(data) {
     }
     if (data.mcpServers && typeof data.mcpServers === "object")
         out.push(...Object.keys(data.mcpServers));
+    // remotes: grants the a2a tools, counted under `limits: {a2a: N}`.
+    if (parseRemotes(data.remotes).length)
+        out.push(A2A_LIMIT_KEY);
     return out;
 }
 export function listAgents(tenant, workspace) {
@@ -1158,12 +1163,16 @@ export function listAgents(tenant, workspace) {
                 workspace: workspaceFront.network,
                 agent: data.network,
                 readsWeb,
-                implied: parseApis(data.apis).map((a) => { try {
-                    return new URL(a.base).host;
-                }
-                catch {
-                    return "";
-                } }),
+                implied: [
+                    ...parseApis(data.apis).map((a) => { try {
+                        return new URL(a.base).host;
+                    }
+                    catch {
+                        return "";
+                    } }),
+                    // remotes: — each card's own host, and nothing its card says.
+                    ...remoteNetworkHosts(parseRemotes(data.remotes)),
+                ],
             }),
             readsWeb,
         };
@@ -1176,6 +1185,7 @@ export function listAgents(tenant, workspace) {
             effort: data.effort ?? null,
             tools,
             apis: parseApis(data.apis),
+            remotes: parseRemotes(data.remotes),
             ownTools: ownToolNames(data),
             legacyUse: legacyUseNames(data),
             retiredTools: retiredToolNames(data),
@@ -1689,6 +1699,7 @@ export function parseFlow(file, raw) {
         approveWithin: durationOf(data.approve_within),
         description: typeof data.description === "string" ? data.description.trim() || null : null,
         ...resolveOwner(data.owner, undefined, undefined, "flow"),
+        a2a: parseA2aPublish(data.a2a),
         frontProblems,
         steps,
     };
@@ -2505,7 +2516,9 @@ export function renameWorkspaceFile(tenant, workspace, from, to, meta = {}) {
     // Refuse with the reason before any path validation: "not an editable
     // path" is true of AGENTS.md too, and the generic sentence buries the
     // specific one worth reading.
-    const why = anchoredReason(from) ?? anchoredReason(to);
+    // Read as the paths the rename will use: `./AGENTS.md` is AGENTS.md
+    // (1 Nov 2026 — the raw spelling slipped past this and still moved it).
+    const why = anchoredReason(path.normalize(from)) ?? anchoredReason(path.normalize(to));
     if (why)
         throw new Error(why);
     const dir = workspaceDir(tenant, workspace);
@@ -3014,6 +3027,8 @@ export function summarizeRun(run) {
         ...(run.startedBy ? { startedBy: run.startedBy } : {}),
         ...(run.parkedAt ? { parkedAt: run.parkedAt } : {}),
         ...(run.revision ? { revision: run.revision } : {}),
+        ...(run.trigger ? { trigger: run.trigger } : {}),
+        ...(run.a2a ? { a2a: run.a2a } : {}),
         awaitingApproval: run.steps.some((s) => s.status === "awaiting-approval" && s.waitFor !== "event"),
         steps: run.steps.map((s) => {
             const error = s.status === "failed" ? s.events.filter((e) => e.type === "error").at(-1)?.text : undefined;
@@ -3212,6 +3227,12 @@ export function listAllRunSummaries(tenant) {
         .flatMap((p) => listRunSummaries(tenant, p.name).map((s) => ({ ...s, workspace: p.name })))
         .sort((a, b) => b.startedAt.localeCompare(a.startedAt));
 }
+/** Who stopped a run, for a trail line: "a person" unless stopRun was told
+ *  otherwise (RunRecord.stoppedBy). */
+export function stoppedByText(run) {
+    const by = run?.stoppedBy?.trim();
+    return by ? by : "a person";
+}
 /**
  * The status a person should see. "failed" and "someone stopped it" are
  * different facts — the record keeps them apart (stopRequested), and the

package/dist/src/subagents.d.ts

@@ -1,3 +1,15 @@
+/**
+ * The a2a tools (remotes:) are the parent's: one server, built for the
+ * PARENT's remotes with the parent's credentials, under the same four names
+ * whatever remotes a sub-agent declares. Intersecting names would hand a
+ * shared-sandbox sub-agent every remote its parent may call. So they are
+ * withheld from it entirely — not in its list, and refused if it calls one.
+ * A `sandbox: own` sub-agent runs as a step of its own, from its own file,
+ * and gets its OWN remotes there (runner.ts delegateFor → runStep).
+ */
+export declare function isA2aTool(tool: string): boolean;
+/** What a shared-sandbox sub-agent is told, and what its refused call says. */
+export declare const SUBAGENT_NO_REMOTES = "remotes: are not available to shared-sandbox sub-agents yet \u2014 give the sub-agent `sandbox: own`, or call the remote from the parent";
 /** Plain JSON: this crosses into the run container. */
 export interface SubagentSpec {
     name: string;
@@ -50,6 +62,10 @@ export declare function subagentPrompt(o: {
     parent: string;
     workspace: string;
     shared?: string | null;
+}, extra?: {
+    /** It declares remotes:, which it does not get here. A second argument,
+     *  so the signature only widened. */
+    remotesWithheld?: boolean;
 }): string;
 /** SDK definitions. `tools` is always set — an absent list inherits every
  *  tool the parent has, which is the one thing this module exists to stop. */

package/dist/src/subagents.js

@@ -27,6 +27,21 @@ import fs from "node:fs";
 import path from "node:path";
 import { refNames } from "./refs.js";
 import { TOOL_MAP } from "./tool-names.js";
+import { A2A_SERVER } from "./a2a-remotes.js";
+/**
+ * The a2a tools (remotes:) are the parent's: one server, built for the
+ * PARENT's remotes with the parent's credentials, under the same four names
+ * whatever remotes a sub-agent declares. Intersecting names would hand a
+ * shared-sandbox sub-agent every remote its parent may call. So they are
+ * withheld from it entirely — not in its list, and refused if it calls one.
+ * A `sandbox: own` sub-agent runs as a step of its own, from its own file,
+ * and gets its OWN remotes there (runner.ts delegateFor → runStep).
+ */
+export function isA2aTool(tool) {
+    return tool === `mcp__${A2A_SERVER}` || tool.startsWith(`mcp__${A2A_SERVER}__`);
+}
+/** What a shared-sandbox sub-agent is told, and what its refused call says. */
+export const SUBAGENT_NO_REMOTES = "remotes: are not available to shared-sandbox sub-agents yet — give the sub-agent `sandbox: own`, or call the remote from the parent";
 /** Does this agent run in its own sandbox when delegated to? */
 export function ownSandbox(front) {
     return front.sandbox === "own";
@@ -63,7 +78,7 @@ export function subagentTools(own, parent) {
     const servers = new Set(parent.filter((t) => /^mcp__[^_]/.test(t)).map((t) => t.replace(/__\*$/, "")).filter((t) => !t.slice(5).includes("__")));
     const out = [];
     for (const t of own) {
-        if (DELEGATE_TOOLS.includes(t) || out.includes(t))
+        if (DELEGATE_TOOLS.includes(t) || isA2aTool(t) || out.includes(t))
             continue;
         const server = /^mcp__([^_].*?)__/.exec(t)?.[1];
         if (held.has(t) || (server && servers.has(`mcp__${server}`)))
@@ -73,9 +88,12 @@ export function subagentTools(own, parent) {
 }
 /** The sub-agent's system prompt: its own prose, told where it stands. It
  *  works in the PARENT's directory — the SDK shares the session's cwd. */
-export function subagentPrompt(o) {
+export function subagentPrompt(o, extra = {}) {
     return [
         o.body.trim(),
+        ...(extra.remotesWithheld
+            ? [`# Outside agents\n\nYour remotes: are not available to you as ${o.parent}'s sub-agent: ${SUBAGENT_NO_REMOTES}. If the job needs an outside agent, say so in your reply and ${o.parent} can call it.`]
+            : []),
         `# Where you are\n\n` +
             `You are ${o.name}, a sub-agent started by ${o.parent} to do one job and report back. ` +
             `You work in ${o.parent}'s directory, \`agents/${o.parent}/\` in the \`${o.workspace}\` workspace: ` +
@@ -131,6 +149,9 @@ export function subagentGuard(specs) {
         if (isDelegate(tool)) {
             return `${s.name} is a sub-agent and cannot start another — do the work with your own tools`;
         }
+        // The parent's remotes, with the parent's credentials: never a sub-agent's.
+        if (isA2aTool(tool))
+            return `${tool} is not available to ${s.name}: ${SUBAGENT_NO_REMOTES}`;
         if (s.disallowedTools.includes(tool))
             return `${tool} is disallowed for ${s.name}`;
         if (subagentTools([tool], s.tools).length === 0)

package/dist/src/triggers.js

@@ -14,7 +14,7 @@
 import crypto from "node:crypto";
 import { platform } from "./platform.js";
 import { listFlows, readRun, runVerdict } from "./store.js";
-import { getSecret } from "./secrets.js";
+import { getSecret, signingSecretShown } from "./secrets.js";
 /** The last step's result — the same reading runner.ts makes, kept local so
  *  this module never imports the runner (the queue imports both). */
 function runResult(run) {
@@ -251,7 +251,7 @@ export function verifyWebhookSignature(tenant, workspace, flow, rawBody, header,
         return { ok: false, reason: `signature: ${flow.signature} needs signing_secret: \${NAME}` };
     const secret = getSecret(tenant, flow.signingSecret, workspace);
     if (!secret)
-        return { ok: false, reason: `signing secret ${flow.signingSecret} is not set` };
+        return { ok: false, reason: `signing secret ${signingSecretShown(flow.signingSecret)} is not set` };
     const hmac = (data) => crypto.createHmac("sha256", secret.value).update(data).digest("hex");
     const fresh = (ts) => Math.abs(now / 1000 - ts) <= 300;
     switch (flow.signature) {

package/dist/src/webhook.d.ts

@@ -27,14 +27,30 @@ export declare function webhookPath(tenant: string, workspace: string, flow: str
  * working hook token.
  */
 export declare function approveToken(tenant: string, workspace: string, runId: string): string;
+/** One parked `wait: event` gate: the step's index in the run record and
+ *  the moment it parked (the `t` of its "waiting for an external event"
+ *  trace line). */
+export interface EventGate {
+    step: number;
+    at: string;
+}
 /**
  * The token that releases a run parked on `wait: event`. Its own HMAC
  * family, so an approval link cannot double as an event URL or the reverse.
+ *
+ * With `gate`, the token is for that one park of that one step (30 Oct
+ * 2026). The per-run token released every later `wait: event` of the run,
+ * so a URL handed to a third party for the first gate also opened the
+ * second, and never expired. A gate's token dies with its park: the step
+ * released is no longer waiting, and parking again (a loop) stamps a new
+ * `at`. The per-run form, without `gate`, is what URLs printed before then
+ * carry — the events route still takes it for a step parked under it.
  */
-export declare function eventToken(tenant: string, workspace: string, runId: string): string;
+export declare function eventToken(tenant: string, workspace: string, runId: string, gate?: EventGate): string;
 /** The URL a `wait: event` step is released at — absolute when the install
- *  knows its origin, a path otherwise. */
-export declare function eventUrl(tenant: string, workspace: string, runId: string): string;
+ *  knows its origin, a path otherwise. With `gate`, that step's own URL
+ *  (`&step=<index>`); the route finds the park's moment on the record. */
+export declare function eventUrl(tenant: string, workspace: string, runId: string, gate?: EventGate): string;
 /**
  * Where this install can be reached from outside, or null. The platform has
  * never needed to know its own address — every URL it hands out has been a

package/dist/src/webhook.js

@@ -80,18 +80,27 @@ export function approveToken(tenant, workspace, runId) {
 /**
  * The token that releases a run parked on `wait: event`. Its own HMAC
  * family, so an approval link cannot double as an event URL or the reverse.
+ *
+ * With `gate`, the token is for that one park of that one step (30 Oct
+ * 2026). The per-run token released every later `wait: event` of the run,
+ * so a URL handed to a third party for the first gate also opened the
+ * second, and never expired. A gate's token dies with its park: the step
+ * released is no longer waiting, and parking again (a loop) stamps a new
+ * `at`. The per-run form, without `gate`, is what URLs printed before then
+ * carry — the events route still takes it for a step parked under it.
  */
-export function eventToken(tenant, workspace, runId) {
+export function eventToken(tenant, workspace, runId, gate) {
     return crypto
         .createHmac("sha256", installKey())
-        .update(`event:${tenant}/${workspace}/${runId}`)
+        .update(gate ? `event:${tenant}/${workspace}/${runId}#${gate.step}@${gate.at}` : `event:${tenant}/${workspace}/${runId}`)
         .digest("hex")
         .slice(0, 32);
 }
 /** The URL a `wait: event` step is released at — absolute when the install
- *  knows its origin, a path otherwise. */
-export function eventUrl(tenant, workspace, runId) {
-    const p = `/api/events/${tenant}/${workspace}/${runId}?token=${eventToken(tenant, workspace, runId)}`;
+ *  knows its origin, a path otherwise. With `gate`, that step's own URL
+ *  (`&step=<index>`); the route finds the park's moment on the record. */
+export function eventUrl(tenant, workspace, runId, gate) {
+    const p = `/api/events/${tenant}/${workspace}/${runId}?token=${eventToken(tenant, workspace, runId, gate)}${gate ? `&step=${gate.step}` : ""}`;
     const base = publicUrl();
     return base ? `${base}${p}` : p;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "9.0.0",
+  "version": "9.2.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "FSL-1.1-ALv2",
   "type": "module",
@@ -17,6 +17,9 @@
   "foldrun": {
     "publicApi": [
       ".",
+      "./a2a-client",
+      "./a2a-publish",
+      "./a2a-remotes",
       "./agents-md",
       "./browser-pod",
       "./flow-patterns",