foldrun 10.1.1 → 10.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/foldrun.mjs +16 -2
- package/docs/a2a.md +330 -0
- package/docs/agents.md +77 -0
- package/docs/api.md +38 -2
- package/docs/checks.md +28 -5
- package/docs/cli.md +14 -2
- package/docs/coding-agents.md +6 -0
- package/docs/flows.md +1 -0
- package/docs/glossary.md +5 -0
- package/docs/mcp.md +127 -0
- package/docs/network.md +3 -2
- package/docs/team-and-access.md +10 -1
- package/docs/tools.md +2 -0
- package/package.json +3 -3
- package/src/commands.mjs +539 -1
- package/src/guide.mjs +1 -1
package/src/commands.mjs
CHANGED
|
@@ -4278,6 +4278,7 @@ async function doctor(flags) {
|
|
|
4278
4278
|
* keys create <label> --workspaces <ws> one that opens that workspace alone
|
|
4279
4279
|
* keys revoke <id>
|
|
4280
4280
|
* keys create <label> --expires 90d it stops working in 90 days (30d, 365d, never)
|
|
4281
|
+
* keys create <label> --a2a --to <ws> --flows a,b [--max-tasks N] a key for an outside agent: /a2a only
|
|
4281
4282
|
* keys rotate <id> [--grace 1h] a new key, same label/role/scope; the old
|
|
4282
4283
|
* one ends now, or when the grace runs out.
|
|
4283
4284
|
* A key already rotated is refused (409):
|
|
@@ -4300,7 +4301,11 @@ async function keysCmd(positional, flags) {
|
|
|
4300
4301
|
const day = (iso) => (iso ? iso.slice(0, 10) : "");
|
|
4301
4302
|
for (const k of keys) {
|
|
4302
4303
|
// A deploy key opened the platform's own git, gone since 17 Oct 2026.
|
|
4303
|
-
const what = k.scope
|
|
4304
|
+
const what = k.scope
|
|
4305
|
+
? "deploy key · opens nothing since the platform's git went — revoke it"
|
|
4306
|
+
: k.purpose === "a2a"
|
|
4307
|
+
? `A2A · ${k.a2a?.workspace ?? "?"} · ${(k.a2a?.flows ?? []).join(",")}${k.a2a?.maxTasks ? ` · up to ${k.a2a.maxTasks} open` : ""}`
|
|
4308
|
+
: `${k.role ?? "admin"} · ${k.workspaces ? k.workspaces.join(",") || "no workspaces" : "all workspaces"}`;
|
|
4304
4309
|
const expired = !k.revokedAt && k.expiresAt && Date.parse(k.expiresAt) <= Date.now();
|
|
4305
4310
|
const state = k.revokedAt ? c.red("revoked") : expired ? c.red("expired") : c.green("live");
|
|
4306
4311
|
console.log(` ${state.padEnd(20)} ${k.id} ${k.prefix}… ${c.bold(k.label)} ${c.dim(what)}${k.createdBy ? c.dim(` by ${k.createdBy}`) : ""}`);
|
|
@@ -4314,6 +4319,7 @@ async function keysCmd(positional, flags) {
|
|
|
4314
4319
|
}
|
|
4315
4320
|
if (verb === "create" || verb === "new") {
|
|
4316
4321
|
if (!arg) throw new Error("what is the key for? foldrun keys create <label>");
|
|
4322
|
+
if (flags.a2a === true) return keysCreateA2a(url, arg, flags);
|
|
4317
4323
|
const body = { label: arg };
|
|
4318
4324
|
if (typeof flags.role === "string") body.role = flags.role;
|
|
4319
4325
|
// --expires 30d|90d|365d|never; unsaid, the key never expires.
|
|
@@ -4363,6 +4369,35 @@ async function keysCmd(positional, flags) {
|
|
|
4363
4369
|
throw new Error(`keys: unknown verb "${verb}" — ls, create, rotate, revoke`);
|
|
4364
4370
|
}
|
|
4365
4371
|
|
|
4372
|
+
/**
|
|
4373
|
+
* `foldrun keys create <label> --a2a --to <ws> --flows a,b [--max-tasks N]` —
|
|
4374
|
+
* a key for an OUTSIDE agent: it opens /a2a/<account>/<ws>/… for those
|
|
4375
|
+
* flows (each also published with a2a:) and no /api route.
|
|
4376
|
+
*/
|
|
4377
|
+
async function keysCreateA2a(url, label, flags) {
|
|
4378
|
+
if (flags.role !== undefined || flags.workspaces !== undefined) {
|
|
4379
|
+
throw new Error("an A2A key takes --to <workspace> and --flows, not --role or --workspaces — it opens /a2a only, for that workspace's flows");
|
|
4380
|
+
}
|
|
4381
|
+
if (typeof flags.to !== "string" || !flags.to) throw new Error("which workspace? `foldrun keys create <label> --a2a --to <workspace> --flows <flow,…>`");
|
|
4382
|
+
const flows = typeof flags.flows === "string" ? [...new Set(flags.flows.split(",").map((f) => f.trim()).filter(Boolean))] : [];
|
|
4383
|
+
if (!flows.length) throw new Error(`which flows may it call? --flows <flow,…> — \`foldrun a2a ls --to ${flags.to}\` lists what ${flags.to} publishes`);
|
|
4384
|
+
const body = { label, purpose: "a2a", workspace: flags.to, flows };
|
|
4385
|
+
if (flags["max-tasks"] !== undefined) {
|
|
4386
|
+
const n = Number(flags["max-tasks"]);
|
|
4387
|
+
if (!Number.isInteger(n) || n < 1 || n > 100) throw new Error("--max-tasks takes a whole number from 1 to 100 — how many tasks the key may have open at once (default 10)");
|
|
4388
|
+
body.maxTasks = n;
|
|
4389
|
+
}
|
|
4390
|
+
if (typeof flags.expires === "string") body.expires = flags.expires;
|
|
4391
|
+
const made = await remoteCall(url, flags, "/api/keys", { method: "POST", body: JSON.stringify(body) });
|
|
4392
|
+
console.log(
|
|
4393
|
+
`\n ${c.green("✓")} ${c.bold(label)} ${c.dim(made.id)} ${c.dim(`A2A · ${made.workspace ?? flags.to} · ${(made.flows ?? flows).join(", ")} · up to ${made.maxTasks ?? body.maxTasks ?? 10} open`)}${made.expiresAt ? c.dim(` expires ${made.expiresAt.slice(0, 10)}`) : ""}\n`,
|
|
4394
|
+
);
|
|
4395
|
+
if (made.key == null) return lostSecret(made.id);
|
|
4396
|
+
console.log(` ${made.key}\n`);
|
|
4397
|
+
console.log(` ${c.dim(`Shown once. The outside agent sends it as its bearer token; it opens /a2a only. Try it: ${A2A_KEY_ENV}=<key> foldrun a2a call <card-url> "…" — \`foldrun a2a ls --to ${flags.to}\` has the card URLs. \`foldrun keys revoke ${made.id}\` ends it.`)}\n`);
|
|
4398
|
+
return 0;
|
|
4399
|
+
}
|
|
4400
|
+
|
|
4366
4401
|
/** A retried mint or rotate is answered from the first call, and the server
|
|
4367
4402
|
* never stores a key's secret — so a retry after a lost answer has none. */
|
|
4368
4403
|
function lostSecret(id) {
|
|
@@ -6586,6 +6621,122 @@ function issueDoctor(issue) {
|
|
|
6586
6621
|
* `restore` take item ids. A key reads the inbox of the person who minted it.
|
|
6587
6622
|
* The dashboard's Inbox. Exit 1 when anything assigned to you is unread.
|
|
6588
6623
|
*/
|
|
6624
|
+
/**
|
|
6625
|
+
* `foldrun mcp` — this account as an MCP server over stdio, for an AI app
|
|
6626
|
+
* (Claude Code, Claude Desktop, Cursor, Codex): `claude mcp add foldrun --
|
|
6627
|
+
* foldrun mcp`. Each line on stdin is one JSON-RPC message, forwarded to the
|
|
6628
|
+
* platform's POST /api/mcp with this machine's sign-in; each answer is one
|
|
6629
|
+
* line on stdout. The tools live on the platform, so they are always the
|
|
6630
|
+
* platform's own — this end holds no list to go stale. stdout carries
|
|
6631
|
+
* nothing but protocol; every note goes to stderr.
|
|
6632
|
+
* @param {string[]} positional @param {Record<string, any>} flags
|
|
6633
|
+
*/
|
|
6634
|
+
async function mcpCmd(positional, flags) {
|
|
6635
|
+
if (positional.length) throw new Error("`foldrun mcp` takes no arguments — an AI app starts it: `claude mcp add foldrun -- foldrun mcp` (--read-only for the tools that read)");
|
|
6636
|
+
if (process.stdin.isTTY && flags.yes !== true) {
|
|
6637
|
+
console.error(`\n ${c.bold("foldrun mcp")} is an MCP server on stdin/stdout, for an AI app to start — not to type into.\n\n claude mcp add foldrun -- foldrun mcp${flags["read-only"] === true ? " --read-only" : ""}\n codex mcp add foldrun -- foldrun mcp\n\n ${c.dim("Claude Desktop, Cursor: { \"mcpServers\": { \"foldrun\": { \"command\": \"foldrun\", \"args\": [\"mcp\"] } } } — `foldrun docs mcp`")}\n`);
|
|
6638
|
+
return 2;
|
|
6639
|
+
}
|
|
6640
|
+
// The account this server acts as is the one it started as: pinned by
|
|
6641
|
+
// profile name, so `foldrun use <other>` in another terminal never moves a
|
|
6642
|
+
// running session to another account, or its key to another platform.
|
|
6643
|
+
const started = typeof flags.token === "string" || env("FOLDRUN_TOKEN") ? null : chosenProfile(flags);
|
|
6644
|
+
if (started?.name) flags = { ...flags, profile: started.name };
|
|
6645
|
+
const url = platformFor(flags, "mcp");
|
|
6646
|
+
await renewedToken(url, flags);
|
|
6647
|
+
/** An app keeps this process for days, and another command may renew the
|
|
6648
|
+
* sign-in meanwhile (the old key ends minutes later): the key is read
|
|
6649
|
+
* again for every message, and the renewal checked again twice a day. */
|
|
6650
|
+
let renewedAt = Date.now();
|
|
6651
|
+
const currentToken = async () => {
|
|
6652
|
+
if (Date.now() - renewedAt > 12 * 60 * 60 * 1000) {
|
|
6653
|
+
renewedAt = Date.now();
|
|
6654
|
+
renewChecked = false;
|
|
6655
|
+
await renewIfDue(url, flags);
|
|
6656
|
+
}
|
|
6657
|
+
return tokenFor(url, flags);
|
|
6658
|
+
};
|
|
6659
|
+
const apiPath = `/api/mcp${flags["read-only"] === true ? "?readonly=1" : ""}`;
|
|
6660
|
+
// Long tool calls (a run's whole record) get longer than a CLI read.
|
|
6661
|
+
const seconds = explicitTimeout(flags) ?? 120;
|
|
6662
|
+
/** The revision `initialize` settled on, sent on every later request. */
|
|
6663
|
+
let protocol = null;
|
|
6664
|
+
const send = (msg) => {
|
|
6665
|
+
process.stdout.write(`${JSON.stringify(msg)}\n`);
|
|
6666
|
+
};
|
|
6667
|
+
const fail = (id, code, message) => send({ jsonrpc: "2.0", id: id ?? null, error: { code, message } });
|
|
6668
|
+
|
|
6669
|
+
/** @param {string} line */
|
|
6670
|
+
const forward = async (line) => {
|
|
6671
|
+
let msg;
|
|
6672
|
+
try {
|
|
6673
|
+
msg = JSON.parse(line);
|
|
6674
|
+
} catch {
|
|
6675
|
+
return fail(null, -32700, "not JSON — one JSON-RPC message per line");
|
|
6676
|
+
}
|
|
6677
|
+
const id = msg && typeof msg === "object" && !Array.isArray(msg) ? msg.id : undefined;
|
|
6678
|
+
const isRequest = id !== undefined && typeof msg?.method === "string";
|
|
6679
|
+
let res;
|
|
6680
|
+
try {
|
|
6681
|
+
const token = await currentToken();
|
|
6682
|
+
res = await remoteFetch(url, apiPath, {
|
|
6683
|
+
method: "POST",
|
|
6684
|
+
headers: { "content-type": "application/json", accept: "application/json, text/event-stream", ...(protocol ? { "mcp-protocol-version": protocol } : {}) },
|
|
6685
|
+
body: line,
|
|
6686
|
+
}, { token, seconds });
|
|
6687
|
+
} catch (err) {
|
|
6688
|
+
console.error(`foldrun mcp: ${explain(err)}`);
|
|
6689
|
+
return isRequest ? fail(id, -32603, `foldrun could not reach ${new URL(url).host}: ${explain(err)}`) : undefined;
|
|
6690
|
+
}
|
|
6691
|
+
if (res.status === 202) return;
|
|
6692
|
+
let text;
|
|
6693
|
+
try {
|
|
6694
|
+
text = await res.text();
|
|
6695
|
+
} catch (err) {
|
|
6696
|
+
// The headers came and the body did not: a dropped connection, the clock.
|
|
6697
|
+
console.error(`foldrun mcp: ${explain(err)}`);
|
|
6698
|
+
return isRequest ? fail(id, -32603, `the answer from ${new URL(url).host} broke off: ${explain(err)}`) : undefined;
|
|
6699
|
+
}
|
|
6700
|
+
let body;
|
|
6701
|
+
try {
|
|
6702
|
+
body = JSON.parse(text);
|
|
6703
|
+
// JSON, but not the protocol: an /api error from a platform that has no
|
|
6704
|
+
// /api/mcp (`{ error: "…" }`), or a proxy's own JSON.
|
|
6705
|
+
if (body?.jsonrpc !== "2.0") throw new Error("not JSON-RPC");
|
|
6706
|
+
} catch {
|
|
6707
|
+
console.error(`foldrun mcp: ${apiPath} → HTTP ${res.status}: ${text.slice(0, 200)}`);
|
|
6708
|
+
if (!isRequest) return;
|
|
6709
|
+
return fail(id, -32603, res.status === 404 ? `${new URL(url).host} has no MCP endpoint — it runs a platform from before 1 Nov 2026` : `the platform's MCP endpoint answered HTTP ${res.status}, and not in MCP — is ${new URL(url).host} the right address?`);
|
|
6710
|
+
}
|
|
6711
|
+
// A refusal before the message was read (no key, a refused key) carries
|
|
6712
|
+
// no id; give it this request's, so the app knows which call failed.
|
|
6713
|
+
if (body && typeof body === "object" && body.id === null && isRequest) body.id = id;
|
|
6714
|
+
if (body?.error && (res.status === 401 || res.status === 403)) body.error.message += refusedHint(url, flags);
|
|
6715
|
+
if (msg?.method === "initialize" && typeof body?.result?.protocolVersion === "string") protocol = body.result.protocolVersion;
|
|
6716
|
+
if (!isRequest && !body?.error) return;
|
|
6717
|
+
send(body);
|
|
6718
|
+
};
|
|
6719
|
+
|
|
6720
|
+
const readline = await import("node:readline");
|
|
6721
|
+
const lines = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
|
|
6722
|
+
const inFlight = new Set();
|
|
6723
|
+
/** An initialize still on its way: what comes after it waits for the revision it settles. */
|
|
6724
|
+
let initializing = Promise.resolve();
|
|
6725
|
+
for await (const raw of lines) {
|
|
6726
|
+
const line = raw.trim();
|
|
6727
|
+
if (!line) continue;
|
|
6728
|
+
// Calls run side by side: a slow tools/call never holds up a ping. Each
|
|
6729
|
+
// answer carries its id, so the order they come back in does not matter.
|
|
6730
|
+
const before = initializing;
|
|
6731
|
+
const p = before.then(() => forward(line)).catch((err) => console.error(`foldrun mcp: ${explain(err)}`));
|
|
6732
|
+
if (/"method"\s*:\s*"initialize"/.test(line)) initializing = p;
|
|
6733
|
+
inFlight.add(p);
|
|
6734
|
+
p.finally(() => inFlight.delete(p));
|
|
6735
|
+
}
|
|
6736
|
+
await Promise.all(inFlight);
|
|
6737
|
+
return 0;
|
|
6738
|
+
}
|
|
6739
|
+
|
|
6589
6740
|
async function inboxCmd(positional, flags) {
|
|
6590
6741
|
const url = platformFor(flags, "inbox");
|
|
6591
6742
|
const [verb, ...ids] = positional;
|
|
@@ -12139,6 +12290,389 @@ function printPreview(p, rel) {
|
|
|
12139
12290
|
}
|
|
12140
12291
|
}
|
|
12141
12292
|
|
|
12293
|
+
// ------------------------------------------------------------------- a2a
|
|
12294
|
+
|
|
12295
|
+
/**
|
|
12296
|
+
* `foldrun a2a …` — A2A (Agent2Agent 1.0): outside agents calling this
|
|
12297
|
+
* account's published flows, and this terminal calling any A2A agent.
|
|
12298
|
+
*
|
|
12299
|
+
* a2a ls --to <ws> what the workspace serves: flows, cards, keys, recent tasks
|
|
12300
|
+
* a2a publish <flow> [--to <ws>] [--name --description --example … --public-card|--private-card]
|
|
12301
|
+
* a2a unpublish <flow> [--to <ws>] publish: false, the rest of a2a: kept
|
|
12302
|
+
* a2a card <flow> --to <ws> the card's URL, then the card
|
|
12303
|
+
* a2a call <card-url> "<text>" [--data <json|@file>] [--context <id>] [--no-wait] [--max-wait <s>]
|
|
12304
|
+
* a2a status <task-id> --card <url>
|
|
12305
|
+
* a2a cancel <task-id> --card <url> [--yes]
|
|
12306
|
+
*
|
|
12307
|
+
* Publishing is an edit of the flow's `a2a:` frontmatter — here, or with
|
|
12308
|
+
* --to on the platform through the flow route's PATCH { a2a } (an admin's:
|
|
12309
|
+
* the platform refuses an editor). The /a2a endpoints take an A2A key and nothing else:
|
|
12310
|
+
* call, status, cancel and a private card read it from $FOLDRUN_A2A_KEY
|
|
12311
|
+
* (or the variable --key-env names), never from the command line, and never
|
|
12312
|
+
* send this terminal's own API key to a card's address.
|
|
12313
|
+
*/
|
|
12314
|
+
const A2A_KEY_ENV = "FOLDRUN_A2A_KEY";
|
|
12315
|
+
// Core's A2A modules, named in variables: the installed core may predate
|
|
12316
|
+
// them, and a literal would fail the typecheck against it. Both are in
|
|
12317
|
+
// core's foldrun.publicApi (tests/cli-release.test.ts reads these strings).
|
|
12318
|
+
/** @type {string} */
|
|
12319
|
+
const A2A_CLIENT_MODULE = "@foldrun/core/a2a-client";
|
|
12320
|
+
/** @type {string} */
|
|
12321
|
+
const A2A_PUBLISH_MODULE = "@foldrun/core/a2a-publish";
|
|
12322
|
+
const A2A_POLL_MS = 2_000;
|
|
12323
|
+
const A2A_CARD_BYTES = 64 * 1024;
|
|
12324
|
+
|
|
12325
|
+
async function a2aCmd(positional, flags, layout) {
|
|
12326
|
+
const verb = positional[0];
|
|
12327
|
+
switch (verb) {
|
|
12328
|
+
case "ls":
|
|
12329
|
+
case "list":
|
|
12330
|
+
case undefined:
|
|
12331
|
+
return a2aLsCmd(flags, layout);
|
|
12332
|
+
case "publish":
|
|
12333
|
+
case "unpublish":
|
|
12334
|
+
return a2aPublishCmd(verb, positional[1], flags, layout);
|
|
12335
|
+
case "card":
|
|
12336
|
+
return a2aCardCmd(positional[1], flags, layout);
|
|
12337
|
+
case "call":
|
|
12338
|
+
return a2aCallCmd(positional[1], positional.slice(2).join(" "), flags);
|
|
12339
|
+
case "status":
|
|
12340
|
+
case "cancel":
|
|
12341
|
+
return a2aTaskCmd(verb, positional[1], flags);
|
|
12342
|
+
}
|
|
12343
|
+
throw new Error(`a2a: unknown verb "${verb}" — ls, publish, unpublish, card, call, status, cancel`);
|
|
12344
|
+
}
|
|
12345
|
+
|
|
12346
|
+
/** GET /api/workspaces/<ws>/a2a — what a workspace serves over A2A. */
|
|
12347
|
+
async function a2aView(flags, layout, what) {
|
|
12348
|
+
const url = platformFor(flags, what);
|
|
12349
|
+
const ws = platformWorkspace(flags, layout, what);
|
|
12350
|
+
return { url, ws, view: await remoteCall(url, flags, `/api/workspaces/${enc(ws)}/a2a`) };
|
|
12351
|
+
}
|
|
12352
|
+
|
|
12353
|
+
const a2aStateWord = (s) => printable(s).replace(/^TASK_STATE_/, "").toLowerCase().replace(/_/g, "-");
|
|
12354
|
+
const a2aStateMark = (s) =>
|
|
12355
|
+
s === "TASK_STATE_COMPLETED" ? c.green("✓") : s === "TASK_STATE_FAILED" || s === "TASK_STATE_REJECTED" ? c.red("✗") : s === "TASK_STATE_CANCELED" ? c.dim("■") : c.amber("…");
|
|
12356
|
+
|
|
12357
|
+
async function a2aLsCmd(flags, layout) {
|
|
12358
|
+
const { ws, view } = await a2aView(flags, layout, "a2a ls");
|
|
12359
|
+
if (flags.json === true) {
|
|
12360
|
+
console.log(JSON.stringify(view, null, 2));
|
|
12361
|
+
return 0;
|
|
12362
|
+
}
|
|
12363
|
+
const flows = view.flows ?? [];
|
|
12364
|
+
console.log(`\n ${c.bold(ws)} ${c.dim("· over A2A")}\n`);
|
|
12365
|
+
if (!flows.length) console.log(` ${c.dim(`no flow says a2a: — \`foldrun a2a publish <flow> --to ${ws}\` publishes one`)}`);
|
|
12366
|
+
for (const f of flows) {
|
|
12367
|
+
const state = f.published ? c.green("published".padEnd(13)) : c.dim("not published");
|
|
12368
|
+
const extra = [f.publicCard ? "public card" : "private card", f.hasInputSchema ? "input schema" : null].filter(Boolean).join(" · ");
|
|
12369
|
+
console.log(` ${state} ${c.bold(printable(f.flow))}${f.name && f.name !== f.flow ? ` ${printable(f.name)}` : ""} ${c.dim(extra)}`);
|
|
12370
|
+
if (f.published) {
|
|
12371
|
+
console.log(` ${" ".repeat(10)}${c.dim("card")} ${printable(f.card)}`);
|
|
12372
|
+
console.log(` ${" ".repeat(10)}${c.dim("url ")} ${printable(f.url)}`);
|
|
12373
|
+
}
|
|
12374
|
+
}
|
|
12375
|
+
if (Array.isArray(view.keys)) {
|
|
12376
|
+
console.log(`\n ${c.bold("A2A keys")}`);
|
|
12377
|
+
if (!view.keys.length) console.log(` ${c.dim(`none — \`foldrun keys create <label> --a2a --to ${ws} --flows <flow>\` mints one`)}`);
|
|
12378
|
+
for (const k of view.keys) {
|
|
12379
|
+
console.log(` ${printable(k.id)} ${printable(k.prefix)}… ${c.bold(printable(k.label) || "(no label)")} ${c.dim(printable(`${(k.flows ?? []).join(", ")}${k.maxTasks ? ` · up to ${k.maxTasks} open` : ""}${k.expiresAt ? ` · expires ${String(k.expiresAt).slice(0, 10)}` : ""}`))}`);
|
|
12380
|
+
}
|
|
12381
|
+
}
|
|
12382
|
+
const tasks = view.tasks ?? [];
|
|
12383
|
+
console.log(`\n ${c.bold("Recent tasks")}`);
|
|
12384
|
+
if (!tasks.length) console.log(` ${c.dim("none yet")}`);
|
|
12385
|
+
for (const t of tasks) {
|
|
12386
|
+
const who = t.key?.label || t.key?.prefix ? `A2A · ${t.key.label || `${t.key.prefix}…`}${t.key.revoked ? " (revoked)" : ""}` : "A2A · a key since removed";
|
|
12387
|
+
console.log(` ${a2aStateMark(t.state)} ${a2aStateWord(t.state).padEnd(14)} ${c.bold(printable(t.flow))} ${c.dim(printable(`${who} · ${when(t.updatedAt)}${t.runId ? ` · run ${t.runId}` : ""}`))}`);
|
|
12388
|
+
}
|
|
12389
|
+
console.log("");
|
|
12390
|
+
return 0;
|
|
12391
|
+
}
|
|
12392
|
+
|
|
12393
|
+
/** What a publish or unpublish changes in `a2a:` — the body of the flow
|
|
12394
|
+
* route's PATCH { a2a }, merged there over the flow's block (a key given
|
|
12395
|
+
* replaces it, a key given as null removes it). */
|
|
12396
|
+
export function a2aPatchFor(verb, flags) {
|
|
12397
|
+
if (verb !== "publish") return { publish: false };
|
|
12398
|
+
const patch = { publish: true };
|
|
12399
|
+
if (typeof flags.name === "string") patch.name = flags.name;
|
|
12400
|
+
if (typeof flags.description === "string") patch.description = flags.description;
|
|
12401
|
+
const examples = many(flags.example);
|
|
12402
|
+
if (examples.length) patch.examples = examples;
|
|
12403
|
+
if (flags["public-card"] === true && flags["private-card"] === true) throw new Error("--public-card or --private-card, not both");
|
|
12404
|
+
if (flags["public-card"] === true) patch.public_card = true;
|
|
12405
|
+
if (flags["private-card"] === true) patch.public_card = null;
|
|
12406
|
+
return patch;
|
|
12407
|
+
}
|
|
12408
|
+
|
|
12409
|
+
/** The `a2a:` the flow will say after `patch`, merged as the platform
|
|
12410
|
+
* merges it: its other keys kept, `publish` first. */
|
|
12411
|
+
export function a2aBlockFor(current, patch) {
|
|
12412
|
+
const base = current && typeof current === "object" && !Array.isArray(current) ? { ...current } : {};
|
|
12413
|
+
delete base.publish;
|
|
12414
|
+
const block = { publish: patch.publish, ...base };
|
|
12415
|
+
for (const [k, v] of Object.entries(patch)) {
|
|
12416
|
+
if (k === "publish") continue;
|
|
12417
|
+
if (v === null) delete block[k];
|
|
12418
|
+
else block[k] = v;
|
|
12419
|
+
}
|
|
12420
|
+
return block;
|
|
12421
|
+
}
|
|
12422
|
+
|
|
12423
|
+
async function a2aPublishCmd(verb, flow, flags, layout) {
|
|
12424
|
+
if (!flow) throw new Error(`which flow? \`foldrun a2a ${verb} <flow> --to <workspace>\``);
|
|
12425
|
+
// The block's own rules are core's (a2a-publish.ts): the same sentences
|
|
12426
|
+
// check and the platform say. A core without them would call a2a: an
|
|
12427
|
+
// unknown field and refuse the edit for a reason that is not one.
|
|
12428
|
+
const pub = /** @type {any} */ (await import(A2A_PUBLISH_MODULE).catch(() => null));
|
|
12429
|
+
if (!pub || typeof pub.a2aPublishProblems !== "function") {
|
|
12430
|
+
throw new Error(`\`foldrun a2a ${verb}\` needs an @foldrun/core that knows a2a: (@foldrun/core/a2a-publish) — this install's is older; update foldrun (npm i -g foldrun@latest)`);
|
|
12431
|
+
}
|
|
12432
|
+
const matter = (await import("gray-matter")).default;
|
|
12433
|
+
const { patchFrontmatter } = await import("@foldrun/core/agents-md");
|
|
12434
|
+
const patch = a2aPatchFor(verb, flags);
|
|
12435
|
+
const code = await flowEditCmd(flags, layout, {
|
|
12436
|
+
flow,
|
|
12437
|
+
what: `a2a ${verb}`,
|
|
12438
|
+
label: verb === "publish" ? "a2a: publish — outside agents with an A2A key naming it may call it" : "a2a: publish: false — no outside agent may call it",
|
|
12439
|
+
compute: (raw) => {
|
|
12440
|
+
let current;
|
|
12441
|
+
try {
|
|
12442
|
+
current = matter(raw, {}).data?.a2a;
|
|
12443
|
+
} catch {
|
|
12444
|
+
current = undefined;
|
|
12445
|
+
}
|
|
12446
|
+
// Nothing to take back from a flow that never said a2a:.
|
|
12447
|
+
if (verb === "unpublish" && (current === undefined || current === null)) return { next: raw, meta: null };
|
|
12448
|
+
const block = a2aBlockFor(current, patch);
|
|
12449
|
+
const problems = pub.a2aPublishProblems(block);
|
|
12450
|
+
if (problems.length) throw new Error(`a2a: ${problems.join("; ")}`);
|
|
12451
|
+
return { next: patchFrontmatter(raw, { a2a: block }), meta: null };
|
|
12452
|
+
},
|
|
12453
|
+
// The flow page's Publish over A2A control sends the same PATCH { a2a }
|
|
12454
|
+
// (an admin's: the platform refuses an editor with 403).
|
|
12455
|
+
bodies: (raw) => [{ body: { a2a: patch }, after: raw }],
|
|
12456
|
+
});
|
|
12457
|
+
if (code !== 0 || flags["dry-run"] === true) return code;
|
|
12458
|
+
if (!namesPlatform(flags)) {
|
|
12459
|
+
if (verb === "publish") console.log(` ${c.dim("Once deployed, an outside agent calls it with an A2A key: `foldrun keys create <label> --a2a --to <workspace> --flows " + flow + "`")}\n`);
|
|
12460
|
+
return 0;
|
|
12461
|
+
}
|
|
12462
|
+
if (verb === "unpublish") return 0;
|
|
12463
|
+
// Where it is served now, and how a caller gets in.
|
|
12464
|
+
const { ws, view } = await a2aView(flags, layout, `a2a ${verb}`).catch(() => ({ ws: flags.to, view: null }));
|
|
12465
|
+
const f = (view?.flows ?? []).find((x) => x.flow === flow);
|
|
12466
|
+
if (f?.published) {
|
|
12467
|
+
console.log(` ${c.dim("card")} ${printable(f.card)}`);
|
|
12468
|
+
console.log(` ${c.dim("url ")} ${printable(f.url)}\n`);
|
|
12469
|
+
}
|
|
12470
|
+
console.log(` ${c.dim(`A caller needs an A2A key that names it: \`foldrun keys create <label> --a2a --to ${ws} --flows ${flow}\``)}\n`);
|
|
12471
|
+
return 0;
|
|
12472
|
+
}
|
|
12473
|
+
|
|
12474
|
+
/** The A2A key this terminal sends to an /a2a address: from $FOLDRUN_A2A_KEY
|
|
12475
|
+
* or the variable --key-env names — never this CLI's own API key. */
|
|
12476
|
+
function a2aKey(flags) {
|
|
12477
|
+
const named = typeof flags["key-env"] === "string";
|
|
12478
|
+
const name = named ? flags["key-env"] : A2A_KEY_ENV;
|
|
12479
|
+
if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`--key-env takes the NAME of an environment variable that holds the A2A key — got "${name}"`);
|
|
12480
|
+
const token = process.env[name]?.trim() || undefined;
|
|
12481
|
+
if (named && !token) throw new Error(`--key-env ${name}: $${name} is not set — export the A2A key in it (a key is never read from the command line)`);
|
|
12482
|
+
return { name, token };
|
|
12483
|
+
}
|
|
12484
|
+
|
|
12485
|
+
/** A card address, checked: http(s), no user:password in it. */
|
|
12486
|
+
function a2aCardUrl(value, what) {
|
|
12487
|
+
if (typeof value !== "string" || !value) throw new Error(`which agent? \`foldrun a2a ${what}\` takes the agent card's URL (…/.well-known/agent-card.json)`);
|
|
12488
|
+
let u;
|
|
12489
|
+
try {
|
|
12490
|
+
u = new URL(value);
|
|
12491
|
+
} catch {
|
|
12492
|
+
throw new Error(`"${value}" is not a URL — \`foldrun a2a ${what}\` takes the agent card's address (…/.well-known/agent-card.json)`);
|
|
12493
|
+
}
|
|
12494
|
+
if (u.protocol !== "https:" && u.protocol !== "http:") throw new Error(`${u.protocol} is not a web address — an A2A card is at https://…`);
|
|
12495
|
+
if (u.username || u.password) throw new Error("the card URL holds a user name or password — the key goes in $FOLDRUN_A2A_KEY, never in a URL");
|
|
12496
|
+
return u;
|
|
12497
|
+
}
|
|
12498
|
+
|
|
12499
|
+
const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
|
|
12500
|
+
|
|
12501
|
+
/** Core's A2A client, or a clear refusal from an older core. */
|
|
12502
|
+
async function a2aClient(what) {
|
|
12503
|
+
const m = /** @type {any} */ (await import(A2A_CLIENT_MODULE).catch(() => null));
|
|
12504
|
+
if (!m || ["fetchCard", "sendMessage", "getTask", "cancelTask", "replyText"].some((f) => typeof m[f] !== "function")) {
|
|
12505
|
+
throw new Error(`\`foldrun a2a ${what}\` needs an @foldrun/core with the A2A client (@foldrun/core/a2a-client) — this install's is older; update foldrun (npm i -g foldrun@latest)`);
|
|
12506
|
+
}
|
|
12507
|
+
return m;
|
|
12508
|
+
}
|
|
12509
|
+
|
|
12510
|
+
/** The connection core's client takes, for one card. */
|
|
12511
|
+
function a2aConnection(u, flags) {
|
|
12512
|
+
const key = a2aKey(flags);
|
|
12513
|
+
if (key.token && u.protocol === "http:" && !LOOPBACK.has(u.hostname)) {
|
|
12514
|
+
console.error(` ${c.amber("!")} ${c.dim(`sending the A2A key to ${u.host} over plain http — anyone on the way can read it`)}`);
|
|
12515
|
+
}
|
|
12516
|
+
return { key, conn: { remote: u.host, card: u.href, origin: u.origin, ...(key.token ? { token: key.token } : {}), timeoutMs: timeoutSeconds(flags) * 1000 } };
|
|
12517
|
+
}
|
|
12518
|
+
|
|
12519
|
+
/** An A2A refusal, said with what to do about it here. */
|
|
12520
|
+
function a2aExplain(err, key) {
|
|
12521
|
+
// The remote's own words can be in the message: printed, so made safe.
|
|
12522
|
+
const msg = printable(err instanceof Error ? err.message : String(err));
|
|
12523
|
+
if (/refused the credential/.test(msg)) {
|
|
12524
|
+
return new Error(key.token ? `${msg} — is $${key.name} an A2A key for this flow? (POST /api/keys { purpose: "a2a" } mints one; an API key never opens /a2a)` : `${msg.replace(/ — this remote has no secret: set one$/, "")} — no A2A key was sent: export it in $${key.name} (or name the variable with --key-env)`);
|
|
12525
|
+
}
|
|
12526
|
+
return new Error(msg);
|
|
12527
|
+
}
|
|
12528
|
+
|
|
12529
|
+
/**
|
|
12530
|
+
* The exit code a task means, whatever the output format: 0 for a task
|
|
12531
|
+
* that completed or is still open (call, status), 1 for one that failed,
|
|
12532
|
+
* was rejected or canceled — and for cancel, 0 only when the agent says
|
|
12533
|
+
* the task IS canceled now.
|
|
12534
|
+
*/
|
|
12535
|
+
export function a2aExitCode(verb, task, terminal) {
|
|
12536
|
+
const state = task?.status?.state;
|
|
12537
|
+
if (verb === "cancel") return state === "TASK_STATE_CANCELED" ? 0 : 1;
|
|
12538
|
+
return state === "TASK_STATE_COMPLETED" || !terminal?.has?.(state) ? 0 : 1;
|
|
12539
|
+
}
|
|
12540
|
+
|
|
12541
|
+
/** An outside agent's text, indented, made safe to print: it cannot move the
|
|
12542
|
+
* cursor, retitle the terminal or write the clipboard (printable). */
|
|
12543
|
+
const a2aIndented = (text) => printable(text).split("\n").map((l) => ` ${l}`).join("\n");
|
|
12544
|
+
|
|
12545
|
+
function a2aPrintTask(task, A, cardUrl) {
|
|
12546
|
+
const state = task.status?.state;
|
|
12547
|
+
const id = printable(task.id);
|
|
12548
|
+
console.log(`\n ${a2aStateMark(state)} ${c.bold(a2aStateWord(state))} ${c.dim(`task ${id}${task.contextId ? ` · context ${printable(task.contextId)}` : ""}`)}`);
|
|
12549
|
+
const text = A.replyText({ task });
|
|
12550
|
+
if (text) console.log(`\n${a2aIndented(text)}`);
|
|
12551
|
+
if (!A.TERMINAL_STATES?.has?.(state)) {
|
|
12552
|
+
console.log(`\n ${c.dim(`still open — \`foldrun a2a status ${id} --card ${cardUrl}\` asks again, \`foldrun a2a cancel ${id} --card ${cardUrl}\` stops it`)}`);
|
|
12553
|
+
}
|
|
12554
|
+
console.log("");
|
|
12555
|
+
return a2aExitCode("status", task, A.TERMINAL_STATES);
|
|
12556
|
+
}
|
|
12557
|
+
|
|
12558
|
+
/** --data: one JSON value, inline or @file — the request's data part. */
|
|
12559
|
+
function a2aData(value) {
|
|
12560
|
+
if (value === undefined) return undefined;
|
|
12561
|
+
if (value === true) throw new Error("--data needs a value — JSON, or @file");
|
|
12562
|
+
const text = String(value).startsWith("@") ? fs.readFileSync(path.resolve(String(value).slice(1)), "utf8") : String(value);
|
|
12563
|
+
try {
|
|
12564
|
+
return JSON.parse(text);
|
|
12565
|
+
} catch (err) {
|
|
12566
|
+
throw new Error(`--data is not JSON (${err instanceof Error ? err.message : err}) — it is sent as the message's data part`);
|
|
12567
|
+
}
|
|
12568
|
+
}
|
|
12569
|
+
|
|
12570
|
+
async function a2aCallCmd(cardArg, text, flags) {
|
|
12571
|
+
const u = a2aCardUrl(cardArg, "call <card-url> \"<text>\"");
|
|
12572
|
+
if (!text.trim()) throw new Error("what should it do? `foldrun a2a call <card-url> \"<text>\"` — the text is the message");
|
|
12573
|
+
const data = a2aData(flags.data);
|
|
12574
|
+
const A = await a2aClient("call");
|
|
12575
|
+
const { key, conn } = a2aConnection(u, flags);
|
|
12576
|
+
const maxWait = flags["max-wait"] === undefined ? 300 : Number(flags["max-wait"]);
|
|
12577
|
+
if (!Number.isFinite(maxWait) || maxWait < 0) throw new Error("--max-wait takes seconds, 0 or more");
|
|
12578
|
+
const wait = flags["no-wait"] !== true && flags["return-immediately"] !== true && maxWait > 0;
|
|
12579
|
+
let task;
|
|
12580
|
+
try {
|
|
12581
|
+
const endpoint = await A.fetchCard(conn);
|
|
12582
|
+
const sent = await A.sendMessage(conn, endpoint, {
|
|
12583
|
+
messageId: crypto.randomUUID(),
|
|
12584
|
+
text,
|
|
12585
|
+
...(data !== undefined ? { data } : {}),
|
|
12586
|
+
...(typeof flags.context === "string" ? { contextId: flags.context } : {}),
|
|
12587
|
+
});
|
|
12588
|
+
if (sent.message) {
|
|
12589
|
+
if (flags.json === true) console.log(JSON.stringify(sent, null, 2));
|
|
12590
|
+
else console.log(`\n${a2aIndented(A.replyText(sent))}\n`);
|
|
12591
|
+
return 0;
|
|
12592
|
+
}
|
|
12593
|
+
task = sent.task;
|
|
12594
|
+
// The id is printed before any waiting, so an interrupted wait still
|
|
12595
|
+
// leaves the task in hand.
|
|
12596
|
+
if (wait && flags.json !== true) console.error(` ${c.dim(`task ${printable(task.id)} — waiting up to ${maxWait}s for it to end (Ctrl-C leaves it running)`)}`);
|
|
12597
|
+
const until = Date.now() + maxWait * 1000;
|
|
12598
|
+
while (wait && !A.TERMINAL_STATES.has(task.status.state) && !A.INTERRUPTED_STATES?.has?.(task.status.state) && Date.now() < until) {
|
|
12599
|
+
await new Promise((r) => setTimeout(r, Math.min(A2A_POLL_MS, Math.max(0, until - Date.now()))));
|
|
12600
|
+
task = await A.getTask(conn, endpoint, task.id);
|
|
12601
|
+
}
|
|
12602
|
+
} catch (err) {
|
|
12603
|
+
throw a2aExplain(err, key);
|
|
12604
|
+
}
|
|
12605
|
+
if (flags.json === true) console.log(JSON.stringify(task, null, 2));
|
|
12606
|
+
else a2aPrintTask(task, A, u.href);
|
|
12607
|
+
return a2aExitCode("call", task, A.TERMINAL_STATES);
|
|
12608
|
+
}
|
|
12609
|
+
|
|
12610
|
+
async function a2aTaskCmd(verb, taskId, flags) {
|
|
12611
|
+
if (!taskId) throw new Error(`which task? \`foldrun a2a ${verb} <task-id> --card <url>\` — \`foldrun a2a call\` prints the id`);
|
|
12612
|
+
const u = a2aCardUrl(flags.card, `${verb} <task-id> --card <url>`);
|
|
12613
|
+
const A = await a2aClient(verb);
|
|
12614
|
+
const { key, conn } = a2aConnection(u, flags);
|
|
12615
|
+
if (verb === "cancel" && !(await confirmed(flags, "a2a cancel", `Cancel task ${taskId} at ${u.host} (its run is stopped)? [y/N] `))) {
|
|
12616
|
+
console.log(`\n ${c.dim("nothing cancelled")}\n`);
|
|
12617
|
+
return 1;
|
|
12618
|
+
}
|
|
12619
|
+
let task;
|
|
12620
|
+
try {
|
|
12621
|
+
const endpoint = await A.fetchCard(conn);
|
|
12622
|
+
task = verb === "cancel" ? await A.cancelTask(conn, endpoint, taskId) : await A.getTask(conn, endpoint, taskId);
|
|
12623
|
+
} catch (err) {
|
|
12624
|
+
throw a2aExplain(err, key);
|
|
12625
|
+
}
|
|
12626
|
+
// JSON or words, the same exit code: a script reading --json must still
|
|
12627
|
+
// see a failed task, or a cancel the agent did not carry out, as a failure.
|
|
12628
|
+
if (flags.json === true) console.log(JSON.stringify(task, null, 2));
|
|
12629
|
+
else a2aPrintTask(task, A, u.href);
|
|
12630
|
+
return a2aExitCode(verb, task, A.TERMINAL_STATES);
|
|
12631
|
+
}
|
|
12632
|
+
|
|
12633
|
+
async function a2aCardCmd(flow, flags, layout) {
|
|
12634
|
+
if (!flow) throw new Error("which flow? `foldrun a2a card <flow> --to <workspace>`");
|
|
12635
|
+
const { ws, view } = await a2aView(flags, layout, "a2a card");
|
|
12636
|
+
const f = (view.flows ?? []).find((x) => x.flow === flow);
|
|
12637
|
+
if (!f) throw new Error(`${flow} in ${ws} says no a2a: — \`foldrun a2a publish ${flow} --to ${ws}\` publishes it`);
|
|
12638
|
+
if (!f.published) throw new Error(`${flow} in ${ws} is not published (a2a: publish: false) — it has no card; \`foldrun a2a publish ${flow} --to ${ws}\``);
|
|
12639
|
+
console.log(`\n ${c.dim("card")} ${printable(f.card)}`);
|
|
12640
|
+
console.log(` ${c.dim("url ")} ${printable(f.url)}\n`);
|
|
12641
|
+
const u = new URL(f.card);
|
|
12642
|
+
const key = a2aKey(flags);
|
|
12643
|
+
if (!f.publicCard && !key.token) {
|
|
12644
|
+
console.log(` ${c.dim(`a private card — reading it takes an A2A key that names ${flow}: export it in $${key.name} (or --key-env NAME), or make it public with \`foldrun a2a publish ${flow} --to ${ws} --public-card\``)}\n`);
|
|
12645
|
+
return 0;
|
|
12646
|
+
}
|
|
12647
|
+
// Only the A2A key goes to the card's address — never this terminal's API key.
|
|
12648
|
+
const res = await fetch(u, {
|
|
12649
|
+
headers: { accept: "application/json", "A2A-Version": "1.0", ...(key.token && !f.publicCard ? { authorization: `Bearer ${key.token}` } : {}) },
|
|
12650
|
+
redirect: "manual",
|
|
12651
|
+
signal: AbortSignal.timeout(timeoutSeconds(flags) * 1000),
|
|
12652
|
+
});
|
|
12653
|
+
const body = await res.text();
|
|
12654
|
+
if (res.status !== 200) {
|
|
12655
|
+
const said = (() => {
|
|
12656
|
+
try {
|
|
12657
|
+
return JSON.parse(body)?.error?.message;
|
|
12658
|
+
} catch {
|
|
12659
|
+
return null;
|
|
12660
|
+
}
|
|
12661
|
+
})();
|
|
12662
|
+
throw new Error(`the card answered HTTP ${res.status}${said ? `: ${printable(said)}` : ""}${res.status === 401 || res.status === 403 ? ` — is $${key.name} an A2A key that names ${flow}?` : ""}`);
|
|
12663
|
+
}
|
|
12664
|
+
if (Buffer.byteLength(body, "utf8") > A2A_CARD_BYTES) throw new Error(`the card is over ${A2A_CARD_BYTES / 1024} KiB — not printed`);
|
|
12665
|
+
let card;
|
|
12666
|
+
try {
|
|
12667
|
+
card = JSON.parse(body);
|
|
12668
|
+
} catch {
|
|
12669
|
+
throw new Error("the card's address did not answer JSON");
|
|
12670
|
+
}
|
|
12671
|
+
console.log(JSON.stringify(card, null, 2).split("\n").map((l) => ` ${l}`).join("\n"));
|
|
12672
|
+
console.log("");
|
|
12673
|
+
return 0;
|
|
12674
|
+
}
|
|
12675
|
+
|
|
12142
12676
|
export async function run(command, positional, flags, workspace, layout) {
|
|
12143
12677
|
// Nothing outside the CLI's own entry point passes a layout — the tests
|
|
12144
12678
|
// that call run() directly, an embedder. A lone workspace is the safe
|
|
@@ -12164,6 +12698,8 @@ export async function run(command, positional, flags, workspace, layout) {
|
|
|
12164
12698
|
return apiCmd(positional, flags);
|
|
12165
12699
|
case "keys":
|
|
12166
12700
|
return keysCmd(positional, flags);
|
|
12701
|
+
case "a2a":
|
|
12702
|
+
return a2aCmd(positional, flags, layout);
|
|
12167
12703
|
case "audit":
|
|
12168
12704
|
return auditCmd(positional, flags);
|
|
12169
12705
|
case "accounts":
|
|
@@ -12307,6 +12843,8 @@ export async function run(command, positional, flags, workspace, layout) {
|
|
|
12307
12843
|
return issuesCmd(positional, flags, layout);
|
|
12308
12844
|
case "inbox":
|
|
12309
12845
|
return inboxCmd(positional, flags);
|
|
12846
|
+
case "mcp":
|
|
12847
|
+
return mcpCmd(positional, flags);
|
|
12310
12848
|
case "insights":
|
|
12311
12849
|
return insightsCmd(flags);
|
|
12312
12850
|
case "approve":
|
package/src/guide.mjs
CHANGED
|
@@ -30,7 +30,7 @@ export function agentRulesBlock() {
|
|
|
30
30
|
|
|
31
31
|
# Read foldrun's docs before you edit this folder
|
|
32
32
|
|
|
33
|
-
This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls; it is also the security scanner (a key written into a file, hidden text, an agent that can leak), and \`foldrun check --security\` fails on what it finds. Never paste a credential into a file: \`foldrun secrets set NAME\` and write \`\${NAME}\`. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). An agent with \`tools: [peers]\` can message the steps running beside it in its parallel group (\`peers_message\`) and ask for what they have instead of guessing or failing (\`foldrun docs agents\`). A sub-agent that reads untrusted content (web pages, mail, uploads) gets \`sandbox: own\` in its own file: each job then runs in a sandbox of its own with its own tools, secrets and network, and only its reply and the files it wrote reach the agent that delegated (\`foldrun agent link <agent> --subagent <worker> --isolated\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value. What a step's sandbox may use is \`size:\` (\`small\` 1 core/1Gi, \`large\`, \`heavy\` 4 cores/8Gi — hard limits and the billed figures); \`resources: {cpu, memory, disk}\` sets the numbers yourself, key by key over the class (\`foldrun docs agents\`). What steps may hold together is capped at four levels, each only narrowing the one above: the account's and a workspace's \`compute: {vcpu, memory, disk}\` in AGENTS.md, a flow's \`compute:\` for each of its runs, and the plan's most for one step; a step past a cap waits its turn, one bigger than a whole cap fails (\`foldrun usage compute\`, \`foldrun docs budgets-and-billing\`). A webhook, email, chained or storage flow says which deliveries start it with \`filter:\` (\`foldrun flow filter <flow> --payload body.json\` tries one); an eval with \`trigger: runs\` grades a \`sample:\` of real finished runs instead of running cases, \`foldrun eval compare\` runs an eval's cases under several models side by side, and \`improve: true\` turns repeated failures into a proposed fix a person applies (\`foldrun docs evals\`).
|
|
33
|
+
This is a foldrun account: agents, flows, tools and knowledge as markdown, run by foldrun. Its formats — frontmatter fields, step options, \`verify:\` prefixes, which folder a file goes in — are foldrun's own and may differ from your training data. Before you write or change an agent, flow, tool or skill, read the relevant guide: \`foldrun docs\` lists them and \`foldrun docs <page>\` prints one (start with \`foldrun docs coding-agents\`). They ship with the CLI, so they match the version you are driving. Check every edit with \`foldrun check\` — offline, no model calls; it is also the security scanner (a key written into a file, hidden text, an agent that can leak), and \`foldrun check --security\` fails on what it finds. Never paste a credential into a file: \`foldrun secrets set NAME\` and write \`\${NAME}\`. For a flow's shape, \`foldrun flow show <flow>\` draws it, and \`foldrun flow add\`, \`foldrun flow rm-step\`, \`foldrun flow dup-step\` and \`foldrun agent link\` make the same edits as the dashboard canvas (patterns, sub-agents, consults, \`ask\`). An agent with \`tools: [peers]\` can message the steps running beside it in its parallel group (\`peers_message\`) and ask for what they have instead of guessing or failing (\`foldrun docs agents\`). A sub-agent that reads untrusted content (web pages, mail, uploads) gets \`sandbox: own\` in its own file: each job then runs in a sandbox of its own with its own tools, secrets and network, and only its reply and the files it wrote reach the agent that delegated (\`foldrun agent link <agent> --subagent <worker> --isolated\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. A hook (\`hooks/<name>/hook.md\` + \`run.mjs\`, turned on with \`hooks: [name]\`) is code at every tool call, step start and step end — \`foldrun hook add\`/\`test\` and \`foldrun docs hooks\`. Paths to the workspace's own folders are written \`workspace/storage/…\` and \`workspace/state/…\` — in an agent's prose, a flow's options and a script's arguments — not \`../../\`, which still works but is the older spelling. Which sites a step's sandbox may reach is \`network:\` — open for an agent that may fetch or browse the web, the trusted list plus what it declares for every other; add a site with \`foldrun agent network <agent> --add <site>\` (\`foldrun docs network\`). Bind a secret to the sites it is for (\`foldrun secrets sites NAME <site>\`) and no sandbox ever holds its value. What a step's sandbox may use is \`size:\` (\`small\` 1 core/1Gi, \`large\`, \`heavy\` 4 cores/8Gi — hard limits and the billed figures); \`resources: {cpu, memory, disk}\` sets the numbers yourself, key by key over the class (\`foldrun docs agents\`). What steps may hold together is capped at four levels, each only narrowing the one above: the account's and a workspace's \`compute: {vcpu, memory, disk}\` in AGENTS.md, a flow's \`compute:\` for each of its runs, and the plan's most for one step; a step past a cap waits its turn, one bigger than a whole cap fails (\`foldrun usage compute\`, \`foldrun docs budgets-and-billing\`). A webhook, email, chained or storage flow says which deliveries start it with \`filter:\` (\`foldrun flow filter <flow> --payload body.json\` tries one); an eval with \`trigger: runs\` grades a \`sample:\` of real finished runs instead of running cases, \`foldrun eval compare\` runs an eval's cases under several models side by side, and \`improve: true\` turns repeated failures into a proposed fix a person applies (\`foldrun docs evals\`). A flow is served to outside agents over A2A 1.0 when its frontmatter says \`a2a: { publish: true }\` (an admin's change; callers need an A2A key naming the flow — \`foldrun a2a publish\`, \`foldrun keys create --a2a\`), and an agent calls outside A2A agents listed in \`remotes: [{name, card, secret?}]\` with the \`a2a_send\`/\`a2a_status\` tools — never send a request twice to retry, poll its handle (\`foldrun docs a2a\`).
|
|
34
34
|
|
|
35
35
|
This block is for coding tools. It is written and re-added by the foldrun CLI, and the runtime strips it, so the agents that run here never see it; the rest of this file is the account's own context, which they do read. Committing the block with your work keeps the tree clean.
|
|
36
36
|
|