@kodax-ai/kodax 0.7.50 → 0.7.52

package/dist/types-chunks/guardrail.d-B18oO1gt.d.ts

@@ -0,0 +1,518 @@
+import { M as McpConnectMode, a as McpServerConfig, b as McpServersConfig, c as McpTransportKind } from './config.d-CJy1WENT.js';
+import { f as KodaXBaseProvider } from './base.d-BBNUF9nz.js';
+import { a as CostTracker } from './cost-tracker.d-wRtyEW9d.js';
+import { aG as RunnerToolCall } from './process.d-Bj82oJhD.js';
+import { f as ToolGuardrail } from './types.d-D4jL-gAA.js';
+
+/**
+ * FEATURE_200 Phase F (v0.7.45) — MCP domain types extracted from types.ts.
+ * Thin KodaX-facing aliases over the @kodax-ai/agent MCP types. Re-exported
+ * from ../types.ts so all `../types` importers are unaffected.
+ */
+
+type KodaXMcpTransport = McpTransportKind;
+type KodaXMcpConnectMode = McpConnectMode;
+type KodaXMcpServerConfig = McpServerConfig;
+/** Flat map of MCP server configs, keyed under `mcpServers` in config.json. */
+type KodaXMcpServersConfig = McpServersConfig;
+
+/**
+ * AGENTS.md - Project-level AI Context Rules Loader
+ *
+ * This module implements loading of project-level context rules from AGENTS.md files,
+ * inspired by pi-mono's implementation.
+ *
+ * Priority: global < root < ... < current directory < .kodax/
+ */
+interface AgentsFile {
+    path: string;
+    content: string;
+    scope: 'global' | 'project' | 'directory';
+}
+interface LoadAgentsOptions {
+    /** Pass cwd explicitly for deterministic prompt building; process.cwd() is only a legacy fallback. */
+    cwd?: string;
+    kodaxDir?: string;
+    projectRoot?: string;
+}
+/**
+ * Get KodaX global directory.
+ *
+ * Routes through {@link getAgentConfigHome} (v0.7.35.1 FEATURE_145 3-tier
+ * resolution: programmatic override > KODAX_HOME env > ~/.kodax default).
+ */
+declare function getKodaxGlobalDir(): string;
+/**
+ * Load all AGENTS files
+ * Priority: global < root < ... < current directory < .kodax/
+ */
+declare function loadAgentsFiles(options?: LoadAgentsOptions): AgentsFile[];
+/**
+ * Format AGENTS files for system prompt
+ */
+declare function formatAgentsForPrompt(files: AgentsFile[]): string;
+
+/**
+ * Auto-Mode Rules Loader — FEATURE_092 Phase 2b.2 (v0.7.33).
+ *
+ * Three-layer trust model for `auto-rules.jsonc` files consumed by the
+ * auto-mode classifier:
+ *
+ *   1. ~/.kodax/auto-rules.jsonc                  — user-level, always trusted
+ *   2. <project>/.kodax/auto-rules.jsonc          — shared, opt-in (sha256 fingerprint)
+ *   3. <project>/.kodax/auto-rules.local.jsonc    — workspace-local, gitignored, trusted
+ *
+ * Why opt-in for the shared file: a malicious PR could land an
+ * `auto-rules.jsonc` claiming "allow any curl" and the user wouldn't
+ * notice. First-checkout opt-in via fingerprint forces the user to
+ * acknowledge the file by content. If the fingerprint changes later,
+ * the file is silently skipped until re-trusted — failures favor safety.
+ *
+ * Schema (each field optional, defaults to []):
+ *   {
+ *     "allow":       string[],   // patterns the classifier defaults to allowing
+ *     "soft_deny":   string[],   // patterns the classifier defaults to blocking
+ *     "environment": string[]    // background context the classifier sees verbatim
+ *   }
+ *
+ * Merge: layers concatenated in order (user → project → local). Identical
+ * strings deduplicated by stable insertion (later layers win position only
+ * when the string is unique per layer).
+ */
+interface AutoRules {
+    readonly allow: readonly string[];
+    readonly soft_deny: readonly string[];
+    readonly environment: readonly string[];
+}
+type RulesOrigin = 'user' | 'project' | 'local';
+interface LoadedRulesSource {
+    readonly origin: RulesOrigin;
+    readonly path: string;
+    readonly fingerprint: string;
+}
+interface SkippedRulesSource {
+    readonly origin: 'project';
+    readonly path: string;
+    readonly fingerprint: string;
+    readonly reason: 'untrusted' | 'fingerprint-changed';
+}
+interface RulesLoadError {
+    readonly path: string;
+    readonly message: string;
+}
+interface RulesLoadResult {
+    readonly merged: AutoRules;
+    readonly sources: readonly LoadedRulesSource[];
+    readonly skipped: readonly SkippedRulesSource[];
+    readonly errors: readonly RulesLoadError[];
+}
+interface LoadAutoRulesOptions {
+    readonly userKodaxDir: string;
+    readonly projectRoot: string;
+}
+interface TrustState {
+    readonly trusted: Readonly<Record<string, string>>;
+}
+declare function computeRulesFingerprint(content: string): string;
+declare function readTrustState(userKodaxDir: string): Promise<TrustState>;
+interface TrustOptions {
+    readonly userKodaxDir: string;
+}
+declare function trustProjectRules(rulesPath: string, fingerprint: string, opts: TrustOptions): Promise<void>;
+type ParseAutoRulesResult = {
+    readonly ok: true;
+    readonly rules: AutoRules;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+declare function parseAutoRules(src: string): ParseAutoRulesResult;
+declare function loadAutoRules(opts: LoadAutoRulesOptions): Promise<RulesLoadResult>;
+
+/**
+ * Tool-Call Signals — FEATURE_158 Step 2 (v0.7.39).
+ *
+ * Mechanical pattern matches over a tool call. Signals are NOT verdicts;
+ * the classifier consumes them as informational input alongside transcript
+ * + user rules and produces the final decision (allow / block / escalate).
+ *
+ * Two invariants the producers must hold:
+ *
+ *   1. **Pure**: same `call` + `projectRoot` ⇒ same signals. No I/O, no
+ *      timestamps, no env reads inside collectors. Collectors run on every
+ *      non-Tier-1 tool call, so they must be cheap and deterministic.
+ *
+ *   2. **Fact-only**: a `protected_path` signal says "this command names
+ *      path X which is under ~/.kodax/", not "this should be blocked".
+ *      Severity stays on the producer side (e.g. `dangerous_pattern.severity`)
+ *      so the classifier can weight signals, but the verdict is not encoded
+ *      here.
+ *
+ * Tier 0 (absolute deny) is a separate module — signals are pre-verdict
+ * material consumed by Tier 2 (LLM classifier). The two paths are not
+ * coupled: Tier 0 catches a fixed catastrophic-pattern set; signals
+ * describe a wider surface for the classifier to reason about.
+ *
+ * Design ref: ADR-025, FEATURE_158 (docs/features/v0.7.39.md).
+ */
+
+/**
+ * One mechanical signal about a tool call. Discriminated union — consumers
+ * narrow on `kind` to access the kind-specific fields.
+ */
+type ToolCallSignal = {
+    readonly kind: 'dangerous_pattern';
+    /** Pattern source (e.g. regex .source) that matched. */
+    readonly pattern: string;
+    /**
+     * Severity hint for the classifier.
+     *   `high`   — destructive intent typical (e.g. `git push --force`,
+     *              `chmod 777`, `curl | bash`). Classifier should lean
+     *              toward escalate/block.
+     *   `medium` — risk-shaped but contextual (e.g. broad `rm`, `sudo`).
+     *              Classifier weighs against transcript context.
+     */
+    readonly severity: 'high' | 'medium';
+} | {
+    readonly kind: 'protected_path';
+    /** Path token that triggered the match (as it appeared in the call). */
+    readonly path: string;
+    /**
+     *   `project-kodax` — under `<projectRoot>/.kodax/`
+     *   `user-kodax`    — under `~/.kodax/` (credentials zone)
+     */
+    readonly zone: 'project-kodax' | 'user-kodax';
+} | {
+    readonly kind: 'outside_project';
+    readonly path: string;
+} | {
+    readonly kind: 'shell_redirect_outside';
+    /** Redirection target path (`>`, `>>`, `tee` etc.). */
+    readonly target: string;
+} | {
+    readonly kind: 'package_install';
+    readonly manager: 'npm' | 'pnpm' | 'yarn' | 'pip' | 'cargo' | 'apt' | 'brew';
+} | {
+    readonly kind: 'git_write';
+    readonly verb: 'commit' | 'push' | 'reset' | 'clean' | 'rebase' | 'cherry-pick' | 'revert';
+} | {
+    readonly kind: 'network';
+    readonly tool: 'curl' | 'wget' | 'fetch';
+} | {
+    readonly kind: 'file_modification';
+    readonly targets: readonly string[];
+};
+/**
+ * Pulls signals from one tool call. A collector declares which tool names
+ * it applies to via `toolNames`; the dispatcher in `collectAllSignals`
+ * skips non-matching collectors so each one only sees calls it was
+ * designed for.
+ *
+ * `collect` returns the signals; an empty array is fine and the common
+ * case for benign calls.
+ */
+interface SignalCollector {
+    /**
+     * Tool names this collector reacts to (lowercase). Other tool names
+     * never reach `collect`. Empty set = matches nothing (effectively
+     * disabled — useful only for tests).
+     */
+    readonly toolNames: ReadonlySet<string>;
+    /**
+     * Inspect the call and produce zero or more signals.
+     *
+     * Must be pure: no I/O, no timing, no global state reads. The
+     * `projectRoot` argument is the only environmental context — pass
+     * the same value through every call site to keep results stable.
+     */
+    collect(call: RunnerToolCall, projectRoot: string): readonly ToolCallSignal[];
+}
+/**
+ * Run every applicable collector on `call` and return the merged signal
+ * list. Order preserved: collectors run in array order; per-collector
+ * signal order preserved within their slice.
+ *
+ * Duplicates intentionally not deduped here — different collectors may
+ * legitimately surface the same kind for different reasons (e.g. a
+ * `protected_path` from a bash redirect target AND a `protected_path`
+ * from an argv token in the same command). The classifier prompt
+ * tolerates duplicates; dedup would risk dropping load-bearing context.
+ */
+declare function collectAllSignals(call: RunnerToolCall, projectRoot: string, collectors: readonly SignalCollector[]): readonly ToolCallSignal[];
+
+/**
+ * Denial Tracker — FEATURE_092 Phase 2b.4 (v0.7.33).
+ *
+ * Tracks classifier blocks per session. When either threshold is crossed,
+ * the auto-mode engine downgrades from `llm` to `rules` (mode stays `auto`).
+ *
+ *   - 3 consecutive blocks → likely an unproductive loop (agent not adapting)
+ *   - 20 cumulative blocks → broader classifier-noise pattern in this session
+ *
+ * Both are session-scoped, shared with subagents (per design doc, to defend
+ * against threshold-bypass via spawning).
+ *
+ * Pure functional API: each operation returns a new tracker. No mutation.
+ */
+declare const CONSECUTIVE_THRESHOLD = 3;
+declare const CUMULATIVE_THRESHOLD = 20;
+interface DenialTracker {
+    readonly consecutive: number;
+    readonly cumulative: number;
+}
+declare function createDenialTracker(): DenialTracker;
+declare function recordBlock(t: DenialTracker): DenialTracker;
+declare function recordAllow(t: DenialTracker): DenialTracker;
+declare function shouldFallback$1(t: DenialTracker): boolean;
+
+/**
+ * Circuit Breaker — FEATURE_092 Phase 2b.4 (v0.7.33).
+ *
+ * Sliding-window error counter for classifier failures (timeouts, 5xx, 429,
+ * unparseable outputs). When ≥ 5 errors land within a 10-minute window, the
+ * auto-mode engine downgrades from `llm` to `rules` (mode stays `auto`) so
+ * the user is not blocked by a degraded classifier path.
+ *
+ * Pure functional API: each operation returns a new breaker. No mutation.
+ * Memory bound: stale timestamps are pruned on each recordError call so
+ * the timestamps array never grows unbounded.
+ */
+declare const ERROR_THRESHOLD = 5;
+declare const WINDOW_MS: number;
+interface CircuitBreaker {
+    readonly timestamps: readonly number[];
+}
+declare function createCircuitBreaker(): CircuitBreaker;
+declare function recordError(b: CircuitBreaker, now: number): CircuitBreaker;
+declare function shouldFallback(b: CircuitBreaker, now: number): boolean;
+
+/**
+ * AutoModeToolGuardrail — FEATURE_092 Phase 2b.6 (v0.7.33).
+ *
+ * Assembles the auto-mode classifier modules (rules + projection +
+ * classify + denial-tracker + circuit-breaker + model-resolver) into a
+ * `ToolGuardrail` that the Runner calls via `beforeTool` on every
+ * tool invocation.
+ *
+ * Decision flow (per design doc "三层权限金字塔"):
+ *
+ *   1. Tool projection is '' (Tier 1)        → allow (zero token cost)
+ *   2. Engine has been downgraded to rules   → escalate (user confirms)
+ *   3. denialTracker.shouldFallback (3/20)   → engine downgrade, then escalate
+ *   4. circuitBreaker.shouldFallback (5/10m) → engine downgrade, then escalate
+ *   5. classify(...) sideQuery
+ *        allow                               → allow (record allow → reset consecutive)
+ *        block                               → block + reason (record block)
+ *        escalate                            → escalate + reason (record error)
+ *        AbortError thrown                   → re-throw (propagate user cancel)
+ *
+ * State (mutable, session-scoped):
+ *   - engine: 'llm' | 'rules' (starts at 'llm', downgrades on threshold)
+ *   - denialTracker (immutable type, swapped on each event)
+ *   - circuitBreaker (immutable type, swapped on each event)
+ *
+ * Subagent sharing:
+ *   The factory accepts an optional `sharedState` ref; passing the same ref
+ *   to a subagent's guardrail means denial / circuit / engine state is
+ *   shared (per design doc "防绕阈值"). Without it each guardrail is
+ *   independent.
+ *
+ * Capability check, Tier 2 path-shortcuts, and the explicit
+ * `supportsAutoModeClassifier` provider flag are deferred to follow-up
+ * phases — v1 of the guardrail relies on Tier 1 (projection==='') as the
+ * structural opt-out and forwards everything else to the classifier.
+ */
+
+type AutoModeEngine = 'llm' | 'rules';
+interface AutoModeSharedState {
+    engine: AutoModeEngine;
+    denials: DenialTracker;
+    breaker: CircuitBreaker;
+}
+/**
+ * User answer for an escalated tool-call. The guardrail translates this into
+ * the actual `GuardrailVerdict` returned to the Runner. `'block'` preserves
+ * the original escalation reason as the verdict reason so downstream consumers
+ * see why the tool was blocked.
+ */
+type AutoModeAskUserVerdict = 'allow' | 'block';
+/**
+ * Optional REPL-supplied prompt callback for the 6 escalate paths in
+ * `beforeTool` (engine-downgraded, denial-threshold-just-crossed,
+ * breaker-just-tripped, classifier-error, classifier-decision-escalate,
+ * provider-not-configured). When supplied, the guardrail calls this and
+ * translates the user's answer into `'allow'` or `'block'`. When NOT
+ * supplied, the guardrail returns `'escalate'` as before — the Runner will
+ * then throw `GuardrailEscalateError` (preserves backward compat with
+ * SDK-side guardrail consumers that have no askUser surface).
+ *
+ * Rejection propagates: if the user cancels (Ctrl-C in the prompt), throw
+ * an AbortError-shaped exception and the Runner aborts the run cleanly.
+ */
+type AutoModeAskUser = (call: RunnerToolCall, reason: string, 
+/**
+ * FEATURE_158 (v0.7.39): static-analysis signals collected for this tool
+ * call. Optional + readonly so existing callers without signal-aware UI
+ * keep working. REPL uses these to render Scope/Risk labels on the
+ * confirm dialog (replacing the input-marker path from FEATURE_066).
+ */
+signals?: readonly ToolCallSignal[]) => Promise<AutoModeAskUserVerdict>;
+interface AutoModeGuardrailConfig {
+    readonly rules: AutoRules;
+    readonly claudeMd?: string;
+    /**
+     * FEATURE_092 phase 2b.7b: optional user-prompt callback for escalate
+     * paths. See `AutoModeAskUser` for semantics.
+     */
+    readonly askUser?: AutoModeAskUser;
+    /**
+     * Look up a tool's `toClassifierInput` projection by tool name.
+     * Returns `undefined` when the tool isn't in the registry — guardrail
+     * treats that as "no projection ⇒ Tier 1 skip" (conservative for
+     * unknown tools is debatable; v1 favors not blocking on noise).
+     */
+    readonly getToolProjection: (toolName: string) => ((input: unknown) => string) | undefined;
+    /**
+     * Resolve a provider name to an instance. Returns `undefined` when
+     * unconfigured / unknown — the guardrail then escalates.
+     */
+    readonly resolveProvider: (providerName: string) => KodaXBaseProvider | undefined;
+    readonly defaultProvider: string;
+    readonly defaultModel: string;
+    /**
+     * FEATURE_092 v0.7.34 hotfix-3 — defaultProvider/defaultModel staleness fix.
+     *
+     * When supplied, these are called on EVERY classify() invocation, so the
+     * classifier follows the user's current main session provider/model even
+     * after `/model` or `/provider` mid-session swaps. Falls back to
+     * `defaultProvider` / `defaultModel` (static strings) when unset, preserving
+     * backward compatibility for SDK consumers that pass string literals.
+     */
+    readonly getDefaultProvider?: () => string;
+    readonly getDefaultModel?: () => string;
+    readonly cliFlag?: string;
+    readonly envVar?: string;
+    readonly sessionOverride?: string;
+    readonly userSettings?: string;
+    /**
+     * Optional cost-tracker accessors. The classifier writes its tokens to
+     * the tracker under `querySource: 'auto_mode'` (handled inside sideQuery).
+     */
+    readonly getCostTracker?: () => CostTracker | undefined;
+    readonly setCostTracker?: (t: CostTracker) => void;
+    /** Optional logger for engine-downgrade and config warnings. */
+    readonly log?: (level: 'info' | 'warn', msg: string) => void;
+    /**
+     * Fired whenever the active engine changes — both on automatic downgrades
+     * (denial threshold / circuit breaker) AND on manual `setEngine(...)`
+     * calls. UI surfaces (status bar engine indicator, slash-command
+     * confirmations) subscribe here so the displayed engine stays in sync
+     * with the guardrail's internal state without the user having to trigger
+     * another mode toggle just to refresh the bar.
+     */
+    readonly onEngineChange?: (engine: AutoModeEngine) => void;
+    /**
+     * Optional shared state for subagent threshold-bypass defense
+     * (design doc "防绕阈值"). When supplied, the parent and child
+     * guardrails reference the SAME object — engine downgrades and
+     * tracker advances are visible across the session boundary.
+     */
+    readonly sharedState?: AutoModeSharedState;
+    /**
+     * FEATURE_092 phase 2b.7b slice C: starting engine. Defaults to `'llm'`.
+     * Set to `'rules'` to skip the classifier entirely from session start
+     * (the rules-mode escalate path runs immediately on the first non-Tier-1
+     * tool call). Resolved by the REPL from `~/.kodax/config.json`
+     * `autoMode.engine` and the `KODAX_AUTO_MODE_ENGINE` env var.
+     */
+    readonly initialEngine?: AutoModeEngine;
+    /**
+     * FEATURE_092 phase 2b.7b slice C: classifier sideQuery timeout in ms.
+     * Defaults to 8000. Resolved by the REPL from `~/.kodax/config.json`
+     * `autoMode.timeoutMs`.
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Project root for signal collectors. File-tool collector uses this to
+     * detect `outside_project` vs project-relative paths. Bash collector
+     * doesn't use it (command-string-level) but threads it for uniform
+     * collector contract.
+     *
+     * Required by FEATURE_158: if omitted, the default coding-side
+     * collectors produce no `outside_project` signal (degrades gracefully),
+     * but **REPL-injected `extraCollectors` will likely require it**.
+     * SDK consumers without a project root should set `projectRoot: ''`
+     * and supply no `extraCollectors`.
+     */
+    readonly projectRoot?: string;
+    /**
+     * Override the default signal-collector set. When unset, defaults to
+     * `[bashSignalCollector, fileSignalCollector]` — coding-side
+     * command-string + file-tool collectors that don't depend on REPL
+     * path utilities.
+     *
+     * Use `extraCollectors` instead if you want to **add** collectors
+     * without replacing the defaults.
+     */
+    readonly signalCollectors?: readonly SignalCollector[];
+    /**
+     * Additional signal collectors to merge with `signalCollectors`.
+     * Primary use: REPL injects a path-aware bash collector built on its
+     * own `extractPathsFromCommand` / `isAlwaysConfirmPath` utilities
+     * (those live in `@kodax/repl` for historical reasons; lifting them
+     * is out-of-scope for FEATURE_158 — see design doc layer-boundary
+     * decision).
+     *
+     * Order: defaults run first, then extras (preserves per-collector
+     * signal order).
+     */
+    readonly extraCollectors?: readonly SignalCollector[];
+    /**
+     * Speculative-classify quiet window (ms). When a classifier promise
+     * settles within this window, the guardrail uses the verdict directly
+     * (no confirm dialog). When the window expires, the call escalates to
+     * the user; the background classifier is left running for cost-tracker
+     * settlement but its eventual result is discarded in v1 (UI doesn't
+     * adopt late verdicts yet).
+     *
+     * Precedence: explicit arg > `KODAX_AUTO_SPECULATIVE_WINDOW_MS` env >
+     * `DEFAULT_WINDOW_MS = 500`. Set to 0 to disable speculative race
+     * (degrades to synchronous classify).
+     */
+    readonly speculativeWindowMs?: number;
+}
+/**
+ * Snapshot of the auto-mode guardrail's session-scoped state. Returned by
+ * `getStats()` for diagnostic surfaces (`/auto-denials`) and the status bar
+ * engine indicator. The DenialTracker / CircuitBreaker types are immutable
+ * value objects, so this is a copy of the references — caller cannot mutate
+ * guardrail state through it.
+ */
+interface AutoModeStats {
+    readonly engine: AutoModeEngine;
+    readonly denials: DenialTracker;
+    readonly breaker: CircuitBreaker;
+}
+interface AutoModeToolGuardrail extends ToolGuardrail {
+    /** Current engine for this session. */
+    getEngine(): AutoModeEngine;
+    /** Snapshot of engine + denial tracker + circuit breaker. */
+    getStats(): AutoModeStats;
+    /**
+     * Manually set the engine. Used by `/auto-engine` slash command to flip
+     * back to 'llm' after an automatic downgrade or to flip to 'rules' for
+     * manual testing. The downgrade thresholds still operate normally — a
+     * subsequent threshold cross will downgrade again.
+     */
+    setEngine(engine: AutoModeEngine): void;
+    /** Test-only alias for getEngine(). Backward-compat for test files. */
+    getEngineForTest(): AutoModeEngine;
+    /** Test-only alias for getStats(). Backward-compat for test files. */
+    getStatsForTest(): AutoModeStats;
+    /** Test-only override: swap the provider mid-test (for downgrade scenarios). */
+    setProviderForTest(provider: KodaXBaseProvider): void;
+}
+declare function createAutoModeToolGuardrail(config: AutoModeGuardrailConfig): AutoModeToolGuardrail;
+
+export { parseAutoRules as B, CONSECUTIVE_THRESHOLD as C, ERROR_THRESHOLD as E, readTrustState as F, recordAllow as G, recordBlock as H, recordError as I, shouldFallback$1 as J, shouldFallback as M, trustProjectRules as N, WINDOW_MS as W, CUMULATIVE_THRESHOLD as i, collectAllSignals as r, computeRulesFingerprint as s, createAutoModeToolGuardrail as t, createCircuitBreaker as u, createDenialTracker as v, formatAgentsForPrompt as w, getKodaxGlobalDir as x, loadAgentsFiles as y, loadAutoRules as z };
+export type { AgentsFile as A, DenialTracker as D, KodaXMcpConnectMode as K, LoadAgentsOptions as L, RulesLoadError as R, SignalCollector as S, ToolCallSignal as T, AutoModeAskUser as a, AutoModeAskUserVerdict as b, AutoModeEngine as c, AutoModeGuardrailConfig as d, AutoModeSharedState as e, AutoModeStats as f, AutoModeToolGuardrail as g, AutoRules as h, CircuitBreaker as j, KodaXMcpServerConfig as k, KodaXMcpServersConfig as l, KodaXMcpTransport as m, LoadedRulesSource as n, RulesLoadResult as o, SkippedRulesSource as p, TrustState as q };