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

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

@@ -0,0 +1,75 @@
+/**
+ * @module core/shell/arity
+ *
+ * EXT-9 Tier-2 ergonomics: classify a shell command into a stable, human-readable
+ * **prefix** (binary + N meaningful subcommands) so an approval the human grants once
+ * (`git checkout main`) can be remembered as a pattern (`git checkout *`) and matched
+ * against later flag-variants (`git checkout -b foo bar`) WITHOUT re-prompting.
+ *
+ * The arity table (which tokens past the binary are "meaningful subcommands" rather
+ * than operands/flags) is a port of a subset of opencode's ~160-command table
+ * (`opencode/packages/opencode/src/permission/arity.ts`). Binaries not in the table
+ * default to arity 0 = just the binary.
+ *
+ * SECURITY — this is the anti-injection core. {@link classifyCommand} returns `null`
+ * (fail-closed) whenever the command contains shell composition that could change the
+ * target of the operation: separators (`;`, `&&`, `||`, `|`, `&`), newlines, command
+ * substitution (`$(...)`, backticks), process substitution (`<(...)`/`>(...)`), or
+ * redirections. Such commands NEVER auto-match an allow-list entry — they always go to
+ * fresh human approval. This is what stops `git checkout x; rm -rf /` from matching an
+ * approved `git checkout *`.
+ */
+/**
+ * Result of classifying a command for allow-list matching.
+ */
+export interface CommandClassification {
+    /**
+     * The meaningful command prefix — binary plus subcommands per the arity table, with
+     * flags removed. This is the allow-list KEY: two commands with the same prefix are the
+     * "same operation" for approval purposes (`git checkout main` and `git checkout -b x`
+     * both → `git checkout`).
+     */
+    prefix: string;
+    /**
+     * Human-facing display pattern, e.g. `git checkout *` (or `ls *`). The trailing `*`
+     * signals "any args/flags". A prefix that already consumed the whole command (no extra
+     * operands) still gets ` *` for a consistent, honest "future args allowed" affordance.
+     */
+    pattern: string;
+}
+/**
+ * Tokenize a shell command into argv, honoring single and double quotes. Quotes group
+ * (and are stripped from) a token; backslash-escaping inside double quotes is collapsed
+ * by the prior normalize step, so this tokenizer treats a residual `\` literally.
+ *
+ * This is a deliberately small tokenizer used ONLY for prefix detection — never for
+ * execution. The original command string is what runs.
+ *
+ * Returns `null` if quoting is unbalanced (an open quote with no close), which is itself
+ * a reason to refuse classification (ambiguous parse → fail-closed).
+ */
+export declare function tokenize(command: string): string[] | null;
+/**
+ * Look up the arity (number of leading meaningful tokens) for an argv, using the
+ * longest-matching-prefix rule against {@link ARITY}. Flag tokens (starting with `-`) are
+ * dropped when forming the candidate prefixes so boolean flags like `git --no-pager
+ * checkout` still resolve `git checkout`. Unknown binaries default to arity 0 → just the
+ * binary.
+ *
+ * LIMITATION (intentional, fail-closed): we do NOT maintain a per-flag arity table, so an
+ * arg-taking flag leaves its operand in the non-flag stream (e.g. `git -C . checkout` →
+ * `git .`). That simply fails to match an approved `git checkout` and re-prompts — safe, by
+ * design — rather than risking a mis-classification that mis-approves.
+ *
+ * Returns the list of meaningful tokens (binary + subcommands), flag tokens excluded.
+ */
+export declare function meaningfulPrefixTokens(argv: string[]): string[];
+/**
+ * Classify a command into a stable allow-list prefix + display pattern, or `null` when it
+ * cannot be safely classified for matching (composition/redirection/substitution present,
+ * empty, or unbalanced quotes).
+ *
+ * @param command Raw command string as the model proposed it.
+ * @param normalize Normalizer to apply for the detection form (inject normalizeCommand).
+ */
+export declare function classifyCommand(command: string, normalize: (cmd: string) => string): CommandClassification | null;

