foldrun 20.7.2 → 20.8.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/docs/api.md +1 -0
- package/docs/checks.md +15 -6
- package/docs/cli.md +9 -6
- package/package.json +1 -1
- package/src/commands.mjs +87 -15
- package/src/guide.mjs +9 -0
package/docs/api.md
CHANGED
|
@@ -396,6 +396,7 @@ Reads return which secrets exist, never their values.
|
|
|
396
396
|
| `/api/account/flags` | GET | the feature flags as they stand for this account — `{ flags: [{ name, description, owner, default, on, source, rollout }] }`, `source` being what decided it: `account` (an override for this account), `global` (the install-wide setting), `rollout` (a percentage of accounts, by a stable hash of account and flag; `rollout` is the percentage) or `default`. Read-only, every role; only the platform's operator changes a flag (a self-hosted install runs every flag at its default). See [Feature flags](feature-flags.md) |
|
|
397
397
|
| `/api/openapi.json` | GET | this API as an OpenAPI 3.1 document — every route and method, bearer auth, the rate-limit, version and Idempotency-Key headers, and request/response schemas for runs, flow runs, deploy, source, secrets, keys and billing. No key needed. Generated from the route files by `scripts/gen-openapi.mjs`; the dashboard renders it at Docs → API reference, `foldrun api spec` saves it |
|
|
398
398
|
| `/api/account` | GET, PATCH | the account's defaults from its AGENTS.md frontmatter — `timezone`, `budget` (a USD cap — a number for a month, `"60/day"`, `"60/week"`, or `{ usd, period }`; null is no limit), `notify` (`{ url?, email?, events }`), `concurrency`, `compute` (`{ vcpu, memGiB, diskGiB }` — the account's own cap on what its running steps hold together, lower than the plan's; PATCH writes it as `compute: { vcpu, memory, disk }`, merged over what is set: a figure not sent is kept, `null` drops one, `compute: null` drops all), `deploy_block` (`none`, `secrets` or `security` — answered as `deployBlock`), `network_enforce` (answered as `networkEnforce`), `owner`, `alerts` (as written), `judge` (`{ model?, effort? }`), `telemetry` (`{ otlp, headers }` — header values are `${SECRET}` names; answered as `{ endpoint, headers }`); PATCH sets the keys sent, null clears one, and edits the file in place. To a caller scoped to some workspaces GET says these are set, never where they go: `notify` loses its `url` and carries `hidden: true` when one is set, and `telemetry` is `{ endpoint: "", headers: {}, hidden: true }`. PATCH needs every workspace |
|
|
399
|
+
| `/api/account/agents-md` | GET, PUT | the account's own `AGENTS.md`, whole — the shared context and defaults every agent in every workspace reads, above its workspace's AGENTS.md. GET answers `{ content, sha256, exists }`. PUT `{ content, ifMatch?, message? }` writes it whole and answers `{ ok, sha256, issues }` (`unchanged: true` when it already said that). Checked as a deploy checks AGENTS.md: a problem a deploy would refuse is `422` with the `issues` and nothing written; warnings come back with the write. `ifMatch` — the `sha256` a GET answered, or `null` for "there was no file" — makes it a `409` if the file changed since. At most 256 KB. Account-wide callers only, both ways (a member or key scoped to some workspaces is `403`: the file can name notify and telemetry targets for every workspace); PUT needs `workspace:manage` (an admin). `foldrun deploy` at an account root sends it and `foldrun pull` fetches it; Settings → Policies → AGENTS.md edits it. Audited as `account.agents_md_set`. Idempotent |
|
|
399
400
|
| `/api/audit?since&until&action&actor&workspace&limit&cursor&format` | GET | the account's audit log, newest first — the caller's account only, whatever a header, query or body names. The owner and unscoped admins (people, or `admin` keys); `audit:read`, and refused to a member or key scoped to some workspaces, because the log is the whole account's. `since`/`until`: `7d`, `24h`, `30m` or a date; `action`: exact (`apikey.created`) or a family (`apikey`); `actor`: exact (an email, `key:<label>`, `support:<email>`); `workspace`: entries about one; `limit` 1–1000 (100; 1000 for CSV); `cursor`: the `next` of the page before. JSON `{ entries: [{ id, at, actor, action, subject, detail }], next, retention }`; `format=csv` downloads the same rows (`x-next-cursor` header when there are more). Records sign-ins and refusals, sign-outs, session revokes, password and email changes, MFA on/off, key mint/rotate/revoke, invites, joins, role/scope changes, removals, ownership transfers, secrets set/deleted (by name — never a value), deploys, workspace deletes, plan and billing changes, export and close requests, and `support.viewed`/`support.ended`. The platform operator's own levers (`operator.*`) are the platform's record and not listed. Kept 365 days (`audit.retention_days`; an install without a database keeps its file-backed log), and no longer than the account |
|
|
400
401
|
| `/api/avatars/<kind>/<id>` | GET, PUT, DELETE | a picture for a `user` (their own id), a `workspace` (its name) or the `account` (the tenant). PUT the bytes of a PNG, JPEG or WebP under 1 MB; a person sets their own, an admin a workspace's or the account's. GET needs a signed-in tenant — a workspace's picture, a caller who may open that workspace (403 otherwise) — and is privately cached for a year — the URL's `?v=` changes with the picture |
|
|
401
402
|
| `/api/search?q=` | GET | find anything in the account by name — workspaces, agents, flows, tools, skills, knowledge, memory, runs (by id, flow or headline); ranked, at most six per kind. The dashboard's Find palette reads it |
|
package/docs/checks.md
CHANGED
|
@@ -248,12 +248,21 @@ or Unicode tag characters: invisible to a person reading the file, read as
|
|
|
248
248
|
text by the model, and the standard way to hide an instruction from a
|
|
249
249
|
reviewer. Tag characters are decoded in the message so you can read what
|
|
250
250
|
they say. Delete them. A byte-order mark at the very start of a file is
|
|
251
|
-
allowed, and so is
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
251
|
+
allowed, and so is what is spelling:
|
|
252
|
+
|
|
253
|
+
- a zero-width non-joiner or joiner (U+200C, U+200D) with a letter of a
|
|
254
|
+
script written with them on one side and a letter on the other — the
|
|
255
|
+
Persian half-space in «میشود» and after a Latin word («channelها»),
|
|
256
|
+
Arabic-script, Syriac, Indic and other Brahmic words — or a ZWJ inside an
|
|
257
|
+
emoji sequence;
|
|
258
|
+
- a bidi mark (LRM U+200E, RLM U+200F, ALM U+061C) on a line of
|
|
259
|
+
right-to-left text, as used to keep a Latin file name or code in order
|
|
260
|
+
inside Persian or Arabic — marks move nothing, unlike overrides.
|
|
261
|
+
|
|
262
|
+
Still flagged: a joiner between Latin letters, before a space or alone; a
|
|
263
|
+
mark on a line with no right-to-left text, or splitting a Latin word; and
|
|
264
|
+
every zero-width space, bidi override or isolate (U+202A–202E,
|
|
265
|
+
U+2066–2069) and tag character, whatever the script.
|
|
257
266
|
|
|
258
267
|
### content/injection-phrase
|
|
259
268
|
|
package/docs/cli.md
CHANGED
|
@@ -367,12 +367,15 @@ foldrun runs blog-desk
|
|
|
367
367
|
foldrun deploy blog-desk
|
|
368
368
|
```
|
|
369
369
|
|
|
370
|
-
**
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
it;
|
|
374
|
-
|
|
375
|
-
|
|
370
|
+
**The account's own AGENTS.md** — the shared context every agent in every
|
|
371
|
+
workspace reads — goes up with the account: `deploy` at an account root sends
|
|
372
|
+
it when it differs (`PUT /api/account/agents-md`, checked as a deploy checks
|
|
373
|
+
it; an admin of every workspace may send it — anyone else is told and the
|
|
374
|
+
rest of the deploy goes on), and `pull` fetches it (refusing to overwrite a
|
|
375
|
+
local edit without `--force`, as for every file). The coding-agent block the
|
|
376
|
+
CLI keeps in that file is never compared or read by a running agent. It is
|
|
377
|
+
also edited in Settings → Policies → AGENTS.md. The shared `library/` has a
|
|
378
|
+
full per-file API and is pushed and pulled normally.
|
|
376
379
|
|
|
377
380
|
## Signing in
|
|
378
381
|
|
package/package.json
CHANGED
package/src/commands.mjs
CHANGED
|
@@ -9,7 +9,7 @@ import net from "node:net";
|
|
|
9
9
|
import os from "node:os";
|
|
10
10
|
import path from "node:path";
|
|
11
11
|
import { fileURLToPath } from "node:url";
|
|
12
|
-
import { writeAgentFiles, hasCurrentAgentRules, agentRulesBlock, codingAgent, docsDir, docPages, docPage } from "./guide.mjs";
|
|
12
|
+
import { writeAgentFiles, hasCurrentAgentRules, agentRulesBlock, codingAgent, docsDir, docPages, docPage, withAgentRules } from "./guide.mjs";
|
|
13
13
|
import { createRequire } from "node:module";
|
|
14
14
|
import { execFileSync, spawnSync } from "node:child_process";
|
|
15
15
|
import { defaultPlatform, saveCredential, removeCredential, normaliseUrl, profileByName, currentProfile, useProfile, listProfiles, credentialsDir } from "./credentials.mjs";
|
|
@@ -5352,16 +5352,71 @@ async function remoteWorkspaceNames(url, flags) {
|
|
|
5352
5352
|
}
|
|
5353
5353
|
|
|
5354
5354
|
/**
|
|
5355
|
-
* The account AGENTS.md
|
|
5356
|
-
*
|
|
5357
|
-
*
|
|
5358
|
-
*
|
|
5359
|
-
* itself. So a deploy cannot ship the account's prose, and a pull cannot
|
|
5360
|
-
* fetch it. Said out loud, once, rather than silently dropped: a scope that
|
|
5361
|
-
* vanishes without a word is the failure this codebase keeps producing.
|
|
5355
|
+
* The account's own AGENTS.md — the shared context and defaults every agent
|
|
5356
|
+
* in every workspace reads — through GET/PUT /api/account/agents-md (11 Nov
|
|
5357
|
+
* 2026; cloudhost's CI copied it into every workspace for want of it). A
|
|
5358
|
+
* platform older than that answers 404: said once, as the old gap was.
|
|
5362
5359
|
*/
|
|
5363
5360
|
const NO_ACCOUNT_FILE_API =
|
|
5364
|
-
"
|
|
5361
|
+
"this platform has no /api/account/agents-md yet, so the account's AGENTS.md is not synced — edit it in Settings, or update the platform.";
|
|
5362
|
+
|
|
5363
|
+
/** The managed coding-agent block (guide.mjs) is the CLI's, never a running
|
|
5364
|
+
* agent's (core withoutAgentRules): two copies that differ only there are the same. */
|
|
5365
|
+
function sameAccountMd(a, b) {
|
|
5366
|
+
// Both as the CLI would leave them: exactly the change writeAgentFiles makes
|
|
5367
|
+
// (its block, the gap after the frontmatter), and no other byte ignored —
|
|
5368
|
+
// blank lines and line endings elsewhere are still a change (Codex review).
|
|
5369
|
+
return withAgentRules(String(a ?? "")) === withAgentRules(String(b ?? ""));
|
|
5370
|
+
}
|
|
5371
|
+
|
|
5372
|
+
/** { content, sha256, exists } on the platform; null on a platform without the
|
|
5373
|
+
* route (404); { refused } when this caller may not read it (403). */
|
|
5374
|
+
async function remoteAccountAgentsMd(url, flags) {
|
|
5375
|
+
try {
|
|
5376
|
+
return await remoteCall(url, flags, "/api/account/agents-md");
|
|
5377
|
+
} catch (err) {
|
|
5378
|
+
if (err instanceof HttpError && err.status === 404) return null;
|
|
5379
|
+
if (err instanceof HttpError && err.status === 403) return { refused: err.message };
|
|
5380
|
+
throw err;
|
|
5381
|
+
}
|
|
5382
|
+
}
|
|
5383
|
+
|
|
5384
|
+
/** Push the account AGENTS.md when it differs. 0 when sent, unchanged or not
|
|
5385
|
+
* this caller's to send (said); 1 when the platform refused the file. */
|
|
5386
|
+
async function deployAccountAgentsMd(url, flags, content, dry) {
|
|
5387
|
+
const there = await remoteAccountAgentsMd(url, flags);
|
|
5388
|
+
if (there === null) {
|
|
5389
|
+
console.log(` ${c.amber("·")} AGENTS.md ${c.dim(`not sent — ${NO_ACCOUNT_FILE_API}`)}`);
|
|
5390
|
+
return 0;
|
|
5391
|
+
}
|
|
5392
|
+
if (there.refused) {
|
|
5393
|
+
console.log(` ${c.amber("·")} AGENTS.md ${c.dim("not sent — the account's AGENTS.md is every workspace's; an admin of every workspace sends it")}`);
|
|
5394
|
+
return 0;
|
|
5395
|
+
}
|
|
5396
|
+
if (sameAccountMd(there.content, content)) {
|
|
5397
|
+
console.log(` ${c.green("✓")} AGENTS.md ${c.dim("(account) unchanged")}`);
|
|
5398
|
+
return 0;
|
|
5399
|
+
}
|
|
5400
|
+
if (dry) {
|
|
5401
|
+
console.log(` ${c.dim("~")} AGENTS.md ${c.dim("(account) would be updated")}`);
|
|
5402
|
+
return 0;
|
|
5403
|
+
}
|
|
5404
|
+
try {
|
|
5405
|
+
const done = await remoteCall(url, flags, "/api/account/agents-md", { method: "PUT", body: JSON.stringify({ content, ifMatch: there.exists ? there.sha256 : null, message: "foldrun deploy" }) });
|
|
5406
|
+
const warns = (done.issues ?? []).filter((i) => i.level !== "error").length;
|
|
5407
|
+
console.log(` ${c.green("✓")} AGENTS.md ${c.dim(`(account) sent — every workspace reads it${warns ? ` · ${warns} warning${warns === 1 ? "" : "s"}` : ""}`)}`);
|
|
5408
|
+
return 0;
|
|
5409
|
+
} catch (err) {
|
|
5410
|
+
if (!(err instanceof HttpError)) throw err;
|
|
5411
|
+
if (err.status === 403) {
|
|
5412
|
+
console.log(` ${c.amber("·")} AGENTS.md ${c.dim("not sent — the account's AGENTS.md is every workspace's; an admin of every workspace sends it")}`);
|
|
5413
|
+
return 0;
|
|
5414
|
+
}
|
|
5415
|
+
console.log(` ${c.red("✗")} AGENTS.md ${c.dim(`(account) not sent — ${err.message}`)}`);
|
|
5416
|
+
for (const i of (err.body?.issues ?? []).filter((x) => x.level === "error").slice(0, 10)) console.log(` ${c.red("·")} ${i.file}${i.line ? `:${i.line}` : ""} ${i.message}`);
|
|
5417
|
+
return 1;
|
|
5418
|
+
}
|
|
5419
|
+
}
|
|
5365
5420
|
|
|
5366
5421
|
/**
|
|
5367
5422
|
* `foldrun deploy` — the whole account, or one workspace of it.
|
|
@@ -5416,7 +5471,7 @@ async function deployAccount(layout, flags, only) {
|
|
|
5416
5471
|
|
|
5417
5472
|
if (tree.agentsMd !== null) {
|
|
5418
5473
|
if (url) {
|
|
5419
|
-
|
|
5474
|
+
worst = Math.max(worst, await deployAccountAgentsMd(url, flags, tree.agentsMd, dry));
|
|
5420
5475
|
} else if (!dry) {
|
|
5421
5476
|
const { accountDir } = await core();
|
|
5422
5477
|
fs.mkdirSync(accountDir(tenant), { recursive: true });
|
|
@@ -5832,7 +5887,13 @@ async function statusCmd(layout, flags, only) {
|
|
|
5832
5887
|
if (gone.length) {
|
|
5833
5888
|
console.log(`\n ${c.dim(`on the platform but not here: ${gone.join(", ")} — \`foldrun pull\` brings them down`)}`);
|
|
5834
5889
|
}
|
|
5835
|
-
|
|
5890
|
+
if (tree.agentsMd !== null) {
|
|
5891
|
+
const there = await remoteAccountAgentsMd(url, flags);
|
|
5892
|
+
if (there === null) console.log(`\n ${c.dim(NO_ACCOUNT_FILE_API)}`);
|
|
5893
|
+
else if (there.refused) console.log(`\n ${c.dim("AGENTS.md (account): not readable with this key — an admin of every workspace sees it")}`);
|
|
5894
|
+
else console.log(`\n ${sameAccountMd(there.content, tree.agentsMd) ? `${c.green("✓")} AGENTS.md ${c.dim("(account) the same here and there")}` : `${c.dim("~")} AGENTS.md ${c.dim("(account) differs — `foldrun deploy` sends it")}`}`);
|
|
5895
|
+
}
|
|
5896
|
+
console.log();
|
|
5836
5897
|
return 0;
|
|
5837
5898
|
}
|
|
5838
5899
|
|
|
@@ -5857,7 +5918,7 @@ async function pullCmd(layout, flags, only) {
|
|
|
5857
5918
|
const names = (await remoteWorkspaceNames(url, flags)).filter((n) => (only ? n === only : true));
|
|
5858
5919
|
if (only && !names.length) throw new Error(`no workspace "${only}" on ${url}`);
|
|
5859
5920
|
|
|
5860
|
-
/** @type {{file: string, content: string}[]} */
|
|
5921
|
+
/** @type {{ file: string, content: string, same?: (before: string) => boolean }[]} */
|
|
5861
5922
|
const incoming = [];
|
|
5862
5923
|
for (const name of names) {
|
|
5863
5924
|
if (!SAFE_NAME.test(name)) throw new Error(`the platform named a workspace "${name}", which is not a workspace name — refusing to write it`);
|
|
@@ -5869,9 +5930,18 @@ async function pullCmd(layout, flags, only) {
|
|
|
5869
5930
|
incoming.push({ file: within(path.join(root, "library", f.kind), f.path), content: f.content });
|
|
5870
5931
|
}
|
|
5871
5932
|
|
|
5933
|
+
// The account's own AGENTS.md, when the platform serves it and this
|
|
5934
|
+
// caller may read it. Compared without the CLI's managed block, which
|
|
5935
|
+
// writeAgentFiles puts back below.
|
|
5936
|
+
const accountMd = await remoteAccountAgentsMd(url, flags);
|
|
5937
|
+
if (accountMd && !accountMd.refused && accountMd.exists) {
|
|
5938
|
+
incoming.push({ file: path.join(root, "AGENTS.md"), content: accountMd.content, same: (before) => sameAccountMd(before, accountMd.content) });
|
|
5939
|
+
}
|
|
5940
|
+
|
|
5872
5941
|
const clashes = incoming.filter((f) => {
|
|
5873
5942
|
try {
|
|
5874
|
-
|
|
5943
|
+
const before = fs.readFileSync(f.file, "utf8");
|
|
5944
|
+
return f.same ? !f.same(before) : before !== f.content;
|
|
5875
5945
|
} catch {
|
|
5876
5946
|
return false; // absent: nothing to clobber
|
|
5877
5947
|
}
|
|
@@ -5893,7 +5963,7 @@ async function pullCmd(layout, flags, only) {
|
|
|
5893
5963
|
} catch {
|
|
5894
5964
|
/* new */
|
|
5895
5965
|
}
|
|
5896
|
-
if (before === f.content) continue;
|
|
5966
|
+
if (before === f.content || (before !== null && f.same?.(before))) continue;
|
|
5897
5967
|
fs.mkdirSync(path.dirname(f.file), { recursive: true });
|
|
5898
5968
|
fs.writeFileSync(f.file, f.content);
|
|
5899
5969
|
written++;
|
|
@@ -5907,7 +5977,9 @@ async function pullCmd(layout, flags, only) {
|
|
|
5907
5977
|
for (const [file, what] of [["AGENTS.md", rules.agentsMd], ["CLAUDE.md", rules.claudeMd]]) {
|
|
5908
5978
|
if (what === "created" || what === "updated") console.log(` ${c.green("✓")} ${file} ${c.dim(`${what} — the coding-agent rules, pointing at \`foldrun docs\``)}`);
|
|
5909
5979
|
}
|
|
5910
|
-
console.log(` ${c.dim(NO_ACCOUNT_FILE_API)}
|
|
5980
|
+
if (accountMd === null) console.log(` ${c.dim(NO_ACCOUNT_FILE_API)}`);
|
|
5981
|
+
else if (accountMd.refused) console.log(` ${c.dim("AGENTS.md (account): not pulled — an admin of every workspace reads it")}`);
|
|
5982
|
+
console.log();
|
|
5911
5983
|
return 0;
|
|
5912
5984
|
}
|
|
5913
5985
|
|
package/src/guide.mjs
CHANGED
|
@@ -69,6 +69,15 @@ function upsert(text, block) {
|
|
|
69
69
|
return `${b}${nl}${text ? `${nl}${text}` : ""}`;
|
|
70
70
|
}
|
|
71
71
|
|
|
72
|
+
/** What writeAgentFiles writes to an AGENTS.md holding `text`: the current
|
|
73
|
+
* block put in (or replaced), the gap after the frontmatter tidied, a final
|
|
74
|
+
* newline. Two files that read the same through this are the same to a
|
|
75
|
+
* person and to a running agent (core withoutAgentRules). */
|
|
76
|
+
export function withAgentRules(text) {
|
|
77
|
+
const next = upsert(text ?? "", agentRulesBlock());
|
|
78
|
+
return next.endsWith("\n") ? next : `${next}\n`;
|
|
79
|
+
}
|
|
80
|
+
|
|
72
81
|
/** True when AGENTS.md (or CLAUDE.md) at `root` already carries the current block. */
|
|
73
82
|
export function hasCurrentAgentRules(root) {
|
|
74
83
|
const want = agentRulesBlock();
|