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

package/dist/tools/shell/allowlist.js

@@ -0,0 +1,12 @@
+/**
+ * @module tools/shell/allowlist
+ *
+ * Re-export of the EXT-9 Tier-2 allow-list engine. The implementation lives in
+ * `@gaunt-sloth/core` (`core/shell/allowlist`) because the core {@link GthAgentRunner}
+ * owns the per-instance session store and the loaded persisted store and consults
+ * `matchesApproval` before prompting (core cannot import from `@gaunt-sloth/agent`).
+ *
+ * See the core module for the exact safe-bin / anti-widening matching rule.
+ */
+export { matchesApproval, hasWideningFlag, AllowlistStore, PersistedAllowlist, } from '@gaunt-sloth/core/core/shell/allowlist.js';
+//# sourceMappingURL=allowlist.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"allowlist.js","sourceRoot":"","sources":["../../../src/tools/shell/allowlist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,eAAe,EACf,eAAe,EACf,cAAc,EACd,kBAAkB,GAGnB,MAAM,2CAA2C,CAAC"}

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

@@ -0,0 +1,11 @@
+/**
+ * @module tools/shell/arity
+ *
+ * Re-export of the EXT-9 Tier-2 command classifier. The implementation lives in
+ * `@gaunt-sloth/core` (`core/shell/arity`) because the core {@link GthAgentRunner}
+ * must consult it BEFORE prompting (and core cannot import from `@gaunt-sloth/agent`).
+ * This stable agent-side path is kept for tests and any agent-layer consumers.
+ *
+ * See the core module for the arity table scope and the anti-injection fail-closed rule.
+ */
+export { classifyCommand, tokenize, meaningfulPrefixTokens, type CommandClassification, } from '@gaunt-sloth/core/core/shell/arity.js';

package/dist/tools/shell/arity.js

@@ -0,0 +1,12 @@
+/**
+ * @module tools/shell/arity
+ *
+ * Re-export of the EXT-9 Tier-2 command classifier. The implementation lives in
+ * `@gaunt-sloth/core` (`core/shell/arity`) because the core {@link GthAgentRunner}
+ * must consult it BEFORE prompting (and core cannot import from `@gaunt-sloth/agent`).
+ * This stable agent-side path is kept for tests and any agent-layer consumers.
+ *
+ * See the core module for the arity table scope and the anti-injection fail-closed rule.
+ */
+export { classifyCommand, tokenize, meaningfulPrefixTokens, } from '@gaunt-sloth/core/core/shell/arity.js';
+//# sourceMappingURL=arity.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"arity.js","sourceRoot":"","sources":["../../../src/tools/shell/arity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACL,eAAe,EACf,QAAQ,EACR,sBAAsB,GAEvB,MAAM,uCAAuC,CAAC"}

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

@@ -0,0 +1,22 @@
+/**
+ * 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 declare const CREDENTIAL_BLOCKLIST: ReadonlyArray<string>;
+/**
+ * Allow-list of credential-shaped names that must survive the wildcard sweep
+ * because gaunt-sloth legitimately depends on them. Matched case-insensitively.
+ */
+export declare const CREDENTIAL_ALLOWLIST: ReadonlyArray<string>;
+/**
+ * True when an env var name should be scrubbed from the child environment.
+ * Exported for testing.
+ */
+export declare function shouldScrubEnvVar(name: string): boolean;
+/**
+ * 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 declare function buildScrubbedEnv(source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

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,MAAM,GAAsB,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/dist/tools/shell/workDir.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Working directory the shell tool spawns in: the ACP session override when set (ACP transport),
+ * otherwise `getCurrentWorkDir()` (local runner + AG-UI, unchanged).
+ */
+export declare function getShellWorkDir(): string;
+/**
+ * ACP-only: point the shell tool at the current ACP session's fs-backend root (the resolved
+ * `session/new.cwd`, or the startup workspace when a session carries no cwd). Pass `undefined` to
+ * clear the override and restore the `getCurrentWorkDir()` default (used by tests).
+ */
+export declare function setAcpShellWorkDir(cwd: string | undefined): void;

package/dist/tools/shell/workDir.js

