@basein/runner 0.2.12 → 0.3.0

package/dist/replay/bash-channel.d.ts

@@ -0,0 +1,35 @@
+/**
+ * bash-channel — delivering text to the model as a `Bash` command's genuine
+ * output (docs/calculatedReplay.md §8).
+ *
+ * The model reaches for `Bash` when it cannot call a scripted tool, and a real
+ * command output is trusted where a `deny` reason reads as interception, so a
+ * divergence bundle or a hand-over note is delivered by rewriting that call
+ * into a `cat`.
+ *
+ * THE COMMAND MUST STAY SHORT. It used to carry the whole text as a heredoc —
+ * up to 60 000 characters inside the command string. Measured through Git Bash
+ * on Windows: 8 000 characters print intact; 9 000 to 30 000 print only the
+ * first 8 171, with "here-document delimited by end-of-file"; 40 000 fail to
+ * spawn at all (ENAMETOOLONG). A bundle cut there loses its later steps and its
+ * footer, and the model redoes work that already ran. So a short text still
+ * rides inline, and anything longer is written to a private file the command
+ * reads. The caller caps the text itself ({@link ./bundle.ts}'s
+ * `BASH_CHANNEL_MAX`), because the host truncates long command output too.
+ */
+/** Up to this many characters the text rides inside the command, as a heredoc. */
+export declare const HEREDOC_MAX = 6000;
+/** Where delivered texts wait to be read. Under `BIR_HOME`, mode 0700. */
+export declare function deliveryDir(): string;
+/**
+ * The command that prints `text`, or undefined when it could not be prepared —
+ * the caller then delivers through another channel.
+ */
+export declare function bashCommandFor(text: string): string | undefined;
+/**
+ * Remove delivered texts older than an hour. For the recorder to call when it
+ * starts and on its housekeeping tick: a process that exits within the hour
+ * cannot sweep what it wrote. Never throws; returns how many it removed.
+ */
+export declare function sweepDeliveries(dir?: string): number;
+//# sourceMappingURL=bash-channel.d.ts.map

package/dist/replay/bash-channel.js

