@factiii/runner 0.12.2 → 0.13.1

package/dist/cli.js

@@ -12928,7 +12928,8 @@ function hostSpacePaths(spaceDir) {
     state: import_path.default.join(spaceDir, "state"),
     backups: import_path.default.join(spaceDir, "backups"),
     builds: import_path.default.join(spaceDir, "builds"),
-    bin: import_path.default.join(spaceDir, "bin")
+    bin: import_path.default.join(spaceDir, "bin"),
+    scratchpad: import_path.default.join(spaceDir, "scratchpad")
   };
 }
 function worktreeFor(paths, workName) {
@@ -13885,6 +13886,7 @@ function hostTarget(spaceDir, extraEnv) {
       const env = {};
       const ports = readSpacePorts(spaceDir);
       if (ports.length) env.FACTIII_PORTS = ports.join(",");
+      env.SCRATCHPAD = paths.scratchpad;
       return { ...env, ...extraEnv?.() };
     },
     agentEnv() {
@@ -14145,6 +14147,9 @@ function createEventSink(send, spaceSlug, notify) {
     emitBareFsChange(postId, change) {
       send(channel(`bare-fs:${postId}`), change);
     },
+    emitScratchpad(payload) {
+      send(channel("scratchpad"), payload);
+    },
     emitActivityUpdate(activity) {
       send(channel("activity-update"), activity);
     }
@@ -17680,6 +17685,8 @@ var NOISE_GLOBS = ["**/.DS_Store", "**/4913", "**/*~", "**/.#*", "**/#*#"];
 var MAX_BATCH = 200;
 var FLUSH_MS = 120;
 var SELF_WRITE_MS = 2e3;
+var RETRY_MIN_MS = 500;
+var RETRY_MAX_MS = 15e3;
 var dynamicImport = new Function("s", "return import(s)");
 var importFs = new Function("s", "return import(s)");
 async function resolveReal(path23) {
@@ -17710,13 +17717,16 @@ var WorkspaceWatcher = class {
    *                 A no-git card's root is the space dir itself, which also
    *                 holds the runner's own bookkeeping.
    */
-  constructor(root, emit, exclude = []) {
+  constructor(root, emit, exclude = [], subscribeImpl) {
     this.root = root;
     this.emit = emit;
     this.exclude = exclude;
+    this.subscribeImpl = subscribeImpl;
     this.sub = null;
     this.pending = emptyPending();
     this.flushTimer = null;
+    this.retryTimer = null;
+    this.retryDelay = RETRY_MIN_MS;
     /** path -> expiry. Events for these are ours (the editor just saved) and must
      *  not come back as "changed on disk". */
     this.selfWrites = /* @__PURE__ */ new Map();
@@ -17726,11 +17736,11 @@ var WorkspaceWatcher = class {
   /** Fire-and-forget: callers treat starting a watch as synchronous, and
    *  nothing can be emitted before `subscribe` resolves anyway. */
   start() {
-    if (this.sub || this.closed) return;
+    if (this.sub || this.closed || this.retryTimer) return;
     void this.open();
   }
   async open() {
-    const subscribe = await getSubscribe();
+    const subscribe = this.subscribeImpl ?? await getSubscribe();
     if (!subscribe) return this.stop();
     this.watchRoot = await resolveReal(this.root);
     const exclude = await Promise.all(this.exclude.map(resolveReal));
@@ -17738,7 +17748,7 @@ var WorkspaceWatcher = class {
       const sub = await subscribe(
         this.watchRoot,
         (err, events) => {
-          if (err) return this.stop();
+          if (err) return this.retry();
           for (const event of events) this.onEvent(event);
         },
         // Prunes the walk itself, so a pruned tree is never enumerated.
@@ -17755,10 +17765,39 @@ var WorkspaceWatcher = class {
         return;
       }
       this.sub = sub;
+      this.retryDelay = RETRY_MIN_MS;
     } catch {
-      this.stop();
+      this.retry();
     }
   }
+  /**
+   * Re-subscribe after the OS dropped the watch — a remount, a wake from
+   * sleep, an inotify limit easing. Treating those as terminal left a runner
+   * watching nothing for the rest of its life. `resync` on the way back up,
+   * since whatever changed while it was down produced no events.
+   */
+  retry() {
+    if (this.closed || this.retryTimer) return;
+    const sub = this.sub;
+    this.sub = null;
+    if (sub) void sub.unsubscribe().catch(() => void 0);
+    const delay = this.retryDelay;
+    this.retryDelay = Math.min(this.retryDelay * 2, RETRY_MAX_MS);
+    this.retryTimer = setTimeout(() => {
+      this.retryTimer = null;
+      if (this.closed) return;
+      void this.open().then(() => {
+        if (this.sub) {
+          this.emit({
+            added: [],
+            changed: [],
+            removed: [],
+            resync: true
+          });
+        }
+      });
+    }, delay);
+  }
   /** Give up and say so once, so the UI falls back to manual refresh rather
    *  than showing a silently frozen tree. */
   stop() {
@@ -17794,6 +17833,10 @@ var WorkspaceWatcher = class {
       this.flushTimer = null;
     }
     this.pending = emptyPending();
+    if (this.retryTimer) {
+      clearTimeout(this.retryTimer);
+      this.retryTimer = null;
+    }
     this.selfWrites.clear();
     const sub = this.sub;
     this.sub = null;
@@ -18013,6 +18056,7 @@ var TerminalModeEngine = class {
       paths.worktrees,
       paths.repo,
       paths.workspace,
+      paths.scratchpad,
       `${paths.root}/drops`
     ];
     const watcher = new WorkspaceWatcher(
@@ -19854,6 +19898,204 @@ async function getDriveRoot(accessToken) {
   };
 }
 
+// ../../shared/all/helpers/scratchpad.ts
+var SCRATCHPAD_MAX_BYTES = 12e6;
+var SCRATCHPAD_MAX_ITEMS = 200;
+var SCRATCHPAD_CHUNK_BYTES = 512 * 1024;
+var SCRATCHPAD_MAX_DOWNLOAD_BYTES = 512 * 1024 * 1024;
+var KIND_BY_EXT = {
+  png: "image",
+  jpg: "image",
+  jpeg: "image",
+  gif: "image",
+  webp: "image",
+  avif: "image",
+  bmp: "image",
+  svg: "image",
+  mp4: "video",
+  webm: "video",
+  mov: "video",
+  m4v: "video",
+  mp3: "audio",
+  wav: "audio",
+  m4a: "audio",
+  ogg: "audio",
+  aac: "audio",
+  flac: "audio",
+  pdf: "pdf",
+  html: "html",
+  htm: "html",
+  md: "markdown",
+  markdown: "markdown",
+  url: "link"
+};
+function scratchpadExt(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0 || dot === name.length - 1) return "";
+  return name.slice(dot + 1).toLowerCase();
+}
+function scratchpadKind(name) {
+  return KIND_BY_EXT[scratchpadExt(name)] ?? "text";
+}
+function isSafeScratchpadName(name) {
+  if (!name || name.length > 255) return false;
+  if (name.startsWith(".")) return false;
+  return /^[A-Za-z0-9][A-Za-z0-9._ -]*$/.test(name);
+}
+
+// ../../shared/all/helpers/board-agent-core/scratchpad-store.ts
+function shEscape2(s) {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+var STAT_META = `stat -f '%m %z' "$f" 2>/dev/null || stat -c '%Y %s' "$f" 2>/dev/null`;
+var TOO_LARGE = "Scratchpad item is too large to open here.";
+var ScratchpadStore = class {
+  /**
+   * @param target Resolved per call, never held: the space's exec target is
+   *               rebuilt as the space provisions, and a captured one would go
+   *               on pointing at the tree it was built for.
+   * @param emit   Tells connected clients the directory moved. Carries a
+   *               timestamp only: the panel refetches the whole listing.
+   */
+  constructor(target, emit) {
+    this.target = target;
+    this.emit = emit;
+    this.watcher = null;
+  }
+  dir() {
+    return this.target().paths.scratchpad;
+  }
+  /**
+   * Everything on the scratchpad, newest first.
+   *
+   * Dotfiles are skipped: the panel is a display surface, and `.DS_Store` is
+   * not something anyone drew. So are subdirectories: the scratchpad is flat,
+   * which is what lets a name be an id everywhere else in this file.
+   */
+  async list() {
+    const dir = this.dir();
+    const out = await this.target().run([
+      "sh",
+      "-c",
+      `mkdir -p ${shEscape2(dir)} && cd ${shEscape2(dir)} && for f in *; do
+          [ -f "$f" ] || continue
+          meta=$(${STAT_META}) || continue
+          echo "$meta $f"
+        done | LC_ALL=C sort -rn | head -n ${SCRATCHPAD_MAX_ITEMS}`
+    ]);
+    this.startWatching();
+    const items = [];
+    for (const line of out.split("\n")) {
+      const match = /^(\d+) (\d+) (.+)$/.exec(line);
+      if (!match) continue;
+      const [, mtime, size, name] = match;
+      if (!isSafeScratchpadName(name)) continue;
+      const bytes = Number(size);
+      items.push({
+        name,
+        kind: scratchpadKind(name),
+        size: bytes,
+        // stat reports seconds; every other timestamp on the wire is ms.
+        modifiedAt: Number(mtime) * 1e3,
+        tooLarge: bytes > SCRATCHPAD_MAX_BYTES
+      });
+    }
+    return items;
+  }
+  /**
+   * One item's bytes, base64. Capped: past SCRATCHPAD_MAX_BYTES the panel is
+   * told to show the path instead, so a 4GB screen recording cannot pin the
+   * data channel for minutes.
+   *
+   * One shell, not a size check and then a read: the panel opens every card at
+   * once, so a second spawn per item is a doubled cost on the whole listing -
+   * and a file that changed between the two calls would have been read past
+   * the cap anyway.
+   */
+  async read(name) {
+    const file = shEscape2(this.resolve(name));
+    const content = await this.target().sh(
+      // Unquoted `$(wc -c)` on purpose: BSD wc pads its count with spaces,
+      // which `[ -gt ]` will not parse. `base64 -w 0` is GNU-only (BSD
+      // spells it -b), so unwrap with tr rather than asking it not to wrap.
+      `[ -f ${file} ] || exit 1
+         if [ $(wc -c < ${file}) -gt ${SCRATCHPAD_MAX_BYTES} ]; then
+           echo '${TOO_LARGE}' >&2; exit 1
+         fi
+         base64 < ${file} | tr -d '
+'`
+    ).catch((err) => {
+      const text = err instanceof Error ? err.message : "";
+      throw new Error(
+        text.includes(TOO_LARGE) ? TOO_LARGE : "Could not read that item."
+      );
+    });
+    return { content: content.trim(), encoding: "base64" };
+  }
+  /**
+   * One byte range of an item, base64. What a download is built out of.
+   *
+   * No size cap here, unlike `read`: the cap exists because a preview holds
+   * the whole file in one message, and a range does not. `tail | head` rather
+   * than `dd`, which needs a GNU-only flag to promise a full block over a pipe.
+   */
+  async readChunk(name, offset, length) {
+    if (!Number.isInteger(offset) || offset < 0) {
+      throw new Error("Invalid scratchpad offset.");
+    }
+    if (!Number.isInteger(length) || length <= 0 || length > SCRATCHPAD_CHUNK_BYTES) {
+      throw new Error("Invalid scratchpad chunk length.");
+    }
+    const file = shEscape2(this.resolve(name));
+    const content = await this.target().sh(
+      // `tail -c +N` counts from 1, so the first byte is offset 0 plus one.
+      `[ -f ${file} ] || exit 1
+         tail -c +${offset + 1} ${file} | head -c ${length} | base64 | tr -d '
+'`
+    ).catch(() => {
+      throw new Error("Could not read that item.");
+    });
+    return { content: content.trim(), encoding: "base64" };
+  }
+  async remove(name) {
+    await this.target().run(["rm", "-f", "--", this.resolve(name)]);
+  }
+  /** Files only, and only at the top level: whatever put a directory in there
+   *  is not something this panel drew, and `rm -rf` on an agent-writable path
+   *  is a worse tool than this job needs. */
+  async clear() {
+    const dir = shEscape2(this.dir());
+    await this.target().run([
+      "sh",
+      "-c",
+      `mkdir -p ${dir} && cd ${dir} && find . -maxdepth 1 -type f -delete`
+    ]);
+  }
+  destroy() {
+    const watcher = this.watcher;
+    this.watcher = null;
+    if (watcher) void watcher.close();
+  }
+  /** Idempotent: every panel that opens calls `list`, and they must not stack
+   *  watchers on one directory. */
+  startWatching() {
+    if (this.watcher) return;
+    const watcher = new WorkspaceWatcher(this.dir(), () => {
+      this.emit({ at: Date.now() });
+    });
+    this.watcher = watcher;
+    watcher.start();
+  }
+  /** Absolute path for a name the agent chose. Flat by construction: the name
+   *  is validated, never joined with anything a caller supplied. */
+  resolve(name) {
+    if (!isSafeScratchpadName(name)) {
+      throw new Error("Invalid scratchpad item name.");
+    }
+    return `${this.dir()}/${name}`;
+  }
+};
+
 // ../../shared/all/helpers/board-agent-core/space-core.ts
 var import_promises10 = require("fs/promises");
 var import_path14 = __toESM(require("path"));
@@ -20369,7 +20611,7 @@ var SpaceCore = class {
         status("Preparing workspace\u2026");
         const { paths } = target;
         await target.sh(
-          `mkdir -p ${paths.root} ${paths.worktrees} ${paths.state} ${paths.backups} ${paths.builds} ${paths.bin}`
+          `mkdir -p ${paths.root} ${paths.worktrees} ${paths.state} ${paths.backups} ${paths.builds} ${paths.bin} ${paths.scratchpad}`
         );
         await allocateSpacePorts(this.spaceDir());
         await this.ensureSecretsBridge().catch(() => void 0);
@@ -20712,6 +20954,10 @@ var BoardAgentEngine = class _BoardAgentEngine {
     this.emitter = options.emitter;
     this.claude = new ClaudeModeEngine(this.core, this.emitter);
     this.terminal = new TerminalModeEngine(this.core, this.emitter);
+    this.scratchpad = new ScratchpadStore(
+      () => this.core.target(),
+      (payload) => this.emitter.emitScratchpad(payload)
+    );
     this.gate.subscribe(() => this.projectGateOntoRun());
   }
   /** Everything the runner does for this space that isn't a card session, so
@@ -21688,6 +21934,22 @@ var BoardAgentEngine = class _BoardAgentEngine {
   bareListExposed(p) {
     return this.terminal.bareListExposed(p);
   }
+  // ── Scratchpad (→ the space's display surface) ──
+  scratchpadList() {
+    return this.scratchpad.list();
+  }
+  scratchpadRead(p) {
+    return this.scratchpad.read(p.name);
+  }
+  scratchpadReadChunk(p) {
+    return this.scratchpad.readChunk(p.name, p.offset, p.length);
+  }
+  scratchpadDelete(p) {
+    return this.scratchpad.remove(p.name);
+  }
+  scratchpadClear() {
+    return this.scratchpad.clear();
+  }
   // ── Cross-mode coordinators ──
   async cardExecute(payload) {
     const {
@@ -22017,6 +22279,7 @@ ${c.content.trim() || "(no description)"}`
     void this.codexLogin?.cancel();
     this.claude.destroy();
     this.terminal.destroy();
+    this.scratchpad.destroy();
     this.core.destroy();
   }
   /** Route one action/payload to the right engine method, for both transports.
@@ -22347,6 +22610,24 @@ ${c.content.trim() || "(no description)"}`
         return await this.bareListExposed(
           payload
         );
+      case "scratchpadList":
+        return await this.scratchpadList();
+      case "scratchpadRead":
+        return await this.scratchpadRead(
+          payload
+        );
+      case "scratchpadReadChunk":
+        return await this.scratchpadReadChunk(
+          payload
+        );
+      case "scratchpadDelete":
+        await this.scratchpadDelete(
+          payload
+        );
+        return void 0;
+      case "scratchpadClear":
+        await this.scratchpadClear();
+        return void 0;
       case "secureStatus":
         return this.secureStatus();
       default:
@@ -27361,7 +27642,8 @@ var localConfigProvider = {
       "builds",
       "secrets",
       "claude",
-      "codex"
+      "codex",
+      "scratchpad"
     ]) {
       import_fs11.default.mkdirSync(import_path23.default.join(dir, sub), { recursive: true });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factiii/runner",
-  "version": "0.12.2",
+  "version": "0.13.1",
   "description": "Factiii Runner, run Board AI agents on a machine you control. Pairs with the Factiii web/mobile clients over WebRTC.",
   "license": "ISC",
   "keywords": [

package/plugin/factiii/skills/scratchpad/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: scratchpad
+description: Show the user something, or hand them a file, through the board's Scratchpad panel - by writing to $SCRATCHPAD. Anything you put there renders beside the terminal (image, screenshot, chart, video, audio, page, link, text) and can be saved to their machine or phone. TRIGGER when the user asks to see, show, preview, display or look at something; when you produce an image/diagram/chart/screenshot/recording; when you have a URL worth opening; when an answer is easier to look at than to read in a terminal; and whenever you need to GIVE the user a file - an export, a report, a bundle, a CSV, a log, a dump, anything they asked you to generate, save, download or send them. Writing it to $SCRATCHPAD is how a file gets off the runner and to the user.
+---
+
+# scratchpad
+
+The terminal you are running in has a panel beside it. Anything you put in the
+`$SCRATCHPAD` directory shows up there, drawn rather than printed: images
+render, video and audio play, links become clickable, text and markdown are
+shown as they are.
+
+```bash
+cp chart.png "$SCRATCHPAD/"
+```
+
+That is the whole interface. There is no command to run, nothing to install,
+and nothing to tell the panel: it is watching the directory and updates on
+its own within a second.
+
+## What renders as what
+
+The **extension decides**, so name the file for what it is:
+
+| Write | You get |
+|---|---|
+| `.png .jpg .gif .webp .svg` | the image, click-to-open-full-size |
+| `.mp4 .webm .mov` | a video player |
+| `.mp3 .wav .m4a .ogg` | an audio player |
+| `.html` | the page itself, rendered in a sandboxed frame |
+| `.md` `.txt` and anything unlisted | the text as-is |
+| `.url` | a clickable link (put the URL on the first line) |
+
+A link:
+
+```bash
+echo "https://example.com/the-thing" > "$SCRATCHPAD/preview.url"
+```
+
+A note, when the answer is a shape rather than a sentence:
+
+```bash
+cat > "$SCRATCHPAD/rollout-plan.md" <<'MD'
+# Rollout
+1. staging, behind the flag
+2. 10% of prod for a day
+3. everyone
+MD
+```
+
+## Handing a file to the user
+
+Every item on the panel has a Save button, and the panel pulls the file off the
+runner for them. So the scratchpad is not only for looking at: it is how you
+give someone a file.
+
+```bash
+cp coverage-report.csv "$SCRATCHPAD/"
+zip -qr "$SCRATCHPAD/failing-run-logs.zip" logs/
+pg_dump "$DATABASE_URL" > "$SCRATCHPAD/schema-before-migration.sql"
+```
+
+A file meant for keeping does not have to render well. A `.zip` shows as
+nothing much and a `.csv` as raw text, which is fine, because the user is going
+to save it rather than read it in a narrow column. Name it for what it is so
+they know what they are saving, and say in one line that it is there.
+
+Nothing else you can do reaches the user's disk. If you write a file into the
+workspace and tell them where it is, they have to go and get it themselves,
+which on a phone means they cannot.
+
+## Rules
+
+- **Flat, plain names.** Letters, numbers, dots, dashes, spaces and
+  underscores; no subdirectories, and never a leading dot. A name the panel
+  cannot show is a drawing the user never sees.
+- **Newest is shown first.** Rewriting a file under the same name replaces its
+  card and moves it to the top, which is how you update a drawing rather than
+  pile up `chart-2.png`, `chart-3.png`.
+- **Under 12MB to be shown inline.** A bigger file is still listed, and the
+  user can download it from the panel, but it will not render on the stage.
+  Trim a recording if you want it watched rather than saved.
+- **The board is shared.** One scratchpad per board, not per session, and it
+  survives the session that drew on it. Clean up what has gone stale:
+  `rm "$SCRATCHPAD/old-thing.png"`.
+
+## When to reach for it
+
+Use it whenever the answer is easier to look at than to read: a screenshot of
+the change you just made, a generated chart, a diagram, a recorded repro, a
+preview URL you just exposed, a table too wide for an 80-column shell.
+
+And use it for anything the user is meant to end up holding: the export they
+asked for, the report you generated, the logs from the run that failed, the
+backup you just took.
+
+Do not narrate it into the terminal as well. Write the file and say, in one
+line, what you put on the scratchpad - the user is looking at the panel.