foldrun 20.7.1 → 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 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,7 +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.
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.
252
266
 
253
267
  ### content/injection-phrase
254
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
- **One gap.** The platform has no endpoint that reads or writes an account's own
371
- `AGENTS.md` — `/api/account` patches a handful of known frontmatter keys and
372
- nothing serves the file. So `deploy` does not push it and `pull` does not fetch
373
- it; both say so rather than dropping the scope in silence. Edit it in Settings,
374
- or on the installation itself. The shared `library/` has a full per-file API
375
- and is pushed and pulled normally.
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "20.7.1",
3
+ "version": "20.8.0",
4
4
  "description": "Agents are just folders. Write them, check them, run them — on your machine.",
5
5
  "license": "FSL-1.1-ALv2",
6
6
  "type": "module",
@@ -11,7 +11,7 @@
11
11
  "node": ">=22"
12
12
  },
13
13
  "dependencies": {
14
- "@foldrun/core": "^18.3.0"
14
+ "@foldrun/core": "^18.3.1"
15
15
  },
16
16
  "files": [
17
17
  "bin",
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 has no write endpoint.
5356
- *
5357
- * `/api/account` reads and PATCHes a handful of known frontmatter keys — a
5358
- * timezone, a notify target, a cap — and nothing reads or writes the file
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
- "the platform has no account-file endpoint — /api/account only PATCHes known frontmatter keys, so AGENTS.md at account scope is not synced. Edit it in Settings, or on the box.";
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
- console.log(` ${c.amber("·")} AGENTS.md ${c.dim(`not sent — ${NO_ACCOUNT_FILE_API}`)}`);
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
- console.log(`\n ${c.dim(NO_ACCOUNT_FILE_API)}\n`);
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
- return fs.readFileSync(f.file, "utf8") !== f.content;
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)}\n`);
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();