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

package/lib/preset.js

@@ -0,0 +1,41 @@
+/**
+ * Session permission-preset awareness for dsh-perm-gate.
+ *
+ * `dsh-permission-presets` folds three durable knob events per session
+ * (`permission/preset`, `sandbox/mode`, `approval/policy`) and pins an initial
+ * `permission/preset` at session creation, so the last `permission/preset`
+ * event names the tier the user selected. The gate reads that fold to decide
+ * whether its own approval tier is the active one.
+ *
+ * Reading the session log directly (instead of requiring the
+ * `permissionPresets` service) keeps the gate usable in a bare embedding and
+ * avoids a hard dependency on a service that may not be composed. The fold
+ * matches `effectivePermissionPreset` in dsh-permission-presets: last event
+ * wins.
+ */
+/**
+ * Fold the last selected permission preset out of one session's event log.
+ * @param events - the session's events in log order.
+ * @returns the preset name, or `undefined` when the log records none.
+ */
+export function permissionPresetOf(events) {
+    if (events === undefined)
+        return undefined;
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        const event = events[index];
+        if (event?.type !== 'permission/preset')
+            continue;
+        const preset = event.data?.preset;
+        if (typeof preset === 'string' && preset !== '')
+            return preset;
+    }
+    return undefined;
+}
+/** Whether one preset name is covered by a configured scope list. */
+export function presetInScope(preset, scope) {
+    if (scope.includes('*'))
+        return true;
+    if (preset === undefined)
+        return false;
+    return scope.includes(preset);
+}

package/lib/receiver-info.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Receiver introspection for the settings card: which LLM the gate will
+ * actually use right now, plus (in host mode) the live provider/model-group
+ * catalog from the DSH `llm` service — including user-configured custom
+ * groups (e.g. a self-hosted provider), the same projection the harness's
+ * model catalog builds via `listProviders` / `listModels`.
+ *
+ * Pure projection: never throws, per-provider failures are reported inline so
+ * one broken group never blanks the whole list.
+ */
+/** One model entry as offered by a provider group. */
+export interface ReceiverModel {
+    readonly id: string;
+    readonly name: string;
+}
+/** One provider group and its models (or the reason it failed to enumerate). */
+export interface ReceiverProvider {
+    readonly id: string;
+    readonly name: string;
+    readonly models: readonly ReceiverModel[];
+    readonly error?: string;
+}
+/** What the settings card needs to render the receiver UI. */
+export interface ReceiverInfo {
+    readonly source: 'custom' | 'host';
+    /** The provider/model the gate will use right now (null when undetermined). */
+    readonly selection: {
+        readonly provider: string;
+        readonly model: string;
+    } | null;
+    /** Live provider groups; non-empty only in host mode. */
+    readonly providers: readonly ReceiverProvider[];
+}
+/** The minimal faces of the host services this projection reads. */
+export interface ReceiverDeps {
+    source: 'custom' | 'host';
+    /** Host `llm` service (host mode only). */
+    llm?: {
+        listProviders?: () => readonly {
+            id: string;
+            name: string;
+        }[];
+        listModels?: (providerId: string) => Promise<readonly {
+            id: string;
+            name: string;
+        }[]>;
+        listConfigurableProviders?: () => readonly {
+            provider: string;
+            settingsNs: string;
+        }[];
+        /** Discovery for a configured route answers from the adapter's own knowledge — no network call. */
+        discoverModels?: (settingsNs: string, request: {
+            provider?: string;
+        }) => Promise<readonly {
+            id: string;
+            name?: string;
+        }[]>;
+    };
+    /** Live session selection (agentDefaultModel.currentSelection). */
+    currentSelection?: () => {
+        provider?: unknown;
+        model?: unknown;
+    } | undefined;
+    /** Namespace overrides (empty string = follow the session). */
+    overrideProvider?: string;
+    overrideModel?: string;
+    /** The model field as configured for the custom receiver. */
+    customModel?: string;
+}
+/** Resolve the effective host model selection (override → session → default). */
+export declare function resolveHostSelection(deps: ReceiverDeps): {
+    provider: string;
+    model: string;
+};
+/** Build the receiver projection. Never throws. */
+export declare function buildReceiverInfo(deps: ReceiverDeps): Promise<ReceiverInfo>;

