dsh-perm-gate 1.0.0 → 2.1.0

package/lib/risk.js

@@ -43,9 +43,9 @@ const RISK_SYSTEM_PROMPT = [
     '  {"risk":"risky","category":"<category>","reason":"short"}',
     '',
     'category must be exactly one of:',
-    '  deletion  — deletes or overwrites data that cannot be regenerated',
+    '  deletion  — deletes or overwrites data that cannot be regenerated (IMPORTANT: see exclusion rules below)',
     '  credential — creates/modifies/exposes credentials, keys, tokens, auth config',
-    '  remote    — affects remote systems, production, databases, messaging, billing, publishing',
+    '  remote    — WRITES to or MODIFIES remote systems (git push, git deploy, kubectl apply, terraform apply, production database writes, messaging, billing, publishing). Must have a write/modify/delete effect on the remote side.',
     '  system    — system-level paths or configuration (/etc, /usr, boot items), shutdown/reboot',
     '  bulk      — mass overwrite of many files, formatting, dd-style irreversible writes',
     '  neutral   — none of the above clearly applies (ordinary edits outside the obvious scope, or you are unsure but see no hard-risk sign)',
@@ -54,6 +54,17 @@ const RISK_SYSTEM_PROMPT = [
     '- safe is only for reversible, in-scope operations that touch no sensitive resource.',
     '- When unsure between safe and neutral, answer neutral; never guess safe.',
     '- Judge the operation content, not merely its location.',
+    '',
+    'DELETION exclusion rules (these override the deletion category):',
+    '- Cleanup of temporary files, build outputs, or failed clone directories is SAFE — even if using rm/rmdir/Remove-Item. Look for temp paths: paths containing "temp", "tmp", "test-clone", "node_modules", ".cache", "dist", "build", or numbered/timestamped directories.',
+    '- Removal of session-local artifacts (files the session itself created) is SAFE.',
+    '- rm -rf on node_modules, .next, __pycache__, .pytest_cache, .git, dist, build is SAFE — these are always regenerable.',
+    '- Deletion inside the workspace that targets non-existent or already-empty paths is SAFE (idempotent cleanup).',
+    '- Only flag as deletion when the target is: (a) user data with no backup, (b) configuration files, (c) database records, (d) files outside the workspace that were not created by this session, or (e) a destructive rm -rf on a directory containing unique, irreplaceable content.',
+    '',
+    'READ-ONLY remote operations are safe: git fetch, git pull, git clone, git log, git diff, git status, git show, npm install (read-only), pip install (read-only), apt-get update, curl/wget (read, no write flag).',
+    '- Operations that only READ from remote systems without modifying them are safe, even if they involve network traffic.',
+    '- Only flag as remote when the operation WRITES, DEPLOYS, PUSHES, or DELETES on the remote side.',
 ].join('\n');
 /** Parse one assistant message into a verdict; anything off-protocol → undefined (caller retries/fails). */
 export function parseRiskVerdict(content) {
@@ -92,9 +103,21 @@ export async function classifyRisk(cfg, req, nowFetch = fetch) {
 }
 /** The bounded user prompt for one risk grading (shared by every transport). */
 export function riskUserText(req) {
+    // Enrich the prompt with full path context so the LLM can judge
+    // whether a deletion targets a temporary/build artifact vs real data.
+    const raw = req.args ?? {};
+    const argsRecord = (typeof raw === 'object' && raw !== null ? raw : {});
+    const enriched = { ...argsRecord };
+    // Surface the working directory if present (helps LLM see temp paths).
+    if (typeof enriched.cwd === 'string' && enriched.cwd !== '') {
+        enriched.__cwd = enriched.cwd;
+    }
+    if (typeof enriched.workdir === 'string' && enriched.workdir !== '') {
+        enriched.__cwd = enriched.workdir;
+    }
     return JSON.stringify({
         tool: req.tool,
-        args: req.args ?? {},
+        args: enriched,
         reason: req.reason,
         instruction: 'Reply strictly as one JSON object: {"risk":"safe"} or {"risk":"risky","category":"..."} plus a short "reason".',
     });

package/lib/runtime.d.ts

@@ -27,13 +27,21 @@ export interface ToolExecutionLike {
      * read from `agent.session.id` / `agent.session.header.cwd`.
      */
     readonly agent?: {
+        /** The agent's own session id (DSH ≥ 0.1.2 exposes it beside `session`). */
+        readonly sessionId?: string;
         readonly session?: {
             readonly id?: string;
             readonly header?: {
                 readonly cwd?: string;
             };
-            /** The durable event log; the permission-preset fold reads it. */
+            /**
+             * The durable event log, behind whichever accessor this DSH line ships:
+             * a plain `events` array (0.1.1), or the `snapshotEvents()` / `ownEvents()`
+             * readers 0.1.2 replaced it with. See {@link sessionEventsOf}.
+             */
             readonly events?: readonly SessionEventLike[];
+            readonly snapshotEvents?: () => readonly SessionEventLike[];
+            readonly ownEvents?: () => readonly SessionEventLike[];
         };
     };
 }
@@ -157,7 +165,14 @@ export declare class PermGateRuntime {
     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. */
+    /**
+     * Cache of the permission-preset fold. The key is the log's length plus the
+     * identity of its LAST event: a session's log only appends, so "same length
+     * and same last event" means the last `permission/preset` event is unchanged.
+     * Identity of the tail — not of the array — is the key because DSH 0.1.2's
+     * `snapshotEvents()` answers every read with a fresh array over the same
+     * frozen events, which would otherwise re-fold on every tool call.
+     */
     private presetCache;
     private readonly learning;
     private readonly events?;
@@ -206,9 +221,11 @@ export declare class PermGateRuntime {
     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.
+     * fold is cached on the log's length plus the identity of its last event: a
+     * session's log only appends, so an unchanged tail means the last
+     * `permission/preset` event is unchanged too. Tail identity — rather than the
+     * array's — is the key because DSH 0.1.2's snapshot accessor returns a fresh
+     * array over the same frozen events on every read.
      */
     private presetOf;
     /**

package/lib/runtime.js

@@ -18,6 +18,7 @@ import { decideRules } from './evaluate.js';
 import { canonicalizeCall, GrantRegistry } from './grant.js';
 import { learnKey, operationFingerprint, RiskLearning } from './learning.js';
 import { ArtifactRegistry } from './path.js';
+import { decomposeShellCommand } from './shell.js';
 import { classifyRisk, classifyRiskWith } from './risk.js';
 import { completeViaHost, DEFAULT_HOST_MODEL } from './host-llm.js';
 import { chatCompletion } from './classifier.js';
@@ -25,11 +26,50 @@ import { compileDocument, documentHash, extractPathCandidates, parsePermissionsD
 import { DEFAULT_DENY_KEYWORDS } from './deny-defaults.js';
 import { permissionPresetOf, presetInScope } from './preset.js';
 import { resolveGatePresets } from './config.js';
+/**
+ * One execution's session event log, or `undefined` when the host exposes none.
+ *
+ * The accessor moved between DSH lines: 0.1.1 exposed `session.events` as a
+ * plain array, while 0.1.2 made the log private behind `snapshotEvents()` /
+ * `ownEvents()`. Reading only `.events` therefore made {@link
+ * PermGateRuntime.presetOf} return `undefined` on 0.1.2, which silently stood
+ * the whole gate down (no rule, grant, deny-keyword, or P0 hard-deny decision,
+ * and no audit event). Every carrier is probed, array-first; a throwing or
+ * missing accessor just moves to the next one, so an unknown future shape
+ * degrades to "no events" instead of breaking the decision path.
+ *
+ * @param exec - the execution whose owning session is inspected.
+ * @returns the session's events in log order, or `undefined`.
+ */
+function sessionEventsOf(exec) {
+    const session = exec.agent?.session;
+    for (const carrier of [session, exec]) {
+        if (carrier === undefined)
+            continue;
+        const direct = carrier.events;
+        if (Array.isArray(direct))
+            return direct;
+        for (const read of ['snapshotEvents', 'ownEvents']) {
+            const accessor = carrier[read];
+            if (typeof accessor !== 'function')
+                continue;
+            try {
+                const events = accessor.call(carrier);
+                if (Array.isArray(events))
+                    return events;
+            }
+            catch {
+                // An accessor that throws is no accessor: try the next carrier.
+            }
+        }
+    }
+    return undefined;
+}
 /** The session id of one execution (direct field, else the agent's session). */
 function sessionIdOf(exec) {
     if (typeof exec.sessionId === 'string' && exec.sessionId !== '')
         return exec.sessionId;
-    const id = exec.agent?.session?.id;
+    const id = exec.agent?.sessionId ?? exec.agent?.session?.id;
     return typeof id === 'string' ? id : '';
 }
 /** The workspace cwd of one execution (direct field, else the session header). */
@@ -60,6 +100,70 @@ const CLEARED_CALL_TTL_MS = 5 * 60_000;
  * unrecognized wording fails closed (the request is forwarded to the human).
  */
 const SANDBOX_ESCALATION_REASON = /^escalate sandbox to (workspace-write|danger-full-access): /;
+// --- Deterministic cleanup pre-screen ----------------------------------------
+// Pattern for shell deletion commands (rm, rmdir, Remove-Item) with flags.
+const SHELL_DELETE_RE = /^(?:rm|rmdir|Remove-Item)\b/i;
+// Temp/build artifact directory name patterns (case-insensitive match on each path segment).
+const REGENERABLE_SEGMENT = /(?:^|[\\/])(?:temp|tmp|test[-_]clone|node_modules|\.cache|dist|build|__pycache__|\.pytest_cache|\.git|\.next|\.nuxt|coverage|\.tox|\.venv|venv|env|\.mypy_cache|\.parcel-cache)(?:[\\/]|$)/i;
+// Workspace-relative path tokens that are always regenerable.
+const REGENERABLE_TOKENS = /^(?:node_modules|\.next|__pycache__|\.cache|dist|build|\.git|coverage|\.pytest_cache|\.tox|\.venv|venv|env)$/i;
+/**
+ * Deterministic pre-screen for deletion commands. Returns a reason string when
+ * the deletion is clearly safe (targeting a regenerable/temp artifact inside the
+ * workspace), or undefined when the LLM should decide.
+ *
+ * This runs BEFORE the LLM risk grader to avoid the LLM's unconditional
+ * "Remove-Item → risky:deletion" bias. The LLM is still the fallback for
+ * ambiguous cases.
+ */
+function isCleanupSafe(exec) {
+    const tool = exec.name;
+    const args = exec.arguments ?? {};
+    // Only applies to shell/pwsh tools.
+    if (!/^(?:pwsh|bash|sh|cmd|shell|terminal)$/i.test(tool))
+        return undefined;
+    const commandText = typeof args.command === 'string' ? args.command : undefined;
+    if (commandText === undefined)
+        return undefined;
+    let commands = [];
+    try {
+        commands = decomposeShellCommand(commandText).commands;
+    }
+    catch {
+        return undefined;
+    }
+    const cwd = typeof args.cwd === 'string' ? args.cwd : cwdOf(exec) ?? '';
+    const posixCwd = cwd.replace(/\\/g, '/').toLowerCase();
+    for (const cmd of commands) {
+        if (!SHELL_DELETE_RE.test(cmd.command))
+            continue;
+        // Collect all non-flag argument tokens as potential targets.
+        const targets = cmd.args.filter((a) => !a.startsWith('-'));
+        if (targets.length === 0)
+            continue;
+        let allSafe = true;
+        for (const target of targets) {
+            const posixTarget = target.replace(/\\/g, '/').toLowerCase();
+            // Resolve relative to cwd.
+            const fullPath = posixTarget.startsWith('/') || /^[a-z]:\//i.test(posixTarget)
+                ? posixTarget
+                : posixCwd !== '' ? `${posixCwd}/${posixTarget}` : posixTarget;
+            // Check if the target path contains a regenerable segment.
+            if (REGENERABLE_SEGMENT.test(fullPath))
+                continue;
+            // Check bare token (e.g. "node_modules" without path separators).
+            if (REGENERABLE_TOKENS.test(target))
+                continue;
+            // Not clearly regenerable — let the LLM decide.
+            allSafe = false;
+            break;
+        }
+        if (allSafe) {
+            return `deletion targets regenerable/temp artifacts: ${targets.join(', ')}`;
+        }
+    }
+    return undefined;
+}
 export class PermGateRuntime {
     options;
     ruleset;
@@ -73,7 +177,14 @@ export class PermGateRuntime {
     gatePresets;
     /** Extra tool names the user classified as safe (config `autoAllowTools`). */
     autoAllowExtra;
-    /** Cache of the permission-preset fold, keyed by log identity + length. */
+    /**
+     * Cache of the permission-preset fold. The key is the log's length plus the
+     * identity of its LAST event: a session's log only appends, so "same length
+     * and same last event" means the last `permission/preset` event is unchanged.
+     * Identity of the tail — not of the array — is the key because DSH 0.1.2's
+     * `snapshotEvents()` answers every read with a fresh array over the same
+     * frozen events, which would otherwise re-fold on every tool call.
+     */
     presetCache;
     learning;
     events;
@@ -224,18 +335,21 @@ export class PermGateRuntime {
     }
     /**
      * 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.
+     * fold is cached on the log's length plus the identity of its last event: a
+     * session's log only appends, so an unchanged tail means the last
+     * `permission/preset` event is unchanged too. Tail identity — rather than the
+     * array's — is the key because DSH 0.1.2's snapshot accessor returns a fresh
+     * array over the same frozen events on every read.
      */
     presetOf(exec) {
-        const events = exec.agent?.session?.events;
+        const events = sessionEventsOf(exec);
         const length = events?.length ?? -1;
+        const last = length > 0 ? events?.[length - 1] : undefined;
         const cached = this.presetCache;
-        if (cached !== undefined && cached.events === events && cached.length === length)
+        if (cached !== undefined && cached.length === length && cached.last === last)
             return cached.preset;
         const preset = permissionPresetOf(events);
-        this.presetCache = { events, length, preset };
+        this.presetCache = { length, last, preset };
         return preset;
     }
     /**
@@ -489,6 +603,19 @@ export class PermGateRuntime {
         };
         const raw = decide(ctx, { decide: (c) => decideRules(this.ruleset, c) }, grantResolver, this.autoAllowExtra);
         const decision = this.applyPermissive(raw);
+        // Deterministic cleanup pre-screen: if a deletion command targets a
+        // regenerable/temporary artifact inside the workspace, allow it directly.
+        // This runs BEFORE the ask/passthrough logic so it works even under
+        // `approval: never` (where refineAsk is never called).
+        if (decision.action === 'ask') {
+            const cleanupSafe = isCleanupSafe(exec);
+            if (cleanupSafe !== undefined) {
+                const reason = `cleanup-safe: ${cleanupSafe}`;
+                this.audit.append(makeEntry({ callId, tool: exec.name, outcome: 'allow', source: 'classifier', reason, at: Date.now() }));
+                this.recordEvent(exec, 'auto', reason, { risk: 'safe', verdict: 'cleanup-safe', category: 'safe' });
+                return undefined; // passthrough (allow)
+            }
+        }
         let outcome;
         let source;
         switch (decision.stage) {
@@ -595,6 +722,19 @@ export class PermGateRuntime {
                 return undefined;
             }
         }
+        // Defensive cleanup pre-screen: normally this is handled in decideExecution
+        // before refineAsk is ever called, but refineAsk is public and may be called
+        // directly by tests or future embedders. Keep the same deterministic check
+        // here as a safety net — identical logic to decideExecution's pre-screen.
+        const cleanupSafe = isCleanupSafe(exec);
+        if (cleanupSafe !== undefined) {
+            const reason = `cleanup-safe: ${cleanupSafe}`;
+            this.audit.append(makeEntry({ callId: randomId(), tool: exec.name, outcome: 'allow', source: 'classifier', reason, at: Date.now() }));
+            this.recordEvent(exec, 'auto', reason, { risk: 'safe', verdict: 'cleanup-safe', category: 'safe' });
+            this.untrackAsk(exec);
+            this.clearCall(exec, reason, 'cleanup-safe', 'classifier');
+            return undefined;
+        }
         if (!permissive.strategies.llmAssist)
             return decision;
         // One live read of the classifier setup. Without a usable receiver (a
@@ -607,7 +747,14 @@ export class PermGateRuntime {
             && (cfg?.endpoint === undefined || cfg?.endpoint === '' || cfg?.model === undefined || cfg?.model === '')) {
             return decision;
         }
-        const req = { tool: exec.name, args: exec.arguments ?? {}, reason: decision.reason };
+        // Inject cwd into the risk request so the LLM can see the full path context
+        // (e.g. that a Remove-Item targets a temp directory, not user data).
+        const riskArgs = { ...(exec.arguments ?? {}) };
+        const cwd = cwdOf(exec);
+        if (typeof cwd === 'string' && cwd !== '' && typeof riskArgs.cwd !== 'string') {
+            riskArgs.cwd = cwd;
+        }
+        const req = { tool: exec.name, args: riskArgs, reason: decision.reason };
         let risk;
         if (this.options.riskHook !== undefined) {
             risk = await this.options.riskHook(req);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-perm-gate",
-  "version": "1.0.0",
-  "description": "DSH permission-gate: a single self-sufficient, deterministic-first, fail-closed gate covering P0 hard-deny -> P1 session grant -> P2 static rule (allow/deny) chain -> P3 optional LLM semantic classifier -> P4 ask, with command whitelist/blacklist.",
+  "version": "2.1.0",
+  "description": "DSH permission-gate for the DeepSeek Harness 0.1.2+ line: a single self-sufficient, deterministic-first, fail-closed gate covering P0 hard-deny -> P1 session grant -> P2 static rule (allow/deny) chain -> P3 optional LLM semantic classifier -> P4 ask, with command whitelist/blacklist.",
   "type": "module",
   "files": [
     "lib",
@@ -58,7 +58,7 @@
   },
   "engines": {
     "node": ">=20",
-    "dsh": ">=0.1.0-rc.7 <0.1.2-alpha.1"
+    "dsh": ">=0.1.2-alpha.1 <0.2.0-0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1"
@@ -69,10 +69,10 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.2",
     "@eslint/js": "^10.0.1",
     "@types/node": "^22.0.0",
     "@types/react": "~18.3.1",
@@ -89,9 +89,10 @@
     "typecheck": "tsc --noEmit && tsc -p tsconfig.client.json --noEmit",
     "lint": "eslint src test scripts tsdown.config.ts eslint.config.mjs",
     "test": "vitest run",
-    "verify:line": "node scripts/verify-line.mjs legacy",
+    "verify:line": "node scripts/verify-line.mjs new",
     "verify:lines": "node scripts/verify-line.mjs both",
     "release:latest": "npm publish --tag latest",
+    "release:2x": "npm publish --tag 2.x",
     "release:legacy": "npm publish --tag legacy"
   },
   "license": "MIT",