@foldrun/core 9.1.0 → 9.2.0

package/src/api-tools.ts

@@ -20,7 +20,12 @@ import { createSdkMcpServer, tool, type SdkMcpToolDefinition } from "@anthropic-
 import type { ApiSpec } from "./store.ts";
 import { previewOrKeep, RESULT_KEEP_CHARS, type KeepIn } from "./tool-output.ts";
 import type { OperationSpec } from "./openapi.ts";
-import { resolveSecrets, materializeSecrets } from "./secrets.ts";
+import { resolveSecrets, materializeCurrent } from "./secrets.ts";
+
+/** Whose vault the secrets came from, on a host step: the account (and
+ *  workspace) they are made live in. Null inside a sandbox, where the values
+ *  crossed already resolved and there is no vault. */
+type VaultScope = { tenant: string; workspace?: string } | null;
 
 // Collected whole up to this; the model sees a preview and where the rest is
 // kept (tool-output.ts), not a cut with the rest gone.
@@ -145,6 +150,7 @@ async function performRequest(
   req: Request,
   /** Where a long body is kept, when the agent can read it back (tool-output.ts). */
   keepIn?: KeepIn,
+  scope: VaultScope = null,
 ): Promise<ToolReply> {
   const started = Date.now();
   try {
@@ -153,8 +159,11 @@ async function performRequest(
     // Per call, not per build: an oauth2 secret's recipe becomes a
     // live access token here, so a step that runs for an hour keeps
     // getting fresh tokens (the exchange is cached until near expiry)
-    // — and a recipe can never end up inside a header.
-    const live = await materializeSecrets(env);
+    // — and a recipe can never end up inside a header. On a host, the
+    // vault's recipe as it is now, made live in the account's scope: a
+    // rotating refresh token the runner (or an earlier call) spent is never
+    // sent again (secrets.ts materializeCurrent).
+    const live = await materializeCurrent(env, scope);
     const path = req.path.startsWith("/") ? req.path : `/${req.path}`;
     const url = new URL(api.base + path);
     // Base-URL confinement: a path can't escape the declared host.
@@ -243,6 +252,7 @@ function typedTool(
   bucket: TokenBucket | null,
   log: string[],
   keepIn?: KeepIn,
+  scope: VaultScope = null,
 ) {
   const keys = argKeys(op);
   const shape: Record<string, z.ZodTypeAny> = {};
@@ -292,11 +302,11 @@ function typedTool(
       query,
       headers,
       body: typeof values.body === "string" ? values.body : undefined,
-    }, keepIn);
+    }, keepIn, scope);
   });
 }
 
-function genericTool(api: ApiSpec, env: Record<string, string>, bucket: TokenBucket | null, log: string[], keepIn?: KeepIn) {
+function genericTool(api: ApiSpec, env: Record<string, string>, bucket: TokenBucket | null, log: string[], keepIn?: KeepIn, scope: VaultScope = null) {
   const typed = api.resolvedOperations?.length
     ? ` Prefer the typed ${api.name}_* tools; this one is the escape hatch for operations they do not cover.`
     : "";
@@ -321,7 +331,7 @@ function genericTool(api: ApiSpec, env: Record<string, string>, bucket: TokenBuc
         query: args.query ?? {},
         headers: {},
         body: args.body,
-      }, keepIn),
+      }, keepIn, scope),
   );
 }
 
@@ -351,6 +361,8 @@ export function buildApiTools(
         missing: resolved.missing,
       }
     : resolveSecrets(tenant, neededSecrets, workspace);
