foldrun 0.9.0 → 1.0.0

package/src/guide.mjs

@@ -30,7 +30,7 @@ export function agentRulesBlock() {
 
 # Read foldrun's docs before you edit this folder
 
-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. 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\`). A script tool's own \`secrets: [NAMES]\` are granted with the tool; list on an agent only the secrets it uses directly. 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.
+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. 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\`). 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.
 
 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.
 

package/src/terminal.mjs

@@ -0,0 +1,85 @@
+// What reaches a person's terminal.
+//
+// The CLI prints what a platform sends — run replies, logs, file contents,
+// release notes, error messages — and a terminal obeys escape sequences in
+// it: move the cursor and overwrite a line, clear the screen, retitle the
+// window, write the clipboard (OSC 52), turn text into a link that goes
+// somewhere else (OSC 8). A hostile or broken platform, or an agent's reply
+// on a compromised one, could do any of that to the person running the CLI.
+//
+// So everything written to stdout and stderr passes through terminalSafe():
+// the only escape sequences let through are the colours this CLI paints
+// itself (bold, dim, red, green, yellow, reset), and every other control
+// character goes, except newline and tab. Covering the streams rather than
+// each print means a new command cannot forget — and a pipe is covered too,
+// because `foldrun logs | cat` still ends on a screen.
+//
+// The one exception is content a person asked for byte for byte: `source
+// cat`, `storage cat`, a download to stdout, a CSV. Those go through
+// writeExact(), untouched into a pipe or a file (`foldrun source cat x > x`
+// stays exact) and still filtered when they land on a terminal. `--json` needs
+// no exception: JSON.stringify writes control characters as \u escapes.
+
+/** The SGR parameters paint() in commands.mjs uses. Nothing else is needed:
+ *  conceal (8) or reverse (7) from a platform could hide or fake text. */
+const OUR_SGR = new Set(["", "0", "1", "2", "31", "32", "33"]);
+
+// ESC [ … final byte (CSI); ESC ] … BEL or ESC \ (OSC); ESC P / ^ / _ … ESC \
+// (DCS, PM, APC); ESC and one more character (everything else); a lone ESC.
+const ESCAPES = /\u001b\[([0-?]*)[ -/]*([@-~])|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)?|\u001b[P^_][^\u001b]*(?:\u001b\\)?|\u001b[ -~]?/g;
+// C0 except tab and newline, DEL, and C1 (U+0080–U+009F: 0x9B is a one-byte CSI).
+const CONTROLS = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/;
+// One pass, escape sequences first, so a kept colour is not then stripped
+// of its ESC as a control character.
+const UNSAFE = new RegExp(`${ESCAPES.source}|${CONTROLS.source}`, "g");
+
+/** @typedef {NodeJS.WriteStream & { __foldrunGuarded?: boolean, __foldrunRawWrite?: (chunk: string | Uint8Array) => boolean }} Guardable */
+
+/** Text made safe for a terminal: this CLI's colours kept, every other
+ *  escape sequence and control character removed. `\r\n` becomes `\n`. */
+export function terminalSafe(text) {
+  return String(text)
+    .replace(/\r\n/g, "\n")
+    .replace(UNSAFE, (seq, params, final) => {
+      if (final === "m" && seq.startsWith("\u001b[") && String(params).split(";").every((p) => OUR_SGR.has(p))) return seq;
+      return "";
+    });
+}
+
+/**
+ * Put terminalSafe() in front of a stream's write. Returns whether it did
+ * (false the second time). A Buffer is decoded as UTF-8 first: bytes meant
+ * for a file have no business on a screen as they are.
+ * @param {Guardable} stream
+ */
+export function guardStream(stream) {
+  if (!stream || stream.__foldrunGuarded) return false;
+  const write = stream.write.bind(stream);
+  stream.__foldrunRawWrite = write;
+  /** @param {string | Uint8Array} chunk @param {unknown} [encoding] @param {(err?: Error | null) => void} [cb] */
+  const guarded = (chunk, encoding, cb) => {
+    const done = typeof encoding === "function" ? /** @type {(err?: Error | null) => void} */ (encoding) : cb;
+    const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+    return write(terminalSafe(text), done);
+  };
+  stream.write = /** @type {typeof stream.write} */ (guarded);
+  stream.__foldrunGuarded = true;
+  return true;
+}
+
+/** Guard stdout and stderr. Once, at start-up. */
+export function guardTerminal() {
+  guardStream(process.stdout);
+  guardStream(process.stderr);
+}
+
+/**
+ * Content a person asked for exactly — a file, a download, a CSV: byte for
+ * byte into a pipe or a file, filtered like everything else on a terminal.
+ * @param {string | Uint8Array} chunk
+ * @param {Guardable} [stream]
+ */
+export function writeExact(chunk, stream = process.stdout) {
+  if (stream.isTTY || !stream.__foldrunRawWrite) return stream.write(chunk);
+  return stream.__foldrunRawWrite(chunk);
+}