package/lib/receiver-info.js

@@ -0,0 +1,70 @@
+/**
+ * Receiver introspection for the settings card: which LLM the gate will
+ * actually use right now, plus (in host mode) the live provider/model-group
+ * catalog from the DSH `llm` service — including user-configured custom
+ * groups (e.g. a self-hosted provider), the same projection the harness's
+ * model catalog builds via `listProviders` / `listModels`.
+ *
+ * Pure projection: never throws, per-provider failures are reported inline so
+ * one broken group never blanks the whole list.
+ */
+function str(v) {
+    return typeof v === 'string' ? v : '';
+}
+/** Resolve the effective host model selection (override → session → default). */
+export function resolveHostSelection(deps) {
+    const sel = deps.currentSelection?.();
+    const provider = deps.overrideProvider !== '' && deps.overrideProvider !== undefined
+        ? deps.overrideProvider
+        : (str(sel?.provider) !== '' ? str(sel?.provider) : 'deepseek-official');
+    const model = deps.overrideModel !== '' && deps.overrideModel !== undefined
+        ? deps.overrideModel
+        : (str(sel?.model) !== '' ? str(sel?.model) : 'deepseek-v4-flash');
+    return { provider, model };
+}
+/** Build the receiver projection. Never throws. */
+export async function buildReceiverInfo(deps) {
+    if (deps.source !== 'host' || deps.llm?.listProviders === undefined) {
+        return {
+            source: deps.source,
+            selection: deps.source === 'custom' && str(deps.customModel) !== ''
+                ? { provider: 'custom', model: str(deps.customModel) }
+                : null,
+            providers: [],
+        };
+    }
+    const selection = resolveHostSelection(deps);
+    const raw = deps.llm.listProviders();
+    const providers = await Promise.all(raw.map(async (p) => {
+        let models = [];
+        let error;
+        try {
+            models = (await deps.llm?.listModels?.(p.id) ?? []).map((m) => ({ id: m.id, name: m.name }));
+        }
+        catch (e) {
+            error = String(e?.message ?? e);
+        }
+        if (models.length === 0) {
+            // Fallback: route discovery. For an already-configured route the
+            // adapter answers from its own stored knowledge (no network call) —
+            // this also covers builds whose `listModels` is absent or dormant.
+            try {
+                const entry = deps.llm?.listConfigurableProviders?.().find((c) => c.provider === p.id);
+                if (entry !== undefined && deps.llm?.discoverModels !== undefined) {
+                    const discovered = await deps.llm.discoverModels(entry.settingsNs, { provider: p.id });
+                    if (discovered.length > 0) {
+                        models = discovered.map((m) => ({ id: m.id, name: m.name ?? m.id }));
+                        error = undefined;
+                    }
+                }
+            }
+            catch {
+                // keep the primary error / empty state
+            }
+        }
+        if (models.length === 0 && error === undefined)
+            error = 'no models advertised';
+        return { id: p.id, name: p.name, models, ...(error === undefined ? {} : { error }) };
+    }));
+    return { source: 'host', selection, providers };
+}

package/lib/risk.d.ts

@@ -6,7 +6,8 @@
  *
  *   safe                      → the gate may auto-allow the ask
  *   risky:<hard category>     → deletion / credential / remote / system / bulk —
- *                               ALWAYS routed to the human, never auto-allowed
+ *                               auto-deny: the operation is clearly dangerous,
+ *                               no popup or human review needed
  *   risky:neutral             → no hard-risk signal but not clearly safe; the
  *                               verdict-learning path may auto-allow after
  *                               enough human confirmations
@@ -56,3 +57,17 @@ export declare function parseRiskVerdict(content: string): RiskVerdict | undefin
  * any failure, timeout, or protocol violation resolves `unresolved` — never throws.
  */
 export declare function classifyRisk(cfg: ClassifierConfig, req: RiskRequest, nowFetch?: typeof fetch): Promise<RiskVerdict>;
