@skillstate/core 2.0.7 → 2.2.0

package/dist/adapter-shared.d.ts

@@ -0,0 +1,61 @@
+/**
+ * @non-paper Wave-5 shared adapter plumbing — the SINGLE SOURCE OF TRUTH
+ * for the state-path resolution, atomic persistence, and hooks-merge
+ * mechanics that were duplicated across the platform adapters (claude,
+ * codex). Adapters stay EVENT TABLES + brand constants + script/config
+ * generators; everything below is host-agnostic:
+ *
+ * - {@link resolveTarget}: the `string | StatePathRef` resolution every
+ *   adapter save/generate methods shared (throws on `..` traversal);
+ * - {@link saveGenerated}: resolve + `atomicWriteFile` + return the dest —
+ *   the body of every adapter `save` method;
+ * - {@link mergeHookGroups}: the hooks.json / settings.json merge —
+ *   idempotent by skillstate commands, appends fresh groups, preserves
+ *   every foreign group and top-level key. Format specifics (which groups
+ *   to generate, which commands are "ours") are passed in by the adapter.
+ */
+import type { StatePathRef } from './atomic-write.js';
+/**
+ * Resolve a `string | StatePathRef` target via `resolveStatePath` — the
+ * exact logic every adapter's private `resolve` helper shared. Raw strings
+ * pass through; `{ root, name }` refs are confined to `root` (traversal
+ * throws).
+ */
+export declare function resolveTarget(target: string | StatePathRef): string;
+/**
+ * Persist adapter-generated content to `target` via `atomicWriteFile`
+ * (temp sibling + fsync + rename) and return the absolute destination
+ * path. The shared body of the adapter `save*` methods.
+ */
+export declare function saveGenerated(target: string | StatePathRef, content: string): Promise<string>;
+/** Parameters for {@link mergeHookGroups} (the adapter-provided specifics). */
+export interface MergeHookGroupsParams {
+    /** The existing hooks document text (hooks.json / settings.json). */
+    existingJson: string;
+    /** The adapter-generated `{ Event: [group, …] }` groups to append. */
+    generatedGroups: Record<string, unknown[]>;
+    /**
+     * JSON-stringified skillstate commands (one per generated event script)
+     * — a handler whose stringified `command` is in this set marks the
+     * document as already wired.
+     */
+    commandsOf: ReadonlySet<string>;
+}
+/**
+ * Merge the skillstate hook groups into an existing hooks document — the
+ * shared mechanics of the claude and codex `mergeHooksConfig` methods:
+ *
+ * - malformed/empty/non-object input starts from a fresh document (the
+ *   CLI guards a live config before calling);
+ * - idempotent: if ANY skillstate command is already wired, the ORIGINAL
+ *   text is returned byte-unchanged (no re-serialization, no duplicate
+ *   groups, no surprise reformatting of a hand-written file);
+ * - otherwise every generated group is APPENDED per event: existing
+ *   (non-skillstate) groups and every other top-level key survive, and a
+ *   non-array event value is replaced by the fresh group.
+ *
+ * Returns the merged document re-serialized (2-space indent, newline-
+ * terminated) — or the untouched input on the already-wired path.
+ */
+export declare function mergeHookGroups({ existingJson, generatedGroups, commandsOf, }: MergeHookGroupsParams): string;
+//# sourceMappingURL=adapter-shared.d.ts.map

package/dist/adapter-shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-shared.d.ts","sourceRoot":"","sources":["../src/adapter-shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGtD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,MAAM,CAInE;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,GAAG,YAAY,EAC7B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAIjB;AAED,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,YAAY,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3C;;;;OAIG;IACH,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,EAC9B,YAAY,EACZ,eAAe,EACf,UAAU,GACX,EAAE,qBAAqB,GAAG,MAAM,CAoChC"}

package/dist/adapter-shared.js

