@foldrun/core 9.1.0 → 9.2.1

package/dist/src/starter.js

@@ -373,6 +373,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 |
 
@@ -380,9 +381,11 @@ Account-level, outside \`/workspaces\`: \`/api/secrets\`, \`/api/keys\`, \`/api/
 \`/api/approvals\`, \`/api/issues\` (what went wrong, open until resolved), \`/api/usage\`, \`/api/library/<kind>\`, \`/api/team\`, \`/api/billing\`,
 \`/api/me/notifications\` (what mail you get; a key acts for whoever minted it),
 \`/api/me/inbox\` (what waits on you: gates, questions, issues, proposed fixes, your failed runs),
+\`/api/mcp\` (this account as MCP tools for an AI app such as Claude Desktop or Cursor — an API key; \`foldrun mcp\` serves the same over stdio, \`foldrun docs mcp\`),
 \`/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\`
@@ -418,6 +421,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}}.
@@ -483,6 +487,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)

package/dist/src/store.d.ts

@@ -14,6 +14,8 @@ import { frontmatterErrorText } from "./matter.ts";
  * the runtime, and there is nothing to fail to import.
  */
 export declare function readFrontmatter(file: string): Record<string, unknown>;
+import { type A2aPublication } from "./a2a-publish.ts";
+import { type RemoteSpec } from "./a2a-remotes.ts";
 import { type NetworkPolicy } from "./network.ts";
 import { type WireFormat, type AuthShape } from "./providers.ts";
 /**
@@ -306,6 +308,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[];
@@ -652,6 +657,10 @@ export interface FlowInfo {
     owner: string | null;
     /** 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,
@@ -1445,6 +1454,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.
@@ -1523,6 +1537,17 @@ 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[];
 }
 /** Merge one part (the input, on the call; the output, on its completion)
@@ -1643,6 +1668,12 @@ 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[];
 }
 /** One run's row. */
@@ -1661,6 +1692,9 @@ export declare function listRunSummaries(tenant: string, workspace: string): Run
 export declare function listAllRunSummaries(tenant: string): (RunSummary & {
     workspace: string;
 })[];
+/** Who stopped a run, for a trail line: "a person" unless stopRun was told
+ *  otherwise (RunRecord.stoppedBy). */
+export declare function stoppedByText(run: Pick<RunRecord, "stoppedBy"> | null | undefined): string;
 /**
  * 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "9.1.0",
+  "version": "9.2.1",
   "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",