@foldrun/core 9.0.0 → 9.2.0

package/src/store.ts

@@ -50,6 +50,8 @@ export function readFrontmatter(file: string): Record<string, unknown> {
 import { ownToolNames, legacyUseNames, retiredToolNames } from "./tool-names.ts";
 import { refNames } from "./refs.ts";
 import { checkFilter } from "./trigger-filter.ts";
+import { parseA2aPublish, type A2aPublication } from "./a2a-publish.ts";
+import { parseRemotes, remoteNetworkHosts, A2A_LIMIT_KEY, type RemoteSpec } from "./a2a-remotes.ts";
 import { parseBudget, budgetProblem } from "./budget.ts";
 import { timezoneProblem } from "./clock.ts";
 import { parseStepLimits, readLimits } from "./limits.ts";
@@ -984,6 +986,9 @@ export interface AgentInfo {
   effort: string | null;
   tools: string[];
   apis: ApiSpec[];
+  /** `remotes:` — the outside A2A agents it may call, the entries that read
+   *  (a2a-remotes.ts). Never a token: names, card URLs, secret NAMES. */
+  remotes?: RemoteSpec[];
   /** The author's own tools named in `tools:` — the subset that is not a
    *  built-in. Same list as `tools`, minus what the runtime provides. */
   ownTools: string[];
@@ -1518,6 +1523,11 @@ export interface FlowInfo {
   /** Which of the three `owner` came from. */
   ownerFrom: OwnerSource | null;
 
+  /** `a2a:` — whether outside agents may call this flow over A2A, and what
+   *  its agent card says (a2a-publish.ts). Null when absent or unreadable:
+   *  a block with a problem publishes nothing. */
+  a2a?: A2aPublication | null;
+
   /** Flow-level frontmatter values the parser could not read — a bad
    *  `overlap:`/`priority:`/`catchup:`/`on:`/`signature:`, or a step line
    *  whose `[[target]]` is malformed. Errors, the way a bad step option is,
@@ -1604,6 +1614,8 @@ function inlineToolNames(data: Record<string, unknown>): string[] {
     }
   }
   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;
 }
 
@@ -1645,7 +1657,11 @@ export function listAgents(tenant: string, workspace: string): AgentInfo[] {
           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,
       };
@@ -1658,6 +1674,7 @@ export function listAgents(tenant: string, workspace: string): AgentInfo[] {
         effort: data.effort ?? null,
         tools,
         apis: parseApis(data.apis),
+        remotes: parseRemotes(data.remotes),
         ownTools: ownToolNames(data),
         legacyUse: legacyUseNames(data),
         retiredTools: retiredToolNames(data),
@@ -2138,6 +2155,7 @@ export function parseFlow(file: string, raw: string): FlowInfo {
     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,
   };
@@ -2985,7 +3003,9 @@ export function renameWorkspaceFile(tenant: string, workspace: string, from: str
   // 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);
   const src = path.join(dir, assertEditablePath(from));
@@ -3740,6 +3760,11 @@ export interface RunRecord {
    *  expressed only as a status, because "failed" and "someone stopped it"
    *  are different facts and the trace should not conflate them. */
   stopRequested?: boolean;
+  /** Who stopped it, as the trail says it, when that was not a person
+   *  stopping it from the dashboard, the CLI or the API: "A2A caller
+   *  <key label>" for an A2A CancelTask (1 Nov 2026). Absent: a person.
+   *  Written by stopRun beside stopRequested, carried the same way. */
+  stoppedBy?: string;
   /**
    * What this run concluded, in one line — the first line of the last step
    * that produced a result, captured when the run finishes.
@@ -3810,6 +3835,14 @@ export interface RunRecord {
    *  step of this run — never the tokens. A link is good once; the second
    *  click is a 409, not a second approval. Written by approvals.ts. */
   approvalLinksUsed?: string[];
+  /** What started it, when that is not a person, a schedule or an event the
+   *  flow's own trigger names: "a2a" — an outside agent, over A2A (1 Nov
+   *  2026). Absent for every other run. */
+  trigger?: "a2a";
+  /** For an A2A run: the A2A task it serves and the id of the A2A key (its
+   *  first id, kept across rotations) that asked. A correlation only — the
+   *  protocol's own state lives in the platform's a2a_tasks. */
+  a2a?: { task: string; key: string };
   steps: StepRecord[];
 }
 
@@ -4089,6 +4122,9 @@ export interface RunSummary {
   revision?: string | null;
   /** A step is parked for a person — what the approvals banner counts. */
   awaitingApproval: boolean;
+  /** RunRecord.trigger and .a2a: an outside agent started it. */
+  trigger?: "a2a";
+  a2a?: { task: string; key: string };
   steps: RunSummaryStep[];
 }
 
@@ -4131,6 +4167,8 @@ export function summarizeRun(run: RunRecord): RunSummary {
     ...(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;
@@ -4319,6 +4357,13 @@ export function listAllRunSummaries(tenant: string): (RunSummary & { workspace:
     .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: Pick<RunRecord, "stoppedBy"> | null | undefined): string {
+  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/src/subagents.ts

@@ -28,6 +28,24 @@ import fs from "node:fs";
 import path from "node:path";
 import { refNames } from "./refs.ts";
 import { TOOL_MAP } from "./tool-names.ts";
+import { A2A_SERVER } from "./a2a-remotes.ts";
+
+/**
+ * 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: string): boolean {
+  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";
 
 /** Plain JSON: this crosses into the run container. */
 export interface SubagentSpec {
@@ -95,7 +113,7 @@ export function subagentTools(own: string[], parent: string[]): string[] {
   );
   const out: string[] = [];
   for (const t of own) {
-    if ((DELEGATE_TOOLS as readonly string[]).includes(t) || out.includes(t)) continue;
+    if ((DELEGATE_TOOLS as readonly string[]).includes(t) || isA2aTool(t) || out.includes(t)) continue;
     const server = /^mcp__([^_].*?)__/.exec(t)?.[1];
     if (held.has(t) || (server && servers.has(`mcp__${server}`))) out.push(t);
   }
@@ -110,9 +128,16 @@ export function subagentPrompt(o: {
   parent: string;
   workspace: string;
   shared?: string | null;
-}): string {
+}, extra: {
+  /** It declares remotes:, which it does not get here. A second argument,
+   *  so the signature only widened. */
+  remotesWithheld?: boolean;
+} = {}): string {
   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: ` +
@@ -183,6 +208,8 @@ export function subagentGuard(specs: SubagentSpec[]): (call: GuardedCall) => str
     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) return `${tool} is not one of ${s.name}'s tools`;
     return null;

package/src/triggers.ts

@@ -15,7 +15,7 @@
 import crypto from "node:crypto";
 import { platform } from "./platform.ts";
 import { listFlows, readRun, runVerdict, type FlowInfo, type FlowStep, type RunRecord } from "./store.ts";
-import { getSecret } from "./secrets.ts";
+import { getSecret, signingSecretShown } from "./secrets.ts";
 
 /** The last step's result — the same reading runner.ts makes, kept local so
  *  this module never imports the runner (the queue imports both). */
@@ -273,7 +273,7 @@ export function verifyWebhookSignature(
   if (!flow.signature) return { ok: true, reason: "no signature required" };
   if (!flow.signingSecret) 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` };
+  if (!secret) return { ok: false, reason: `signing secret ${signingSecretShown(flow.signingSecret)} is not set` };
   const hmac = (data: string) => crypto.createHmac("sha256", secret.value).update(data).digest("hex");
   const fresh = (ts: number) => Math.abs(now / 1000 - ts) <= 300;
 

package/src/webhook.ts

@@ -96,22 +96,39 @@ export function approveToken(tenant: string, workspace: string, runId: string):
     .slice(0, 32);
 }
 
+/** 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 function eventToken(tenant: string, workspace: string, runId: string): string {
+export function eventToken(tenant: string, workspace: string, runId: string, gate?: EventGate): string {
   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: string, workspace: string, runId: string): string {
-  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: string, workspace: string, runId: string, gate?: EventGate): string {
+  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;
 }