@@ -0,0 +1,96 @@
+/**
+ * @non-paper Wave-5 shared adapter plumbing — the SINGLE SOURCE OF TRUTH
+ * for the state-path resolution, atomic persistence, and hooks-merge
+ * mechanics that were duplicated across the platform adapters (claude,
+ * codex). Adapters stay EVENT TABLES + brand constants + script/config
+ * generators; everything below is host-agnostic:
+ *
+ * - {@link resolveTarget}: the `string | StatePathRef` resolution every
+ *   adapter save/generate methods shared (throws on `..` traversal);
+ * - {@link saveGenerated}: resolve + `atomicWriteFile` + return the dest —
+ *   the body of every adapter `save` method;
+ * - {@link mergeHookGroups}: the hooks.json / settings.json merge —
+ *   idempotent by skillstate commands, appends fresh groups, preserves
+ *   every foreign group and top-level key. Format specifics (which groups
+ *   to generate, which commands are "ours") are passed in by the adapter.
+ */
+import { atomicWriteFile, resolveStatePath } from './atomic-write.js';
+import { isPlainObject } from './hook-runtime.js';
+/**
+ * Resolve a `string | StatePathRef` target via `resolveStatePath` — the
+ * exact logic every adapter's private `resolve` helper shared. Raw strings
+ * pass through; `{ root, name }` refs are confined to `root` (traversal
+ * throws).
+ */
+export function resolveTarget(target) {
+    return typeof target === 'string'
+        ? target
+        : resolveStatePath(target.root, target.name);
+}
+/**
+ * Persist adapter-generated content to `target` via `atomicWriteFile`
+ * (temp sibling + fsync + rename) and return the absolute destination
+ * path. The shared body of the adapter `save*` methods.
+ */
+export async function saveGenerated(target, content) {
+    const dest = resolveTarget(target);
+    await atomicWriteFile(dest, content);
+    return dest;
+}
+/**
+ * Merge the skillstate hook groups into an existing hooks document — the
+ * shared mechanics of the claude and codex `mergeHooksConfig` methods:
+ *
+ * - malformed/empty/non-object input starts from a fresh document (the
+ *   CLI guards a live config before calling);
+ * - idempotent: if ANY skillstate command is already wired, the ORIGINAL
+ *   text is returned byte-unchanged (no re-serialization, no duplicate
+ *   groups, no surprise reformatting of a hand-written file);
+ * - otherwise every generated group is APPENDED per event: existing
+ *   (non-skillstate) groups and every other top-level key survive, and a
+ *   non-array event value is replaced by the fresh group.
+ *
+ * Returns the merged document re-serialized (2-space indent, newline-
+ * terminated) — or the untouched input on the already-wired path.
+ */
+export function mergeHookGroups({ existingJson, generatedGroups, commandsOf, }) {
+    let doc = {};
+    try {
+        doc = JSON.parse(existingJson);
+    }
+    catch {
+        // Missing or malformed input: start from a fresh document.
+    }
+    if (!isPlainObject(doc)) {
+        doc = {};
+    }
+    if (!isPlainObject(doc['hooks'])) {
+        doc['hooks'] = {};
+    }
+    const hooks = doc['hooks'];
+    let alreadyWired = false;
+    for (const groups of Object.values(hooks)) {
+        if (!Array.isArray(groups))
+            continue;
+        for (const group of groups) {
+            if (!isPlainObject(group) || !Array.isArray(group['hooks']))
+                continue;
+            for (const handler of group['hooks']) {
+                if (isPlainObject(handler) && commandsOf.has(JSON.stringify(handler['command']))) {
+                    alreadyWired = true;
+                }
+            }
+        }
+    }
+    if (alreadyWired) {
+        return existingJson;
+    }
+    for (const [event, groups] of Object.entries(generatedGroups)) {
+        const existing = Array.isArray(hooks[event])
+            ? hooks[event]
+            : [];
+        hooks[event] = [...existing, ...groups];
+    }
+    return `${JSON.stringify(doc, null, 2)}\n`;
+}
+//# sourceMappingURL=adapter-shared.js.map

package/dist/adapter-shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-shared.js","sourceRoot":"","sources":["../src/adapter-shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAEtE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,MAA6B;IACzD,OAAO,OAAO,MAAM,KAAK,QAAQ;QAC/B,CAAC,CAAC,MAAM;QACR,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAA6B,EAC7B,OAAe;IAEf,MAAM,IAAI,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,IAAI,CAAC;AACd,CAAC;AAgBD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,YAAY,EACZ,eAAe,EACf,UAAU,GACY;IACtB,IAAI,GAAG,GAA4B,EAAE,CAAC;IACtC,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAe,CAAC;IAC/C,CAAC;IAAC,MAAM,CAAC;QACP,2DAA2D;IAC7D,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,GAAG,GAAG,EAAE,CAAC;IACX,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACjC,GAAG,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC;IACD,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAA4B,CAAC;IACtD,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,SAAS;QACrC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAAE,SAAS;YACtE,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;gBACrC,IAAI,aAAa,CAAC,OAAO,CAAC,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;oBACjF,YAAY,GAAG,IAAI,CAAC;gBACtB,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC;QAC9D,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1C,CAAC,CAAE,KAAK,CAAC,KAAK,CAAe;YAC7B,CAAC,CAAC,EAAE,CAAC;QACP,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,QAAQ,EAAE,GAAG,MAAM,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC"}