@@ -0,0 +1,133 @@
+/**
+ * bash-channel — delivering text to the model as a `Bash` command's genuine
+ * output (docs/calculatedReplay.md §8).
+ *
+ * The model reaches for `Bash` when it cannot call a scripted tool, and a real
+ * command output is trusted where a `deny` reason reads as interception, so a
+ * divergence bundle or a hand-over note is delivered by rewriting that call
+ * into a `cat`.
+ *
+ * THE COMMAND MUST STAY SHORT. It used to carry the whole text as a heredoc —
+ * up to 60 000 characters inside the command string. Measured through Git Bash
+ * on Windows: 8 000 characters print intact; 9 000 to 30 000 print only the
+ * first 8 171, with "here-document delimited by end-of-file"; 40 000 fail to
+ * spawn at all (ENAMETOOLONG). A bundle cut there loses its later steps and its
+ * footer, and the model redoes work that already ran. So a short text still
+ * rides inline, and anything longer is written to a private file the command
+ * reads. The caller caps the text itself ({@link ./bundle.ts}'s
+ * `BASH_CHANNEL_MAX`), because the host truncates long command output too.
+ */
+import { randomUUID } from "node:crypto";
+import { readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configDir, ensureDir } from "../control/paths.js";
+/** Up to this many characters the text rides inside the command, as a heredoc. */
+export const HEREDOC_MAX = 6_000;
+/** A delivered file is read once, at once; an hour is a generous margin. */
+const MAX_AGE_MS = 60 * 60_000;
+/** Where delivered texts wait to be read. Under `BIR_HOME`, mode 0700. */
+export function deliveryDir() {
+    return join(configDir(), "tmp");
+}
+/**
+ * The command that prints `text`, or undefined when it could not be prepared —
+ * the caller then delivers through another channel.
+ */
+export function bashCommandFor(text) {
+    if (text.length <= HEREDOC_MAX) {
+        // Neutralise the delimiter, so no text can end the heredoc early.
+        const delimiter = "BIR_EOF";
+        const safe = text.split(delimiter).join("BIR_EOF_");
+        return `cat <<'${delimiter}'\n${safe}\n${delimiter}`;
+    }
+    try {
+        const dir = deliveryDir();
+        ensureDir(dir);
+        sweep(dir);
+        const path = join(dir, `replay-${randomUUID()}.txt`);
+        writeFileSync(path, text, { encoding: "utf8", mode: 0o600 });
+        // The file holds live tool outputs. It is kept an hour — a Bash call can
+        // wait that long on a permission prompt before it reads it — and then
+        // removed by this process, not only by a later delivery that may never
+        // come ("swept after 1 h").
+        scheduleSweep(dir);
+        return `cat ${shellQuote(shellPath(path))}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Remove delivered texts older than an hour. For the recorder to call when it
+ * starts and on its housekeeping tick: a process that exits within the hour
+ * cannot sweep what it wrote. Never throws; returns how many it removed.
+ */
+export function sweepDeliveries(dir = deliveryDir()) {
+    return sweep(dir).removed;
+}
+/** Past {@link MAX_AGE_MS}, how long a scheduled sweep waits more. */
+const SWEEP_SLACK_MS = 60_000;
+/** The sweep waiting for this process's newest delivered file to age out, by directory. */
+const scheduledSweeps = new Map();
+/**
+ * Sweep `dir` once the file just written is old enough to go, and again while
+ * younger ones are left. Unref'd: it never keeps the process alive.
+ */
+function scheduleSweep(dir) {
+    const earlier = scheduledSweeps.get(dir);
+    if (earlier)
+        clearTimeout(earlier);
+    const timer = setTimeout(() => {
+        scheduledSweeps.delete(dir);
+        if (sweep(dir).left > 0)
+            scheduleSweep(dir);
+    }, MAX_AGE_MS + SWEEP_SLACK_MS);
+    timer.unref?.();
+    scheduledSweeps.set(dir, timer);
+}
+/**
+ * A path every shell the host may run can open. Forward slashes on Windows:
+ * Git Bash reads `C:/Users/…` as it is, and so does PowerShell's `cat`.
+ */
+function shellPath(path) {
+    return process.platform === "win32" ? path.replace(/\\/g, "/") : path;
+}
+/** Single-quoted for a POSIX shell (and harmless in PowerShell). */
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Remove delivered texts older than {@link MAX_AGE_MS}. Never throws. Says how
+ * many it removed, and how many younger ones are left.
+ */
+function sweep(dir) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return { removed: 0, left: 0 };
+    }
+    const cutoff = Date.now() - MAX_AGE_MS;
+    let removed = 0;
+    let left = 0;
+    for (const name of names) {
+        if (!name.startsWith("replay-") || !name.endsWith(".txt"))
+            continue;
+        const path = join(dir, name);
+        try {
+            if (statSync(path).mtimeMs < cutoff) {
+                unlinkSync(path);
+                removed += 1;
+            }
+            else {
+                left += 1;
+            }
+        }
+        catch {
+            // Gone already, or not ours to remove.
+        }
+    }
+    return { removed, left };
+}
+//# sourceMappingURL=bash-channel.js.map

package/dist/replay/bundle.d.ts

@@ -16,6 +16,16 @@
  */
 /** `permissionDecisionReason` is fed to the model as text; keep denials bounded. */
 export declare const MAX_REPLAY_REASON = 60000;
+/**
+ * Ceiling on text delivered as a `Bash` command's output.
+ *
+ * Claude Code middle-truncates Bash output above `BASH_MAX_OUTPUT_LENGTH`
+ * (30 000 by default), and a bundle cut in the middle loses exactly the steps
+ * the model needs to see were already done — so it does them again. Laid out
+ * at this size with the fair-share rule, every step stays represented and the
+ * cut never happens. A hand-over note in front of it is counted inside this.
+ */
+export declare const BASH_CHANNEL_MAX = 25000;
 /** One executed step, pre-stringified and ready to lay out. */
 export interface BundleEntry {
     toolName: string;

package/dist/replay/bundle.js

@@ -16,6 +16,16 @@
  */
 /** `permissionDecisionReason` is fed to the model as text; keep denials bounded. */
 export const MAX_REPLAY_REASON = 60_000;
+/**
+ * Ceiling on text delivered as a `Bash` command's output.
+ *
+ * Claude Code middle-truncates Bash output above `BASH_MAX_OUTPUT_LENGTH`
+ * (30 000 by default), and a bundle cut in the middle loses exactly the steps
+ * the model needs to see were already done — so it does them again. Laid out
+ * at this size with the fair-share rule, every step stays represented and the
+ * cut never happens. A hand-over note in front of it is counted inside this.
+ */
+export const BASH_CHANNEL_MAX = 25_000;
 /** Cap each computed input so one huge argument object cannot starve responses. */
 const MAX_INPUT_CHARS = 2_000;
 /** Fixed structural overhead reserved per step (labels, separators). */