package/dist/core/shell/arity.js

@@ -0,0 +1,313 @@
+/**
+ * @module core/shell/arity
+ *
+ * EXT-9 Tier-2 ergonomics: classify a shell command into a stable, human-readable
+ * **prefix** (binary + N meaningful subcommands) so an approval the human grants once
+ * (`git checkout main`) can be remembered as a pattern (`git checkout *`) and matched
+ * against later flag-variants (`git checkout -b foo bar`) WITHOUT re-prompting.
+ *
+ * The arity table (which tokens past the binary are "meaningful subcommands" rather
+ * than operands/flags) is a port of a subset of opencode's ~160-command table
+ * (`opencode/packages/opencode/src/permission/arity.ts`). Binaries not in the table
+ * default to arity 0 = just the binary.
+ *
+ * SECURITY — this is the anti-injection core. {@link classifyCommand} returns `null`
+ * (fail-closed) whenever the command contains shell composition that could change the
+ * target of the operation: separators (`;`, `&&`, `||`, `|`, `&`), newlines, command
+ * substitution (`$(...)`, backticks), process substitution (`<(...)`/`>(...)`), or
+ * redirections. Such commands NEVER auto-match an allow-list entry — they always go to
+ * fresh human approval. This is what stops `git checkout x; rm -rf /` from matching an
+ * approved `git checkout *`.
+ */
+/**
+ * Arity table: command-prefix string → number of leading tokens (binary + subcommands,
+ * flags excluded) that define the "human-understandable command". Longest matching
+ * prefix wins. Ported subset of opencode's table — git/npm/pnpm/yarn/docker/kubectl/
+ * cargo/go/etc. Binaries absent here default to arity 0 (just the binary), see
+ * {@link arityFor}.
+ *
+ * Rule (from opencode): flags never count as tokens; only subcommands do. Include a
+ * longer prefix only when its arity differs from what the shorter prefix implies.
+ */
+const ARITY = {
+    // Single-token utilities (arity 1 = just the binary; here for completeness/clarity).
+    cat: 1,
+    cd: 1,
+    chmod: 1,
+    chown: 1,
+    cp: 1,
+    echo: 1,
+    env: 1,
+    export: 1,
+    grep: 1,
+    kill: 1,
+    killall: 1,
+    ln: 1,
+    ls: 1,
+    mkdir: 1,
+    mv: 1,
+    ps: 1,
+    pwd: 1,
+    rm: 1,
+    rmdir: 1,
+    sleep: 1,
+    source: 1,
+    tail: 1,
+    head: 1,
+    touch: 1,
+    unset: 1,
+    which: 1,
+    find: 1,
+    // Cloud / infra CLIs.
+    aws: 3,
+    az: 3,
+    bazel: 2,
+    brew: 2,
+    bun: 2,
+    'bun run': 3,
+    'bun x': 3,
+    cargo: 2,
+    'cargo add': 3,
+    'cargo run': 3,
+    cdk: 2,
+    cf: 2,
+    cmake: 2,
+    composer: 2,
+    consul: 2,
+    'consul kv': 3,
+    crictl: 2,
+    deno: 2,
+    'deno task': 3,
+    doctl: 3,
+    docker: 2,
+    'docker builder': 3,
+    'docker compose': 3,
+    'docker container': 3,
+    'docker image': 3,
+    'docker network': 3,
+    'docker volume': 3,
+    eksctl: 2,
+    'eksctl create': 3,
+    firebase: 2,
+    flyctl: 2,
+    gcloud: 3,
+    gh: 3,
+    git: 2,
+    'git config': 3,
+    'git remote': 3,
+    'git stash': 3,
+    go: 2,
+    gradle: 2,
+    helm: 2,
+    heroku: 2,
+    hugo: 2,
+    ip: 2,
+    'ip addr': 3,
+    'ip link': 3,
+    'ip netns': 3,
+    'ip route': 3,
+    kind: 2,
+    'kind create': 3,
+    kubectl: 2,
+    'kubectl kustomize': 3,
+    'kubectl rollout': 3,
+    kustomize: 2,
+    make: 2,
+    mc: 2,
+    'mc admin': 3,
+    minikube: 2,
+    mongosh: 2,
+    mysql: 2,
+    mvn: 2,
+    ng: 2,
+    npm: 2,
+    'npm exec': 3,
+    'npm init': 3,
+    'npm run': 3,
+    'npm view': 3,
+    npx: 2,
+    nvm: 2,
+    nx: 2,
+    openssl: 2,
+    'openssl req': 3,
+    'openssl x509': 3,
+    pip: 2,
+    pipenv: 2,
+    pnpm: 2,
+    'pnpm dlx': 3,
+    'pnpm exec': 3,
+    'pnpm run': 3,
+    poetry: 2,
+    podman: 2,
+    'podman container': 3,
+    'podman image': 3,
+    psql: 2,
+    pulumi: 2,
+    'pulumi stack': 3,
+    pyenv: 2,
+    python: 2,
+    python3: 2,
+    rake: 2,
+    rbenv: 2,
+    'redis-cli': 2,
+    rustup: 2,
+    serverless: 2,
+    sfdx: 3,
+    skaffold: 2,
+    sls: 2,
+    sst: 2,
+    swift: 2,
+    systemctl: 2,
+    terraform: 2,
+    'terraform workspace': 3,
+    tmux: 2,
+    turbo: 2,
+    ufw: 2,
+    vault: 2,
+    'vault auth': 3,
+    'vault kv': 3,
+    vercel: 2,
+    volta: 2,
+    wp: 2,
+    yarn: 2,
+    'yarn dlx': 3,
+    'yarn run': 3,
+};
+/**
+ * Tokens / sequences whose presence means the command composes or redirects in a way that
+ * could change what actually runs — so it must NOT be classifiable for auto-match. Checked
+ * against the NORMALIZED command (see normalize.ts) which has already collapsed obfuscation.
+ *
+ * Note: `&&`/`||`/`|` are covered by the bare `&`/`|` character scan; listed conceptually.
+ */
+function hasUnsafeComposition(normalized) {
+    // Newlines are folded by normalizeCommand, but guard anyway in case a raw string is passed.
+    if (/[\n\r]/.test(normalized))
+        return true;
+    // Shell control / separator operators and background.
+    if (/[;|&]/.test(normalized))
+        return true;
+    // Command substitution: $(...) or `...`.
+    if (/\$\(/.test(normalized))
+        return true;
+    if (/`/.test(normalized))
+        return true;
+    // Variable/arith expansion that could inject: ${...} and $((...)).
+    if (/\$\{/.test(normalized))
+        return true;
+    // Process substitution: <(...) or >(...).
+    if (/[<>]\(/.test(normalized))
+        return true;
+    // Redirections (any < or > not already caught as process substitution): >, >>, <, 2>, &>.
+    if (/[<>]/.test(normalized))
+        return true;
+    return false;
+}
+/**
+ * Tokenize a shell command into argv, honoring single and double quotes. Quotes group
+ * (and are stripped from) a token; backslash-escaping inside double quotes is collapsed
+ * by the prior normalize step, so this tokenizer treats a residual `\` literally.
+ *
+ * This is a deliberately small tokenizer used ONLY for prefix detection — never for
+ * execution. The original command string is what runs.
+ *
+ * Returns `null` if quoting is unbalanced (an open quote with no close), which is itself
+ * a reason to refuse classification (ambiguous parse → fail-closed).
+ */
+export function tokenize(command) {
+    const tokens = [];
+    let current = '';
+    let inToken = false;
+    let quote = null;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = null;
+            }
+            else {
+                current += ch;
+            }
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            inToken = true;
+            continue;
+        }
+        if (ch === ' ' || ch === '\t') {
+            if (inToken) {
+                tokens.push(current);
+                current = '';
+                inToken = false;
+            }
+            continue;
+        }
+        current += ch;
+        inToken = true;
+    }
+    if (quote)
+        return null; // unbalanced quote
+    if (inToken)
+        tokens.push(current);
+    return tokens;
+}
+/**
+ * Look up the arity (number of leading meaningful tokens) for an argv, using the
+ * longest-matching-prefix rule against {@link ARITY}. Flag tokens (starting with `-`) are
+ * dropped when forming the candidate prefixes so boolean flags like `git --no-pager
+ * checkout` still resolve `git checkout`. Unknown binaries default to arity 0 → just the
+ * binary.
+ *
+ * LIMITATION (intentional, fail-closed): we do NOT maintain a per-flag arity table, so an
+ * arg-taking flag leaves its operand in the non-flag stream (e.g. `git -C . checkout` →
+ * `git .`). That simply fails to match an approved `git checkout` and re-prompts — safe, by
+ * design — rather than risking a mis-classification that mis-approves.
+ *
+ * Returns the list of meaningful tokens (binary + subcommands), flag tokens excluded.
+ */
+export function meaningfulPrefixTokens(argv) {
+    // Drop leading flags before the binary cannot happen (binary is first), but a binary
+    // can be followed by flags interleaved with subcommands (e.g. `git -C . checkout`).
+    // Build the flag-free token sequence first, preserving order.
+    const nonFlag = argv.filter((t) => !t.startsWith('-'));
+    if (nonFlag.length === 0)
+        return [];
+    // Longest matching prefix in the arity table wins.
+    for (let len = nonFlag.length; len > 0; len--) {
+        const candidate = nonFlag.slice(0, len).join(' ');
+        const arity = ARITY[candidate];
+        if (arity !== undefined) {
+            // arity counts meaningful tokens from the start of the non-flag sequence.
+            return nonFlag.slice(0, Math.min(arity, nonFlag.length));
+        }
+    }
+    // Not in the table → arity 0 means "just the binary".
+    return nonFlag.slice(0, 1);
+}
+/**
+ * Classify a command into a stable allow-list prefix + display pattern, or `null` when it
+ * cannot be safely classified for matching (composition/redirection/substitution present,
+ * empty, or unbalanced quotes).
+ *
+ * @param command Raw command string as the model proposed it.
+ * @param normalize Normalizer to apply for the detection form (inject normalizeCommand).
+ */
+export function classifyCommand(command, normalize) {
+    const normalized = normalize(command);
+    if (!normalized)
+        return null;
+    // FAIL-CLOSED on any composition/redirection/substitution. This is the anti-injection
+    // guarantee: such commands never auto-match an allow-list entry.
+    if (hasUnsafeComposition(normalized))
+        return null;
+    const argv = tokenize(normalized);
+    if (!argv || argv.length === 0)
+        return null;
+    const prefixTokens = meaningfulPrefixTokens(argv);
+    if (prefixTokens.length === 0)
+        return null;
+    const prefix = prefixTokens.join(' ');
+    return { prefix, pattern: `${prefix} *` };
+}
+//# sourceMappingURL=arity.js.map

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

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

package/dist/core/shell/judge.d.ts

@@ -0,0 +1,161 @@
+/**
+ * @module core/shell/judge
+ *
+ * EXT-10 — LLM-as-judge bash-safety gate. An optional, opt-in pre-filter that sits *in front
+ * of* the human approval prompt for `run_shell_command` (EXT-9). It is a tiered
+ * fatigue-reducer, NOT merely a blocker: clearly-safe commands auto-approve, the rest escalate
+ * to the human, and clearly-catastrophic ones may be rejected outright. Default OFF — it costs
+ * one LLM call per command — opt-in via {@link GthDevToolsConfig.shell}'s `judge` knob.
+ *
+ * Validated prior art (both place the judge in front of the human prompt as an auto-approve
+ * fatigue-reducer): openclaw `exec-auto-reviewer.ts` and hermes-agent `approval.py` "smart" mode.
+ *
+ * Two hardening guarantees are baked in here:
+ *
+ * 1. **Prompt-injection defense.** The command is attacker-controlled text. It is normalized
+ *    (reusing {@link normalizeCommand} + home-path folding) and embedded inside an XML
+ *    `<command_to_evaluate>` tag, behind a preamble that states the tagged text is UNTRUSTED
+ *    DATA to be analyzed, never instructions to follow. See {@link buildJudgePrompt}.
+ * 2. **Fail-closed on error.** If the LLM call throws, times out, or returns unparseable
+ *    output, the verdict returned NEVER auto-approves — it is `high`/escalate. A judge failure
+ *    can never silently green-light a command. See {@link FAIL_CLOSED_VERDICT}.
+ *
+ * Fail-closed-on-AMBIGUITY (when the command's target can't be statically resolved) lives in the
+ * decision mapping ({@link mapVerdictToAction}), not here, so it applies regardless of what the
+ * judge says.
+ *
+ * Mirrors the QA-3 judge substrate (`packages/review/src/middleware/reviewRateMiddleware.ts`):
+ * structured-output evaluation over `config.llm`, wrapped in try/catch.
+ */
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import * as z from 'zod';
+import type { GthConfig } from '#src/config.js';
+/**
+ * Structured verdict the judge model must return. Kept small and conservative:
+ * - `risk` is the primary tier driving the decision (low → auto-approve, medium/high → escalate).
+ * - `destructive` flags data-loss / irreversible operations (rm, drop, format, force-push, …).
+ * - `outOfScope` flags actions outside the current project/work (network exfil, system mutation,
+ *   touching paths well outside cwd) — a signal to escalate even when not strictly destructive.
+ * - `reason` is one short sentence surfaced to the human when escalating.
+ */
+export declare const ShellSafetyVerdictSchema: z.ZodObject<{
+    risk: z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>;
+    destructive: z.ZodBoolean;
+    outOfScope: z.ZodBoolean;
+    reason: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The judge's structured verdict on a single shell command.
+ */
+export type ShellSafetyVerdict = z.infer<typeof ShellSafetyVerdictSchema>;
+/**
+ * The verdict returned whenever the judge cannot produce a trustworthy answer (LLM throws,
+ * times out, or returns unparseable output). Fail-closed: `high` + escalate, never auto-approve.
+ */
+export declare const FAIL_CLOSED_VERDICT: ShellSafetyVerdict;
+/**
+ * Default wall-clock budget (ms) for the judge LLM call. Kept low so a slow/hung judge can't
+ * wedge the approval flow — on timeout we fail closed and escalate. Mirrors openclaw's low
+ * exec-reviewer timeout minimum.
+ */
+export declare const JUDGE_DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * System preamble for the judge. States the role, the untrusted-input contract (the tagged
+ * command is DATA, not instructions), and the bias toward escalation when unsure. Patterned
+ * after openclaw's `DEFAULT_EXEC_REVIEWER_SYSTEM_PROMPT` and hermes' untrusted-input framing.
+ */
+export declare const JUDGE_SYSTEM_PROMPT: string;
+/**
+ * Detect whether the command invokes an interpreter on a script target AND passes an
+ * `$ALL_CAPS` shell-variable expansion in its arguments — openclaw's "script preflight". Such a
+ * command can leak environment (often secrets) into the script, so it should bias toward
+ * escalation. Lightweight heuristic over the normalized command; a positive flag is fed to the
+ * judge prompt AND forces escalation in the decision mapping.
+ *
+ * @returns true when an interpreter+script invocation also expands an ALL_CAPS env var.
+ */
+export declare function hasScriptEnvLeakRisk(normalizedCommand: string): boolean;
+/**
+ * Fold an absolute home path to `~` so the judge sees a stable, less-identifying form (mirrors
+ * hermes `_normalize_command_for_detection` path folding). Best-effort: only the literal home
+ * dir prefix is folded.
+ */
+export declare function foldHomePath(command: string, home: string | undefined): string;
+/**
+ * Build the messages for the judge call: a system preamble ({@link JUDGE_SYSTEM_PROMPT}) plus a
+ * human message that embeds the NORMALIZED command inside an XML `<command_to_evaluate>` tag and
+ * (optionally) notes the script-env-leak preflight flag. The command text is only ever DATA in
+ * the tag — the builder never executes or interpolates it as instructions.
+ *
+ * Exposed (and returning plain strings) so tests can assert the structure: the tag is present,
+ * the untrusted-input preamble is present, and an injection string inside the command lands
+ * inside the tag rather than being acted on.
+ */
+export declare function buildJudgePrompt(command: string, options?: {
+    home?: string;
+}): {
+    system: string;
+    user: string;
+};
+/**
+ * Vet a single shell command with the judge model and return a structured {@link ShellSafetyVerdict}.
+ *
+ * - Builds an injection-hardened, normalized prompt ({@link buildJudgePrompt}).
+ * - Calls the judge model (defaults to `config.llm`) via `withStructuredOutput(schema)`.
+ * - Races the call against {@link JUDGE_DEFAULT_TIMEOUT_MS}.
+ * - **Fail-closed:** any throw / timeout / parse failure returns {@link FAIL_CLOSED_VERDICT}
+ *   (`high`/escalate), never an auto-approve.
+ *
+ * Note: this only produces a verdict; the auto-approve / escalate / reject decision (including
+ * fail-closed-on-ambiguity) is made by {@link mapVerdictToAction} in the runner.
+ */
+export declare function judgeShellCommand(command: string, config: GthConfig, options?: {
+    model?: BaseChatModel;
+    home?: string;
+    timeoutMs?: number;
+}): Promise<ShellSafetyVerdict>;
+/**
+ * The action the judge gate resolves to for a single command, BEFORE the human prompt.
+ * - `auto-approve` — clearly safe; approve once, do NOT touch the human or the allow-list.
+ * - `escalate` — fall through to the existing human approval callback (carrying the verdict).
+ * - `reject` — refuse outright without prompting (reserved for clearly-catastrophic verdicts).
+ */
+export type JudgeAction = 'auto-approve' | 'escalate' | 'reject';
+/**
+ * Behaviour knobs for the decision mapping, derived from config with safe defaults.
+ */
+export interface JudgeDecisionOptions {
+    /** Auto-approve `low`-risk, non-ambiguous, non-flagged commands. Default true. */
+    autoApproveLow: boolean;
+    /**
+     * Reject (without prompting) a clearly-catastrophic verdict (`high` + `destructive`). Default
+     * false — keep the gate conservative; EXT-9's hardline floor already refuses truly
+     * catastrophic commands at exec time, so the judge's main jobs are auto-approve-low + escalate.
+     */
+    blockHigh: boolean;
+}
+/**
+ * Pure, testable mapping from a {@link ShellSafetyVerdict} + ambiguity to a {@link JudgeAction}.
+ *
+ * Order of precedence (fail-closed first):
+ * 1. **Fail-closed on ambiguity:** when {@link classifyCommand} returns null — the command
+ *    composes / substitutes / redirects so its target can't be statically resolved — NEVER
+ *    auto-approve. Escalate (or reject if `blockHigh` and the verdict is catastrophic). This is
+ *    enforced regardless of what the judge said, so an unresolvable command can't be slipped
+ *    through by a manipulated `low` verdict.
+ * 2. **Script-env-leak preflight:** if the (normalized) command leaks an ALL_CAPS env var into a
+ *    script/interpreter, never auto-approve — escalate.
+ * 3. `blockHigh` + catastrophic (`high` + `destructive`) → reject.
+ * 4. `low` + autoApproveLow + not ambiguous + not flagged → auto-approve.
+ * 5. otherwise → escalate.
+ *
+ * @param command The raw command string (used to recompute ambiguity + preflight independently
+ *   of the judge, so the gate is robust even if the judge is wrong).
+ * @param verdict The judge's verdict (or the fail-closed verdict).
+ * @param opts Behaviour knobs.
+ */
+export declare function mapVerdictToAction(command: string, verdict: ShellSafetyVerdict, opts: JudgeDecisionOptions): JudgeAction;