@gaunt-sloth/agent 2.0.0-alpha.2 → 2.0.0-alpha.3

package/dist/tools/shell/env.js

@@ -0,0 +1,110 @@
+/**
+ * @module tools/shell/env
+ *
+ * Credential scrubbing for the shell tool's child environment. By default a
+ * spawned child inherits `process.env` verbatim, so an approved (or yolo'd)
+ * command can `echo $ANTHROPIC_API_KEY` and exfiltrate the operator's LLM/cloud
+ * credentials. {@link buildScrubbedEnv} returns a copy of the parent env with
+ * those credentials removed before spawn.
+ *
+ * Policy (deliberately scoped):
+ * - Strip LLM provider keys and cloud-provider secrets (the explicit blocklist +
+ *   a wildcard sweep for `*_API_KEY` / `*_TOKEN` / `*_SECRET` / `*SECRET_KEY`).
+ * - LEAVE generic dev env intact (PATH, HOME, SHELL, LANG, npm/pnpm config, …)
+ *   so normal commands still work.
+ * - LEAVE `GITHUB_TOKEN` / `GH_TOKEN` intact: gaunt-sloth's content/requirement
+ *   providers shell out to `gh` (`gh pr diff`, `gh issue view`), so stripping
+ *   these would break first-class workflows. They are explicitly allow-listed
+ *   against the wildcard `*_TOKEN` sweep.
+ *
+ * Patterned after hermes-agent `_HERMES_PROVIDER_ENV_BLOCKLIST` (tools/environments/local.py)
+ * — but narrower: we only own the provider/cloud-secret floor.
+ */
+import { env as processEnv } from '@gaunt-sloth/core/utils/systemUtils.js';
+/**
+ * Explicit blocklist of LLM-provider and cloud credentials. Covers the providers
+ * gaunt-sloth (and its consumers) can be configured against, plus the standard
+ * cloud secret-bearing vars. Matched case-insensitively.
+ */
+export const CREDENTIAL_BLOCKLIST = [
+    // LLM providers
+    'ANTHROPIC_API_KEY',
+    'ANTHROPIC_AUTH_TOKEN',
+    'CLAUDE_CODE_OAUTH_TOKEN',
+    'OPENAI_API_KEY',
+    'GOOGLE_API_KEY',
+    'GEMINI_API_KEY',
+    'GOOGLE_APPLICATION_CREDENTIALS',
+    'GROQ_API_KEY',
+    'XAI_API_KEY',
+    'DEEPSEEK_API_KEY',
+    'MISTRAL_API_KEY',
+    'OPENROUTER_API_KEY',
+    'COHERE_API_KEY',
+    'TOGETHER_API_KEY',
+    'PERPLEXITY_API_KEY',
+    'FIREWORKS_API_KEY',
+    // Azure OpenAI
+    'AZURE_OPENAI_API_KEY',
+    'AZURE_API_KEY',
+    // Cloud provider secrets (AWS / GCP)
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN',
+    'AWS_ACCESS_KEY_ID',
+];
+/**
+ * Allow-list of credential-shaped names that must survive the wildcard sweep
+ * because gaunt-sloth legitimately depends on them. Matched case-insensitively.
+ */
+export const CREDENTIAL_ALLOWLIST = [
+    // `gh` CLI auth — used by the github content/requirement providers.
+    'GITHUB_TOKEN',
+    'GH_TOKEN',
+];
+// Wildcard sweep: any var whose name ends in one of these suffixes is treated as
+// a secret and stripped (unless allow-listed). Catches provider keys we didn't
+// enumerate (e.g. a new `FOO_API_KEY`).
+const SECRET_SUFFIXES = [
+    /_API_KEY$/i,
+    /_SECRET_ACCESS_KEY$/i,
+    /_SECRET_KEY$/i,
+    /_SECRET$/i,
+    /_TOKEN$/i,
+];
+function isAllowlisted(name) {
+    return CREDENTIAL_ALLOWLIST.some((a) => a.toUpperCase() === name.toUpperCase());
+}
+function isBlocklisted(name) {
+    return CREDENTIAL_BLOCKLIST.some((b) => b.toUpperCase() === name.toUpperCase());
+}
+function matchesSecretSuffix(name) {
+    return SECRET_SUFFIXES.some((re) => re.test(name));
+}
+/**
+ * True when an env var name should be scrubbed from the child environment.
+ * Exported for testing.
+ */
+export function shouldScrubEnvVar(name) {
+    if (isAllowlisted(name))
+        return false;
+    if (isBlocklisted(name))
+        return true;
+    return matchesSecretSuffix(name);
+}
+/**
+ * Build the child environment for a spawned shell command: a copy of the parent
+ * env with LLM/cloud credentials removed. Defaults to the live `process.env`
+ * (via systemUtils); a source can be injected for testing.
+ */
+export function buildScrubbedEnv(source = processEnv) {
+    const scrubbed = {};
+    for (const [key, value] of Object.entries(source)) {
+        if (value === undefined)
+            continue;
+        if (shouldScrubEnvVar(key))
+            continue;
+        scrubbed[key] = value;
+    }
+    return scrubbed;
+}
+//# sourceMappingURL=env.js.map

