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

package/dist/utils/redactSecrets.js

@@ -0,0 +1,238 @@
+/**
+ * @packageDocumentation
+ * GS2-47 — a shared, reusable secret-redaction pass for diagnostic output.
+ *
+ * Built for `/debug-dump` ({@link file://./debugDump.ts}) but deliberately generic and
+ * dependency-free — it takes `env` as a PARAMETER rather than reading `process.env`, so the pass is
+ * pure, deterministic in tests, and reusable by GS2-48's crash-report handler (which hard-depends on
+ * this module). Nothing here reads ambient process state.
+ *
+ * DESIGN DECISION (settled by the coordinator, GS2-47): **PATTERN-ONLY** redaction — we do NOT scan
+ * for high-entropy strings. Rationale: pattern-only is safe to reason about and near-zero
+ * false-positive; entropy scanning catches marginally more but produces false-positive redactions
+ * the user has to squint through, degrading the dump's debug value. A high-entropy scanner is a
+ * DELIBERATELY-DEFERRED option (a config surface for it could be added later if ever warranted) and
+ * is intentionally NOT implemented here.
+ *
+ * Three techniques, in priority order:
+ *  1. [load-bearing] Known-secret VALUE substitution — collect the literal values of secret-named
+ *     env vars + inline config secrets, then substitute every occurrence across ALL artifacts. This
+ *     catches a leaked key wherever it surfaces (config, env, transcript, log) with no guessing.
+ *  2. Provider key/token PATTERNS — a tight, documented, prefix-anchored set of well-known key
+ *     shapes plus explicit auth-header contexts. We never blanket-redact long alphanumeric strings.
+ *  3. Sensitive config-FIELD masking — mask the VALUES of secret-named config keys while preserving
+ *     structure (the key stays; only the value becomes the marker).
+ *
+ * Fail-safe throughout: on any internal error the functions redact MORE (return the marker), never
+ * less — a redaction hiccup must never cause raw content to be emitted.
+ */
+/** The visible, greppable placeholder substituted for every redacted secret value. */
+export const REDACTED = '<redacted>';
+/**
+ * Minimum length for a collected VALUE to be treated as a substitutable secret literal (technique
+ * 1). Guards against redacting trivial values ("1", "on", a short model name) that happen to be the
+ * value of a secret-named env var — substituting those everywhere would gut the dump's debug value
+ * with false positives (exactly the trap the pattern-only decision avoids). Short sensitive *config*
+ * fields are still masked structurally by key name (technique 3), so nothing sensitive slips through
+ * this floor.
+ */
+const MIN_SECRET_LITERAL_LENGTH = 6;
+/** Max recursion depth for the config walks — a guard against pathological/deep object graphs. */
+const MAX_REDACT_DEPTH = 12;
+/**
+ * env-var NAME shapes whose VALUE is a secret to substitute everywhere (technique 1): `*_API_KEY`,
+ * `*_TOKEN`, `*_SECRET`, `*_KEY`, and anything containing `PASSWORD`. Case-insensitive.
+ */
+const SECRET_ENV_NAME_RE = /(?:_API_KEY|_TOKEN|_SECRET|_KEY)$|PASSWORD/i;
+/**
+ * Config-FIELD NAME shapes whose VALUE is masked in place (technique 3), matched case-insensitively
+ * at any depth. Mirrors `configCommand.ts`'s `redactConfigForPrint` set for cross-surface
+ * consistency. NOTE: `apiKeyEnvironmentVariable` also matches `api?key`, but it holds a var NAME
+ * (not a secret) and is what technique 1 reads to find the real key's value — so it is EXCLUDED via
+ * {@link NON_SECRET_KEY_NAMES}.
+ */
+const SECRET_KEY_RE = /(api[-_]?key|secret|token|password|passwd|authorization|bearer|credential)/i;
+/** Field names that match {@link SECRET_KEY_RE} but must NOT be masked (they hold a var name). */
+const NON_SECRET_KEY_NAMES = new Set(['apikeyenvironmentvariable']);
+/**
+ * Provider key / auth-header PATTERNS (technique 2) — a tight, prefix-anchored set. Each entry is
+ * `[regex, replacement]`. Kept deliberately narrow (well-known key prefixes + explicit auth
+ * contexts); we do NOT blanket-redact long alphanumeric strings — that IS the entropy trap the
+ * pattern-only decision avoids. A long opaque token is only redacted when it sits in an auth context
+ * (`Bearer …` / `Authorization: …`), never on its own.
+ */
+const PROVIDER_PATTERNS = [
+    // OpenAI (`sk-…`) and Anthropic (`sk-ant-…`, also `sk-`-prefixed) secret keys.
+    [/\bsk-(?:ant-)?[A-Za-z0-9_-]{16,}/g, REDACTED],
+    // Google API keys (`AIza…`).
+    [/\bAIza[0-9A-Za-z_-]{16,}/g, REDACTED],
+    // xAI (`xai-…`).
+    [/\bxai-[A-Za-z0-9_-]{16,}/g, REDACTED],
+    // Groq (`gsk_…`).
+    [/\bgsk_[A-Za-z0-9_-]{16,}/g, REDACTED],
+    // GS2-54 (gap 2) — GitHub tokens. Classic/scoped PATs share the `gh[oprsu]_` prefix (personal
+    // `ghp_`, OAuth `gho_`, user-to-server `ghu_`, server-to-server `ghs_`, refresh `ghr_`); the value
+    // is base62 (no `_`). Prefix-anchored + a length floor, same tight style as the provider keys —
+    // NOT a blanket long-alphanumeric redaction (that IS the entropy trap avoided).
+    [/\bgh[oprsu]_[A-Za-z0-9]{16,}/g, REDACTED],
+    // GS2-54 (gap 2) — GitHub fine-grained PATs (`github_pat_…`); the value carries an inner `_`, so
+    // its charset includes `_`. Distinct prefix from the classic rule above (`github_` ≠ `gh[oprsu]_`).
+    [/\bgithub_pat_[A-Za-z0-9_]{16,}/g, REDACTED],
+    // GS2-54 (gap 2) — credentials embedded in a URL (`scheme://user:password@host`). Redact the
+    // `user:password` userinfo, KEEP the scheme + host so the artifact stays debuggable. Bounded: the
+    // userinfo stops at `@` (and the password never spans `/` or whitespace), so it cannot swallow the
+    // rest of the URL/line. A URL without userinfo (`https://host:port/path`) has no `user:pass@` and
+    // is left untouched.
+    [/(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/gi, `$1${REDACTED}@`],
+    // GS2-54 (gap 1) — an `Authorization` header value (`Authorization: <scheme?> <credential>` /
+    // `"Authorization":"…"`): keep the header name + separator, redact the value REGARDLESS OF SCHEME.
+    // Generalized beyond the old fixed `Bearer|Basic|Token|Digest|Negotiate` list so a non-standard
+    // scheme (`ApiKey <secret>`, an unknown scheme, `AWS4-HMAC-SHA256 Credential=…`) no longer leaks
+    // its token beside the marker. Bounded to <scheme> + ONE credential token (two token runs max,
+    // separated by horizontal whitespace only — never a newline), so it can never swallow following
+    // prose the way the original `[^"]+` did. An optional value-quote is consumed so JSON
+    // `"Authorization":"…"` works too. Runs before the SigV4 and standalone-`Bearer` rules so a normal
+    // header collapses to a single marker; a SigV4 header's `Credential=…` is eaten here and its
+    // trailing `Signature=…` is mopped up by the next rule.
+    [
+        /(\bAuthorization["']?\s*[:=]\s*["']?)[A-Za-z0-9._~+/=-]+(?:[ \t]+[A-Za-z0-9._~+/=-]+)?/gi,
+        `$1${REDACTED}`,
+    ],
+    // GS2-54 (gap 1) — AWS SigV4 authorization components. The header is comma-separated `key=value`
+    // pairs; redact the SENSITIVE `Credential=…` (access-key id) and `Signature=…` values wherever they
+    // appear (header value OR a presigned-URL `X-Amz-Credential=…&X-Amz-Signature=…` query), keeping the
+    // key name for debuggability. `SignedHeaders=…` is just header names and is intentionally NOT
+    // touched. The value charset excludes whitespace/comma/quote/`&`, so it stops at the component
+    // boundary and never swallows the next pair or trailing prose.
+    [/\b(Credential|Signature)=[A-Za-z0-9._~+/=-]+/gi, `$1=${REDACTED}`],
+    // A standalone `Bearer <token>` — keep the scheme word, redact only the credential. A long opaque
+    // token is redacted ONLY in this auth context, never on its own (that is the entropy trap avoided).
+    [/\b(Bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi, `$1${REDACTED}`],
+];
+/**
+ * Collect the literal secret VALUES to substitute everywhere (technique 1), from two sources:
+ *  - process-env vars whose NAME matches {@link SECRET_ENV_NAME_RE}, PLUS the specific var(s) named
+ *    by any `apiKeyEnvironmentVariable` in the config;
+ *  - non-empty inline secret field values in the config (technique 3's field names), so a key pasted
+ *    inline is scrubbed wherever it *also* surfaces (transcript, log, env), not only in config.json.
+ *
+ * `env` is a PARAMETER — never read ambiently — so the pass is pure, reusable (GS2-48) and
+ * deterministic in tests. Values shorter than {@link MIN_SECRET_LITERAL_LENGTH} are skipped. The
+ * result is returned longest-first so an overlapping-substring secret can't leave a shorter one
+ * partially intact. Never throws (a hostile config getter is swallowed — patterns + structural
+ * masking still apply).
+ */
+export function collectSecretValues(config, env) {
+    const values = new Set();
+    const add = (v) => {
+        if (typeof v === 'string' && v.length >= MIN_SECRET_LITERAL_LENGTH)
+            values.add(v);
+    };
+    // (a) env vars whose NAME looks secret → their VALUE is a literal to scrub.
+    try {
+        for (const [name, value] of Object.entries(env ?? {})) {
+            if (SECRET_ENV_NAME_RE.test(name))
+                add(value);
+        }
+    }
+    catch {
+        // ignore — a broken env object is not fatal to redaction.
+    }
+    // (b) walk the config for `apiKeyEnvironmentVariable` (→ read that env var's value) and inline
+    //     secret-named field values.
+    const seen = new WeakSet();
+    const walk = (node, depth) => {
+        if (node === null || typeof node !== 'object' || depth > MAX_REDACT_DEPTH)
+            return;
+        if (seen.has(node))
+            return;
+        seen.add(node);
+        if (Array.isArray(node)) {
+            for (const item of node)
+                walk(item, depth + 1);
+            return;
+        }
+        for (const [key, value] of Object.entries(node)) {
+            if (key.toLowerCase() === 'apikeyenvironmentvariable' && typeof value === 'string') {
+                add(env?.[value]); // resolve the NAMED env var's VALUE (the var name itself is not a secret)
+            }
+            else if (SECRET_KEY_RE.test(key) && !NON_SECRET_KEY_NAMES.has(key.toLowerCase())) {
+                add(value);
+            }
+            walk(value, depth + 1);
+        }
+    };
+    try {
+        walk(config, 0);
+    }
+    catch {
+        // fail safe: a hostile getter threw — we simply have fewer literals; patterns + structural
+        // masking still cover the artifacts. Never rethrow (redaction must not break the dump).
+    }
+    return [...values].sort((a, b) => b.length - a.length);
+}
+/**
+ * Redact a STRING: substitute every known literal secret value (technique 1, longest-first), then
+ * apply the provider key/auth patterns (technique 2). Never throws — on any error it returns the
+ * fully-withheld marker (fail safe: redact MORE, never emit the raw text). Applying it twice is
+ * safe (re-redacting already-redacted text is a no-op).
+ */
+export function redactText(text, secrets) {
+    try {
+        let out = text;
+        for (const secret of secrets) {
+            if (secret)
+                out = out.split(secret).join(REDACTED); // literal — no regex escaping needed
+        }
+        for (const [re, replacement] of PROVIDER_PATTERNS) {
+            out = out.replace(re, replacement);
+        }
+        return out;
+    }
+    catch {
+        return REDACTED; // fail safe
+    }
+}
+/**
+ * Deep-redact an arbitrary value for serialization: mask the VALUES of secret-named fields
+ * (technique 3 — structure preserved: the key stays, only its value becomes the marker) and run
+ * {@link redactText} over every string leaf (techniques 1 + 2). Circular refs are broken; functions
+ * and bigints are rendered the way `safeStringify` would, so the result is JSON-safe. Pure — never
+ * mutates the input. `apiKeyEnvironmentVariable` is intentionally NOT masked (it is a var name).
+ *
+ * Intended for the CONFIG artifact (where field-name masking is wanted). Non-config artifacts use
+ * {@link redactText} over their stringified form instead (literal + pattern only), so a legitimate
+ * `token`/`secret`-named field in tool output is not blanket-masked.
+ */
+export function redactValue(value, secrets) {
+    const seen = new WeakSet();
+    const walk = (node, depth) => {
+        if (typeof node === 'string')
+            return redactText(node, secrets);
+        if (typeof node === 'function')
+            return `[Function: ${node.name || 'anonymous'}]`;
+        if (typeof node === 'bigint')
+            return node.toString();
+        if (node === null || typeof node !== 'object')
+            return node;
+        if (seen.has(node))
+            return '[Circular]';
+        if (depth > MAX_REDACT_DEPTH)
+            return '[Truncated]';
+        seen.add(node);
+        if (Array.isArray(node))
+            return node.map((item) => walk(item, depth + 1));
+        const out = {};
+        for (const [key, val] of Object.entries(node)) {
+            if (SECRET_KEY_RE.test(key) && !NON_SECRET_KEY_NAMES.has(key.toLowerCase())) {
+                out[key] = REDACTED; // mask the value, keep the key — shape is part of the debug signal
+            }
+            else {
+                out[key] = walk(val, depth + 1);
+            }
+        }
+        return out;
+    };
+    return walk(value, 0);
+}
+//# sourceMappingURL=redactSecrets.js.map

package/dist/utils/redactSecrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redactSecrets.js","sourceRoot":"","sources":["../../src/utils/redactSecrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,sFAAsF;AACtF,MAAM,CAAC,MAAM,QAAQ,GAAG,YAAY,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAEpC,kGAAkG;AAClG,MAAM,gBAAgB,GAAG,EAAE,CAAC;AAE5B;;;GAGG;AACH,MAAM,kBAAkB,GAAG,6CAA6C,CAAC;AAEzE;;;;;;GAMG;AACH,MAAM,aAAa,GAAG,6EAA6E,CAAC;AAEpG,kGAAkG;AAClG,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC;AAEpE;;;;;;GAMG;AACH,MAAM,iBAAiB,GAA6C;IAClE,+EAA+E;IAC/E,CAAC,mCAAmC,EAAE,QAAQ,CAAC;IAC/C,6BAA6B;IAC7B,CAAC,2BAA2B,EAAE,QAAQ,CAAC;IACvC,iBAAiB;IACjB,CAAC,2BAA2B,EAAE,QAAQ,CAAC;IACvC,kBAAkB;IAClB,CAAC,2BAA2B,EAAE,QAAQ,CAAC;IACvC,8FAA8F;IAC9F,mGAAmG;IACnG,gGAAgG;IAChG,gFAAgF;IAChF,CAAC,+BAA+B,EAAE,QAAQ,CAAC;IAC3C,iGAAiG;IACjG,oGAAoG;IACpG,CAAC,iCAAiC,EAAE,QAAQ,CAAC;IAC7C,6FAA6F;IAC7F,kGAAkG;IAClG,mGAAmG;IACnG,kGAAkG;IAClG,qBAAqB;IACrB,CAAC,iDAAiD,EAAE,KAAK,QAAQ,GAAG,CAAC;IACrE,8FAA8F;IAC9F,mGAAmG;IACnG,gGAAgG;IAChG,iGAAiG;IACjG,+FAA+F;IAC/F,gGAAgG;IAChG,sFAAsF;IACtF,mGAAmG;IACnG,6FAA6F;IAC7F,wDAAwD;IACxD;QACE,0FAA0F;QAC1F,KAAK,QAAQ,EAAE;KAChB;IACD,iGAAiG;IACjG,oGAAoG;IACpG,qGAAqG;IACrG,8FAA8F;IAC9F,+FAA+F;IAC/F,+DAA+D;IAC/D,CAAC,gDAAgD,EAAE,MAAM,QAAQ,EAAE,CAAC;IACpE,kGAAkG;IAClG,oGAAoG;IACpG,CAAC,uCAAuC,EAAE,KAAK,QAAQ,EAAE,CAAC;CAC3D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAe,EACf,GAAuC;IAEvC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IAEjC,MAAM,GAAG,GAAG,CAAC,CAAU,EAAQ,EAAE;QAC/B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,IAAI,yBAAyB;YAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACpF,CAAC,CAAC;IAEF,4EAA4E;IAC5E,IAAI,CAAC;QACH,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC;YACtD,IAAI,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,GAAG,CAAC,KAAK,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0DAA0D;IAC5D,CAAC;IAED,+FAA+F;IAC/F,iCAAiC;IACjC,MAAM,IAAI,GAAG,IAAI,OAAO,EAAU,CAAC;IACnC,MAAM,IAAI,GAAG,CAAC,IAAa,EAAE,KAAa,EAAQ,EAAE;QAClD,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,GAAG,gBAAgB;YAAE,OAAO;QAClF,IAAI,IAAI,CAAC,GAAG,CAAC,IAAc,CAAC;YAAE,OAAO;QACrC,IAAI,CAAC,GAAG,CAAC,IAAc,CAAC,CAAC;QACzB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,KAAK,MAAM,IAAI,IAAI,IAAI;gBAAE,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YAC/C,OAAO;QACT,CAAC;QACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAA+B,CAAC,EAAE,CAAC;YAC3E,IAAI,GAAG,CAAC,WAAW,EAAE,KAAK,2BAA2B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBACnF,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,0EAA0E;YAC/F,CAAC;iBAAM,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;gBACnF,GAAG,CAAC,KAAK,CAAC,CAAC;YACb,CAAC;YACD,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QACzB,CAAC;IACH,CAAC,CAAC;IACF,IAAI,CAAC;QACH,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,2FAA2F;QAC3F,wFAAwF;IAC1F,CAAC;IAED,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,OAA0B;IACjE,IAAI,CAAC;QACH,IAAI,GAAG,GAAG,IAAI,CAAC;QACf,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,MAAM;gBAAE,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,qCAAqC;QAC3F,CAAC;QACD,KAAK,MAAM,CAAC,EAAE,EAAE,WAAW,CAAC,IAAI,iBAAiB,EAAE,CAAC;YAClD,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,QAAQ,CAAC,CAAC,YAAY;IAC/B,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,OAA0B;IACpE,MAAM,IAAI,GAAG,IAAI,OAAO,EAAU,CAAC;IACnC,MAAM,IAAI,GAAG,CAAC,IAAa,EAAE,KAAa,EAAW,EAAE;QACrD,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC/D,IAAI,OAAO,IAAI,KAAK,UAAU;YAC5B,OAAO,cAAe,IAA0B,CAAC,IAAI,IAAI,WAAW,GAAG,CAAC;QAC1E,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;QACrD,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QAC3D,IAAI,IAAI,CAAC,GAAG,CAAC,IAAc,CAAC;YAAE,OAAO,YAAY,CAAC;QAClD,IAAI,KAAK,GAAG,gBAAgB;YAAE,OAAO,aAAa,CAAC;QACnD,IAAI,CAAC,GAAG,CAAC,IAAc,CAAC,CAAC;QACzB,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;QAC1E,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAA+B,CAAC,EAAE,CAAC;YACzE,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;gBAC5E,GAAG,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,mEAAmE;YAC1F,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC,CAAC;IACF,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AACxB,CAAC"}

package/dist/utils/systemPromptNotes.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Shared code-mode system-prompt augmentations (GS2-27).
+ *
+ * These notes describe capabilities that are IDENTICAL across both agent backends — the lean
+ * {@link import('#src/core/GthLangChainAgent.js').GthLangChainAgent} (`createAgent`, in core) and
+ * the deep `GthDeepAgent` (`createDeepAgent`, in `@gaunt-sloth/agent`): both expose the opt-in
+ * `run_shell_command` tool and both operate on the real filesystem cwd. They were originally
+ * composed ONLY inside `GthDeepAgent.init()` (EXT-13/EXT-26), so the now-default lean backend never
+ * received them — accidental deep-only drift of the same class GS2-21 fixed for the main prompt.
+ *
+ * They live here in core so BOTH backends compose from ONE source. `GthDeepAgent` re-exports them
+ * for back-compat with existing importers. The deepagents virtual-fs-namespace notes
+ * (`appendVirtualCwdNote` / `PATH_NAMESPACE_GUIDANCE` / the correction middleware) are NOT here:
+ * they are genuinely deep-only (a deepagents artifact — lean never runs virtualMode) and stay in
+ * `GthDeepAgent`.
+ */
+import type { McpServerInstruction } from '#src/core/types.js';
+/**
+ * EXT-26: the platform-agnostic tail shared by both {@link appendOsShellNote} branches.
+ *
+ * The recurring failure mode on non-POSIX hosts is not just wrong command NAMES but shell
+ * REDIRECTION quoting: a grouped/multi-line `echo` redirect on cmd.exe reported success yet wrote
+ * a 0-byte file. So on every platform we steer file creation/mutation to the built-in
+ * `write_file`/`edit_file` tools (which never touch the shell's quoting) and keep each shell
+ * command a single line. Kept short — this is prompt text an LLM reads, not documentation.
+ */
+export declare const OS_SHELL_GUIDANCE: string;
+/**
+ * EXT-26: append an OS + shell-dialect note to the composed code-mode system prompt.
+ *
+ * The model was never told its host OS or which shell `run_shell_command` uses, so on
+ * non-POSIX hosts it defaulted to POSIX idioms that fail (ran `ls` where cmd.exe has `dir`, a
+ * multi-line echo-redirect that wrote 0 bytes, a PowerShell here-string, `python -c` multi-line).
+ * This is ORTHOGONAL to the EXT-13/16/22 path-namespace notes: those say WHERE the model is (path
+ * form); this says WHAT shell it speaks (dialect). Backend-agnostic — the lean backend also exposes
+ * `run_shell_command`, so GS2-27 composes it in the shared path.
+ *
+ * The shell is derived from the SAME rule Node's `spawn(command, { shell: true })` uses — exactly
+ * how `run_shell_command` spawns (GthDevToolkit spawn) — so on `win32` it is cmd.exe (via
+ * `%ComSpec%`) and on POSIX it is `/bin/sh` (POSIX sh, NOT guaranteed bash). Computed from
+ * `process.platform` at call time so the text is correct per host. Returns the note alone when
+ * there is no base prompt. A single injection is authoritative (nothing in the base prompt
+ * contradicts shell dialect), so unlike EXT-22 no correction middleware is needed.
+ */
+export declare function appendOsShellNote(systemPrompt: string | undefined): string;
+/**
+ * EXT-13 (part b): append a real-cwd / path-model note to the composed code-mode system prompt.
+ *
+ * Code mode runs in REAL-path mode, so the filesystem tools and `run_shell_command` share one
+ * real-absolute-path namespace rooted at `cwd`. The shared `.gsloth.code.md` prompt already tells
+ * the model "the current working directory is provided to you separately"; this note is what
+ * provides it — without it the model assumes `/` is cwd and hands `/`-rooted paths to the real-fs
+ * shell. The cwd is injected dynamically (never baked into the .md). Backend-agnostic — the lean
+ * backend also runs real-fs code sessions and previously received NO cwd value, so GS2-27 composes
+ * it in the shared path. Returns the note alone when there is no base prompt.
+ */
+export declare function appendCwdNote(systemPrompt: string | undefined, cwd: string): string;
+/** GS2-35 — the configured Git co-author identity (both fields optional; each defaults on its own). */
+export interface CommitCoAuthor {
+    name?: string;
+    email?: string;
+}
+/**
+ * GS2-35: append the commit co-authoring rule to the composed code-mode system prompt.
+ *
+ * Gaunt Sloth has **no dedicated git-commit tool** — the agent commits by calling
+ * `run_shell_command` with `git commit`, composing the message (including any trailer) itself. Left
+ * unguided, models emit `Co-Authored-By: <their own model name>` (e.g. `Claude`, `GPT`, `Gemini`)
+ * from trained habit, which is **factually wrong**: the commit was produced by *Gaunt Sloth*, not by
+ * the model. This note is the fix at the correct layer — first-party prompt guidance that (a) states
+ * the exact trailer to emit and (b) forbids a model-name co-author.
+ *
+ * The identity is config-driven (`commit.coAuthor` in {@link import('#src/config/types.js').GthConfig}).
+ * Each field falls back INDEPENDENTLY to the Gaunt Sloth account
+ * ({@link DEFAULT_COMMIT_CO_AUTHOR_NAME} / {@link DEFAULT_COMMIT_CO_AUTHOR_EMAIL}) — so a partial
+ * override (name only, or a config that bypassed the loader) still yields a complete trailer, and a
+ * fully-absent config yields the default account. Blank/whitespace values are treated as unset.
+ *
+ * Backend-agnostic: composed through the shared code path so BOTH the lean `GthLangChainAgent` and
+ * the deep `GthDeepAgent` inject it (the git-commit capability rides on `run_shell_command`, which
+ * both backends expose in code mode). Returns the note alone when there is no base prompt.
+ */
+export declare function appendCommitCoAuthorNote(systemPrompt: string | undefined, coAuthor?: CommitCoAuthor): string;
+/**
+ * GS2-34/GS2-53 — the resolved active-model identity, as a STRUCTURED value.
+ *
+ * `hasProvider` is the authoritative "a real provider half was resolved" signal — carried
+ * explicitly rather than inferred from `identity.includes(':')`, because a bare model name can
+ * itself contain a colon (e.g. an Ollama/HF tag `gemma3:27b`) and would otherwise be mistaken for a
+ * `provider:model` string. It is true iff a non-empty provider (configured `type` OR a non-empty
+ * `_llmType()`) formed the leading `provider:` segment; false when `identity` is the bare model.
+ */
+export interface ResolvedModelIdentity {
+    /** `provider:model` when a provider resolved, otherwise the bare `model`. */
+    identity: string;
+    /** True iff a real provider formed the `provider:` segment (never merely a colon in the model). */
+    hasProvider: boolean;
+}
+/**
+ * GS2-34: resolve the active model identity from the effective config, for injection into the
+ * system prompt by {@link appendModelContextNote}.
+ *
+ * Both halves are read the SAME way the rest of gsloth already surfaces the active model:
+ *   - MODEL: `config.modelDisplayName` (the string the status line renders — set by the loader from
+ *     `llm.model`), falling back to the live model's own `model` field.
+ *   - PROVIDER: the configured `config.modelProviderType` (the raw `llm.type` the loader stashed —
+ *     `openrouter`/`deepseek`/`xai`/`anthropic`/…) when present, otherwise the live LangChain
+ *     model's `_llmType()` (the source the AG-UI `/info` endpoint reports). GS2-53 — preferring the
+ *     configured `type` fixes the OpenAI-compatible shims (openrouter/deepseek/xai all extend
+ *     ChatOpenAI, so their `_llmType()` reports `openai`): a `type: openrouter` config now injects
+ *     `openrouter:<model>`, not `openai:<model>`. The `type` is absent for module configs (which
+ *     hand us an already-built LLM), where we fall back to `_llmType()` unchanged. The MODEL half is
+ *     always exact.
+ *
+ * Returns `{ identity: 'provider:model', hasProvider: true }` when both resolve, `{ identity:
+ * 'model', hasProvider: false }` when only the model resolves, and `undefined` when the model is
+ * unknown (a provider with no model is not a usable identity) — in which case {@link
+ * appendModelContextNote} injects nothing, leaving the prompt exactly as before. `hasProvider` is
+ * the authoritative provider-present flag (GS2-53), so a bare model whose NAME contains a colon
+ * (e.g. `gemma3:27b`) is correctly reported as `hasProvider: false`. `_llmType()` is called
+ * defensively (guarded) so a provider whose accessor throws can never break prompt assembly (and is
+ * skipped entirely when a configured `type` is present).
+ */
+export declare function resolveModelIdentity(config: {
+    llm?: {
+        _llmType?: () => string;
+        model?: string;
+    };
+    modelDisplayName?: string;
+    modelProviderType?: string;
+} | null | undefined): ResolvedModelIdentity | undefined;
+/**
+ * GS2-34: append the active model-identity note to the composed system prompt.
+ *
+ * The agent otherwise has no reliable knowledge of which `provider:model` is serving it, so it
+ * cannot answer "what model are you?" accurately or reason about its own capabilities/limits. This
+ * injects a single first-party line naming the resolved identity (see {@link resolveModelIdentity}).
+ *
+ * Injected in EVERY mode (chat/ask/code/exec), NOT gated to `code` like the cwd/os-shell/commit
+ * notes: "which model are you?" can be asked in any session, so the identity must be visible
+ * everywhere. Config-gated by `injectModelContext` (default ON): a caller passes an `undefined`
+ * `modelIdentity` — because the config opted out (`injectModelContext: false`) or because no model
+ * could be resolved — and the base prompt is returned UNCHANGED (no line), preserving the current
+ * prompt byte-for-byte.
+ *
+ * A short capability note from the GS2-6 model catalog is a DEFERRED follow-up (GS2-6 has not
+ * landed): this injects the bare `provider:model` identity only.
+ */
+export declare function appendModelContextNote(systemPrompt: string | undefined, modelIdentity: ResolvedModelIdentity | undefined): string | undefined;
+/**
+ * EXT-32: hard per-server cap on injected MCP instruction length.
+ *
+ * A connected MCP server could advertise a very long `instructions` string that would then ride
+ * along in EVERY turn's system prompt and bloat context. This is a simple defensive constant (no
+ * config-schema plumbing — that stays out of this node): text beyond the cap is dropped and a
+ * truncation marker is appended so the model knows it was clipped. Generous enough that realistic
+ * server instructions pass through untouched.
+ */
+export declare const MCP_INSTRUCTIONS_MAX_CHARS_PER_SERVER = 4000;
+/** EXT-32: truncation marker appended when a server's instructions exceed the per-server cap. */
+export declare const MCP_INSTRUCTIONS_TRUNCATION_MARKER = "\u2026 [truncated]";
+/**
+ * EXT-32: append connected MCP servers' discovery `instructions` to the composed system prompt.
+ *
+ * Each connected MCP server may return an `instructions` string in its `initialize` handshake that
+ * describes how to use its tools. We surface those to the model — but the text is **server-supplied
+ * and therefore a prompt-injection surface**, so it is:
+ *   - fenced in an explicit `[BEGIN/END MCP SERVER-PROVIDED CONTEXT]` block (never blended into
+ *     first-party prompt text),
+ *   - labelled per server (`--- Server: "name" ---`) so the model can attribute each block, and
+ *   - bracketed by a leading framing line AND a trailing first-party reassertion, so the LAST thing
+ *     the model reads is gsloth's own authority, not the server text — server instructions may not
+ *     override the system instructions, safety rules, or the user's directives.
+ *
+ * Backend-agnostic: composed through the shared path so BOTH the lean `GthLangChainAgent` and the
+ * deep `GthDeepAgent` inject it. Empty/absent contributes NOTHING: when no server supplied
+ * (non-whitespace) instructions the base prompt is returned unchanged — no empty header, no dangling
+ * label. Each server's text is trimmed and capped at {@link MCP_INSTRUCTIONS_MAX_CHARS_PER_SERVER}.
+ * Returns the block alone when there is no base prompt.
+ */
+export declare function appendMcpServerInstructionsNote(systemPrompt: string | undefined, instructions: McpServerInstruction[] | undefined): string | undefined;