@dsh-cc/subagent-resume-pins 0.5.0

package/lib/store.js

@@ -0,0 +1,133 @@
+/**
+ * Per-child pin store: one JSON file per child under `<pinsRoot>/<childId>.json`.
+ *
+ * Durability and coherence contract (plan §4.1/§4.6):
+ * - `write` creates a pin and fails if one already exists (preallocated ids).
+ * - `update` rewrites the file atomically (temp file + rename) AND publishes
+ *   the mutated pin to the store's single synchronous in-memory cache, so no
+ *   stale-cache read can serve the first request after a gate mutation.
+ * - `read` resolves `undefined` for an absent pin (legacy/foreign child,
+ *   pass-through) and a `{kind:'corrupt'}` sentinel for a file that exists
+ *   but is unparseable or unsupported-version — fail-closed callers
+ *   distinguish those; it never throws.
+ * - `remove` tombstone-deletes the file and the cache entry.
+ * - childIds are UUID-ish; anything containing a path separator or `..` is
+ *   rejected before it can traverse out of `pinsRoot`.
+ *
+ * @module @dsh-cc/subagent-resume-pins/store
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PinParseError, parsePin, writePin } from "./pin.js";
+/** The childId shape the store accepts: no separators, no `..`. */
+function assertSafeChildId(childId) {
+    if (childId.length === 0 || childId.includes('/') || childId.includes('\\') || childId.includes('..')) {
+        throw new Error(`unsafe resume-pin childId: ${JSON.stringify(childId)}`);
+    }
+}
+/**
+ * Owns the pin files under one root and the single shared in-memory cache the
+ * gate and overlay listeners consult.
+ */
+export class PinStore {
+    pinsRoot;
+    cache = new Map();
+    constructor(pinsRoot) {
+        this.pinsRoot = pinsRoot;
+        mkdirSync(this.pinsRoot, { recursive: true });
+    }
+    /** The on-disk path for one child's pin (validates the childId first). */
+    pathFor(childId) {
+        assertSafeChildId(childId);
+        return join(this.pinsRoot, `${childId}.json`);
+    }
+    /**
+     * Read a pin by child id: `undefined` when absent, the corrupt sentinel when
+     * the file exists but cannot be parsed. Read-through: the disk is re-read on
+     * every call (files are tiny, one per model request), so a file deleted or
+     * corrupted out-of-band is never served stale from the cache; the cache only
+     * accelerates nothing — it exists to publish synchronous in-process updates
+     * and is invalidated by any failed disk read.
+     */
+    read(childId) {
+        const path = this.pathFor(childId);
+        if (!existsSync(path)) {
+            this.cache.delete(childId);
+            return undefined;
+        }
+        let text;
+        try {
+            text = readFileSync(path, 'utf8');
+        }
+        catch (cause) {
+            this.cache.delete(childId);
+            return { kind: 'corrupt', reason: `unreadable: ${String(cause)}` };
+        }
+        try {
+            const pin = parsePin(text);
+            this.cache.set(childId, pin);
+            return pin;
+        }
+        catch (cause) {
+            this.cache.delete(childId);
+            const reason = cause instanceof PinParseError ? cause.message : String(cause);
+            return { kind: 'corrupt', reason };
+        }
+    }
+    /** Read only the in-memory cache: `undefined` on miss (no disk access). */
+    getCached(childId) {
+        return this.cache.get(childId);
+    }
+    /** Create the pin file; fails when a pin for this child already exists. */
+    write(pin) {
+        const path = this.pathFor(pin.childId);
+        if (existsSync(path)) {
+            throw new Error(`resume pin already exists for child ${pin.childId}`);
+        }
+        this.atomicWrite(path, pin);
+        this.cache.set(pin.childId, pin);
+    }
+    /**
+     * Atomically rewrite a pin through `mutator` (a structural clone is handed
+     * to the mutator) and publish the result to the shared cache synchronously.
+     */
+    update(childId, mutator) {
+        const current = this.read(childId);
+        if (current === undefined)
+            throw new Error(`no resume pin for child ${childId}`);
+        if ('kind' in current && current.kind === 'corrupt') {
+            throw new Error(`cannot update corrupt resume pin for child ${childId}`);
+        }
+        const draft = structuredClone(current);
+        mutator(draft);
+        const updated = parsePin(writePin(draft));
+        this.atomicWrite(this.pathFor(childId), updated);
+        this.cache.set(childId, updated);
+        return updated;
+    }
+    /** Tombstone-delete the pin file and its cache entry (idempotent). */
+    remove(childId) {
+        rmSync(this.pathFor(childId), { force: true });
+        this.cache.delete(childId);
+    }
+    /**
+     * The child ids with a pin file on disk (best-effort; used by the
+     * `list_agents` annotation). Not guaranteed cached or readable.
+     */
+    ids() {
+        try {
+            return readdirSync(this.pinsRoot)
+                .filter(name => name.endsWith('.json'))
+                .map(name => name.slice(0, -'.json'.length));
+        }
+        catch {
+            return [];
+        }
+    }
+    atomicWrite(path, pin) {
+        const temp = `${path}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        writeFileSync(temp, writePin(pin), { flag: 'wx' });
+        renameSync(temp, path);
+    }
+}
+//# sourceMappingURL=store.js.map

package/lib/store.js.map

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

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@dsh-cc/subagent-resume-pins",
+  "description": "Pinned resume descriptors for continuable background subagents",
+  "version": "0.5.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dsh-cc/dsh-cc.git",
+    "directory": "packages/subagent/resume-pins"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./pin": {
+      "types": "./lib/pin.d.ts",
+      "default": "./lib/pin.js"
+    },
+    "./store": {
+      "types": "./lib/store.d.ts",
+      "default": "./lib/store.js"
+    },
+    "./fingerprint": {
+      "types": "./lib/fingerprint.d.ts",
+      "default": "./lib/fingerprint.js"
+    },
+    "./gate": {
+      "types": "./lib/gate.d.ts",
+      "default": "./lib/gate.js"
+    },
+    "./overlay": {
+      "types": "./lib/overlay.d.ts",
+      "default": "./lib/overlay.js"
+    },
+    "./policy": {
+      "types": "./lib/policy.d.ts",
+      "default": "./lib/policy.js"
+    },
+    "./plugin": {
+      "types": "./lib/plugin.d.ts",
+      "default": "./lib/plugin.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": ">=0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": ">=0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@dsh-cc/claude-code-agents": "^0.5.0",
+    "@dsh-cc/model-aliases": "^0.5.0"
+  },
+  "dependencies": {
+    "@dsh-cc/claude-code-agents": "^0.5.0",
+    "@dsh-cc/model-aliases": "^0.5.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "link:../../../../deepseek-harness/vendor/cordis",
+    "@deepseek-ai/dsh-agent": "link:../../../../deepseek-harness/packages/core/agent",
+    "@deepseek-ai/dsh-llm": "link:../../../../deepseek-harness/packages/llm/llm",
+    "@deepseek-ai/dsh-session": "link:../../../../deepseek-harness/packages/core/session",
+    "@deepseek-ai/dsh-session-persistence": "link:../../../../deepseek-harness/packages/session/session-persistence",
+    "@deepseek-ai/dsh-settings": "link:../../../../deepseek-harness/packages/settings/settings",
+    "@deepseek-ai/dsh-tools": "link:../../../../deepseek-harness/packages/core/tools",
+    "@deepseek-ai/schemastery": "link:../../../../deepseek-harness/vendor/schemastery",
+    "@dsh-cc/claude-code-agents": "^0.5.0",
+    "@dsh-cc/model-aliases": "^0.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}