package/dist/tools/shell/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../../src/tools/shell/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,GAAG,IAAI,UAAU,EAAE,MAAM,wCAAwC,CAAC;AAE3E;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA0B;IACzD,gBAAgB;IAChB,mBAAmB;IACnB,sBAAsB;IACtB,yBAAyB;IACzB,gBAAgB;IAChB,gBAAgB;IAChB,gBAAgB;IAChB,gCAAgC;IAChC,cAAc;IACd,aAAa;IACb,kBAAkB;IAClB,iBAAiB;IACjB,oBAAoB;IACpB,gBAAgB;IAChB,kBAAkB;IAClB,oBAAoB;IACpB,mBAAmB;IACnB,eAAe;IACf,sBAAsB;IACtB,eAAe;IACf,qCAAqC;IACrC,uBAAuB;IACvB,mBAAmB;IACnB,mBAAmB;CACpB,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA0B;IACzD,oEAAoE;IACpE,cAAc;IACd,UAAU;CACX,CAAC;AAEF,iFAAiF;AACjF,+EAA+E;AAC/E,wCAAwC;AACxC,MAAM,eAAe,GAAG;IACtB,YAAY;IACZ,sBAAsB;IACtB,eAAe;IACf,WAAW;IACX,UAAU;CACX,CAAC;AAEF,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AAClF,CAAC;AAED,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;AAClF,CAAC;AAED,SAAS,mBAAmB,CAAC,IAAY;IACvC,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACrD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,aAAa,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,aAAa,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAA4B,UAAU;IACrE,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,IAAI,iBAAiB,CAAC,GAAG,CAAC;YAAE,SAAS;QACrC,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACxB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/tools/shell/hardline.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Hardline patterns: [regex, human description]. Matched case-insensitively
+ * against the normalized command.
+ */
+export declare const HARDLINE_PATTERNS: ReadonlyArray<readonly [RegExp, string]>;
+export interface HardlineMatch {
+    /** Human-readable reason the command was refused. */
+    description: string;
+}
+/**
+ * Check a raw command against the hardline blocklist. Normalizes first so
+ * obfuscated variants are caught. Returns the match (with a description) when the
+ * command is catastrophic, or `null` when it is allowed to proceed.
+ */
+export declare function checkHardline(command: string): HardlineMatch | null;

package/dist/tools/shell/hardline.js