+  // Read from the vault here: made live per call in its account's scope.
+  const scope: VaultScope = !resolved && tenant ? { tenant, ...(workspace ? { workspace } : {}) } : null;
   const log: string[] = [];
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the SDK types its own list this way
@@ -393,11 +405,11 @@ export function buildApiTools(
 
     const typedNames: string[] = [];
     for (const op of ops) {
-      tools.push(typedTool(api, op, env, bucket, log, keepIn));
+      tools.push(typedTool(api, op, env, bucket, log, keepIn, scope));
       typedNames.push(typedToolName(api.name, op.id));
       methods[`mcp__foldrun_apis__${typedToolName(api.name, op.id)}`] = String(op.method ?? "").toUpperCase();
     }
-    if (withGeneric) tools.push(genericTool(api, env, bucket, log, keepIn));
+    if (withGeneric) tools.push(genericTool(api, env, bucket, log, keepIn, scope));
 
     const names = [...typedNames, ...(withGeneric ? [`call_${api.name}`] : [])];
     for (const n of names) {

package/src/browser-pod.ts

@@ -162,6 +162,9 @@ export function classifyCall(tool: string, input: Record<string, unknown> | unde
   // tools: [peers] — reading the roster changes nothing; a message to a
   // colleague is said, and a re-run would say it twice.
   if (server === "foldrun_peers") return name === "peers_list" ? { write: false } : write("a message to a colleague");
+  // remotes: — reading where a request got to changes nothing; a send, a
+  // reply or a cancel acts on an outside agent's system.
+  if (server === "foldrun_a2a") return name === "a2a_status" ? { write: false } : write(`${name.replace(/^a2a_/, "")} to an outside agent`);
   if (server === "foldrun_scripts") {
     if (name !== "web") return write(`script ${name}`);
     const action = String(args.action ?? "").trim().toLowerCase();

package/src/completions.ts

@@ -394,9 +394,9 @@ export function completionsAt(
     // that field's files and nothing else. `[[search]]` in tools: is how a
     // tool named after a runtime group gets granted; offering the group
     // here would defeat the point of the brackets.
-    const inlineOwner = line.match(/^\s*([a-zA-Z_]+):\s*(?:\[.*)?\[\[[^\]]*$/)?.[1];
+    const inlineOwner = line.match(/^\s*([a-zA-Z_][a-zA-Z0-9_]*):\s*(?:\[.*)?\[\[[^\]]*$/)?.[1];
     const blockOwner = /^\s+-\s*\[\[/.test(line)
-      ? before.slice(0, lineStart).split("\n").reverse().find((l) => /^\s*[a-zA-Z_]+:\s*$/.test(l))?.trim().replace(":", "")
+      ? before.slice(0, lineStart).split("\n").reverse().find((l) => /^\s*[a-zA-Z_][a-zA-Z0-9_]*:\s*$/.test(l))?.trim().replace(":", "")
       : undefined;
     const owner = inlineOwner ?? blockOwner;
     const byField: Record<string, Completion[]> = {
@@ -460,7 +460,7 @@ export function completionsAt(
   //    been chosen yet, one at a time. Fixed combinations were the wrong
   //    model: nobody wants a menu of every permutation, they want to add the
   //    next verb.
-  const inlineList = line.match(/^(\s*)([a-zA-Z_]+):\s*\[([^\]]*)$/);
+  const inlineList = line.match(/^(\s*)([a-zA-Z_][a-zA-Z0-9_]*):\s*\[([^\]]*)$/);
   if (inlineList) {
     const [, , key, inside] = inlineList;
     // The inline and block forms of a list are the same field — `tools: [a, b]`
@@ -505,7 +505,7 @@ export function completionsAt(
   }
 
   // 4. `key: value` — the value side of a known field.
-  const kv = line.match(/^(\s*)([a-zA-Z_]+):\s*(\S*)$/);
+  const kv = line.match(/^(\s*)([a-zA-Z_][a-zA-Z0-9_]*):\s*(\S*)$/);
   if (kv) {
     const [, , key, partial] = kv;
     const from = cursor - partial.length;
@@ -587,7 +587,7 @@ export function completionsAt(
     const partial = listItem[2];
     const from = cursor - partial.length;
     const priorLines = before.slice(0, lineStart).split("\n").reverse();
-    const owner = priorLines.find((l) => /^\s*[a-zA-Z_]+:\s*$/.test(l))?.trim().replace(":", "");
+    const owner = priorLines.find((l) => /^\s*[a-zA-Z_][a-zA-Z0-9_]*:\s*$/.test(l))?.trim().replace(":", "");
     const byOwner: Record<string, Completion[]> = {
       // One list now: built-ins and your own tools are granted the same way.
       // Groups first (they cover most needs), then your own tools — the ones
@@ -629,7 +629,7 @@ export function completionsAt(
     const partial = mapping[2] ?? "";
     const priorLines = before.slice(0, lineStart).split("\n").reverse();
     const owner = priorLines
-      .find((l) => /^\s*[a-zA-Z_]+:\s*$/.test(l))
+      .find((l) => /^\s*[a-zA-Z_][a-zA-Z0-9_]*:\s*$/.test(l))
       ?.trim()
       .replace(":", "");
     const byOwner: Record<string, Completion[]> = {
@@ -666,7 +666,7 @@ export function completionsAt(
   //     kind of file — the block takes nothing else.
   const fmClose = text.indexOf("\n---", text.indexOf("---") + 3);
   const insideFrontmatter = text.startsWith("---") && (fmClose === -1 || cursor <= fmClose);
-  const nested = line.match(/^(\s+)([a-zA-Z_]*)$/);
+  const nested = line.match(/^(\s+)([a-zA-Z_][a-zA-Z0-9_]*|)$/);
   if (insideFrontmatter && nested) {
     const header = before.slice(0, lineStart).split("\n").reverse().find((l) => /^\S/.test(l));
     const job = JOBS.find((j) => new RegExp(`^${j.name}\\s*:\\s*$`).test(header ?? ""));
@@ -699,7 +699,7 @@ export function completionsAt(
   //    this kind of file. This is where you learn the format by writing it.
   const fmEnd = text.indexOf("\n---", text.indexOf("---") + 3);
   const inFrontmatter = text.startsWith("---") && (fmEnd === -1 || cursor <= fmEnd);
-  if (inFrontmatter && /^[a-zA-Z_][a-zA-Z_-]*$|^$/.test(line)) {
+  if (inFrontmatter && /^[a-zA-Z_][a-zA-Z0-9_-]*$|^$/.test(line)) {
     const from = cursor - line.length;
     return { from, query: line, items: filter(fieldsFor(path, kind), line), title: `${kind} fields` };
   }

package/src/frontmatter-fields.ts

@@ -88,6 +88,7 @@ const AGENT: FieldSpec[] = [
   { key: "scripts", type: "list", help: "programs in scripts/, each a tool" },
   { key: "apis", type: "list", help: "an HTTP API as a tool" },
   { key: "mcpServers", type: "object", help: "MCP servers, name → {command | url, args, env, headers}" },
+  { key: "remotes", type: "list", help: "outside A2A agents it may call — [{name, card: the https URL of its agent card, secret?: a vault NAME sent as a bearer token, description?}]" },
   { key: "agents", type: ["list", "string"], help: "colleagues it may consult" },
   { key: "subagents", type: ["list", "string"], help: "colleagues it may delegate to" },
   { key: "sandbox", type: "string", values: ["own", "parent"], help: "when delegated to as a sub-agent: own = its own sandbox, tools, secrets and network; parent (default) = inside the delegating step's" },
@@ -174,6 +175,7 @@ const FLOW: FieldSpec[] = [
   { key: "budget", type: ["number", "string"], help: "USD per run" },
   { key: "compute", type: "object", help: "{vcpu, memory, disk} one run's steps may hold together at once — only narrows the workspace's and account's" },
   { key: "live", type: "boolean", help: "true: steps may act for real in a test run" },
+  { key: "a2a", type: "object", help: "serve this flow to outside agents over A2A 1.0 — {publish: true, name?, description?, examples?, public_card?, input?}; changing it needs workspace:manage" },
 ];
 
 const TOOL: FieldSpec[] = [

package/src/frontmatter-schema.ts

@@ -10,6 +10,8 @@ import { cronProblem, parseCron, cronCanFire } from "./cron.ts";
 import { SECRET_NAME } from "./secrets.ts";
 import { modelSecretCollision } from "./model-credential.ts";
 import { resourcesProblem, computeProblem } from "./resources.ts";
+import { remotesProblem } from "./a2a-remotes.ts";
+import { a2aPublishProblem } from "./a2a-publish.ts";
 
 export { FRONTMATTER, schemaKindOf, type FieldSpec, type FieldType, type SchemaKind } from "./frontmatter-fields.ts";
 
@@ -33,6 +35,7 @@ const CHECKS: Partial<Record<SchemaKind, Record<string, (value: unknown) => stri
   "agent": {
     effort: (v) => (resolveEffort(v) ? null : `"${String(v)}" is not an effort — low, medium, high, xhigh or max; the step runs at the model's default`),
     apis: apisProblem,
+    remotes: remotesProblem,
     budget: (v) => budgetProblem(v, ["run"]),
     ask: (v) => askProblem(v),
     resources: resourcesProblem,
@@ -57,6 +60,7 @@ const CHECKS: Partial<Record<SchemaKind, Record<string, (value: unknown) => stri
     pause_when: (v) => (String(v).length <= 60 ? null : "is longer than 60 characters"),
     budget: (v) => budgetProblem(v, ["run"]),
     compute: computeProblem,
+    a2a: a2aPublishProblem,
   },
   "tool": {
     transport: (v) => (["http", "script", "mcp"].includes(String(v).toLowerCase()) ? null : `"${String(v)}" is not a transport — http, script or mcp`),

package/src/limits.ts

@@ -5,6 +5,8 @@
 //     web.search: 40      # one action of the web tool
 //     web: 150            # every web action together
 //     crm: 20             # an API, script or MCP tool, by the name it is granted as
+//     a2a: 10             # messages to outside agents (a2a_send and a2a_reply)
+//     a2a.status: 30      # polls of them, apart from the sends
 //     calls: 300          # every tool call in the step, whatever the tool
 //     repeat: 5           # the same call — one tool, the same input — at most this often
 //
@@ -22,6 +24,7 @@
 import crypto from "node:crypto";
 import { WEB_ACTIONS } from "./providers.ts";
 import { DELEGATE_TOOLS } from "./subagents.ts";
+import { A2A_SERVER, A2A_LIMIT_KEY, A2A_LIMIT_ACTIONS } from "./a2a-remotes.ts";
 
 export type Limits = Record<string, number>;
 
@@ -103,8 +106,13 @@ export function readLimits(raw: unknown, where = "limits"): { limits: Limits; pr
     }
     if (k.includes(".")) {
       const [head, action] = k.split(".");
-      if (head !== "web" || !(WEB_ACTIONS as readonly string[]).includes(action)) {
-        problems.push(`${where}: "${k}" is not a key — the dotted keys are web.<action>: ${WEB_ACTIONS.map((a) => `web.${a}`).join(", ")}.`);
+      const web = head === "web" && (WEB_ACTIONS as readonly string[]).includes(action);
+      const a2a = head === A2A_LIMIT_KEY && (A2A_LIMIT_ACTIONS as readonly string[]).includes(action);
+      if (!web && !a2a) {
+        problems.push(
+          `${where}: "${k}" is not a key — the dotted keys are web.<action>: ${WEB_ACTIONS.map((a) => `web.${a}`).join(", ")}, ` +
+            `and ${A2A_LIMIT_ACTIONS.map((a) => `${A2A_LIMIT_KEY}.${a}`).join(", ")}.`,
+        );
         continue;
       }
     }
@@ -166,6 +174,15 @@ export function limitKeysFor(toolName: string, input: Record<string, unknown> |
   if (toolName === "WebSearch") { webAction("search"); return keys; }
   if (toolName === "WebFetch") { webAction("fetch"); return keys; }
   if ((DELEGATE_TOOLS as readonly string[]).includes(toolName)) return keys;
+  // remotes: — a message to an outside agent (a2a_send, a2a_reply) counts
+  // under `a2a`; every tool also under its own `a2a.<action>`, so polling
+  // (`a2a.status`) is capped apart from sending.
+  const a2a = new RegExp(`^mcp__${A2A_SERVER}__a2a_([a-z]+)$`).exec(toolName);
+  if (a2a) {
+    if (a2a[1] === "send" || a2a[1] === "reply") keys.push(A2A_LIMIT_KEY);
+    keys.push(`${A2A_LIMIT_KEY}.${a2a[1]}`);
+    return keys;
+  }
   const owner = owners[toolName];
   const mcp = /^mcp__(.+?)__(.+)$/.exec(toolName);
   const name = owner
@@ -274,7 +291,7 @@ export function limitKeyProblems(
   ctx: { known: Iterable<string>; granted: Iterable<string> },
 ): { level: "error" | "warn"; message: string }[] {
   const out: { level: "error" | "warn"; message: string }[] = [];
-  const builtinKeys = ["read", "write", "code", ...Object.keys(BUILTIN_GROUP), "TodoWrite", "search", "history", "desks", "ask", "web"];
+  const builtinKeys = ["read", "write", "code", ...Object.keys(BUILTIN_GROUP), "TodoWrite", "search", "history", "desks", "ask", "web", A2A_LIMIT_KEY];
   const known = new Set([...builtinKeys, ...ctx.known].map(normKey));
   const granted = new Set([...ctx.granted].flatMap((g) => {
     const n = normKey(g);
@@ -287,10 +304,11 @@ export function limitKeyProblems(
   }).map(normKey));
   for (const key of Object.keys(limits)) {
     if (key === TOTAL_KEY || key === REPEAT_KEY) continue;
-    const base = key.startsWith("web.") ? "web" : key;
+    const base = key.startsWith("web.") ? "web" : key.startsWith(`${A2A_LIMIT_KEY}.`) ? A2A_LIMIT_KEY : key;
     const n = normKey(base);
     if (!known.has(n)) {
       const valid = [TOTAL_KEY, "web", ...WEB_ACTIONS.map((a) => `web.${a}`), ...[...new Set([...ctx.granted].map(String))].filter((g) => g !== "web")];
+      if ([...ctx.granted].map(String).includes(A2A_LIMIT_KEY)) valid.push(...A2A_LIMIT_ACTIONS.map((a) => `${A2A_LIMIT_KEY}.${a}`));
       out.push({ level: "error", message: `limits: ${key} — not a tool this agent could call. The keys: ${[...new Set(valid)].join(", ")}.` });
     } else if (!granted.has(n)) {
       out.push({ level: "warn", message: `limits: ${key} — this agent is not granted ${base}, so the limit never applies` });

package/src/run-container.ts

@@ -44,6 +44,7 @@ import { isOperatorEvent, type OperatorEvent } from "./operator.ts";
 import type { SearchRoot, RunDigest } from "./context-tools.ts";
 import type { TranslatorSpec } from "./translator.ts";
 import { parseBrowserPod, type BrowserPodOutcome } from "./browser-pod.ts";
+import type { RemoteSpec } from "./a2a-remotes.ts";
 
 /** What crosses the boundary. Everything in here is values — pre-resolved
  *  secrets in headers, assembled prompt, serializable MCP configs. */
@@ -61,6 +62,10 @@ export interface ContainerStepInput {
   /** http/stdio configs only — in-process servers are rebuilt inside. */
   mcpServers: Record<string, McpServerConfig>;
   apis: ApiSpec[]; // headers pre-substituted from the vault, host-side
+  /** `remotes:` — outside A2A agents, each spec's `token` filled host-side
+   *  (`${NAME}` for the egress proxy, or the value with no proxy), and the
+   *  run and step its handles are kept under (a2a-tools.ts). */
+  a2a?: { remotes: RemoteSpec[]; runId: string | null; step: number | null };
   scripts: ScriptSpec[];
   /** The agent's `runtime:` declaration — the driver builds the venv/npm
    *  prefix inside the container, where the network is. Without this,
@@ -749,6 +754,7 @@ try {
   process.env.FOLDRUN_DATA = "/home/agent/.foldrun";
   const { executeStep } = await import("@foldrun/core/step-exec");
   const { buildApiTools } = await import("@foldrun/core/api-tools");
+  const { buildA2ATools } = await import("@foldrun/core/a2a-tools");
   const { buildScriptTools } = await import("@foldrun/core/script-tools");
   const { buildConsultTools } = await import("@foldrun/core/agent-tools");
   const { buildSearchTools, buildHistoryTools, buildDeskTools } = await import("@foldrun/core/context-tools");
@@ -825,6 +831,20 @@ try {
   const toolEnv = { ...env };
   for (const [k, v] of Object.entries(env)) if (k.startsWith("FOLDRUN_DECLARED_")) toolEnv[k.slice("FOLDRUN_DECLARED_".length)] = v;
   const api = buildApiTools("", input.apis, undefined, { env: toolEnv, missing: [] }, keepIn);
+  // remotes: — the four a2a tools, rebuilt from values. Each token crossed in
+  // its spec (a placeholder the proxy fills for the card's origin alone), so
+  // nothing here asks a vault; handles go under the workspace's state/.
+  const a2a = input.a2a && Array.isArray(input.a2a.remotes) && input.a2a.remotes.length
+    ? buildA2ATools("", input.a2a.remotes, undefined, { env: {}, missing: [] }, {
+        stateDir: "/workspace/state/a2a/" + input.agentRel.split("/").pop(),
+        runId: input.a2a.runId,
+        step: input.a2a.step,
+        egress: env.FOLDRUN_EGRESS || null,
+        test: env.FOLDRUN_TEST_MODE === "1",
+        keepIn,
+        emit,
+      })
+    : { server: null, drainLog: () => [] };
   const script = buildScriptTools(
     agentDir,
     input.scripts,
@@ -901,6 +921,7 @@ try {
     mcpNames: input.mcpNames,
     mcpServers: {
       ...(api.server ? { foldrun_apis: api.server } : {}),
+      ...(a2a.server ? { foldrun_a2a: a2a.server } : {}),
       ...(script.server ? { foldrun_scripts: script.server } : {}),
       ...(consult.server ? { foldrun_agents: consult.server } : {}),
       ...(search.server ? { foldrun_search: search.server } : {}),
@@ -940,6 +961,7 @@ try {
     emit,
   });
   for (const line of api.drainLog()) emit("info", "api: " + line);
+  for (const line of a2a.drainLog()) emit("info", "a2a: " + line);
   for (const line of script.drainLog()) emit("info", "script: " + line);
   if (translator) {
     for (const line of translator.drainLog()) emit("info", line.startsWith("translator") ? line : "translator: " + line);