dsh-perm-gate 0.2.0 → 0.2.1-beta.3

package/lib/host-llm.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Host-side LLM transport for dsh-perm-gate's llmAssist: instead of a custom
+ * OpenAI-compatible endpoint, the gate may call the DSH host's `llm` service
+ * (the model-group setup the user already configured, as demonstrated by
+ * dsh-approval-gate's `llm.stream` + `agentDefaultModel.currentSelection`).
+ *
+ * Transport-only and never throws: any failure resolves `{ ok: false }` so the
+ * caller keeps the ask (fail-closed). Node-half only — never imported by the
+ * client bundle.
+ */
+/** One request to the host `llm` service (shape per the dsh runtime contract). */
+export interface HostLlmRequest {
+    readonly provider: string;
+    readonly model: string;
+    readonly messages: readonly {
+        readonly role: 'user';
+        readonly content: readonly {
+            readonly type: 'text';
+            readonly text: string;
+        }[];
+    }[];
+    readonly system?: string;
+    readonly temperature?: number;
+    readonly reasoningEffort?: string;
+    readonly maxTokens?: number;
+    readonly signal?: AbortSignal;
+}
+/** One stream chunk: text/reasoning deltas, or a terminal finish event. */
+export interface HostLlmChunk {
+    readonly type: string;
+    readonly text?: string;
+    readonly reason?: {
+        readonly kind?: string;
+        readonly failure?: {
+            readonly message?: string;
+        };
+    };
+}
+/** The minimal face of the DSH `llm` service this plugin uses. */
+export interface HostLlmLike {
+    stream(request: HostLlmRequest): AsyncIterable<HostLlmChunk>;
+}
+/** The model-group selection used when no explicit override is configured. */
+export interface HostModelSelection {
+    readonly provider: string;
+    readonly model: string;
+}
+/** Fallback matching dsh-approval-gate's resolveModel default. */
+export declare const DEFAULT_HOST_MODEL: HostModelSelection;
+/**
+ * One completion through the host `llm` service with an abort timeout.
+ * Resolves `{ ok: true, content }` with the accumulated assistant text, or
+ * `{ ok: false, error }` on stream failure, abort, or an empty answer.
+ */
+export declare function completeViaHost(hostLlm: HostLlmLike, selection: HostModelSelection, system: string, user: string, timeoutMs: number): Promise<{
+    ok: true;
+    content: string;
+} | {
+    ok: false;
+    error?: string;
+}>;

package/lib/host-llm.js

@@ -0,0 +1,52 @@
+/**
+ * Host-side LLM transport for dsh-perm-gate's llmAssist: instead of a custom
+ * OpenAI-compatible endpoint, the gate may call the DSH host's `llm` service
+ * (the model-group setup the user already configured, as demonstrated by
+ * dsh-approval-gate's `llm.stream` + `agentDefaultModel.currentSelection`).
+ *
+ * Transport-only and never throws: any failure resolves `{ ok: false }` so the
+ * caller keeps the ask (fail-closed). Node-half only — never imported by the
+ * client bundle.
+ */
+/** Fallback matching dsh-approval-gate's resolveModel default. */
+export const DEFAULT_HOST_MODEL = { provider: 'deepseek-official', model: 'deepseek-v4-flash' };
+/**
+ * One completion through the host `llm` service with an abort timeout.
+ * Resolves `{ ok: true, content }` with the accumulated assistant text, or
+ * `{ ok: false, error }` on stream failure, abort, or an empty answer.
+ */
+export async function completeViaHost(hostLlm, selection, system, user, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        let text = '';
+        const stream = hostLlm.stream({
+            provider: selection.provider,
+            model: selection.model,
+            messages: [{ role: 'user', content: [{ type: 'text', text: user }] }],
+            system,
+            temperature: 0,
+            reasoningEffort: 'off',
+            maxTokens: 256,
+            signal: controller.signal,
+        });
+        for await (const chunk of stream) {
+            if ((chunk.type === 'text-delta' || chunk.type === 'reasoning-delta') && typeof chunk.text === 'string') {
+                text += chunk.text;
+            }
+            else if (chunk.type === 'finish' && chunk.reason !== undefined && (chunk.reason.kind === 'error' || chunk.reason.kind === 'aborted')) {
+                const failure = chunk.reason.failure?.message;
+                return { ok: false, error: failure ?? chunk.reason.kind };
+            }
+        }
+        if (text.trim() === '')
+            return { ok: false, error: 'empty answer' };
+        return { ok: true, content: text };
+    }
+    catch (e) {
+        return { ok: false, error: String(e?.message ?? e) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/lib/index.d.ts

@@ -7,11 +7,40 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { Config } from './config.js';
-import { PermGateRuntime } from './runtime.js';
+import { PermGateRuntime, type ToolExecutionLike } from './runtime.js';
 export declare const name = "dsh-perm-gate";
-/** The `tools` service drives `tools/pre-execute`/`tools/result`; it is supplied by dsh-tools. */
+/**
+ * The `tools` service drives `tools/pre-execute`/`tools/result` (dsh-tools).
+ * `webServer` hosts the plugin's HTTP routes; `llm` + `agentDefaultModel` back
+ * the `host` llmAssist receiver — all supplied by the dsh runtime through the
+ * loader inject (the same pattern dsh-approval-gate demonstrates; probing via
+ * `ctx.get` does not cross the plugin's isolated context).
+ */
 export declare const inject: string[];
 export { Config };
 /** Runtime settings namespace: `permissive` + `permissiveStrategies` (editable in the UI). */
 export declare const PERMISSIVE_NAMESPACE = "dsh-perm-gate";
+/**
+ * Build the passive `approval/request` observer (exported for tests).
+ *
+ * It forwards the waterfall untouched and records the closed outcome for a
+ * tracked ask. Recording is best-effort: a throw here would be normalized by
+ * the approval service to `unavailable` — a rejection on the human's behalf.
+ */
+export declare function makeApprovalObserver(runtime: Pick<PermGateRuntime, 'settleAskOutcome'>): (req: unknown, next: () => Promise<unknown>) => Promise<unknown>;
+/**
+ * Build the `tools/pre-execute` waterfall listener (exported for tests).
+ *
+ * The llmAssist refinement is awaited **before** the decision leaves the
+ * waterfall. An ask that has been returned to the host is already on its way to
+ * the approval answerers, and DSH offers no API to retract it — the request's
+ * own `signal` can only settle it `cancelled` — so a `safe` verdict learned
+ * afterwards could be *recorded* but never acted on: the human still had to
+ * click. Grading here is what turns `safe` into a real auto-allow and keeps the
+ * prompt for the genuinely uncertain verdicts only (`risky:neutral`,
+ * `unresolved`, transport failure). The wait is bounded by the classifier's own
+ * `riskTimeoutMs` (default 20 s), and a grader failure keeps the original ask
+ * (fail-closed).
+ */
+export declare function makePreExecuteListener(runtime: Pick<PermGateRuntime, 'decideExecution' | 'refineAsk'>): (exec: ToolExecutionLike, next: () => Promise<unknown>) => Promise<unknown>;
 export declare function apply(ctx: Context, config?: Record<string, unknown>): PermGateRuntime;

package/lib/index.js

@@ -1,10 +1,17 @@
 import { join } from 'node:path';
-import { Config, resolvePermissiveStrategies } from './config.js';
-import { registerEventsRoute } from './events.js';
+import { Config, resolveDataDir, resolveGatePresets, resolvePermissiveStrategies, resolveRulesFile } from './config.js';
+import { registerEventsRoute, registerHealthRoute, registerLearningRoute, registerReceiverRoute, registerReviewRoutes } from './events.js';
+import { buildReceiverInfo } from './receiver-info.js';
 import { PermGateRuntime } from './runtime.js';
 export const name = 'dsh-perm-gate';
-/** The `tools` service drives `tools/pre-execute`/`tools/result`; it is supplied by dsh-tools. */
-export const inject = ['tools'];
+/**
+ * The `tools` service drives `tools/pre-execute`/`tools/result` (dsh-tools).
+ * `webServer` hosts the plugin's HTTP routes; `llm` + `agentDefaultModel` back
+ * the `host` llmAssist receiver — all supplied by the dsh runtime through the
+ * loader inject (the same pattern dsh-approval-gate demonstrates; probing via
+ * `ctx.get` does not cross the plugin's isolated context).
+ */
+export const inject = ['tools', 'webServer', 'llm', 'agentDefaultModel'];
 export { Config };
 /** Runtime settings namespace: `permissive` + `permissiveStrategies` (editable in the UI). */
 export const PERMISSIVE_NAMESPACE = 'dsh-perm-gate';
@@ -35,15 +42,138 @@ function asSurface(value) {
         ? value
         : undefined;
 }
+/**
+ * Deliver a revert instruction into a conversation (the review page's "撤销此改动").
+ * A DSH user message content must be a block array — a bare string is rendered
+ * per character by the GUI — and two channels are tried in order: the typert
+ * gateway, then the live agent's followup.
+ */
+function buildSessionSender(get) {
+    return async (sessionId, content) => {
+        const textBlock = [{ type: 'text', text: content }];
+        const gateway = get('typertGateway');
+        if (gateway !== undefined && typeof gateway.invoke === 'function') {
+            try {
+                await gateway.invoke({ namespace: 'session', method: 'prompt', args: { sessionId, mode: 'queue', content: textBlock } });
+                return { ok: true, via: 'gateway' };
+            }
+            catch {
+                // fall through to the agent channel
+            }
+        }
+        const agents = get('agents');
+        if (agents !== undefined && typeof agents.get === 'function') {
+            const agent = agents.get(sessionId);
+            if (agent !== undefined && typeof agent.followup === 'function') {
+                agent.followup({
+                    id: 'pg-revert-' + Date.now().toString(36) + '-' + Math.floor(Math.random() * 1e9).toString(36),
+                    role: 'user',
+                    content: textBlock,
+                    source: { kind: 'user' },
+                });
+                return { ok: true, via: 'followup' };
+            }
+        }
+        return { ok: false, error: '没有可用的消息投递通道' };
+    };
+}
+/**
+ * Build the passive `approval/request` observer (exported for tests).
+ *
+ * It forwards the waterfall untouched and records the closed outcome for a
+ * tracked ask. Recording is best-effort: a throw here would be normalized by
+ * the approval service to `unavailable` — a rejection on the human's behalf.
+ */
+export function makeApprovalObserver(runtime) {
+    return async (req, next) => {
+        const outcome = await next();
+        try {
+            const callId = req?.callId;
+            runtime.settleAskOutcome(typeof callId === 'string' ? callId : '', String(outcome ?? ''));
+        }
+        catch {
+            // Recording must never influence the approval outcome.
+        }
+        return outcome;
+    };
+}
+/**
+ * Build the `tools/pre-execute` waterfall listener (exported for tests).
+ *
+ * The llmAssist refinement is awaited **before** the decision leaves the
+ * waterfall. An ask that has been returned to the host is already on its way to
+ * the approval answerers, and DSH offers no API to retract it — the request's
+ * own `signal` can only settle it `cancelled` — so a `safe` verdict learned
+ * afterwards could be *recorded* but never acted on: the human still had to
+ * click. Grading here is what turns `safe` into a real auto-allow and keeps the
+ * prompt for the genuinely uncertain verdicts only (`risky:neutral`,
+ * `unresolved`, transport failure). The wait is bounded by the classifier's own
+ * `riskTimeoutMs` (default 20 s), and a grader failure keeps the original ask
+ * (fail-closed).
+ */
+export function makePreExecuteListener(runtime) {
+    return async (exec, next) => {
+        const decision = runtime.decideExecution(exec);
+        // Passthrough (allow / stand-down) and a hard-deny need no grading.
+        if (decision === undefined)
+            return next();
+        if (decision.kind !== 'ask')
+            return decision;
+        // A cancelled call is never worth a model round-trip; the registry rechecks
+        // cancellation after this gate settles.
+        if (exec.signal?.aborted === true)
+            return decision;
+        let refined;
+        try {
+            refined = await runtime.refineAsk(exec, decision);
+        }
+        catch {
+            return decision; // fail-closed: keep the human ask
+        }
+        return refined ?? next();
+    };
+}
 export function apply(ctx, config = {}) {
     // Runtime-adjustable config: the composition entry is the base; the settings
     // namespace layers on top and `current()` always reads the active section.
     let current = () => config;
-    // Plugin-owned data files live under $DSH_HOME (node_modules may be read-only);
-    // a missing dshHome degrades both stores to in-memory.
-    const dataDir = typeof config.dshHome === 'string' && config.dshHome !== '' ? join(config.dshHome, 'perm-gate') : undefined;
+    // Plugin-owned data files live under $DSH_HOME (node_modules may be
+    // read-only). The default resolves to `$DSH_HOME` / `~/.dsh`, so a profile
+    // entry that omits `config` still records events, snapshots and learning.
+    const dataDir = resolveDataDir(typeof config.dshHome === 'string' ? config.dshHome : undefined);
+    // Host model-group services (typed minimally; supplied by the dsh runtime
+    // through the loader `inject` — dsh-approval-gate demonstrates the same
+    // contract). The llm service backs the `host` receiver; agentDefaultModel
+    // supplies the current model-group selection.
+    const injected = ctx;
+    const fallbackGet = (name) => {
+        try {
+            return injected.get(name);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const llmService = (injected.llm ?? fallbackGet('llm'));
+    const hostLlm = llmService !== null && typeof llmService === 'object' && typeof llmService.stream === 'function'
+        ? llmService
+        : undefined;
+    const hostModelService = injected.agentDefaultModel ?? fallbackGet('agentDefaultModel');
+    // The live approval service, captured by the optional inject below. Its
+    // `effectivePolicy` tells the gate whether an ask can reach a human at all.
+    //
+    // DUAL-VERSION NOTE (DSH 0.1.1-rc.2 and 0.1.2-rc.1): `effectivePolicy` is a
+    // **private** method of the user-approval service in BOTH versions
+    // (packages/interaction/user-approval/src/index.ts, `private effectivePolicy`).
+    // It is therefore a duck-typed, non-contract dependency: read it only through
+    // a `typeof` probe, never assume it exists, and never let a failure escape
+    // (a throw would be normalized by the approval seam into a rejection on the
+    // human's behalf). The public fallback is the `agents.get(id).followup(...)`
+    // channel in buildSessionSender.
+    let approvalService;
     const runtime = new PermGateRuntime({
         ...config,
+        hostLlm,
         // Read the Permissive tier live so the UI card's switches take effect on
         // the next tool call (no reload). Falls back to the composition entry.
         readPermissive: () => {
@@ -72,12 +202,71 @@ export function apply(ctx, config = {}) {
                 threshold: c.riskThreshold ?? 3,
             };
         },
+        // Read the deny-keyword blacklist live; unset (not an array) applies the preset.
+        readDenyKeywords: () => {
+            const c = current();
+            return Array.isArray(c.denyKeywords) ? c.denyKeywords : undefined;
+        },
+        // Learning sedimentation: threshold-reached samples become deterministic allows.
+        readRiskSediment: () => current().riskSediment ?? true,
+        // llmAssist receiver source: custom OpenAI-compatible endpoint or the host llm service.
+        readClassifySource: () => (current().classifierSource === 'host' ? 'host' : 'custom'),
+        readHostModel: () => {
+            const c = current();
+            let selection;
+            try {
+                selection = hostModelService?.currentSelection?.();
+            }
+            catch {
+                selection = undefined;
+            }
+            const provider = typeof c.classifierProvider === 'string' && c.classifierProvider !== ''
+                ? c.classifierProvider
+                : (typeof selection?.provider === 'string' && selection.provider !== '' ? selection.provider : 'deepseek-official');
+            const model = typeof c.classifierModel === 'string' && c.classifierModel !== ''
+                ? c.classifierModel
+                : (typeof selection?.model === 'string' && selection.model !== '' ? selection.model : 'deepseek-v4-flash');
+            return { provider, model };
+        },
         learningFile: typeof config.learningFile === 'string' && config.learningFile !== ''
             ? config.learningFile
-            : (dataDir !== undefined ? join(dataDir, 'learning.json') : undefined),
+            : join(dataDir, 'learning.json'),
+        // The rules document lives in the plugin's data dir by default, so a
+        // `$DSH_HOME/perm-gate/rules.yml` the user writes is actually loaded without
+        // also having to declare `rulesFile` in the composition entry.
+        rulesFile: resolveRulesFile(typeof config.rulesFile === 'string' ? config.rulesFile : undefined, dataDir),
+        // The whole gate is scoped to the presets that opt into it (default: the
+        // `permissive` tier this plugin adds); elsewhere it stands down entirely.
+        gatePresets: resolveGatePresets(Array.isArray(config.gatePresets) ? config.gatePresets : undefined),
+        // Third-party read-only tools the user classified as safe; the built-in
+        // read-only/internal sets already cover DSH's own tools.
+        autoAllowTools: Array.isArray(config.autoAllowTools) ? config.autoAllowTools : undefined,
+        // `approval: never` rejects every request before any answerer runs, so an
+        // ask the gate cannot answer must pass through instead of denying.
+        //
+        // Capability probe, not a version check: `effectivePolicy` is private in
+        // both DSH 0.1.1-rc.2 and 0.1.2-rc.1, so an absent or throwing reader means
+        // "unknown policy" — return undefined and let the ask stand (the approval
+        // seam then decides). Never surface the failure to the decision path.
+        readApprovalPolicy: (exec) => {
+            const read = approvalService?.effectivePolicy;
+            if (typeof read !== 'function')
+                return undefined;
+            try {
+                const policy = read.call(approvalService, exec.agent?.session);
+                return typeof policy === 'string' ? policy : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
         eventsFile: typeof config.eventsFile === 'string' && config.eventsFile !== ''
             ? config.eventsFile
-            : (dataDir !== undefined ? join(dataDir, 'events.jsonl') : undefined),
+            : join(dataDir, 'events.jsonl'),
+        // Per-event pre-change snapshots back the review page's diff/revert plane.
+        snapshotsDir: typeof config.snapshotsDir === 'string' && config.snapshotsDir !== ''
+            ? config.snapshotsDir
+            : join(dataDir, 'snapshots'),
     });
     installSettingsSection(ctx, PERMISSIVE_NAMESPACE, Config, config, {
         setSource: (source) => {
@@ -105,36 +294,105 @@ export function apply(ctx, config = {}) {
     // Event feed HTTP API (best effort): the dsh webServer service exposes the
     // JSONL decision events to the browser half; without it events stay on disk.
     try {
-        const webServer = ctx.get('webServer');
+        const webServerCandidate = (injected.webServer ?? fallbackGet('webServer'));
+        const webServer = webServerCandidate !== null && typeof webServerCandidate === 'object' && typeof webServerCandidate.register === 'function'
+            ? webServerCandidate
+            : undefined;
+        if (webServer === undefined) {
+            // Loud but non-fatal: everything else keeps working without the HTTP routes.
+            console.warn('[dsh-perm-gate] webServer service unavailable — events/learning/health/receiver routes not registered');
+        }
         if (webServer !== undefined && runtime.eventLog !== undefined) {
-            registerEventsRoute(webServer, runtime.eventLog);
+            const offEvents = registerEventsRoute(webServer, runtime.eventLog);
+            if (offEvents !== undefined)
+                ctx.effect(() => () => { offEvents(); }, 'dsh-perm-gate: events route');
+        }
+        // Review-page plane (diff / revert / snapshot stats / snapshot clear): the
+        // approval-history view's file chips and snapshot bar drive these.
+        if (webServer !== undefined && runtime.eventLog !== undefined && runtime.snapshotDir !== undefined) {
+            const offs = registerReviewRoutes(webServer, {
+                log: runtime.eventLog,
+                snapshotsDir: runtime.snapshotDir,
+                send: buildSessionSender(fallbackGet),
+            });
+            for (const off of offs) {
+                ctx.effect(() => () => { off(); }, 'dsh-perm-gate: review route');
+            }
+        }
+        if (webServer !== undefined) {
+            const offLearning = registerLearningRoute(webServer, {
+                snapshot: () => runtime.learningSnapshot(),
+                threshold: () => runtime.learningThreshold(),
+                reset: (key, fp) => { runtime.learningReset(key, fp); },
+            });
+            if (offLearning !== undefined)
+                ctx.effect(() => () => { offLearning(); }, 'dsh-perm-gate: learning route');
+            const offHealth = registerHealthRoute(webServer, { check: () => runtime.healthCheck() });
+            if (offHealth !== undefined)
+                ctx.effect(() => () => { offHealth(); }, 'dsh-perm-gate: health route');
+            // Receiver projection for the settings card (provider/model catalog is
+            // potentially slow to enumerate — cached briefly).
+            let receiverCache = null;
+            const offReceiver = registerReceiverRoute(webServer, {
+                info: async () => {
+                    const now = Date.now();
+                    if (receiverCache !== null && now - receiverCache.at < 60_000)
+                        return receiverCache.info;
+                    const c = current();
+                    const info = await buildReceiverInfo({
+                        source: c.classifierSource === 'host' ? 'host' : 'custom',
+                        llm: llmService,
+                        currentSelection: () => {
+                            try {
+                                return hostModelService?.currentSelection?.();
+                            }
+                            catch {
+                                return undefined;
+                            }
+                        },
+                        overrideProvider: typeof c.classifierProvider === 'string' ? c.classifierProvider : '',
+                        overrideModel: typeof c.classifierModel === 'string' ? c.classifierModel : '',
+                        customModel: typeof c.classifierModel === 'string' ? c.classifierModel : '',
+                    });
+                    receiverCache = { at: now, info };
+                    return info;
+                },
+            });
+            if (offReceiver !== undefined)
+                ctx.effect(() => () => { offReceiver(); }, 'dsh-perm-gate: receiver route');
         }
     }
     catch {
-        // webServer unavailable: the feed remains disk-only
+        // webServer unavailable: the feed remains disk-only, sediment is view-only in files
     }
-    const listener = async (exec, next) => {
-        const decision = runtime.decideExecution(exec);
-        if (decision === undefined)
-            return next();
-        // llmAssist: refine an `ask` with the risk grader before the human seam.
-        // undefined = auto-allowed (risk-safe / learned) → proceed.
-        if (decision.kind === 'ask') {
-            const refined = await runtime.refineAsk(exec, decision);
-            if (refined === undefined)
-                return next();
-            return refined;
-        }
-        return decision;
-    };
-    // `tools/pre-execute` / `tools/result` are dsh-tools events, not part of
-    // cordis core's typed `Events`, so they are registered through the string overload.
+    const listener = makePreExecuteListener(runtime);
+    // `tools/pre-execute` / `tools/result` / `approval/request` are service events,
+    // not part of cordis core's typed `Events`, so they are registered through the
+    // string overload.
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const host = ctx;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     host.on('tools/pre-execute', listener);
-    // Settle verdict-learning candidates: a result for a registered ask means the
-    // human approved it and it executed — one confirmation recorded.
-    host.on('tools/result', ((exec) => { runtime.settleExecution(exec); }));
+    // Fallback terminal-answer channel: settle the ask from the call's result,
+    // and settle a pending learning candidate (a result for one means the human
+    // approved it and it executed — one confirmation).
+    host.on('tools/result', ((exec, result) => { runtime.settleExecution(exec, result); }));
+    // Primary terminal-answer channel: passively observe the approval waterfall.
+    // The ask we vetoed is forwarded by dsh-tools to `approval.request(...)`, so
+    // the closed outcome is observable here. This listener MUST return `next()`'s
+    // value unchanged — a throw is normalized to `unavailable`, i.e. a rejection
+    // on the human's behalf. Requests we never tracked (other agents, other
+    // sources) are ignored.
+    const approvalAware = ctx;
+    approvalAware.inject(['approval'], (actx) => {
+        // Capture the live service: the gate reads `effectivePolicy` per call to
+        // learn whether an ask can reach a human (`approval: never` cannot).
+        approvalService = actx.approval;
+        const off = actx.on('approval/request', makeApprovalObserver(runtime));
+        actx.effect(() => () => {
+            off();
+            approvalService = undefined;
+        }, 'dsh-perm-gate: approval observer');
+    });
     return runtime;
 }

package/lib/learning.d.ts

@@ -12,6 +12,13 @@ export interface LearningDoc {
     /** key → the most recent confirmed samples (bounded). */
     samples: Record<string, LearningSample[]>;
 }
+/** One sedimented rule view: a threshold-reached key's confirmed sample. */
+export interface SedimentEntry {
+    readonly key: string;
+    readonly fp: string;
+    readonly ctx: string;
+    readonly at: number;
+}
 export interface RiskLearningOptions {
     /** Confirmations required before an exact-sample re-run may auto-allow. A getter reads the live setting. Default 3. */
     readonly threshold?: number | (() => number);
@@ -26,8 +33,8 @@ export interface RiskLearningOptions {
  * when they perform the same kind of write against the same-named target.
  */
 export declare function operationFingerprint(tool: string, args: Record<string, unknown>, commandText?: string): string;
-/** The learning key for one call: `tool|category` (only neutral learns today). */
-export declare function learnKey(tool: string, category: string): string;
+/** The learning key for one call: `tool|fingerprint` (fingerprint-level learning). */
+export declare function learnKey(tool: string, _category: string, fp?: string): string;
 export declare class RiskLearning {
     /** Persistence path; `undefined` keeps state in memory only. */
     private readonly filePath;
@@ -53,6 +60,16 @@ export declare class RiskLearning {
     confirm(key: string, fp: string, ctx: string): void;
     /** Drop all learning state (counts and samples) and persist the empty doc. */
     reset(): void;
+    /**
+     * The sedimented-rule view: every confirmed sample of a key whose count
+     * reached the threshold. These are the deterministic auto-allow rules —
+     * derived from the store, so no extra persistence is needed.
+     */
+    sedimented(): SedimentEntry[];
+    /** Remove one sedimented sample (its fingerprint no longer auto-allows). */
+    dropSample(key: string, fp: string): void;
+    /** Terminate learning for one key: drop its confirmation count and samples. */
+    resetKey(key: string): void;
     /** Read-only deep view (for tests and diagnostics). */
     snapshot(): LearningDoc;
 }

package/lib/learning.js

@@ -15,10 +15,12 @@
  */
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+// Single source of truth for the shell-tool roster: `evaluate.ts` owns it, so a
+// newly supported tool name cannot drift between the decision path and the
+// learning fingerprint (which is what hid the missing `shell` entry).
+import { SHELL_TOOLS } from './evaluate.js';
 const DEFAULT_THRESHOLD = 3;
 const DEFAULT_MAX_SAMPLES = 10;
-/** Shell tool names whose first argument word is the operation handle. */
-const SHELL_TOOLS = new Set(['bash', 'pwsh', 'sh', 'cmd', 'powershell']);
 /** Structured arg keys carrying the operation target. */
 const TARGET_KEYS = ['file_path', 'filePath', 'path', 'file', 'filename', 'target', 'url'];
 function basename(p) {
@@ -62,9 +64,9 @@ export function operationFingerprint(tool, args, commandText) {
     }
     return tool;
 }
-/** The learning key for one call: `tool|category` (only neutral learns today). */
-export function learnKey(tool, category) {
-    return `${tool}|${category}`;
+/** The learning key for one call: `tool|fingerprint` (fingerprint-level learning). */
+export function learnKey(tool, _category, fp) {
+    return fp !== undefined ? `${tool}|${fp}` : `${tool}|${_category}`;
 }
 function emptyDoc() {
     return { version: 1, confirmed: {}, samples: {} };
@@ -173,6 +175,46 @@ export class RiskLearning {
         this.loaded = true;
         this.persist();
     }
+    /**
+     * The sedimented-rule view: every confirmed sample of a key whose count
+     * reached the threshold. These are the deterministic auto-allow rules —
+     * derived from the store, so no extra persistence is needed.
+     */
+    sedimented() {
+        const doc = this.load();
+        const out = [];
+        for (const [key, count] of Object.entries(doc.confirmed)) {
+            if (count < this.threshold)
+                continue;
+            for (const s of doc.samples[key] ?? [])
+                out.push({ key, fp: s.fp, ctx: s.ctx, at: s.at });
+        }
+        return out;
+    }
+    /** Remove one sedimented sample (its fingerprint no longer auto-allows). */
+    dropSample(key, fp) {
+        const doc = this.load();
+        const list = doc.samples[key];
+        if (list === undefined)
+            return;
+        const next = list.filter((s) => s.fp !== fp);
+        if (next.length === list.length)
+            return;
+        if (next.length === 0)
+            delete doc.samples[key];
+        else
+            doc.samples[key] = next;
+        this.persist();
+    }
+    /** Terminate learning for one key: drop its confirmation count and samples. */
+    resetKey(key) {
+        const doc = this.load();
+        if (doc.confirmed[key] === undefined && doc.samples[key] === undefined)
+            return;
+        delete doc.confirmed[key];
+        delete doc.samples[key];
+        this.persist();
+    }
     /** Read-only deep view (for tests and diagnostics). */
     snapshot() {
         const doc = this.load();

package/lib/llm-presets.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Known OpenAI-compatible endpoint presets for the llmAssist receiver
+ * (the settings card fills endpoint + model from one pick; every field stays
+ * editable afterwards). Pure data shared by the node half and the client
+ * bundle, so it must stay import-free.
+ */
+/** One preset receiver endpoint. */
+export interface LlmPreset {
+    readonly id: string;
+    readonly label: string;
+    /** OpenAI-compatible base URL (the `/chat/completions` suffix is normalized away). */
+    readonly endpoint: string;
+    /** Suggested chat model id (editable after filling). */
+    readonly model: string;
+}
+export declare const LLM_PRESETS: readonly LlmPreset[];