@skillstate/core 2.0.7 → 2.2.0

package/dist/hook-runtime.js

@@ -0,0 +1,364 @@
+/**
+ * @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 function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * 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 function sanitizeAgentId(agentId) {
+    return agentId
+        .replace(/[^A-Za-z0-9_-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64);
+}
+/**
+ * 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 function resolveAgentIdFromSession(sessionId) {
+    if (typeof sessionId !== 'string' || sessionId.length === 0)
+        return '';
+    return sessionId.slice(0, 8);
+}
+/**
+ * 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 function resolveStatePathForCwd(cwd, home, agentId) {
+    const normalize = (p) => {
+        const isAbsolute = p.startsWith('/');
+        const segments = [];
+        for (const segment of p.split('/')) {
+            if (segment === '' || segment === '.')
+                continue;
+            if (segment === '..') {
+                if (segments.length > 0 && segments[segments.length - 1] !== '..') {
+                    segments.pop();
+                }
+                else if (!isAbsolute) {
+                    segments.push('..');
+                }
+                continue;
+            }
+            segments.push(segment);
+        }
+        return (isAbsolute ? '/' : '') + segments.join('/');
+    };
+    const rootless = (p) => (p === '/' ? '' : p);
+    const resolvedCwd = normalize(cwd);
+    const resolvedHome = home === undefined || home === null ? '' : normalize(home);
+    const agent = typeof agentId === 'string' && agentId.length > 0 ? sanitizeAgentId(agentId) : '';
+    const base = resolvedCwd === resolvedHome
+        ? `${rootless(resolvedHome)}/.skillstate/global`
+        : `${rootless(resolvedCwd)}/.skillstate`;
+    if (agent.length > 0) {
+        return `${base}/agents/${agent}/skillstate.json`;
+    }
+    return `${base}/skillstate.json`;
+}
+/**
+ * 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 function readStateEnvelope(statePath, readFile) {
+    try {
+        const parsed = JSON.parse(readFile(statePath));
+        if (isPlainObject(parsed)) {
+            if (isPlainObject(parsed.state)) {
+                return parsed.state;
+            }
+            return parsed;
+        }
+    }
+    catch {
+        // Missing or corrupt state file — fall back to the empty state.
+    }
+    return {};
+}
+/**
+ * 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 function saveStateEnvelope(statePath, state, writeFile) {
+    writeFile(statePath, `${JSON.stringify({ version: 1, state }, null, 2)}\n`);
+}
+/**
+ * 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 function sleepSync(ms) {
+    try {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+        return;
+    }
+    catch (error) {
+        // Atomics.wait unavailable in this host — spin below.
+    }
+    const end = Date.now() + ms;
+    while (Date.now() < end) {
+        // Spin — hook scripts must stay synchronous.
+    }
+}
+/**
+ * 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 function lockStateWrite(statePath, fs, fn) {
+    const lockPath = `${statePath}.lock`;
+    const ttl = 10_000;
+    const retries = 40;
+    const dir = lockPath.replace(/\/[^/]+$/, '');
+    try {
+        fs.mkdirSync(dir);
+    }
+    catch (error) {
+        // Exists already — only the lockfile itself must be exclusive.
+    }
+    let acquired = false;
+    for (let attempt = 0; attempt < retries; attempt++) {
+        try {
+            fs.closeSync(fs.openSync(lockPath, 'wx'));
+            acquired = true;
+            break;
+        }
+        catch (error) {
+            let mtimeMs = 0;
+            try {
+                mtimeMs = fs.statSync(lockPath).mtimeMs;
+            }
+            catch (error) {
+                // Vanished between the failed create and the stat — retry at once.
+            }
+            if (Date.now() - mtimeMs > ttl) {
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch (error) {
+                    // Another waiter removed it first — retry from the top.
+                }
+            }
+            else {
+                sleepSync(50);
+            }
+        }
+    }
+    if (!acquired) {
+        throw new Error(`skillstate: could not acquire the state lock: ${lockPath}`);
+    }
+    try {
+        return fn();
+    }
+    finally {
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch (error) {
+            // Lock already removed (stale takeover raced us) — nothing to release.
+        }
+    }
+}
+/**
+ * Paper ⊕ merge: `null` deletes a key, nested plain objects merge
+ * recursively, everything else replaces. Pure — neither `state` nor
+ * `patch` is mutated.
+ */
+export function mergePatch(state, patch) {
+    const result = { ...state };
+    for (const key of Object.keys(patch)) {
+        const value = patch[key];
+        if (value === null) {
+            delete result[key];
+        }
+        else if (isPlainObject(value) && isPlainObject(result[key])) {
+            result[key] = mergePatch(result[key], value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * 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 function readResponseText(response) {
+    if (typeof response === 'string')
+        return response;
+    if (isPlainObject(response)) {
+        if (typeof response['content'] === 'string')
+            return response['content'];
+        if (typeof response['text'] === 'string')
+            return response['text'];
+        return JSON.stringify(response);
+    }
+    return response === null || response === undefined ? '' : String(response);
+}
+/**
+ * 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 function findFencedPatch(text) {
+    const match = text.match(/```json\s*\n?([\s\S]*?)\n?\s*```/) ||
+        text.match(/```json\s*\n?([\s\S]+)$/);
+    if (!match)
+        return { absent: true };
+    try {
+        const parsed = JSON.parse(match[1]);
+        if (isPlainObject(parsed) && isPlainObject(parsed['state_patch'])) {
+            return { patch: parsed['state_patch'] };
+        }
+    }
+    catch {
+        // Malformed fenced JSON — report an invalid patch attempt.
+    }
+    return { invalid: true };
+}
+/**
+ * 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 function findRawPatch(text) {
+    const trimmed = text.trim();
+    const candidates = [];
+    try {
+        candidates.push(JSON.parse(trimmed));
+    }
+    catch {
+        // Not a whole-text JSON object — try the braced slice below.
+    }
+    const first = trimmed.indexOf('{');
+    const last = trimmed.lastIndexOf('}');
+    if (first !== -1 && last > first) {
+        try {
+            candidates.push(JSON.parse(trimmed.slice(first, last + 1)));
+        }
+        catch {
+            // The braced slice is not JSON either — no candidates left.
+        }
+    }
+    for (const candidate of candidates) {
+        if (isPlainObject(candidate)) {
+            if (isPlainObject(candidate['state_patch'])) {
+                return { patch: candidate['state_patch'] };
+            }
+            if (Object.prototype.hasOwnProperty.call(candidate, 'state_patch')) {
+                return { invalid: true };
+            }
+        }
+    }
+    return { absent: true };
+}
+/**
+ * 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 function readSessionMetaStatus(metaPath, readFile) {
+    try {
+        const parsed = JSON.parse(readFile(metaPath));
+        if (isPlainObject(parsed) && typeof parsed.status === 'string') {
+            return parsed.status;
+        }
+    }
+    catch (error) {
+        // Missing or corrupt sidecar — no lifecycle marker.
+    }
+    return 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 function hookRuntimeSnippet() {
+    return [
+        isPlainObject,
+        resolveAgentIdFromSession,
+        sanitizeAgentId,
+        resolveStatePathForCwd,
+        readStateEnvelope,
+        saveStateEnvelope,
+        mergePatch,
+        readResponseText,
+        findFencedPatch,
+        findRawPatch,
+        sleepSync,
+        lockStateWrite,
+        readSessionMetaStatus,
+    ]
+        .map((fn) => fn.toString())
+        .join('\n\n');
+}
+//# sourceMappingURL=hook-runtime.js.map

package/dist/hook-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-runtime.js","sourceRoot":"","sources":["../src/hook-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,oDAAoD;AACpD,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,OAAO,OAAO;SACX,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC;SAChC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,SAAkB;IAC1D,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACvE,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW,EAAE,IAAa,EAAE,OAAgB;IACjF,MAAM,SAAS,GAAG,CAAC,CAAS,EAAU,EAAE;QACtC,MAAM,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,EAAE,CAAC;QACpB,KAAK,MAAM,OAAO,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,IAAI,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG;gBAAE,SAAS;YAChD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;oBAClE,QAAQ,CAAC,GAAG,EAAE,CAAC;gBACjB,CAAC;qBAAM,IAAI,CAAC,UAAU,EAAE,CAAC;oBACvB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACtB,CAAC;gBACD,SAAS;YACX,CAAC;YACD,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtD,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7D,MAAM,WAAW,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,YAAY,GAAG,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAChF,MAAM,KAAK,GACT,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpF,MAAM,IAAI,GACR,WAAW,KAAK,YAAY;QAC1B,CAAC,CAAC,GAAG,QAAQ,CAAC,YAAY,CAAC,qBAAqB;QAChD,CAAC,CAAC,GAAG,QAAQ,CAAC,WAAW,CAAC,cAAc,CAAC;IAC7C,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,GAAG,IAAI,WAAW,KAAK,kBAAkB,CAAC;IACnD,CAAC;IACD,OAAO,GAAG,IAAI,kBAAkB,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAiB,EACjB,QAA+B;IAE/B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;QAC/C,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,IAAI,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBAChC,OAAO,MAAM,CAAC,KAAK,CAAC;YACtB,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;IAClE,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,SAAiB,EACjB,KAAa,EACb,SAA4C;IAE5C,SAAS,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AAC9E,CAAC;AAeD;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,EAAU;IAClC,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QACjE,OAAO;IACT,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,sDAAsD;IACxD,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;IAC5B,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,EAAE,CAAC;QACxB,6CAA6C;IAC/C,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,EAAe,EAAE,EAAiB;IAClF,MAAM,QAAQ,GAAG,GAAG,SAAS,OAAO,CAAC;IACrC,MAAM,GAAG,GAAG,MAAM,CAAC;IACnB,MAAM,OAAO,GAAG,EAAE,CAAC;IACnB,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC7C,IAAI,CAAC;QACH,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,+DAA+D;IACjE,CAAC;IACD,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC;QACnD,IAAI,CAAC;YACH,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;YAC1C,QAAQ,GAAG,IAAI,CAAC;YAChB,MAAM;QACR,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,OAAO,GAAG,CAAC,CAAC;YAChB,IAAI,CAAC;gBACH,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC;YAC1C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,mEAAmE;YACrE,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,GAAG,EAAE,CAAC;gBAC/B,IAAI,CAAC;oBACH,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;gBAC1B,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,wDAAwD;gBAC1D,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,SAAS,CAAC,EAAE,CAAC,CAAC;YAChB,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,iDAAiD,QAAQ,EAAE,CAAC,CAAC;IAC/E,CAAC;IACD,IAAI,CAAC;QACH,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,uEAAuE;QACzE,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,KAA8B,EAC9B,KAA8B;IAE9B,MAAM,MAAM,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;IAC5B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;aAAM,IAAI,aAAa,CAAC,KAAK,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAC9D,MAAM,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,GAAG,CAA4B,EAAE,KAAK,CAAC,CAAC;QAC1E,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAiB;IAChD,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAClD,IAAI,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,IAAI,OAAO,QAAQ,CAAC,SAAS,CAAC,KAAK,QAAQ;YAAE,OAAO,QAAQ,CAAC,SAAS,CAAC,CAAC;QACxE,IAAI,OAAO,QAAQ,CAAC,MAAM,CAAC,KAAK,QAAQ;YAAE,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC;QAClE,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC7E,CAAC;AAQD;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,KAAK,GACT,IAAI,CAAC,KAAK,CAAC,kCAAkC,CAAC;QAC9C,IAAI,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACpC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,IAAI,aAAa,CAAC,MAAM,CAAC,IAAI,aAAa,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC;YAClE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;QAC1C,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,2DAA2D;IAC7D,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC5B,MAAM,UAAU,GAAG,EAAE,CAAC;IACtB,IAAI,CAAC;QACH,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,6DAA6D;IAC/D,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9D,CAAC;QAAC,MAAM,CAAC;YACP,4DAA4D;QAC9D,CAAC;IACH,CAAC;IACD,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7B,IAAI,aAAa,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC;gBAC5C,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,aAAa,CAAC,EAAE,CAAC;YAC7C,CAAC;YACD,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,EAAE,CAAC;gBACnE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YAC3B,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAAgB,EAChB,QAA+B;IAE/B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC9C,IAAI,aAAa,CAAC,MAAM,CAAC,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/D,OAAO,MAAM,CAAC,MAAM,CAAC;QACvB,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,oDAAoD;IACtD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,aAAa;QACb,yBAAyB;QACzB,eAAe;QACf,sBAAsB;QACtB,iBAAiB;QACjB,iBAAiB;QACjB,UAAU;QACV,gBAAgB;QAChB,eAAe;QACf,YAAY;QACZ,SAAS;QACT,cAAc;QACd,qBAAqB;KACtB;SACE,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC;SAC1B,IAAI,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC"}

package/dist/host-state.d.ts

@@ -2,7 +2,8 @@
  * Resolve the per-project state file for a working directory —
  * `<cwd>/.skillstate/skillstate.json`, or the global bucket
  * `<home>/.skillstate/global/skillstate.json` when cwd equals home
- * (`home` defaults to `os.homedir()`).
+ * (`home` defaults to `os.homedir()`). A non-empty `agentId` scopes the
+ * file under `<bucket>/agents/<sanitized agentId>/skillstate.json`.
  */
-export declare function resolveHostStateForCwd(cwd: string, home?: string): string;
+export declare function resolveHostStateForCwd(cwd: string, home?: string, agentId?: string): string;
 //# sourceMappingURL=host-state.d.ts.map

package/dist/host-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-state.d.ts","sourceRoot":"","sources":["../src/host-state.ts"],"names":[],"mappings":"AAiBA;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAOzE"}
+{"version":3,"file":"host-state.d.ts","sourceRoot":"","sources":["../src/host-state.ts"],"names":[],"mappings":"AAyBA;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAa3F"}

package/dist/host-state.js

@@ -1,31 +1,44 @@
 /**
  * @non-paper Wave-4 DX helper — the canonical per-project state resolver
  * shared by every host adapter (OpenCode plugin, Codex hooks/fork-trim,
- * Claude Code hooks).
+ * Claude Code hooks, MCP).
  *
  * Semantics: the state file for a working directory is
  * `<cwd>/.skillstate/skillstate.json`; a session opened directly in the
  * user's home resolves to the global bucket
- * `<home>/.skillstate/global/skillstate.json`. Pure path arithmetic — no
- * filesystem access. Host-embedded hook scripts (self-contained `.cjs`)
- * keep a byte-equivalent copy of this logic because they must run without
- * importing `@skillstate/*`; this function is the single source of truth
- * the copies mirror.
+ * `<home>/.skillstate/global/skillstate.json`. AGENT-SCOPED STATE: a
+ * non-empty `agentId` (sanitized `[A-Za-z0-9_-]`, ≤64 chars) scopes the
+ * file under an isolated copy — `agents/<agentId>/skillstate.json` inside
+ * the same bucket — so 2-3 parallel sub-agents (hook sessions) never
+ * last-writer-win over each other; the main agent keeps the unscoped
+ * path and merges sub-agent copies explicitly (MCP `agent.merge`).
+ *
+ * Pure path arithmetic — no filesystem access. Host-embedded hook scripts
+ * (self-contained `.cjs`) keep a behavior-equivalent copy of this logic in
+ * the hook-runtime `resolveStatePathForCwd` because they must run without
+ * importing `@skillstate/*`; that function is the parity mirror. The agent
+ * id sanitizer is shared verbatim from the hook-runtime module.
  */
 import * as os from 'node:os';
 import * as path from 'node:path';
+import { sanitizeAgentId } from './hook-runtime.js';
 /**
  * Resolve the per-project state file for a working directory —
  * `<cwd>/.skillstate/skillstate.json`, or the global bucket
  * `<home>/.skillstate/global/skillstate.json` when cwd equals home
- * (`home` defaults to `os.homedir()`).
+ * (`home` defaults to `os.homedir()`). A non-empty `agentId` scopes the
+ * file under `<bucket>/agents/<sanitized agentId>/skillstate.json`.
  */
-export function resolveHostStateForCwd(cwd, home) {
+export function resolveHostStateForCwd(cwd, home, agentId) {
     const resolvedCwd = path.resolve(cwd);
     const resolvedHome = path.resolve(home ?? os.homedir());
-    if (resolvedCwd === resolvedHome) {
-        return path.join(resolvedHome, '.skillstate', 'global', 'skillstate.json');
+    const bucket = resolvedCwd === resolvedHome
+        ? path.join(resolvedHome, '.skillstate', 'global')
+        : path.join(resolvedCwd, '.skillstate');
+    const agent = typeof agentId === 'string' && agentId.length > 0 ? sanitizeAgentId(agentId) : '';
+    if (agent.length > 0) {
+        return path.join(bucket, 'agents', agent, 'skillstate.json');
     }
-    return path.join(resolvedCwd, '.skillstate', 'skillstate.json');
+    return path.join(bucket, 'skillstate.json');
 }
 //# sourceMappingURL=host-state.js.map

package/dist/host-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"host-state.js","sourceRoot":"","sources":["../src/host-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW,EAAE,IAAa;IAC/D,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IACxD,IAAI,WAAW,KAAK,YAAY,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,iBAAiB,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,iBAAiB,CAAC,CAAC;AAClE,CAAC"}
+{"version":3,"file":"host-state.js","sourceRoot":"","sources":["../src/host-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW,EAAE,IAAa,EAAE,OAAgB;IACjF,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;IACxD,MAAM,MAAM,GACV,WAAW,KAAK,YAAY;QAC1B,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,aAAa,EAAE,QAAQ,CAAC;QAClD,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;IAC5C,MAAM,KAAK,GACT,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACpF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,iBAAiB,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAC9C,CAAC"}

package/dist/index.d.ts

@@ -16,6 +16,10 @@ export * from './logger.js';
 export * from './provider.js';
 export * from './config.js';
 export * from './host-state.js';
+export * from './hook-runtime.js';
+export * from './adapter-shared.js';
+export * from './prompt-contract.js';
 export * from './shutdown.js';
+export * from './session-meta.js';
 export * from './schemas/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AAErC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAElC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAE5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AAErC,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAElC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAE5B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,qBAAqB,CAAC;AAEpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAE9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -24,6 +24,16 @@ export * from './logger.js';
 export * from './provider.js';
 export * from './config.js';
 export * from './host-state.js';
+// @non-paper Wave-5 hook runtime (single source of truth for generated
+// hook scripts and the OpenCode plugin).
+export * from './hook-runtime.js';
+// @non-paper Wave-5 shared adapter plumbing (resolve/save/merge helpers
+// reused by the claude/codex adapters).
+export * from './adapter-shared.js';
+// @non-paper Wave-5 deduplicated prompt texts (shared adapter vocabulary).
+export * from './prompt-contract.js';
 export * from './shutdown.js';
+// @non-paper release-2.3.0 session lifecycle marker (orchestration meta).
+export * from './session-meta.js';
 export * from './schemas/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,EAAE;AACF,0EAA0E;AAC1E,6EAA6E;AAC7E,qDAAqD;AACrD,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,qEAAqE;AACrE,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,0EAA0E;AAC1E,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,mDAAmD;AACnD,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,EAAE;AACF,0EAA0E;AAC1E,6EAA6E;AAC7E,qDAAqD;AACrD,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,qEAAqE;AACrE,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,0EAA0E;AAC1E,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,mDAAmD;AACnD,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,uEAAuE;AACvE,yCAAyC;AACzC,cAAc,mBAAmB,CAAC;AAClC,wEAAwE;AACxE,wCAAwC;AACxC,cAAc,qBAAqB,CAAC;AACpC,2EAA2E;AAC3E,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,0EAA0E;AAC1E,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}

package/dist/prompt-contract.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @non-paper Canonical prompt texts — the SINGLE SOURCE OF TRUTH for the
+ * {state_patch, action} JSON contract, the history-unreliability hint, the
+ * schema renderer, and the SKILL.md body shared by every platform adapter.
+ *
+ * PROMPT-FIDELITY BOUNDARY: `PromptTransformer.formatPaper` (Appendix A.4)
+ * is byte-verbatim paper text and deliberately does NOT use these
+ * constants — its inline `{ "state_patch": { <dict: ...> }, "action": ... }`
+ * directive differs from the fenced example below by design. Everything
+ * here is the @non-paper adapter vocabulary, deduplicated across
+ * claude/codex/opencode adapters and the prompt transformer.
+ */
+import type { ProceduralSpec, StateSchema } from './types.js';
+/**
+ * The two-key response directive (without the fenced example). Adapters
+ * prepend their own lead-in ("Based on your current state, provide your
+ * response with:" etc.) and append the numbered items via
+ * {@link STATE_PATCH_CONTRACT}.
+ */
+export declare const STATE_PATCH_CONTRACT_HEADER = "A JSON block containing both your State Patch and your Action. The JSON block MUST have exactly these two keys:";
+/** Canonical fenced ```json example block for the two-key contract. */
+export declare const STATE_PATCH_EXAMPLE_JSON: string;
+/** Canonical sparse-patch rules: null deletes, omissions leave state unchanged. */
+export declare const STATE_PATCH_RULES = "In `state_patch`, set keys to null to delete them. Only include fields you want to change. Omit fields to leave them unchanged.";
+/**
+ * The reasoning-is-discarded persistence bullet (paper §3.2, §4): any fact
+ * that must survive belongs in `state_patch`, never in the conversation.
+ */
+export declare const REASONING_DISCARDED_NOTE = "Reasoning is discarded after execution \u2014 put anything you need to persist into `state_patch`.";
+/**
+ * The full numbered response contract: reasoning is discarded (paper §3.2),
+ * the JSON block carries exactly the two keys, and the patch follows the
+ * sparse ⊕ semantics. Includes the example block and the rules — no lead-in.
+ */
+export declare const STATE_PATCH_CONTRACT: string;
+/**
+ * The single history-unreliability hint appended to the additionalContext
+ * of every inject-style hook script (claude + codex alike). Names the MCP
+ * tools AND the fenced ```json state_patch channel — one text for all
+ * hosts, so the Bash-carried patch option can no longer drift away.
+ */
+export declare const HISTORY_UNRELIABLE_NOTE = "\nHistory is not reliable. Persist anything you need via the skillstate MCP tools (state.summary / state.patch) or a fenced ```json state_patch block.";
+/**
+ * The interrupted-session hint injected by the SessionStart hooks
+ * (claude + codex alike) when the session-meta sidecar carries
+ * `status: "interrupted"` — a previous run of this session was killed
+ * (SIGINT/SIGTERM) mid-procedure. The hook appends the preserved state
+ * path so the agent can review progress/blockers before continuing.
+ * A fresh launch overwrites the status back to `running`.
+ */
+export declare const INTERRUPTED_SESSION_NOTE = "\nPrevious session was interrupted; state preserved at <path>; review progress/blockers before continuing.";
+/**
+ * Render a state schema as the shared `## Schema` markdown block used by
+ * every prompt formatter and adapter `injectState`. Fields without a
+ * description fall back to "no description".
+ */
+export declare function describeSchema(schema: StateSchema): string;
+/** Options for {@link skillMdBody}. */
+export interface SkillMdBodyOptions {
+    /** Brand label woven into the hooks intro ("Claude Code", "Codex"). */
+    hostLabel: string;
+    /**
+     * How the injected state reaches the model, as a predicate:
+     * "injected into your context via hooks" (claude) /
+     * "provided as developer context" (codex).
+     */
+    injectionPhrase: string;
+    /** The skill spec — name/instructions/version fill the frontmatter. */
+    spec: ProceduralSpec;
+    /** State path written into the frontmatter and the body (default `./.skillstate/skillstate.json`). */
+    statePath?: string;
+}
+/**
+ * Generate the whole SKILL.md document shared by the hook-wiring adapters
+ * (claude, codex): identical frontmatter, Execution Context, and Process
+ * sections; the ONLY brand-specific parts are `hostLabel` (hooks intro)
+ * and `injectionPhrase` (how the state reaches the model). OpenCode keeps
+ * its own body — its history is trimmed by the plugin, not by hooks, so
+ * its Execution Context and Process genuinely differ.
+ */
+export declare function skillMdBody(options: SkillMdBodyOptions): string;
+//# sourceMappingURL=prompt-contract.d.ts.map

package/dist/prompt-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-contract.d.ts","sourceRoot":"","sources":["../src/prompt-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,oHAC2E,CAAC;AAEpH,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,QAOzB,CAAC;AAEb,mFAAmF;AACnF,eAAO,MAAM,iBAAiB,oIACqG,CAAC;AAEpI;;;GAGG;AACH,eAAO,MAAM,wBAAwB,uGAC4D,CAAC;AAElG;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAOrB,CAAC;AAEb;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,2JACsH,CAAC;AAE3J;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,+GACyE,CAAC;AAE/G;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAQ1D;AAED,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,IAAI,EAAE,cAAc,CAAC;IACrB,sGAAsG;IACtG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAwD/D"}