+/** A transport-agnostic completion: system+user prompt → assistant text. */
+export type RiskSend = (system: string, user: string) => Promise<{
+    ok: true;
+    content: string;
+} | {
+    ok: false;
+}>;
+/** The bounded user prompt for one risk grading (shared by every transport). */
+export declare function riskUserText(req: RiskRequest): string;
+/**
+ * Grade one tool call through any transport. Up to two attempts (one retry);
+ * any failure, timeout, or protocol violation resolves `unresolved` — never throws.
+ */
+export declare function classifyRiskWith(send: RiskSend, req: RiskRequest): Promise<RiskVerdict>;

package/lib/risk.js

@@ -6,7 +6,8 @@
  *
  *   safe                      → the gate may auto-allow the ask
  *   risky:<hard category>     → deletion / credential / remote / system / bulk —
- *                               ALWAYS routed to the human, never auto-allowed
+ *                               auto-deny: the operation is clearly dangerous,
+ *                               no popup or human review needed
  *   risky:neutral             → no hard-risk signal but not clearly safe; the
  *                               verdict-learning path may auto-allow after
  *                               enough human confirmations
@@ -87,13 +88,24 @@ export function parseRiskVerdict(content) {
  * any failure, timeout, or protocol violation resolves `unresolved` — never throws.
  */
 export async function classifyRisk(cfg, req, nowFetch = fetch) {
-    const user = JSON.stringify({
+    return classifyRiskWith((system, user) => chatCompletion(cfg, system, user, nowFetch), req);
+}
+/** The bounded user prompt for one risk grading (shared by every transport). */
+export function riskUserText(req) {
+    return JSON.stringify({
         tool: req.tool,
         args: req.args ?? {},
         reason: req.reason,
         instruction: 'Reply strictly as one JSON object: {"risk":"safe"} or {"risk":"risky","category":"..."} plus a short "reason".',
     });
-    const content = await withLlmRetry(() => chatCompletion(cfg, RISK_SYSTEM_PROMPT, user, nowFetch).then((r) => (r.ok ? r.content : undefined)));
+}
+/**
+ * Grade one tool call through any transport. Up to two attempts (one retry);
+ * any failure, timeout, or protocol violation resolves `unresolved` — never throws.
+ */
+export async function classifyRiskWith(send, req) {
+    const user = riskUserText(req);
+    const content = await withLlmRetry(() => send(RISK_SYSTEM_PROMPT, user).then((r) => (r.ok ? r.content : undefined)));
     if (content === undefined)
         return { kind: 'unresolved' };
     return parseRiskVerdict(content) ?? { kind: 'unresolved' };

package/lib/runtime.d.ts

@@ -4,7 +4,9 @@ import type { ClassifierConfig } from './classifier.js';
 import { EventLog } from './events.js';
 import { RiskLearning } from './learning.js';
 import { type RiskRequest, type RiskVerdict } from './risk.js';
+import { type HostLlmLike, type HostModelSelection } from './host-llm.js';
 import { type CompiledRuleset } from './rule.js';
+import { type SessionEventLike } from './preset.js';
 export interface PreToolDecisionLike {
     kind: 'deny' | 'ask';
     reason: string;
@@ -17,6 +19,50 @@ export interface ToolExecutionLike {
     readonly sessionId?: string;
     readonly parentAuthorized?: boolean;
     readonly signal?: AbortSignal;
+    /** Host-minted execution id; the correlation key for an ask's terminal answer. */
+    readonly callId?: string;
+    /**
+     * The host agent face. DSH carries the session here — `exec.sessionId` and
+     * `exec.cwd` are usually absent — so the session id and workspace cwd must be
+     * read from `agent.session.id` / `agent.session.header.cwd`.
+     */
+    readonly agent?: {
+        readonly session?: {
+            readonly id?: string;
+            readonly header?: {
+                readonly cwd?: string;
+            };
+            /** The durable event log; the permission-preset fold reads it. */
+            readonly events?: readonly SessionEventLike[];
+        };
+    };
+}
+/**
+ * The face of a `tools/result` payload this plugin inspects: a human rejection
+ * surfaces as `isError` plus the approval seam's reason message (see findings E3).
+ */
+export interface ToolResultLike {
+    readonly isError?: boolean;
+    readonly error?: {
+        readonly message?: string;
+    };
+}
+/**
+ * One ask awaiting the human's answer. The event context is snapshotted when
+ * the ask is recorded, because the `approval/request` observer has no execution
+ * object of its own — the terminal event must still carry the right session and
+ * file chips.
+ */
+interface PendingAsk {
+    readonly reason: string;
+    readonly tool: string;
+    readonly sessionId: string;
+    readonly files: readonly string[];
+    readonly baseDir?: string;
+    /** Snapshot file key: used to load pre-change snapshots for review. */
+    readonly snapshotId: number;
+    /** Set when this ask also registered a learning candidate (drives the progress chip). */
+    readonly learningKey?: string;
 }
 export interface PermGateRuntimeOptions extends PermGateConfig {
     readonly onRulesChanged?: (ruleset: CompiledRuleset) => void;
@@ -30,15 +76,54 @@ export interface PermGateRuntimeOptions extends PermGateConfig {
     readonly readPermissive?: () => PermissiveState;
     /** Optional live source of the llmAssist classifier setup. */
     readonly readClassifyConfig?: () => ClassifierConfig;
+    /**
+     * Optional live receiver source: `'custom'` (an OpenAI-compatible endpoint,
+     * default) or `'host'` (the DSH host `llm` service — the model-group setup
+     * the user already configured, via {@link hostLlm}).
+     */
+    readonly readClassifySource?: () => 'custom' | 'host';
+    /** The host `llm` service (typed minimally); `undefined` disables the host receiver. */
+    readonly hostLlm?: HostLlmLike;
+    /**
+     * Live model-group selection for the host receiver (e.g. DSH's
+     * agentDefaultModel.currentSelection, possibly overridden from settings).
+     */
+    readonly readHostModel?: () => HostModelSelection | undefined;
     /**
      * Optional live source of the verdict-learning state. When unset, the static
      * `riskLearning` / `riskThreshold` options apply.
      */
     readonly readRiskLearning?: () => RiskLearningState;
+    /**
+     * Optional live switch for learning sedimentation (default on while verdict
+     * learning is enabled): a threshold-reached key's confirmed fingerprint
+     * becomes a deterministic auto-allow — no LLM round-trip, and it survives
+     * the llmAssist switch because the human confirmations already happened.
+     */
+    readonly readRiskSediment?: () => boolean;
+    /**
+     * Optional live source of the deny-keyword blacklist. `undefined` or an
+     * empty array applies the preset `DEFAULT_DENY_KEYWORDS` (the blacklist is
+     * protective and never silently off); a non-empty array replaces the preset.
+     */
+    readonly readDenyKeywords?: () => readonly string[] | undefined;
+    /**
+     * Optional live source of the session's effective approval policy (`'ask'` /
+     * `'never'`), normally `approval.effectivePolicy(agent.session)`. Under
+     * `'never'` the DSH approval seam rejects every request before any answerer
+     * runs, so an ask the gate cannot answer degrades to passthrough instead of
+     * becoming a denial that reads as "the user rejected tool ...".
+     */
+    readonly readApprovalPolicy?: (exec: ToolExecutionLike) => string | undefined;
     /** Persistence path for verdict learning; `undefined` keeps it in memory. */
     readonly learningFile?: string;
     /** Persistence path for the decision-event feed; `undefined` disables it. */
     readonly eventsFile?: string;
+    /**
+     * Directory for per-event pre-change file snapshots; `undefined` disables the
+     * review page's diff/revert data plane (events are still recorded).
+     */
+    readonly snapshotsDir?: string;
 }
 export type CallDecision = 'allow' | 'deny' | 'ask';
 /** The effective Permissive tier state read per tool call. */
@@ -60,10 +145,23 @@ export declare class PermGateRuntime {
     private readonly cache;
     private readonly permissiveEnabled;
     private readonly strategies;
+    /** Presets in which this gate is active at all; outside them it stands down. */
+    private readonly gatePresets;
+    /** Extra tool names the user classified as safe (config `autoAllowTools`). */
+    private readonly autoAllowExtra;
+    /** Cache of the permission-preset fold, keyed by log identity + length. */
+    private presetCache;
     private readonly learning;
     private readonly events?;
     /** Learning candidates awaiting human approval + execution (call fingerprint → candidate). */
     private readonly pending;
+    /**
+     * Asks awaiting the human's terminal answer, keyed by {@link askKey}. Both the
+     * approval observer (primary) and `tools/result` (fallback) settle an entry by
+     * deleting it — "delete on settle" is the whole de-duplication rule, so a
+     * missing `callId` or an untriggered observer can never lose a record.
+     */
+    private readonly pendingAsks;
     constructor(options?: PermGateRuntimeOptions);
     private compileInline;
     /** Reload rules from disk (HMR); on failure keeps the previous rules. */
@@ -79,14 +177,77 @@ export declare class PermGateRuntime {
     artifactCount(): number;
     /** The decision-event feed (undefined when event recording is disabled). */
     get eventLog(): EventLog | undefined;
+    /** The snapshot directory backing diff/revert (undefined when disabled). */
+    get snapshotDir(): string | undefined;
     /** Learning candidates currently awaiting settlement (diagnostics/tests). */
     pendingCount(): number;
     /** Deep read-only view of the learning state (diagnostics/tests). */
     learningSnapshot(): ReturnType<RiskLearning['snapshot']>;
     private ctxFor;
     private liveRiskLearning;
+    private liveRiskSediment;
+    private liveClassifySource;
+    /** The host model-group selection, or undefined when unusable. */
+    private hostModel;
     private livePermissive;
+    /**
+     * The session's selected permission preset, folded from its event log. The
+     * fold is cached by the log array identity plus its length: a session's log
+     * is a stable, append-only array, so a changed reference or a grown log
+     * invalidates the cache while repeated calls on the same log stay cheap.
+     */
+    private presetOf;
+    /**
+     * Whether this gate is active for one call at all.
+     *
+     * The gate owns an independent permission tier, so it only acts while that
+     * tier (or another preset the user listed in `gatePresets`) is selected.
+     * Outside it the gate stands down completely — no allow, no ask, no deny, no
+     * P0 hard-deny — because the selected tier's own policy governs the session:
+     * `danger-full-access` means "full access without approval prompts", where a
+     * forwarded ask can only fail (the approval seam rejects before any answerer
+     * runs) and a hard-deny would silently overrule the tier the user chose.
+     */
+    private gateActive;
+    /**
+     * Whether an `ask` produced while the gate is active can actually reach a
+     * human. Under `approval: never` the DSH approval seam returns `rejected`
+     * before any answerer runs, so such an ask degrades to passthrough.
+     *
+     * The reader is an optional duck-typed seam (the host half probes a PRIVATE
+     * approval-service method, identical in DSH 0.1.1-rc.2 and 0.1.2-rc.1). A
+     * throwing reader must not kill the decision path: "unknown" is treated as
+     * answerable, so the ask stands and the approval seam decides.
+     */
+    private askAnswerable;
+    /** Effective deny-keyword blacklist: the live namespace override or the preset.
+     * An empty override is treated as "no meaningful override" (the blacklist is
+     * protective and stays on); schemastery materializes unset arrays as `[]`. */
+    private liveDenyKeywords;
+    /**
+     * The preset deny-keyword layer (inherited from dsh-approval-gate): a keyword
+     * hit over the call's command/argument text vetoes it with `deny` before any
+     * allow path (deny wins over allow). Purely additive to P0 — it can only ever
+     * deny, never widen. Matching is boundary-aware and skips document bodies, so
+     * a keyword can no longer veto an unrelated identifier or a file's text.
+     */
+    private denyKeywordHit;
+    /**
+     * Record one decision event on the feed. `verdict` labels the decision path
+     * for the history view; `files` (defaulted from the call itself) drives the
+     * snapshot/diff/revert chain, and `baseDir` resolves relative paths.
+     */
     private recordEvent;
+    /** The correlation key of one ask: its call id, or a canonical call fingerprint. */
+    private askKey;
+    /** Remember one ask so either settlement channel can record its terminal answer. */
+    private trackAsk;
+    /** Drop one tracked ask without recording it (the call never needed a human). */
+    private untrackAsk;
+    /** Asks currently awaiting a terminal answer (diagnostics/tests). */
+    pendingAskCount(): number;
+    /** Get one pending ask by its key (diagnostics/tests only). */
+    getPendingAsk(key: string): PendingAsk | undefined;
     /**
      * Decide one tool call. Returns a decision to veto (`deny`/`ask`) or
      * undefined to delegate via `next()` (allow / passthrough). Always records an
@@ -117,11 +278,55 @@ export declare class PermGateRuntime {
      */
     refineAsk(exec: ToolExecutionLike, decision: PreToolDecisionLike): Promise<PreToolDecisionLike | undefined>;
     /**
-     * Settle a learning candidate after the call finished (`tools/result`).
-     * A result arriving for a registered pending candidate means the human
-     * approved it and it actually executed — record one confirmation.
+     * Record the human's terminal answer for one tracked ask. This is the primary
+     * channel, driven by the `approval/request` observer, which sees the closed
+     * outcome (`allowed-once` / `rejected` / `cancelled` / `unavailable`) without
+     * having to parse any reason text.
+     *
+     * Consuming the entry is the entire de-duplication rule: a second call for the
+     * same ask — or a later `tools/result` — finds nothing and records nothing.
+     * @returns whether an ask was settled.
+     */
+    settleAskOutcome(callId: string, outcome: string): boolean;
+    /**
+     * Settle after the call finished (`tools/result`): the fallback channel for an
+     * ask whose approval never surfaced to the observer (no approval service, a
+     * missing `callId`, or an earlier listener short-circuiting the waterfall).
+     * Also settles a pending learning candidate: a result for one means the human
+     * approved it and it actually executed — one confirmation.
+     */
+    settleExecution(exec: ToolExecutionLike, result?: ToolResultLike): void;
+    /**
+     * Promote a pending learning candidate to a session-level grant: the same
+     * operation auto-passes for the rest of the session (bounded by TTL and
+     * max-uses) without waiting for human confirmations. This is the "one-click
+     * allow in session" shortcut the settings card can expose.
+     *
+     * @returns `true` when a pending candidate was promoted.
+     */
+    approveSessionGrant(exec: ToolExecutionLike): boolean;
+    /** Classify one `tools/result` payload into the ask's terminal outcome. */
+    private settleAskFromResult;
+    /**
+     * Write one terminal event from the ask's snapshotted context. The observer
+     * has no execution object of its own, so everything here comes from what
+     * {@link trackAsk} captured when the ask was recorded.
+     */
+    private recordAskOutcome;
+    /** The live confirmation threshold the sediment view compares counts against. */
+    learningThreshold(): number;
+    /** Terminate one key's learning, or drop a single sedimented sample. */
+    learningReset(key: string, fp?: string): void;
+    /**
+     * One minimal completion through the currently configured receiver (host
+     * model group or custom endpoint) with latency — the settings card's
+     * "health test". Never throws; failures come back as `ok: false` + detail.
      */
-    settleExecution(exec: ToolExecutionLike): void;
+    healthCheck(): Promise<{
+        ok: boolean;
+        ms: number;
+        detail: string;
+    }>;
     /** Mint a precise session grant bound to a canonical call fingerprint. */
     grant(exec: ToolExecutionLike, maxUses: number, ttlMs: number): void;
     /**
@@ -144,3 +349,4 @@ export declare class PermGateRuntime {
      */
     setAllowlist(patterns: readonly string[]): boolean;
 }
+export {};