@atbash/cli 0.5.15 → 0.6.1-dev.2

package/dist/lib/llm.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * Shared OpenRouter transport for the scan's optional LLM passes.
+ *
+ * Every pass here spends the USER'S OWN key. The hosted dashboard runs equivalent
+ * passes against a platform key; running locally there is no platform key, so the
+ * user supplies one or the scan stays deterministic.
+ *
+ * Deliberately small: one request per pass, a hard timeout, and no connection
+ * pooling. The dashboard's transport multiplexes waves of batches over an HTTP/2
+ * pool because it grades 87-tool surfaces from a server; a terminal scan issues a
+ * handful of calls and does not need any of that machinery.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MODEL = void 0;
+exports.chatJson = chatJson;
+exports.coerceStr = coerceStr;
+/**
+ * Measured default from the dashboard's enrichment pass. Overridable with
+ * --model; re-measure before repointing, because the tuning below was tuned
+ * against this model.
+ */
+exports.DEFAULT_MODEL = "z-ai/glm-5.3-flash";
+const OPENROUTER_ENDPOINT = "https://openrouter.ai/api/v1/chat/completions";
+/**
+ * OpenRouter settings that are load-bearing, not cosmetic.
+ *
+ * `reasoning.effort: "low"` — the default scan model is a reasoning model and
+ * otherwise spends ~1000 tokens per call on deliberation we never read, which we
+ * pay for twice: in latency, and in max_tokens, which COUNTS reasoning tokens, so
+ * the JSON gets truncated mid-object and the whole pass is lost.
+ * `provider.sort: "throughput"` — routing spread for the same model and prompt was
+ * measured between 9.8s and 64s. Verified harmless for non-reasoning models.
+ */
+const REQUEST_TUNING = {
+    reasoning: { effort: "low" },
+    provider: { sort: "throughput", allow_fallbacks: true },
+};
+/** Strip a ```json fence if the model wrapped its answer, which not every
+ *  provider avoids even with response_format set. */
+function unfence(raw) {
+    const t = raw.trim();
+    if (!t.startsWith("```"))
+        return t;
+    return t.replace(/^```(?:json)?\s*/i, "").replace(/```\s*$/, "").trim();
+}
+async function chatJson(options) {
+    const ctrl = new AbortController();
+    // Never unbounded: a hung socket must not hold the terminal open.
+    const timer = setTimeout(() => ctrl.abort(), options.timeoutMs ?? 30000);
+    try {
+        const res = await fetch(OPENROUTER_ENDPOINT, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${options.apiKey}`,
+                "HTTP-Referer": "https://atbash.ai",
+                "X-Title": "ATBASH Local Scan",
+            },
+            body: JSON.stringify({
+                model: options.model || exports.DEFAULT_MODEL,
+                messages: [
+                    { role: "system", content: options.system },
+                    { role: "user", content: options.user },
+                ],
+                temperature: 0,
+                max_tokens: options.maxTokens ?? 4000,
+                response_format: { type: "json_object" },
+                ...REQUEST_TUNING,
+            }),
+            signal: ctrl.signal,
+            redirect: "error",
+        });
+        if (!res.ok) {
+            // Status only. A provider error body can echo the request, and the request
+            // carries the user's key in a header.
+            return { data: null, requests: 1, error: `provider returned ${res.status}` };
+        }
+        const body = (await res.json());
+        const content = body.choices?.[0]?.message?.content;
+        if (!content)
+            return { data: null, requests: 1, error: "provider returned no content" };
+        return { data: JSON.parse(unfence(content)), requests: 1 };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return {
+            data: null,
+            requests: 1,
+            // An abort is our own deadline, not a provider fault — say which.
+            error: ctrl.signal.aborted ? "timed out" : msg,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function coerceStr(v, cap) {
+    return typeof v === "string" ? v.slice(0, cap) : "";
+}
+//# sourceMappingURL=llm.js.map

package/dist/lib/llm.js.map

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

package/dist/lib/policy.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Scan → starter policy.
+ *
+ * Turns the risk report into a first-draft governance boundary: a mandate line,
+ * Red Lines (block/jail paths), Approval boundaries (hold paths), and always the
+ * self-modification containment rule. This is what makes a scan ACTIONABLE rather
+ * than a read-only inventory. Deterministic, grouped by category, and needs no
+ * API key.
+ *
+ * PROVENANCE: ported from the dashboard's `src/lib/scan/policy-suggest.ts`.
+ * Suggesting a boundary is not the same as deploying one — deploying stays a
+ * dashboard function, and this command never writes a policy anywhere.
+ *
+ * Divergences from the dashboard version, all found against real output:
+ *   - Takes the agent's declared instructions directly instead of a
+ *     `CapabilityManifest`, because the CLI has no manifest type.
+ *   - A TOOL that already carries a red line elsewhere in the same category is
+ *     dropped from that category's approvals, not the whole category. Upstream
+ *     emits both unconditionally, producing "never perform data access / egress"
+ *     and "require human approval before data access / egress" for the SAME tool
+ *     in one boundary. An earlier version of this fix dropped the whole category
+ *     instead of just that tool — which silently discarded a DIFFERENT tool's
+ *     real, distinct hold finding whenever it shared a category name with
+ *     anything blocked (found against a real `export_crm_contacts` +
+ *     `delete_customer_records` surface: the export tool's approval line vanished
+ *     entirely, with no trace of it anywhere in the printed boundary). The
+ *     collision check itself must key on source+name, not name alone — otherwise
+ *     a blocked `x` on one MCP server can wrongly erase a held `x` on another.
+ *   - Drops the appended word "actions", which doubled up on every category that
+ *     already ended in one ("destructive action actions").
+ *   - Prefers primary paths when picking example tool names.
+ */
+import { type RiskReport } from "./risk";
+export interface PolicySuggestion {
+    mandate: string;
+    redLines: string[];
+    approvals: string[];
+    notes: string;
+}
+export declare function suggestPolicy(risk: RiskReport, systemPrompt?: string): PolicySuggestion;

package/dist/lib/policy.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.suggestPolicy = suggestPolicy;
+/**
+ * Scan → starter policy.
+ *
+ * Turns the risk report into a first-draft governance boundary: a mandate line,
+ * Red Lines (block/jail paths), Approval boundaries (hold paths), and always the
+ * self-modification containment rule. This is what makes a scan ACTIONABLE rather
+ * than a read-only inventory. Deterministic, grouped by category, and needs no
+ * API key.
+ *
+ * PROVENANCE: ported from the dashboard's `src/lib/scan/policy-suggest.ts`.
+ * Suggesting a boundary is not the same as deploying one — deploying stays a
+ * dashboard function, and this command never writes a policy anywhere.
+ *
+ * Divergences from the dashboard version, all found against real output:
+ *   - Takes the agent's declared instructions directly instead of a
+ *     `CapabilityManifest`, because the CLI has no manifest type.
+ *   - A TOOL that already carries a red line elsewhere in the same category is
+ *     dropped from that category's approvals, not the whole category. Upstream
+ *     emits both unconditionally, producing "never perform data access / egress"
+ *     and "require human approval before data access / egress" for the SAME tool
+ *     in one boundary. An earlier version of this fix dropped the whole category
+ *     instead of just that tool — which silently discarded a DIFFERENT tool's
+ *     real, distinct hold finding whenever it shared a category name with
+ *     anything blocked (found against a real `export_crm_contacts` +
+ *     `delete_customer_records` surface: the export tool's approval line vanished
+ *     entirely, with no trace of it anywhere in the printed boundary). The
+ *     collision check itself must key on source+name, not name alone — otherwise
+ *     a blocked `x` on one MCP server can wrongly erase a held `x` on another.
+ *   - Drops the appended word "actions", which doubled up on every category that
+ *     already ended in one ("destructive action actions").
+ *   - Prefers primary paths when picking example tool names.
+ */
+const risk_1 = require("./risk");
+/**
+ * Cap and de-duplicate example tool names per category.
+ *
+ * PRIMARY paths first: a tool that belongs to a category only as a SECONDARY harm
+ * is a real member of it, but a confusing example. `delete-customer-records`
+ * carries a data-egress harm, yet naming it as the example for data egress when
+ * `export-crm-contacts` is right there reads like a misclassification.
+ */
+function examplesFor(paths) {
+    const ordered = [...paths].sort((a, b) => Number(!!a.secondary) - Number(!!b.secondary));
+    const names = [...new Set(ordered.map((p) => p.tool))];
+    return names.slice(0, 3).join(", ") + (names.length > 3 ? ", …" : "");
+}
+function suggestPolicy(risk, systemPrompt) {
+    // Prefer the agent's own declared instructions. Otherwise a neutral, editable
+    // default — NEVER built from risk category names, which are what the agent must
+    // avoid, not its operating scope.
+    const mandate = systemPrompt?.trim() ||
+        "Use only the connected tools, and only as needed to fulfil the assigned task. (Edit to state the specific outcome this agent owns.)";
+    const byCategory = (verdicts) => {
+        const groups = new Map();
+        for (const p of risk.paths) {
+            if (!verdicts.includes(p.recommendedVerdict))
+                continue;
+            const arr = groups.get(p.category) ?? [];
+            arr.push({ tool: p.tool, source: p.source, secondary: p.secondary });
+            groups.set(p.category, arr);
+        }
+        return groups;
+    };
+    const redLineGroups = byCategory(["block", "jail"]);
+    const redLines = Array.from(redLineGroups.entries()).map(([cat, tools]) => `Never perform ${cat} autonomously (e.g. ${examplesFor(tools)}).`);
+    // Governance staple — always present.
+    redLines.push("Never modify its own mandate, red lines, or authority.");
+    const approvals = Array.from(byCategory(["hold"]).entries())
+        // Most-restrictive-wins, PER TOOL. A tool's verdict is uniform across every
+        // path it appears in (classify() forces every secondary to the primary's
+        // verdict), so the only way the SAME tool shows up here AND in redLineGroups
+        // for this category is if it can't — it can't. What DOES happen: two
+        // DIFFERENT tools land in the same category, one blocked, one merely held.
+        // Dropping the whole category then would erase the held tool's real finding
+        // with no trace anywhere in the boundary — worse than the "never X"/"ask
+        // before X" wording clash this exists to avoid. So only drop the specific
+        // tool names the category's red line already names; a different tool's hold
+        // finding survives under its own example.
+        .map(([cat, tools]) => {
+        // Keyed on source+name: a block/jail path in this category belongs to a
+        // SPECIFIC tool instance, and only that instance should drop out of the
+        // approvals list here — not any other tool that merely shares its name.
+        const alreadyRedLined = new Set((redLineGroups.get(cat) ?? []).map((t) => (0, risk_1.toolKey)(t.source, t.tool)));
+        const remaining = tools.filter((t) => !alreadyRedLined.has((0, risk_1.toolKey)(t.source, t.tool)));
+        return remaining.length > 0 ? `Require human approval before ${cat} (e.g. ${examplesFor(remaining)}).` : null;
+    })
+        .filter((line) => line !== null);
+    const notes = `Draft boundary generated from the ${risk.method === "llm" ? "model-analyzed" : "scanned"} capability surface (${risk.paths.length} paths). Review before enforcing — it reflects authorized exposure, not observed behavior.`;
+    return { mandate, redLines, approvals, notes };
+}
+//# sourceMappingURL=policy.js.map

package/dist/lib/policy.js.map

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

package/dist/lib/risk.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Deterministic risk / blast-radius derivation for a locally scanned surface.
+ *
+ * Turns a tool surface into the "what could go wrong" report: each tool is
+ * matched to a consequence class, a severity, and a recommended runtime verdict.
+ * It reasons only over the DECLARED surface — what the agent is authorized to
+ * attempt — which is what a scan authoritatively knows. It never claims
+ * certainty, and that framing is what keeps a governance report honest.
+ *
+ * PROVENANCE: ported from the Atbash dashboard's `src/lib/scan/risk.ts`. The
+ * rules table, its ORDER, the severity weights and the scoring band are kept
+ * faithful on purpose: a local `atbash scan` that graded a surface differently
+ * from the hosted scan would be worse than no local scan at all.
+ *
+ * DIVERGENCE FROM THE DASHBOARD (deliberate, since the CLI now owns this copy):
+ *   - `call|calls` removed from external communication, replaced with `phone\w*`.
+ *     In a tool catalog "calls" overwhelmingly means FUNCTION calls: a real
+ *     `js_reset` whose description read "bindings created by prior `js` calls"
+ *     was graded as messaging outsiders. "phone" carries the intent unambiguously.
+ *   - `add|adds|added|adding` added to state change. A real
+ *     `js_add_node_module_dir` — which mutates module resolution, and so controls
+ *     what code can be imported — was graded low/read-only on the word "search"
+ *     in "module search roots". Spelled out rather than `add\w*`, which would
+ *     match "address" and "additional".
+ * Both were found against a real Codex `node_repl` surface. If these are ported
+ * back upstream, delete this block rather than letting the two engines drift.
+ *
+ * Two further mechanical divergences:
+ *   - `deriveRisk` takes a tool list rather than a `CapabilityManifest`; the CLI
+ *     has no manifest type and only `.tools` was ever read.
+ *   - `ScanTool` is declared here instead of imported, since only two of its
+ *     fields are used.
+ *
+ * If the scan logic is ever extracted into a shared package, this file is what
+ * gets deleted — nothing else in the CLI depends on its internals.
+ */
+/** One tool/capability the agent can invoke. */
+export interface ScanTool {
+    name: string;
+    description?: string;
+    /** Which config/server surfaced this tool (provenance). */
+    source: string;
+}
+/**
+ * Identity key for a specific tool INSTANCE — source + name, not name alone.
+ *
+ * Two different MCP servers can each expose a tool called e.g. "search": they are
+ * different capabilities that happen to share a name. Anything that maps a tool
+ * to a per-tool result (which of its paths is unclassified, what an LLM pass
+ * graded it) must key on this, or one server's tool silently absorbs another's
+ * classification/grade.
+ */
+export declare function toolKey(source: string | undefined, name: string): string;
+export type Verdict = "allow" | "hold" | "block" | "jail";
+export type Severity = "low" | "medium" | "high";
+export interface RiskPath {
+    tool: string;
+    /** An ADDITIONAL harm this tool matched beyond its primary one. Governed like
+     *  any other path, but deliberately NOT scored — see summarizePaths. */
+    secondary?: boolean;
+    category: string;
+    severity: Severity;
+    recommendedVerdict: Verdict;
+    consequence: string;
+    /** Where the tool came from, so a report can name the offending config. */
+    source?: string;
+}
+export interface RiskReport {
+    paths: RiskPath[];
+    score: number;
+    level: "Low" | "Elevated" | "High";
+    summary: string;
+    /** How the report was produced. The LLM pass sets "llm"; default deterministic. */
+    method?: "deterministic" | "llm";
+}
+export declare const UNCLASSIFIED_CATEGORY = "general action";
+export declare const UNCLASSIFIED_CONSEQUENCE = "no specific high-risk class matched \u2014 allowed and monitored";
+/**
+ * Marks the fall-through rule. A tool that matched NOTHING is unclassified — it
+ * is not a considered "medium risk" finding, and presenting it as one turns every
+ * unrecognized plugin into a false signal.
+ */
+export declare function isUnclassifiedPath(path: {
+    category?: string;
+    consequence?: string;
+}): boolean;
+/** Score + level + summary from a set of paths — shared by both passes. */
+export declare function summarizePaths(paths: RiskPath[]): Pick<RiskReport, "score" | "level" | "summary">;
+/** Derive the blast-radius report from a scanned tool surface (deterministic). */
+export declare function deriveRisk(tools: ScanTool[]): RiskReport;
+/**
+ * Fill in the paths the keyword rules could not classify, using a model's per-tool
+ * grade and its plain-English effect.
+ *
+ * Gap-filling ONLY: a path that matched a real rule is returned untouched, so the
+ * deterministic engine stays the auditable floor and an LLM can never downgrade a
+ * known-dangerous capability. `critical` folds to `high` because that is the top
+ * of this module's scale. The score is recomputed so the level reflects the
+ * enriched set.
+ *
+ * `grades` is keyed by `${source}::${name}` (see `toolKey`), not name alone: two
+ * different MCP servers can expose a same-named tool, and a name-only key would
+ * apply one tool's grade to the other's unrelated path.
+ *
+ * Returns the ORIGINAL report object when nothing was filled, so a caller can test
+ * `graded !== report` to know whether the pass actually contributed.
+ */
+export declare function gradeUnclassifiedPaths(report: RiskReport, grades: Record<string, {
+    severity?: string;
+    effect?: string;
+    policyGroup?: string;
+}>): RiskReport;

package/dist/lib/risk.js

@@ -0,0 +1,288 @@
+"use strict";
+/**
+ * Deterministic risk / blast-radius derivation for a locally scanned surface.
+ *
+ * Turns a tool surface into the "what could go wrong" report: each tool is
+ * matched to a consequence class, a severity, and a recommended runtime verdict.
+ * It reasons only over the DECLARED surface — what the agent is authorized to
+ * attempt — which is what a scan authoritatively knows. It never claims
+ * certainty, and that framing is what keeps a governance report honest.
+ *
+ * PROVENANCE: ported from the Atbash dashboard's `src/lib/scan/risk.ts`. The
+ * rules table, its ORDER, the severity weights and the scoring band are kept
+ * faithful on purpose: a local `atbash scan` that graded a surface differently
+ * from the hosted scan would be worse than no local scan at all.
+ *
+ * DIVERGENCE FROM THE DASHBOARD (deliberate, since the CLI now owns this copy):
+ *   - `call|calls` removed from external communication, replaced with `phone\w*`.
+ *     In a tool catalog "calls" overwhelmingly means FUNCTION calls: a real
+ *     `js_reset` whose description read "bindings created by prior `js` calls"
+ *     was graded as messaging outsiders. "phone" carries the intent unambiguously.
+ *   - `add|adds|added|adding` added to state change. A real
+ *     `js_add_node_module_dir` — which mutates module resolution, and so controls
+ *     what code can be imported — was graded low/read-only on the word "search"
+ *     in "module search roots". Spelled out rather than `add\w*`, which would
+ *     match "address" and "additional".
+ * Both were found against a real Codex `node_repl` surface. If these are ported
+ * back upstream, delete this block rather than letting the two engines drift.
+ *
+ * Two further mechanical divergences:
+ *   - `deriveRisk` takes a tool list rather than a `CapabilityManifest`; the CLI
+ *     has no manifest type and only `.tools` was ever read.
+ *   - `ScanTool` is declared here instead of imported, since only two of its
+ *     fields are used.
+ *
+ * If the scan logic is ever extracted into a shared package, this file is what
+ * gets deleted — nothing else in the CLI depends on its internals.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNCLASSIFIED_CONSEQUENCE = exports.UNCLASSIFIED_CATEGORY = void 0;
+exports.toolKey = toolKey;
+exports.isUnclassifiedPath = isUnclassifiedPath;
+exports.summarizePaths = summarizePaths;
+exports.deriveRisk = deriveRisk;
+exports.gradeUnclassifiedPaths = gradeUnclassifiedPaths;
+/**
+ * Identity key for a specific tool INSTANCE — source + name, not name alone.
+ *
+ * Two different MCP servers can each expose a tool called e.g. "search": they are
+ * different capabilities that happen to share a name. Anything that maps a tool
+ * to a per-tool result (which of its paths is unclassified, what an LLM pass
+ * graded it) must key on this, or one server's tool silently absorbs another's
+ * classification/grade.
+ */
+function toolKey(source, name) {
+    return `${source ?? ""}::${name}`;
+}
+// Ordered most-severe first; first match wins. Patterns run against
+// "name description" lowercased and tokenized (see classify()).
+//
+// Every keyword is \b-anchored on BOTH sides, either as a whole token or as an
+// explicit stem (`deploy\w*`). Bare substrings look equivalent but are not: they
+// fire on unrelated words that merely contain the keyword, and because the rules
+// are ordered most-severe-first, a stray substring hit OUTRANKS the correct rule.
+// Real misclassifications this prevents: "design_review"/"assign_reviewer" ->
+// binding commitment (`sign`), "get_executive_summary" -> runtime execution
+// (`exec`), "introduce_yourself" -> containment/jail (`self`), "list_assets" and
+// "get_settings" -> state change (`set`), "postgres_list_tables" -> external
+// communication (`post`), "recall_conversation" -> external communication (`call`).
+const RULES = [
+    {
+        test: /\b(polic(y|ies)|mandate|red\s?line|guardrail|self|jailbreak|disabl\w*)\b|\b(escalat\w*\s+privilege|privilege\s+escalat\w*)/,
+        category: "self-modification / containment",
+        severity: "high",
+        verdict: "jail",
+        consequence: "could weaken or bypass its own authority — loss of control",
+    },
+    {
+        test: /\b(delete\w*|drop|destroy\w*|rm|remove\w*|force\s?push|wipe|truncate|revoke\w*)\b/,
+        category: "destructive action",
+        severity: "high",
+        verdict: "block",
+        consequence: "irreversible data/infrastructure loss",
+    },
+    {
+        test: /\b(pay|payment\w*|transfer\w*|refund\w*|reward\w*|charge\w*|invoice\w*|payout\w*|wire|disburse\w*)\b/,
+        category: "financial",
+        severity: "high",
+        verdict: "hold",
+        consequence: "direct financial loss",
+    },
+    {
+        test: /\b(shell|exec|execut(e|es|ed|ing|ion)|command|bash|python|code\s?interpreter|git|deploy\w*|terraform)\b/,
+        category: "runtime execution",
+        severity: "high",
+        verdict: "block",
+        consequence: "arbitrary code / infra actions at the runtime boundary",
+    },
+    // The read-proximity clause is bounded to one intervening word: "read customer
+    // records" is data egress, but "read a document ... for the user" is not — an
+    // unbounded .* made every read tool whose description says "the user" high-severity.
+    {
+        test: /\b(export\w*|download\w*|scrape\w*|dump|crm|database|sql|quer(y|ies))\b|\bread\w*\s+(\w+\s+)?(customer|user|pii|record)/,
+        category: "data access / egress",
+        severity: "high",
+        verdict: "hold",
+        consequence: "data leakage / privacy breach",
+    },
+    {
+        test: /\b(sign|signs|signed|signature|contract\w*|agree\w*|commit|commits|committed|commitment|order|orders|purchase\w*|book)\b|\bapprove\s?terms/,
+        category: "binding commitment",
+        severity: "high",
+        verdict: "hold",
+        consequence: "unauthorized commitment / liability",
+    },
+    // Autonomy-first: BLOCK (auto-deny) and ALLOW (auto-proceed, monitored) are both
+    // AUTOMATIC — the agent gets a decision without a human. HOLD is the narrow
+    // "pause for a human" set, reserved above for the truly irreversible
+    // external-harm categories. Reversible, monitorable actions default to ALLOW so
+    // a governed agent stays autonomous instead of routing half its work to a human.
+    {
+        test: /\b(send\w*|email\w*|message\w*|post|posts|publish\w*|tweet\w*|notif(y|ies|ication\w*)|slack|sms|phone\w*|contact\w*|broadcast\w*)\b/,
+        category: "external communication",
+        severity: "medium",
+        verdict: "allow",
+        consequence: "external message sent on the owner's behalf (monitored)",
+    },
+    {
+        test: /\b(updat\w*|modif(y|ies|ied)|edit\w*|writ\w*|creat\w*|set|chang\w*|schedul\w*|move|moves|rename\w*|add|adds|added|adding)\b/,
+        category: "state change",
+        severity: "medium",
+        verdict: "allow",
+        consequence: "changes records or state (monitored; reversible in most systems)",
+    },
+    {
+        test: /\b(search\w*|brows\w*|fetch\w*|lookup|look\s?up|retriev\w*|recall\w*|get|list|lists|read|describe\w*|show\w*|view\w*|summar\w*)\b/,
+        category: "read / research",
+        severity: "low",
+        verdict: "allow",
+        consequence: "low-consequence information access",
+    },
+];
+/** The read-only class. Meaningful as a primary, never as an added finding. */
+const READ_ONLY_CATEGORY = "read / research";
+exports.UNCLASSIFIED_CATEGORY = "general action";
+exports.UNCLASSIFIED_CONSEQUENCE = "no specific high-risk class matched — allowed and monitored";
+/**
+ * Marks the fall-through rule. A tool that matched NOTHING is unclassified — it
+ * is not a considered "medium risk" finding, and presenting it as one turns every
+ * unrecognized plugin into a false signal.
+ */
+function isUnclassifiedPath(path) {
+    return path.category === exports.UNCLASSIFIED_CATEGORY && path.consequence === exports.UNCLASSIFIED_CONSEQUENCE;
+}
+const DEFAULT_RULE = {
+    category: exports.UNCLASSIFIED_CATEGORY,
+    // Autonomy-first: an unclassified action defaults to ALLOW (auto, monitored)
+    // rather than routing every unrecognized tool to a human.
+    severity: "medium",
+    verdict: "allow",
+    consequence: exports.UNCLASSIFIED_CONSEQUENCE,
+};
+const SEV_WEIGHT = { low: 3, medium: 8, high: 16 };
+// Score band per worst-severity-present. The worst severity on the surface picks
+// the BAND; breadth only moves the score within it. Summing weights across all
+// paths instead lets count outrank severity: 20 read-only tools (20x3=60) used to
+// outscore two tools that permanently delete data (2x16=32), so a read-only agent
+// read "High" while a destructive one read "Elevated".
+const SEV_BAND = { low: [0, 32], medium: [33, 65], high: [66, 100] };
+function pathFromRule(tool, rule, secondary) {
+    return {
+        tool: tool.name,
+        category: rule.category,
+        severity: rule.severity,
+        recommendedVerdict: rule.verdict,
+        consequence: rule.consequence,
+        source: tool.source,
+        ...(secondary ? { secondary: true } : {}),
+    };
+}
+/**
+ * Every consequence class this tool belongs to, most important first.
+ *
+ * The first match is the PRIMARY path and is what the score is built on. The rest
+ * are harms that would otherwise be dropped — a tool is rarely one kind of danger
+ * (`delete_repo_and_notify` destroys data AND messages outsiders). Every secondary
+ * is emitted at the PRIMARY's verdict: the rules are ordered by importance, not by
+ * verdict, so letting a secondary keep its own could hand a tool a BLOCK its
+ * primary never gave it — and letting it come in weaker would list the same tool
+ * as both a red line and an allowed limit.
+ */
+function classify(tool) {
+    // Normalize non-alphanumerics to spaces so snake_case/camel/kebab tool names
+    // tokenize ("issue_refund" -> "issue refund"). This lets the \b anchors match
+    // keywords inside identifiers while keeping short tokens like "rm"/"git" safe
+    // (they only match as standalone words, not inside "form").
+    const hay = ` ${`${tool.name} ${tool.description ?? ""}`.toLowerCase().replace(/[^a-z0-9]+/g, " ")} `;
+    const matched = RULES.filter((r) => r.test.test(hay));
+    const primaryRule = matched[0] ?? DEFAULT_RULE;
+    const primary = pathFromRule(tool, primaryRule);
+    const seen = new Set([primary.category]);
+    const secondary = [];
+    for (const rule of matched.slice(1)) {
+        // One statement per consequence class.
+        if (seen.has(rule.category))
+            continue;
+        // "Also reads" is not a finding: every tool that writes, sends or deletes also
+        // matches the read rule, so as a SECONDARY it covers most of the surface and
+        // tells the owner nothing.
+        if (rule.category === READ_ONLY_CATEGORY)
+            continue;
+        seen.add(rule.category);
+        secondary.push(pathFromRule(tool, { ...rule, verdict: primaryRule.verdict }, true));
+    }
+    return [primary, ...secondary];
+}
+/** Score + level + summary from a set of paths — shared by both passes. */
+function summarizePaths(paths) {
+    // Secondary paths describe a tool more precisely; they do not add capability.
+    // Counting them would raise the score of an unchanged runtime purely because
+    // the classifier learned to name a second harm.
+    const scored = paths.filter((p) => !p.secondary);
+    const sorted = [...scored].sort((a, b) => SEV_WEIGHT[b.severity] - SEV_WEIGHT[a.severity]);
+    const worst = sorted[0]?.severity;
+    const raw = sorted.reduce((sum, p) => sum + SEV_WEIGHT[p.severity], 0);
+    const [floor, ceil] = worst ? SEV_BAND[worst] : [0, 0];
+    const score = Math.min(100, Math.round(floor + (ceil - floor) * (1 - Math.exp(-raw / 40))));
+    const level = score >= 66 ? "High" : score >= 33 ? "Elevated" : "Low";
+    const highs = sorted.filter((p) => p.severity === "high").length;
+    const summary = sorted.length === 0
+        ? "No tool surface was resolved, so no blast radius could be derived. Behavior must be observed at the runtime boundary."
+        : `${sorted.length} authorized action path${sorted.length === 1 ? "" : "s"} (${highs} high-severity). This is what the agent is authorized to attempt before any boundary — not a prediction of intent.`;
+    return { score, level, summary };
+}
+/** Derive the blast-radius report from a scanned tool surface (deterministic). */
+function deriveRisk(tools) {
+    const paths = tools
+        .flatMap(classify)
+        // Stable: equal severities keep the order the tools were scanned in, so a
+        // rescan of an unchanged runtime produces an identical report.
+        .sort((a, b) => SEV_WEIGHT[b.severity] - SEV_WEIGHT[a.severity]);
+    return { paths, ...summarizePaths(paths), method: "deterministic" };
+}
+/**
+ * Fill in the paths the keyword rules could not classify, using a model's per-tool
+ * grade and its plain-English effect.
+ *
+ * Gap-filling ONLY: a path that matched a real rule is returned untouched, so the
+ * deterministic engine stays the auditable floor and an LLM can never downgrade a
+ * known-dangerous capability. `critical` folds to `high` because that is the top
+ * of this module's scale. The score is recomputed so the level reflects the
+ * enriched set.
+ *
+ * `grades` is keyed by `${source}::${name}` (see `toolKey`), not name alone: two
+ * different MCP servers can expose a same-named tool, and a name-only key would
+ * apply one tool's grade to the other's unrelated path.
+ *
+ * Returns the ORIGINAL report object when nothing was filled, so a caller can test
+ * `graded !== report` to know whether the pass actually contributed.
+ */
+function gradeUnclassifiedPaths(report, grades) {
+    let filled = 0;
+    const paths = report.paths.map((path) => {
+        if (!isUnclassifiedPath(path))
+            return path;
+        const hint = grades[toolKey(path.source, path.tool)];
+        const graded = (hint?.severity ?? "").toLowerCase();
+        const severity = graded === "critical" || graded === "high"
+            ? "high"
+            : graded === "medium"
+                ? "medium"
+                : graded === "low"
+                    ? "low"
+                    : undefined;
+        if (!severity)
+            return path;
+        filled++;
+        return {
+            ...path,
+            severity,
+            category: hint?.policyGroup?.trim() || path.category,
+            consequence: hint?.effect?.trim() || path.consequence,
+        };
+    });
+    if (!filled)
+        return report;
+    return { ...report, paths, ...summarizePaths(paths), method: "llm" };
+}
+//# sourceMappingURL=risk.js.map