@@ -0,0 +1,45 @@
+/**
+ * @packageDocumentation
+ * Resolves the working directory the shell tool (`run_shell_command`) spawns in, keeping it aligned
+ * with the deepagents filesystem-backend root so the shell and the fs tools (ls/read_file/write_file/
+ * edit_file/glob/grep) share ONE path namespace.
+ *
+ * DEFAULT (local `code`/`chat` runner + AG-UI): `getCurrentWorkDir()`. On these surfaces the fs
+ * backend is rooted at `getCurrentWorkDir()` by `GthDeepAgent.init()` (`rootDir: getCurrentWorkDir()`),
+ * so the shell already matches it — this is exactly EXT-22 S4. These surfaces NEVER call
+ * {@link setAcpShellWorkDir}, so {@link getShellWorkDir} stays `getCurrentWorkDir()` for them.
+ *
+ * ACP transport override: unlike the local runner, the ACP server does NOT call `init()`; it re-roots
+ * ITS per-session fs backend to each `session/new.cwd` (see `gthAcpServer.ts`). The shell tool
+ * instances are built ONCE at startup (`buildDeepAgentParams`), so they cannot themselves see the
+ * later session cwd. The ACP server therefore updates this module-level override on every
+ * `session/new`; the shell reads it at spawn time so it tracks the session fs root.
+ *
+ * This also removes the EXT-22 S4 `INIT_CWD` hazard on ACP: `getCurrentWorkDir()` prefers `INIT_CWD`,
+ * which is stale in the long-lived ACP subprocess (the reason `acpModule` roots the startup workspace
+ * at raw `process.cwd()`). Once the override tracks the session cwd, the ACP shell never consults
+ * `INIT_CWD`.
+ *
+ * Scope note: this mirrors the ACP design, which is ALREADY "latest-session-cwd wins" process-wide —
+ * `gthAcpServer` clobbers every backend to the newest session cwd. A single process-wide override has
+ * the same semantics. The ACP subprocess is dedicated (never co-hosts a local runner / AG-UI), so the
+ * override can never leak into a non-ACP surface.
+ */
+import { getCurrentWorkDir } from '@gaunt-sloth/core/utils/systemUtils.js';
+let acpShellWorkDir;
+/**
+ * Working directory the shell tool spawns in: the ACP session override when set (ACP transport),
+ * otherwise `getCurrentWorkDir()` (local runner + AG-UI, unchanged).
+ */
+export function getShellWorkDir() {
+    return acpShellWorkDir ?? getCurrentWorkDir();
+}
+/**
+ * ACP-only: point the shell tool at the current ACP session's fs-backend root (the resolved
+ * `session/new.cwd`, or the startup workspace when a session carries no cwd). Pass `undefined` to
+ * clear the override and restore the `getCurrentWorkDir()` default (used by tests).
+ */
+export function setAcpShellWorkDir(cwd) {
+    acpShellWorkDir = cwd;
+}
+//# sourceMappingURL=workDir.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"workDir.js","sourceRoot":"","sources":["../../../src/tools/shell/workDir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAE3E,IAAI,eAAmC,CAAC;AAExC;;;GAGG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,eAAe,IAAI,iBAAiB,EAAE,CAAC;AAChD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAuB;IACxD,eAAe,GAAG,GAAG,CAAC;AACxB,CAAC"}

package/dist/utils/mcpAuthError.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @packageDocumentation
+ * EXT-31 — classify and format MCP integration connect/tool-load failures so an expired or invalid
+ * credential is SURFACED (named + actionable) instead of silently dropping the integration's tools.
+ *
+ * The `@langchain/mcp-adapters` client only tags a bare HTTP 401 as an authentication error; a 403
+ * (forbidden / expired scope) otherwise falls through as a generic "Failed to connect". This module
+ * classifies auth failures independently (401/403 + credential keywords) so a stale token is not
+ * mistaken for "this integration was never configured" or an unrelated transient error.
+ *
+ * Pure + side-effect free: callers do the surfacing (`displayWarning`) with the returned message.
+ */
+/** Coarse classification of an MCP connect/tool-load failure. */
+export type McpConnectErrorKind = 'auth' | 'other';
+/** Options that tune the suggested fix path in the surfaced message. */
+export interface McpConnectFailureOptions {
+    /** The server uses OAuth (`authProvider: 'OAuth'`) — suggest re-running the OAuth login. */
+    oauth?: boolean;
+}
+/**
+ * Classify an MCP connect/tool-load failure as a credential problem (`auth`) or anything else
+ * (`other`). Detection is independent of the adapter (which only tags 401), so a 403 or an
+ * "expired token" surfaced by the upstream server is still recognised as auth.
+ */
+export declare function classifyMcpConnectError(error: unknown): McpConnectErrorKind;
+/**
+ * Build the user-facing message for a failed MCP integration. For `auth` failures it names the
+ * integration, states the credential is expired/invalid, and points at the concrete fix path
+ * (OAuth login or the API token / authorization header, plus the `mcpServers` entry in gth config).
+ * For `other` failures it surfaces the failure plainly and explicitly says it is NOT an auth error,
+ * so an unrelated transient never triggers a spurious "re-authenticate" nudge.
+ *
+ * Either way the caller degrades gracefully AFTER surfacing this — the integration's tools are
+ * dropped for the session, but the user (and the log) now knows why.
+ */
+export declare function formatMcpConnectFailureMessage(serverName: string | undefined, error: unknown, options?: McpConnectFailureOptions): string;