@@ -0,0 +1,88 @@
+/**
+ * @module tools/shell/hardline
+ *
+ * Unbypassable hardline blocklist for the shell tool. These are catastrophic,
+ * non-recoverable commands (wipe the root filesystem, format a disk, overwrite a
+ * raw block device, fork-bomb, take the host down). They are refused inside
+ * `executeCommand` itself — BEFORE spawn — so the refusal fires regardless of
+ * yolo (`shellYolo`), any allow-list, or the confirmation path. yolo deliberately
+ * bypasses the *confirmation*; it does NOT bypass this floor.
+ *
+ * Recoverable-but-costly operations (e.g. `git reset --hard`, `rm -rf ./build`,
+ * `chmod -R 777 ./dir`, `curl | sh`) are intentionally NOT here — those are what
+ * the confirmation dialog / yolo are for.
+ *
+ * Patterns match the NORMALIZED command ({@link ./normalize.js}) so obfuscation
+ * (ANSI/fullwidth/backslash splits/whitespace padding) cannot bypass them.
+ *
+ * Patterned after hermes-agent `tools/approval.py` HARDLINE_PATTERNS.
+ */
+import { normalizeCommand } from '#src/tools/shell/normalize.js';
+// Matches a position where the shell would begin parsing a NEW command: start of
+// string, after a separator (; & | newline), after `$(` or backtick, optionally
+// consuming leading wrappers (sudo/env VAR=VAL/exec/nohup/setsid/time). Used by
+// the shutdown-family patterns so they don't false-positive on `echo reboot`.
+const CMD_POS = '(?:^|[;&|\\n`]|\\$\\()' +
+    '\\s*' +
+    '(?:sudo\\s+(?:-[^\\s]+\\s+)*)?' +
+    '(?:env\\s+(?:\\w+=\\S*\\s+)*)?' +
+    '(?:(?:exec|nohup|setsid|time)\\s+)*' +
+    '\\s*';
+/**
+ * Hardline patterns: [regex, human description]. Matched case-insensitively
+ * against the normalized command.
+ */
+export const HARDLINE_PATTERNS = [
+    // rm -rf targeting the root filesystem (`/`, `/*`).
+    [/\brm\s+(?:-[^\s]*\s+)*\/\s*\*?\s*(?:$|[;&|])/, 'recursive delete of root filesystem'],
+    // rm -rf targeting protected system directories (with optional /* suffix).
+    [
+        /\brm\s+(?:-[^\s]*\s+)*(?:\/(?:home|root|etc|usr|var|bin|sbin|boot|lib|lib64|opt|sys|proc))(?:\/\*)?\s*(?:$|[;&|])/,
+        'recursive delete of system directory',
+    ],
+    // rm -rf targeting the home directory (~ or $HOME).
+    // Note: patterns match the LOWERCASED normalized command, so $HOME → $home.
+    [
+        /\brm\s+(?:-[^\s]*\s+)*(?:~|\$home)(?:\/\*)?\s*(?:$|[;&|])/,
+        'recursive delete of home directory',
+    ],
+    // Filesystem format.
+    [/\bmkfs(?:\.[a-z0-9]+)?\b/, 'format filesystem (mkfs)'],
+    // dd writing to a raw block device.
+    [/\bdd\b[^\n]*\bof=\/dev\/(?:sd|nvme|hd|mmcblk|vd|xvd)[a-z0-9]*/, 'dd to raw block device'],
+    // Shell redirection to a raw block device (`> /dev/sda`).
+    [/>\s*\/dev\/(?:sd|nvme|hd|mmcblk|vd|xvd)[a-z0-9]*\b/, 'redirect to raw block device'],
+    // Classic fork bomb `:(){ :|:& };:`.
+    [/:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/, 'fork bomb'],
+    // chmod -R 777 / (recursive world-writable on root).
+    [
+        /\bchmod\s+(?:-[^\s]*\s+)*(?:-r|--recursive)\s+(?:-[^\s]*\s+)*777\s+\//,
+        'recursive chmod 777 of root',
+    ],
+    // Kill every process on the system (`kill -1`, `kill -9 -1`).
+    [/\bkill\s+(?:-[^\s]+\s+)*-1\b/, 'kill all processes'],
+    // System shutdown / reboot — anchored to a command position so `echo reboot`
+    // and `grep shutdown log` don't trip it.
+    [new RegExp(CMD_POS + '(?:shutdown|reboot|halt|poweroff)\\b'), 'system shutdown/reboot'],
+    [new RegExp(CMD_POS + 'init\\s+[06]\\b'), 'init 0/6 (shutdown/reboot)'],
+    [
+        new RegExp(CMD_POS + 'systemctl\\s+(?:poweroff|reboot|halt|kexec)\\b'),
+        'systemctl poweroff/reboot',
+    ],
+    [new RegExp(CMD_POS + 'telinit\\s+[06]\\b'), 'telinit 0/6 (shutdown/reboot)'],
+];
+/**
+ * Check a raw command against the hardline blocklist. Normalizes first so
+ * obfuscated variants are caught. Returns the match (with a description) when the
+ * command is catastrophic, or `null` when it is allowed to proceed.
+ */
+export function checkHardline(command) {
+    const normalized = normalizeCommand(command).toLowerCase();
+    for (const [pattern, description] of HARDLINE_PATTERNS) {
+        if (pattern.test(normalized)) {
+            return { description };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=hardline.js.map

package/dist/tools/shell/hardline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hardline.js","sourceRoot":"","sources":["../../../src/tools/shell/hardline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEjE,iFAAiF;AACjF,gFAAgF;AAChF,gFAAgF;AAChF,8EAA8E;AAC9E,MAAM,OAAO,GACX,wBAAwB;IACxB,MAAM;IACN,gCAAgC;IAChC,gCAAgC;IAChC,qCAAqC;IACrC,MAAM,CAAC;AAET;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAA6C;IACzE,oDAAoD;IACpD,CAAC,8CAA8C,EAAE,qCAAqC,CAAC;IACvF,2EAA2E;IAC3E;QACE,mHAAmH;QACnH,sCAAsC;KACvC;IACD,oDAAoD;IACpD,4EAA4E;IAC5E;QACE,2DAA2D;QAC3D,oCAAoC;KACrC;IACD,qBAAqB;IACrB,CAAC,0BAA0B,EAAE,0BAA0B,CAAC;IACxD,oCAAoC;IACpC,CAAC,+DAA+D,EAAE,wBAAwB,CAAC;IAC3F,0DAA0D;IAC1D,CAAC,oDAAoD,EAAE,8BAA8B,CAAC;IACtF,qCAAqC;IACrC,CAAC,gDAAgD,EAAE,WAAW,CAAC;IAC/D,qDAAqD;IACrD;QACE,uEAAuE;QACvE,6BAA6B;KAC9B;IACD,8DAA8D;IAC9D,CAAC,8BAA8B,EAAE,oBAAoB,CAAC;IACtD,6EAA6E;IAC7E,yCAAyC;IACzC,CAAC,IAAI,MAAM,CAAC,OAAO,GAAG,sCAAsC,CAAC,EAAE,wBAAwB,CAAC;IACxF,CAAC,IAAI,MAAM,CAAC,OAAO,GAAG,iBAAiB,CAAC,EAAE,4BAA4B,CAAC;IACvE;QACE,IAAI,MAAM,CAAC,OAAO,GAAG,gDAAgD,CAAC;QACtE,2BAA2B;KAC5B;IACD,CAAC,IAAI,MAAM,CAAC,OAAO,GAAG,oBAAoB,CAAC,EAAE,+BAA+B,CAAC;CAC9E,CAAC;AAOF;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,MAAM,UAAU,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;IAC3D,KAAK,MAAM,CAAC,OAAO,EAAE,WAAW,CAAC,IAAI,iBAAiB,EAAE,CAAC;QACvD,IAAI,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YAC7B,OAAO,EAAE,WAAW,EAAE,CAAC;QACzB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/tools/shell/normalize.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @module tools/shell/normalize
+ *
+ * Re-export of the canonical command normalizer, which now lives in
+ * `@gaunt-sloth/core` (`core/shell/normalize`) so the core runner's EXT-9 Tier-2
+ * allow-list classifier and the agent's Tier-1 hardline blocklist share ONE
+ * implementation. Kept as a stable import path for existing agent-side consumers
+ * (`tools/shell/hardline`, specs).
+ */
+export { normalizeCommand } from '@gaunt-sloth/core/core/shell/normalize.js';

package/dist/tools/shell/normalize.js

@@ -0,0 +1,11 @@
+/**
+ * @module tools/shell/normalize
+ *
+ * Re-export of the canonical command normalizer, which now lives in
+ * `@gaunt-sloth/core` (`core/shell/normalize`) so the core runner's EXT-9 Tier-2
+ * allow-list classifier and the agent's Tier-1 hardline blocklist share ONE
+ * implementation. Kept as a stable import path for existing agent-side consumers
+ * (`tools/shell/hardline`, specs).
+ */
+export { normalizeCommand } from '@gaunt-sloth/core/core/shell/normalize.js';
+//# sourceMappingURL=normalize.js.map

package/dist/tools/shell/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../../src/tools/shell/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC"}

package/dist/tools/shell/outputBuffer.d.ts

@@ -0,0 +1,53 @@
+export interface CappedOutput {
+    /** The bounded text to surface to the model (head + tail with a gap note). */
+    text: string;
+    /** True when the output exceeded the budget and was truncated. */
+    truncated: boolean;
+    /** Total bytes captured (the full, untruncated size). */
+    totalBytes: number;
+    /** Absolute path to the spilled full output, or undefined when not truncated. */
+    spillPath?: string;
+}
+/**
+ * Accumulates command output up to a byte budget using a head + tail window.
+ * The full output is retained in memory so it can be spilled to disk on demand;
+ * the in-memory full copy is itself bounded at a hard safety ceiling to avoid
+ * unbounded growth from a runaway command.
+ */
+export declare class OutputBuffer {
+    private head;
+    private headBytes;
+    private readonly tailChunks;
+    private tailBytes;
+    private totalBytesCount;
+    /** Full copy for spillover, bounded by a hard ceiling. */
+    private full;
+    private fullTruncated;
+    private readonly headBudget;
+    private readonly tailBudget;
+    private readonly fullCeiling;
+    /**
+     * @param maxOutputBytes total byte budget for the returned (head+tail) window.
+     * @param fullCeiling hard ceiling for the in-memory full copy kept for spillover.
+     *        Defaults to a generous 16MB so the spill file holds the real output for
+     *        typical noisy logs, while still bounding memory for a runaway command.
+     */
+    constructor(maxOutputBytes: number, fullCeiling?: number);
+    /** Append a chunk of output. Byte accounting uses UTF-8 byte length. */
+    append(chunk: string): void;
+    /** Push into the tail ring-buffer, evicting oldest data beyond the budget. */
+    private pushTail;
+    get totalBytes(): number;
+    get isTruncated(): boolean;
+    /** The full captured output (bounded by the in-memory ceiling). */
+    getFull(): string;
+    /**
+     * Finalize the capture. When not truncated, returns the output verbatim. When
+     * truncated, spills the full output to a temp file and returns head + a gap
+     * note (with the file path) + tail.
+     *
+     * @param spill optional injected spill function (path-returning) for testing.
+     *        Defaults to writing into `os.tmpdir()`.
+     */
+    finalize(spill?: (content: string) => string): CappedOutput;
+}

package/dist/tools/shell/outputBuffer.js

@@ -0,0 +1,157 @@
+/**
+ * @module tools/shell/outputBuffer
+ *
+ * Bounded capture of a shell command's combined stdout/stderr for the value
+ * returned to the model. A noisy build/test log can be megabytes; dumping it
+ * verbatim into a ToolMessage blows the context window. This buffer keeps a
+ * HEAD window (the first N bytes) and a TAIL ring-buffer (the last N bytes) and
+ * drops the middle, while accumulating the FULL output separately so it can be
+ * spilled to a temp file the model can re-read with `read_file`.
+ *
+ * Live streaming to the terminal is unaffected — the toolkit still writes every
+ * chunk to stdout as it arrives; only the returned string is capped.
+ *
+ * Patterned after opencode `bash.ts` (per-stream cap + temp-file tail) and
+ * openclaw `bash-tools.shared.ts` `truncateMiddle`.
+ */
+import { writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+/**
+ * Accumulates command output up to a byte budget using a head + tail window.
+ * The full output is retained in memory so it can be spilled to disk on demand;
+ * the in-memory full copy is itself bounded at a hard safety ceiling to avoid
+ * unbounded growth from a runaway command.
+ */
+export class OutputBuffer {
+    head = '';
+    headBytes = 0;
+    tailChunks = [];
+    tailBytes = 0;
+    totalBytesCount = 0;
+    /** Full copy for spillover, bounded by a hard ceiling. */
+    full = '';
+    fullTruncated = false;
+    headBudget;
+    tailBudget;
+    fullCeiling;
+    /**
+     * @param maxOutputBytes total byte budget for the returned (head+tail) window.
+     * @param fullCeiling hard ceiling for the in-memory full copy kept for spillover.
+     *        Defaults to a generous 16MB so the spill file holds the real output for
+     *        typical noisy logs, while still bounding memory for a runaway command.
+     */
+    constructor(maxOutputBytes, fullCeiling = 16 * 1024 * 1024) {
+        // Split the budget evenly between head and tail.
+        this.headBudget = Math.max(1, Math.floor(maxOutputBytes / 2));
+        this.tailBudget = Math.max(1, maxOutputBytes - this.headBudget);
+        // The full copy must hold at least the preview window.
+        this.fullCeiling = Math.max(fullCeiling, maxOutputBytes);
+    }
+    /** Append a chunk of output. Byte accounting uses UTF-8 byte length. */
+    append(chunk) {
+        const bytes = Buffer.byteLength(chunk, 'utf8');
+        this.totalBytesCount += bytes;
+        // Maintain the full copy up to the ceiling (for spillover). Store as much of
+        // an oversized chunk as fits rather than dropping it wholesale.
+        if (!this.fullTruncated) {
+            const used = Buffer.byteLength(this.full, 'utf8');
+            const room = this.fullCeiling - used;
+            if (bytes <= room) {
+                this.full += chunk;
+            }
+            else {
+                if (room > 0) {
+                    this.full += Buffer.from(chunk, 'utf8').subarray(0, room).toString('utf8');
+                }
+                this.fullTruncated = true;
+            }
+        }
+        // Fill the head window first.
+        if (this.headBytes < this.headBudget) {
+            const room = this.headBudget - this.headBytes;
+            if (bytes <= room) {
+                this.head += chunk;
+                this.headBytes += bytes;
+                return;
+            }
+            // Partial: take what fits into head, the rest flows to tail.
+            const take = Buffer.from(chunk, 'utf8').subarray(0, room).toString('utf8');
+            this.head += take;
+            this.headBytes += Buffer.byteLength(take, 'utf8');
+            const rest = chunk.slice(take.length);
+            this.pushTail(rest);
+            return;
+        }
+        this.pushTail(chunk);
+    }
+    /** Push into the tail ring-buffer, evicting oldest data beyond the budget. */
+    pushTail(chunk) {
+        if (chunk.length === 0)
+            return;
+        this.tailChunks.push(chunk);
+        this.tailBytes += Buffer.byteLength(chunk, 'utf8');
+        while (this.tailBytes > this.tailBudget && this.tailChunks.length > 1) {
+            const removed = this.tailChunks.shift();
+            this.tailBytes -= Buffer.byteLength(removed, 'utf8');
+        }
+        // If a single chunk alone exceeds the tail budget, trim it from the front.
+        if (this.tailBytes > this.tailBudget && this.tailChunks.length === 1) {
+            const only = this.tailChunks[0];
+            const overflow = this.tailBytes - this.tailBudget;
+            const buf = Buffer.from(only, 'utf8');
+            const trimmed = buf.subarray(overflow).toString('utf8');
+            this.tailChunks[0] = trimmed;
+            this.tailBytes = Buffer.byteLength(trimmed, 'utf8');
+        }
+    }
+    get totalBytes() {
+        return this.totalBytesCount;
+    }
+    get isTruncated() {
+        return this.totalBytesCount > this.headBytes + this.tailBytes;
+    }
+    /** The full captured output (bounded by the in-memory ceiling). */
+    getFull() {
+        return this.full;
+    }
+    /**
+     * Finalize the capture. When not truncated, returns the output verbatim. When
+     * truncated, spills the full output to a temp file and returns head + a gap
+     * note (with the file path) + tail.
+     *
+     * @param spill optional injected spill function (path-returning) for testing.
+     *        Defaults to writing into `os.tmpdir()`.
+     */
+    finalize(spill = defaultSpill) {
+        const tail = this.tailChunks.join('');
+        if (!this.isTruncated) {
+            return {
+                text: this.head + tail,
+                truncated: false,
+                totalBytes: this.totalBytesCount,
+            };
+        }
+        const spillPath = spill(this.full);
+        const fullNote = this.fullTruncated
+            ? `First ${Buffer.byteLength(this.full, 'utf8')} bytes`
+            : 'Full output';
+        const droppedNote = `\n\n... [output truncated: ${this.totalBytesCount} bytes total; ` +
+            `showing first ${this.headBytes} + last ${this.tailBytes} bytes. ` +
+            `${fullNote} written to ${spillPath} — use read_file to inspect.] ...\n\n`;
+        return {
+            text: this.head + droppedNote + tail,
+            truncated: true,
+            totalBytes: this.totalBytesCount,
+            spillPath,
+        };
+    }
+}
+/** Default spill: write to a uniquely-named file in the OS temp dir. */
+function defaultSpill(content) {
+    const name = `gsloth-shell-${Date.now()}-${Math.random().toString(36).slice(2, 10)}.log`;
+    const filePath = path.join(tmpdir(), name);
+    writeFileSync(filePath, content, 'utf8');
+    return filePath;
+}
+//# sourceMappingURL=outputBuffer.js.map

package/dist/tools/shell/outputBuffer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outputBuffer.js","sourceRoot":"","sources":["../../../src/tools/shell/outputBuffer.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@gaunt-sloth/agent",
-  "version": "2.0.0-alpha.2",
+  "version": "2.0.0-alpha.3",
   "description": "Deep agent runtime for Gaunt Sloth: tools, middleware, MCP/A2A clients and the AG-UI server",
   "license": "MIT",
   "author": "Andrew Kondratev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Galvanized-Pukeko/gaunt-sloth.git",
+    "url": "git+https://github.com/pukeko-robotics/gaunt-sloth.git",
     "directory": "packages/agent"
   },
   "bugs": {
-    "url": "https://github.com/Galvanized-Pukeko/gaunt-sloth/issues"
+    "url": "https://github.com/pukeko-robotics/gaunt-sloth/issues"
   },
-  "homepage": "https://github.com/Galvanized-Pukeko/gaunt-sloth/tree/main/packages/agent#readme",
+  "homepage": "https://github.com/pukeko-robotics/gaunt-sloth/tree/main/packages/agent#readme",
   "keywords": [
     "ai",
     "agent",
@@ -52,7 +52,7 @@
     "langchain": "^1.5.0",
     "uuid": ">=11.1.1",
     "zod": "^3.25.0 || ^4.0.0",
-    "@gaunt-sloth/core": "2.0.0-alpha.2"
+    "@gaunt-sloth/core": "2.0.0-alpha.3"
   },
   "files": [
     "./dist/*",