package/dist/atomic-write.d.ts

@@ -30,6 +30,23 @@ export interface LockHandle {
  * - Unreadable/missing locations (stat fails) → `null`, never throws.
  */
 export declare function acquireLock(lockPath: string, ttlMs?: number): Promise<LockHandle | null>;
+/** Default retry count for {@link withStateLock} (~10s at 50ms per try). */
+export declare const DEFAULT_LOCK_RETRIES = 200;
+/** Delay between {@link withStateLock} acquisition retries (50ms). */
+export declare const LOCK_RETRY_DELAY_MS = 50;
+/**
+ * Run `fn` while holding an exclusive cross-process lock on
+ * `statePath + '.lock'` ({@link acquireLock}, default TTL). Waits for a
+ * live holder: up to `retries` (default {@link DEFAULT_LOCK_RETRIES})
+ * attempts {@link LOCK_RETRY_DELAY_MS} apart, so 2-3 concurrent agent
+ * processes serialize instead of failing. The lock is acquired before
+ * `fn` starts and ALWAYS released in the `finally` block; the `fn`
+ * result (or failure) propagates after the release. Throws when the lock
+ * cannot be acquired within the retry budget. This is the async
+ * hot-path serialization primitive for the MCP server writes
+ * (patch/rollback/checkpoint/merge) and the host adapters.
+ */
+export declare function withStateLock<T>(statePath: string, fn: () => Promise<T> | T, ttlMs?: number, retries?: number): Promise<T>;
 /**
  * Resolve `name` inside `root` and return the absolute path. Throws when
  * the result escapes `root` (`..` traversal or an absolute outsider).

package/dist/atomic-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAkBA,4DAA4D;AAC5D,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,UAAU,GAC3B,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAUD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAwB5B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAOnE"}
+{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAkBA,4DAA4D;AAC5D,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,UAAU,GAC3B,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,oEAAoE;AACpE,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAUD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAwB5B;AAED,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,sEAAsE;AACtE,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACxB,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,GAAE,MAA6B,GACrC,OAAO,CAAC,CAAC,CAAC,CAgBZ;AAeD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAOnE"}

package/dist/atomic-write.js

@@ -80,6 +80,53 @@ export async function acquireLock(lockPath, ttlMs) {
         return makeHandle(lockPath);
     }
 }
+/** Default retry count for {@link withStateLock} (~10s at 50ms per try). */
+export const DEFAULT_LOCK_RETRIES = 200;
+/** Delay between {@link withStateLock} acquisition retries (50ms). */
+export const LOCK_RETRY_DELAY_MS = 50;
+/**
+ * Run `fn` while holding an exclusive cross-process lock on
+ * `statePath + '.lock'` ({@link acquireLock}, default TTL). Waits for a
+ * live holder: up to `retries` (default {@link DEFAULT_LOCK_RETRIES})
+ * attempts {@link LOCK_RETRY_DELAY_MS} apart, so 2-3 concurrent agent
+ * processes serialize instead of failing. The lock is acquired before
+ * `fn` starts and ALWAYS released in the `finally` block; the `fn`
+ * result (or failure) propagates after the release. Throws when the lock
+ * cannot be acquired within the retry budget. This is the async
+ * hot-path serialization primitive for the MCP server writes
+ * (patch/rollback/checkpoint/merge) and the host adapters.
+ */
+export async function withStateLock(statePath, fn, ttlMs, retries = DEFAULT_LOCK_RETRIES) {
+    const lockPath = `${statePath}.lock`;
+    await fs.promises.mkdir(path.dirname(lockPath), { recursive: true });
+    let handle = await acquireLockSafely(lockPath, ttlMs);
+    for (let attempt = 0; handle === null && attempt < retries; attempt++) {
+        await new Promise((resolve) => setTimeout(resolve, LOCK_RETRY_DELAY_MS));
+        handle = await acquireLockSafely(lockPath, ttlMs);
+    }
+    if (!handle) {
+        throw new Error(`skillstate: could not acquire the state lock: ${lockPath}`);
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        handle.release();
+    }
+}
+/**
+ * {@link acquireLock} with the stale-takeover race collapsed to `null`:
+ * between `unlink` and the re-`writeFile`, another waiter may recreate
+ * the lockfile (`EEXIST`) — that loser must retry, never crash.
+ */
+async function acquireLockSafely(lockPath, ttlMs) {
+    try {
+        return await acquireLock(lockPath, ttlMs);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Resolve `name` inside `root` and return the absolute path. Throws when
  * the result escapes `root` (`..` traversal or an absolute outsider).

package/dist/atomic-write.js.map

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

package/dist/hook-runtime.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @non-paper Wave-5 hook runtime — the SINGLE SOURCE OF TRUTH for every
+ * piece of logic embedded into self-contained generated hook scripts
+ * (Claude Code `.cjs` hooks, Codex `.cjs` hooks) and reused directly by
+ * the OpenCode plugin.
+ *
+ * CONSTRAINT: the generated scripts cannot import `@skillstate/*`, so the
+ * adapters inline these functions into the emitted `.cjs` via
+ * `fn.toString()` (see {@link hookRuntimeSnippet}). That means every
+ * function body below must be PLAIN JavaScript:
+ *
+ * - no imports and no `require` — dependencies are passed as parameters
+ *   (`readFile`, `writeFile`, `home`), so the caller wires the real
+ *   `node:fs`/`node:os`/`node:path` (or test mocks) at the call site;
+ * - type annotations live ONLY in the signatures — both `tsc` (dist) and
+ *   the vitest/esbuild transform erase them, so `fn.toString()` yields a
+ *   valid CJS snippet;
+ * - no references to module-scope helpers — each function is either fully
+ *   self-contained or calls only its sibling functions from this module
+ *   (which the snippet inlines together).
+ *
+ * The parity suite (`tests/core/hook-runtime-parity.test.ts`) evals the
+ * snippets extracted from the generated scripts and asserts byte-identical
+ * behavior against these originals, so the "embedded copy" can no longer
+ * drift from the source of truth.
+ */
+/** True for plain (non-null, non-array) objects. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Agent-id sanitization: keep `[A-Za-z0-9_-]` runs, collapse everything
+ * else into single `-`, trim edge dashes, cap at 64 chars. Garbage input
+ * sanitizes to `''` — callers treat that as "no agent" (the main state).
+ */
+export declare function sanitizeAgentId(agentId: string): string;
+/**
+ * Agent id from a host session id (Claude Code / Codex hook stdin carry
+ * `session_id`; opencode hooks carry `sessionID`): the short prefix — the
+ * first 8 characters — keeps agent directories bounded while remaining
+ * unique enough per session. Non-string/empty input yields `''`.
+ */
+export declare function resolveAgentIdFromSession(sessionId: unknown): string;
+/**
+ * Resolve the per-project state file for a working directory — the pure,
+ * dependency-free mirror of `resolveHostStateForCwd`
+ * (`<cwd>/.skillstate/skillstate.json`; the global bucket
+ * `<home>/.skillstate/global/skillstate.json` when cwd equals home).
+ *
+ * AGENT-SCOPED STATE: a non-empty `agentId` (sanitized via
+ * {@link sanitizeAgentId}) scopes the file under an isolated
+ * `agents/<agentId>/` copy — parallel sub-agents (hook sessions) never
+ * share the main state file.
+ *
+ * String arithmetic only (POSIX): absolute paths are normalized like
+ * `path.resolve` (empty/`.` segments dropped, `..` popped, trailing
+ * slashes trimmed); relative inputs stay relative because there is no
+ * `process` access. Callers that may see relative paths resolve them
+ * first (`path.resolve(cwd)`) — the generated hook scripts do exactly
+ * that. `home` must be provided to detect the global bucket; when it is
+ * omitted the project path is returned.
+ */
+export declare function resolveStatePathForCwd(cwd: string, home?: string, agentId?: string): string;
+/**
+ * Read the state file through the injected `readFile` (real `fs` in
+ * generated scripts, mocks in tests). The on-disk envelope is
+ * `{ version: 1, state }`; a bare object is tolerated and treated as the
+ * state itself; anything else (missing file, corrupt JSON, arrays,
+ * scalars) yields `{}` — best-effort, never throws.
+ */
+export declare function readStateEnvelope(statePath: string, readFile: (p: string) => string): unknown;
+/**
+ * Persist the state through the injected `writeFile` as the
+ * `{ version: 1, state }` envelope (pretty-printed, newline-terminated).
+ * Throws on failure — the caller decides whether to swallow it (OpenCode
+ * plugin) or surface a `systemMessage` (PostToolUse hooks).
+ */
+export declare function saveStateEnvelope(statePath: string, state: object, writeFile: (p: string, data: string) => void): void;
+/**
+ * Minimal `node:fs` surface {@link lockStateWrite} needs. Injections keep
+ * the hook-runtime pure: real `node:fs` in generated scripts and the
+ * plugin, mocks in tests (the established hook-runtime dependency style).
+ */
+export interface StateLockFs {
+    openSync(path: string, flags: string): number;
+    closeSync(fd: number): void;
+    statSync(path: string): {
+        mtimeMs: number;
+    };
+    unlinkSync(path: string): void;
+    mkdirSync(path: string): unknown;
+}
+/**
+ * Block the current thread for `ms` milliseconds — the sync sleep for the
+ * {@link lockStateWrite} retry loop. Prefers `Atomics.wait` on a shared
+ * integer (a real sleep); falls back to a busy spin when the primitive is
+ * unavailable. Plain JS — survives `fn.toString()` inlining.
+ */
+export declare function sleepSync(ms: number): void;
+/**
+ * Cross-process state lock for the SELF-CONTAINED hook scripts (sync,
+ * no imports): exclusive `O_EXCL` lockfile at `statePath + '.lock'`,
+ * stale-TTL takeover (10s — crashed hook holders), and a retry loop
+ * (50ms × 40 ≈ 2s) while a live holder runs its critical section. The
+ * injected `fs` (real `node:fs` in generated scripts and the plugin,
+ * mocks in tests) performs the lockfile I/O and creates the parent
+ * directory. The injected `fn` runs inside the lock; the lockfile is
+ * ALWAYS removed in the `finally` block. `fn` failures propagate AFTER
+ * the release; lock exhaustion throws.
+ */
+export declare function lockStateWrite(statePath: string, fs: StateLockFs, fn: () => unknown): unknown;
+/**
+ * Paper ⊕ merge: `null` deletes a key, nested plain objects merge
+ * recursively, everything else replaces. Pure — neither `state` nor
+ * `patch` is mutated.
+ */
+export declare function mergePatch(state: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Coerce a tool response into text: strings pass through, plain objects
+ * expose their `content` then `text` string field, other objects are
+ * JSON-stringified, null/undefined becomes `""`, everything else is
+ * `String()`-ed.
+ */
+export declare function readResponseText(response: unknown): string;
+/** Outcome of the patch extractors: a patch, an invalid attempt, or nothing. */
+export type PatchLookup = {
+    patch: Record<string, unknown>;
+} | {
+    invalid: true;
+} | {
+    absent: true;
+};
+/**
+ * Look for a fenced ```json block: `{ patch }` when it parses and carries
+ * an object-shaped `state_patch`, `{ invalid: true }` when a block exists
+ * but is malformed (an open fence that never closes — truncated output —
+ * is still a patch attempt and classifies as invalid), `{ absent: true }`
+ * when there is no block at all.
+ */
+export declare function findFencedPatch(text: string): PatchLookup;
+/**
+ * Fallback: a raw JSON object with `state_patch` anywhere in the text
+ * (first `{` … last `}`). Ordinary JSON output without a `state_patch`
+ * key is simply not a patch (`{ absent: true }`); a `state_patch` key
+ * holding a non-object is an invalid attempt.
+ */
+export declare function findRawPatch(text: string): PatchLookup;
+/**
+ * Read the session-meta sidecar's status (`<dir>/.session-meta.json`,
+ * sibling of the state file). Plain JS — inlined into the generated
+ * SessionStart hooks via `fn.toString()`. Returns the `status` string for
+ * a readable object-shaped sidecar, else `null` (missing/corrupt/other
+ * shape — no lifecycle marker). The `readFile` dependency is injected at
+ * the call site (real `node:fs` in hooks, mocks in tests).
+ */
+export declare function readSessionMetaStatus(metaPath: string, readFile: (p: string) => string): string | null;
+/**
+ * Assemble the CJS snippet embedded into every generated hook script:
+ * all sibling functions of this module, source-verbatim via
+ * `fn.toString()`. The adapters splice this block after their `require`
+ * preamble, which keeps the embedded logic byte-identical across hosts
+ * and impossible to drift from this module.
+ */
+export declare function hookRuntimeSnippet(): string;
+//# sourceMappingURL=hook-runtime.d.ts.map

package/dist/hook-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-runtime.d.ts","sourceRoot":"","sources":["../src/hook-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,oDAAoD;AACpD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKvD;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,CAGpE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CA+B3F;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAC9B,OAAO,CAaT;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAC3C,IAAI,CAEN;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9C,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAClC;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAW1C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,OAAO,GAAG,OAAO,CA8C7F;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,MAAM,CAQ1D;AAED,gFAAgF;AAChF,MAAM,MAAM,WAAW,GACnB;IAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAClC;IAAE,OAAO,EAAE,IAAI,CAAA;CAAE,GACjB;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,CAAC;AAErB;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAczD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CA4BtD;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAC9B,MAAM,GAAG,IAAI,CAUf;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAkB3C"}