@skillstate/codex 2.0.0

package/dist/codex-adapter.d.ts

@@ -0,0 +1,125 @@
+import type { StatePathRef } from '@skillstate/core';
+import type { ProceduralSpec } from '@skillstate/core';
+/** Codex lifecycle hook events this adapter can generate scripted hooks for. */
+export type CodexHookEvent = 'UserPromptSubmit' | 'PostToolUse' | 'SessionStart';
+/**
+ * Canonical `.cjs` filename suffix per Codex hook event, used by
+ * {@link CodexAdapter.codexHookScriptPath} so `hooks.json` commands and the
+ * on-disk hook scripts always agree.
+ */
+export declare const CODEX_HOOK_SCRIPT_SUFFIX: {
+    readonly UserPromptSubmit: 'user-prompt-submit';
+    readonly PostToolUse: 'post-tool-use';
+    readonly SessionStart: 'session-start-compact';
+};
+/** Executable hook-script suffix for a {@link CodexHookEvent}. */
+export type CodexHookEventSuffix = (typeof CODEX_HOOK_SCRIPT_SUFFIX)[CodexHookEvent];
+/** Options for {@link CodexAdapter.generateCodexAmendments}. */
+export interface CodexAmendmentsOptions {
+    /** Fill a `## State schema` section from the provided spec. */
+    spec?: ProceduralSpec;
+    /** Append the hook setup note (default true). */
+    includeHooksNote?: boolean;
+}
+/** Options for {@link CodexAdapter.generateCodexHooksConfig}. */
+export interface CodexHooksConfigOptions {
+    /** Command that runs the per-event hook scripts. Overrides the default. */
+    command?: string;
+    /** `matcher` for the `SessionStart` hook (default `compact`). */
+    sessionStartMatcher?: string;
+}
+/**
+ * OpenAI Codex platform adapter (@non-paper; see module doc).
+ *
+ * Codegen mirrors the Claude adapter's shape: every generator accepts a
+ * raw path (legacy) or a `{ root, name }` ref confined by
+ * `resolveStatePath` — `..` escapes throw instead of embedding an unsafe
+ * path into the generated artifact.
+ */
+export declare class CodexAdapter {
+    readonly name = "codex";
+    /**
+     * Generate an `AGENTS.md`-compatible amendment that puts the agent in
+     * state-based execution mode: read `.skillstate.json` each step, treat
+     * reasoning as discarded, and emit a `state_patch` that the hooks merge
+     * back into the state file.
+     */
+    generateCodexAmendments(statePath: string | StatePathRef, options?: CodexAmendmentsOptions): string;
+    /**
+     * Generate a markdown "read the state file" instruction block — the
+     * standalone form of the state-read contract (the core line the model
+     * must follow), suitable for embedding in an AGENTS.md, a skill body, or
+     * a system prompt.
+     */
+    generateCodexStateRead(statePath: string | StatePathRef): string;
+    /**
+     * Generate a self-contained Node CommonJS hook script for a Codex
+     * lifecycle event. The script is invoked by the hook's `command`; the
+     * event config (matcher) lives in the hooks.json document.
+     *
+     * - `UserPromptSubmit`: read the state file and inject it as
+     *   `additionalContext` (runs on every prompt submit).
+     * - `SessionStart`: same injection shape; combined with a `compact`
+     *   matcher it re-injects state after Codex compacts the chat.
+     * - `PostToolUse`: read `tool_response` from stdin, extract
+     *   `state_patch`, schema-validate (when a schema is provided) and merge
+     *   it into the state file via the paper ⊕ operator. Malformed outputs
+     *   are rejected and never persisted.
+     */
+    generateCodexHookScript(eventType: CodexHookEvent, statePath: string, schema?: ProceduralSpec['schema']): string;
+    generateCodexHookScript(eventType: CodexHookEvent, stateRef: StatePathRef, schema?: ProceduralSpec['schema']): string;
+    /**
+     * Generate a Codex `hooks.json` document that wires the state-injection /
+     * persistence hooks into the agent lifecycle:
+     *
+     * - `UserPromptSubmit` → inject current state (every prompt).
+     * - `SessionStart` (matcher `compact`) → re-inject state after compaction.
+     * - `PostToolUse` → extract `state_patch` and persist it.
+     */
+    generateCodexHooksConfig(statePath: string | StatePathRef, options?: CodexHooksConfigOptions): string;
+    /**
+     * Canonical absolute path of the generated hook script for a Codex event,
+     * derived from the state file name. Both {@link generateCodexHooksConfig}
+     * and {@link saveCodexHookScript} use this single convention so the
+     * `hooks.json` commands and the on-disk scripts always agree.
+     *
+     * For `./.skillstate.json`:
+     * - `UserPromptSubmit` → `.../.codex-.skillstate-user-prompt-submit.cjs`
+     * - `SessionStart`    → `.../.codex-.skillstate-session-start-compact.cjs`
+     * - `PostToolUse`     → `.../.codex-.skillstate-post-tool-use.cjs`
+     *
+     * Accepts a raw state path or a `{ root, name }` ref resolved via
+     * `resolveStatePath`.
+     */
+    codexHookScriptPath(statePath: string | StatePathRef, eventType: CodexHookEvent): string;
+    /**
+     * @non-paper additive helper: generate the AGENTS.md amendment and persist
+     * it via `atomicWriteFile` (tmp + fsync + rename). Both the destination and
+     * the embedded state path accept raw strings (legacy behavior) or
+     * `{ root, name }` refs confined by `resolveStatePath`. Returns the
+     * absolute destination path.
+     */
+    saveCodexAmendments(target: string | StatePathRef, statePath: string | StatePathRef, options?: CodexAmendmentsOptions): Promise<string>;
+    /**
+     * @non-paper additive helper: generate the hooks.json document and persist
+     * it via `atomicWriteFile`. Both the destination and the embedded state
+     * path accept raw strings or `{ root, name }` refs. Returns the absolute
+     * destination path.
+     */
+    saveCodexHooksConfig(target: string | StatePathRef, statePath: string | StatePathRef, options?: CodexHooksConfigOptions): Promise<string>;
+    /**
+     * @non-paper additive helper: generate a single hook script and persist it
+     * via `atomicWriteFile`. Accepts raw strings or `{ root, name }` refs for
+     * both the destination and the embedded state path. Returns the absolute
+     * destination path.
+     */
+    saveCodexHookScript(eventType: CodexHookEvent, statePath: string | StatePathRef, schema?: ProceduralSpec['schema']): Promise<string>;
+    saveCodexHookScript(target: string | StatePathRef, eventType: CodexHookEvent, statePath: string | StatePathRef, schema?: ProceduralSpec['schema']): Promise<string>;
+    /** Resolve a `string | StatePathRef` via `resolveStatePath` (throws on `..`). */
+    private resolve;
+    /** Shared injection body for injection-only hooks (read + emit context). */
+    private buildInjection;
+    /** PostToolUse body: extract, validate (if schema given), merge, persist. */
+    private buildPostToolUse;
+}
+//# sourceMappingURL=codex-adapter.d.ts.map

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

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

package/dist/codex-adapter.js

@@ -0,0 +1,433 @@
+/**
+ * @non-paper adapter — no adapters exist in arXiv 2608.26263v3.
+ *
+ * This file bridges the paper-exact core (Algorithm 1 prompt, ⊕ merge,
+ * §7 rollback-retry rejection) into OpenAI Codex CLI sessions.
+ *
+ * RESEARCH (github.com/openai/codex, docs "Hooks" / "AGENTS.md"): Codex
+ * exposes a real hook system configured as `hooks.json` (or inline
+ * `[hooks]` tables) under `~/.codex/` and `<repo>/.codex/`, plus the
+ * `AGENTS.md` project-instructions file that Codex loads into the agent's
+ * context. Hooks relevant to skillstate:
+ *
+ * - `UserPromptSubmit`  → `hookSpecificOutput.additionalContext` is added
+ *   as extra developer context on every prompt submit (state injection).
+ * - `PostToolUse`       → receives `tool_response` on stdin (JSON); a
+ *   command hook can read it, extract `state_patch`, and write the state
+ *   file (state persistence).
+ * - `SessionStart`      → `matcher: "compact"` fires after compaction and
+ *   can emit `additionalContext` (post-compaction re-injection).
+ * - `PreCompact`        → Codex only honours the shared output fields
+ *   (`continue`/`stopReason`/`systemMessage`) — it does NOT take
+ *   `additionalContext` for this event, so compaction injection is done
+ *   via `SessionStart(compact)` instead.
+ *
+ * LIMITATION: there is no `messages.transform` equivalent (unlike
+ * OpenCode). Codex hooks are additive — host history is never trimmed, so
+ * true O(1) is not possible. The best strategy is: `AGENTS.md` instructs
+ * the model to read `.skillstate.json` each step and patch it, while the
+ * hooks keep state injected/persisted around prompt submission and
+ * compaction. No host history is dropped, hence @non-paper best-effort.
+ */
+import * as path from 'node:path';
+import { atomicWriteFile, resolveStatePath, } from '@skillstate/core';
+/**
+ * Canonical `.cjs` filename suffix per Codex hook event, used by
+ * {@link CodexAdapter.codexHookScriptPath} so `hooks.json` commands and the
+ * on-disk hook scripts always agree.
+ */
+export const CODEX_HOOK_SCRIPT_SUFFIX = {
+    UserPromptSubmit: 'user-prompt-submit',
+    PostToolUse: 'post-tool-use',
+    SessionStart: 'session-start-compact',
+};
+/**
+ * OpenAI Codex platform adapter (@non-paper; see module doc).
+ *
+ * Codegen mirrors the Claude adapter's shape: every generator accepts a
+ * raw path (legacy) or a `{ root, name }` ref confined by
+ * `resolveStatePath` — `..` escapes throw instead of embedding an unsafe
+ * path into the generated artifact.
+ */
+export class CodexAdapter {
+    name = 'codex';
+    /**
+     * Generate an `AGENTS.md`-compatible amendment that puts the agent in
+     * state-based execution mode: read `.skillstate.json` each step, treat
+     * reasoning as discarded, and emit a `state_patch` that the hooks merge
+     * back into the state file.
+     */
+    generateCodexAmendments(statePath, options) {
+        const resolved = this.resolve(statePath);
+        const spec = options?.spec;
+        const sections = [
+            `## State-based execution (skillstate)`,
+            ``,
+            `You are running in state-based execution mode. Your execution state is`,
+            `persisted in the JSON file at \\\`${resolved}\\\`.`,
+            ``,
+            `Read \\\`${resolved}\\\` at the start of EVERY step and trust it over`,
+            `this conversation; reasoning and history are discarded between steps.`,
+            ``,
+            `After each step, respond with a JSON block containing exactly two keys:`,
+            `\`state_patch\` and \`action\`.`,
+            ``,
+            '```json',
+            `{`,
+            `  "state_patch": { "field_to_update": "new_value", "obsolete_field": null },`,
+            `  "action": "next_action_name"`,
+            `}`,
+            '```',
+            ``,
+            `- In \`state_patch\`, set keys to \`null\` to delete them. Only include`,
+            `  fields you want to change. Omit fields to leave them unchanged.`,
+            `- Put anything you need to persist into \`state_patch\`; never rely on`,
+            `  the model remembering it from history.`,
+            `- \`action\` names what you will do next.`,
+        ];
+        if (spec) {
+            sections.push('', '## Skill state schema', '');
+            for (const [name, field] of Object.entries(spec.schema)) {
+                sections.push(`- \`${name}\` (${field.type}): ${field.description ?? 'no description'}`);
+            }
+        }
+        if (options?.includeHooksNote !== false) {
+            sections.push('', 'A Codex hooks config (`.codex/hooks.json`) keeps this state injected on', '`UserPromptSubmit` and re-injected after compaction, and persists your', '`state_patch` on `PostToolUse`. Generate one with', '`CodexAdapter.generateCodexHooksConfig`.');
+        }
+        return sections.join('\n') + '\n';
+    }
+    /**
+     * Generate a markdown "read the state file" instruction block — the
+     * standalone form of the state-read contract (the core line the model
+     * must follow), suitable for embedding in an AGENTS.md, a skill body, or
+     * a system prompt.
+     */
+    generateCodexStateRead(statePath) {
+        const resolved = this.resolve(statePath);
+        return [
+            `You operate in state-based execution mode.`,
+            ``,
+            `1. Read \\\`${resolved}\\\` at the start of every step.`,
+            `2. Trust it over conversation history — history is discarded between steps.`,
+            `3. Reason about the next step, then output a fenced JSON block with`,
+            `   exactly two keys: \`state_patch\` (sparse update) and \`action\`.`,
+            `4. Set any key in \`state_patch\` to \`null\` to delete it.`,
+            ``,
+            `Never persist reasoning in the state; keep it only in \`state_patch\`.`,
+        ].join('\n');
+    }
+    generateCodexHookScript(eventType, statePathOrRef, schema) {
+        const resolved = this.resolve(statePathOrRef);
+        const sp = JSON.stringify(resolved);
+        if (eventType === 'PostToolUse') {
+            return this.buildPostToolUse(sp, schema ?? {});
+        }
+        // UserPromptSubmit and SessionStart share the same injection body.
+        const context = this.buildInjection(sp);
+        return [
+            `// Codex hook: ${eventType === 'SessionStart'
+                ? 'SessionStart (matcher: compact)'
+                : 'UserPromptSubmit'}`,
+            `// Injects the current skill state as additionalContext so the model`,
+            `// never has to reconstruct execution context from history.`,
+            ...context,
+        ].join('\n');
+    }
+    /**
+     * Generate a Codex `hooks.json` document that wires the state-injection /
+     * persistence hooks into the agent lifecycle:
+     *
+     * - `UserPromptSubmit` → inject current state (every prompt).
+     * - `SessionStart` (matcher `compact`) → re-inject state after compaction.
+     * - `PostToolUse` → extract `state_patch` and persist it.
+     */
+    generateCodexHooksConfig(statePath, options) {
+        const resolved = this.resolve(statePath);
+        const defaultCommand = (eventType) => `node ${JSON.stringify(this.codexHookScriptPath(resolved, eventType))}`;
+        const sessionStartMatcher = options?.sessionStartMatcher ?? 'compact';
+        const command = options?.command;
+        const doc = {
+            description: 'Skillstate lifecycle hooks: inject state per prompt, re-inject after compaction, persist state_patch.',
+            hooks: {
+                UserPromptSubmit: [
+                    {
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: command ?? defaultCommand('UserPromptSubmit'),
+                                statusMessage: 'Injecting skill state',
+                            },
+                        ],
+                    },
+                ],
+                SessionStart: [
+                    {
+                        matcher: sessionStartMatcher,
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: command ?? defaultCommand('SessionStart'),
+                                statusMessage: 'Re-injecting skill state after compaction',
+                            },
+                        ],
+                    },
+                ],
+                PostToolUse: [
+                    {
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: command ?? defaultCommand('PostToolUse'),
+                                statusMessage: 'Persisting skill state patch',
+                            },
+                        ],
+                    },
+                ],
+            },
+        };
+        return JSON.stringify(doc, null, 2) + '\n';
+    }
+    /**
+     * Canonical absolute path of the generated hook script for a Codex event,
+     * derived from the state file name. Both {@link generateCodexHooksConfig}
+     * and {@link saveCodexHookScript} use this single convention so the
+     * `hooks.json` commands and the on-disk scripts always agree.
+     *
+     * For `./.skillstate.json`:
+     * - `UserPromptSubmit` → `.../.codex-.skillstate-user-prompt-submit.cjs`
+     * - `SessionStart`    → `.../.codex-.skillstate-session-start-compact.cjs`
+     * - `PostToolUse`     → `.../.codex-.skillstate-post-tool-use.cjs`
+     *
+     * Accepts a raw state path or a `{ root, name }` ref resolved via
+     * `resolveStatePath`.
+     */
+    codexHookScriptPath(statePath, eventType) {
+        const resolved = this.resolve(statePath);
+        const dir = path.dirname(resolved);
+        const base = path.basename(resolved, '.json');
+        return path.join(dir, `.codex-${base}-${CODEX_HOOK_SCRIPT_SUFFIX[eventType]}.cjs`);
+    }
+    /**
+     * @non-paper additive helper: generate the AGENTS.md amendment and persist
+     * it via `atomicWriteFile` (tmp + fsync + rename). Both the destination and
+     * the embedded state path accept raw strings (legacy behavior) or
+     * `{ root, name }` refs confined by `resolveStatePath`. Returns the
+     * absolute destination path.
+     */
+    async saveCodexAmendments(target, statePath, options) {
+        const dest = this.resolve(target);
+        const resolved = this.resolve(statePath);
+        const content = this.generateCodexAmendments(resolved, options);
+        await atomicWriteFile(dest, content);
+        return dest;
+    }
+    /**
+     * @non-paper additive helper: generate the hooks.json document and persist
+     * it via `atomicWriteFile`. Both the destination and the embedded state
+     * path accept raw strings or `{ root, name }` refs. Returns the absolute
+     * destination path.
+     */
+    async saveCodexHooksConfig(target, statePath, options) {
+        const dest = this.resolve(target);
+        const resolved = this.resolve(statePath);
+        const content = this.generateCodexHooksConfig(resolved, options);
+        await atomicWriteFile(dest, content);
+        return dest;
+    }
+    async saveCodexHookScript(targetOrEvent, eventTypeOrPath, statePathOrSchema, schema) {
+        const refForm = typeof targetOrEvent === 'string' &&
+            (targetOrEvent === 'UserPromptSubmit' ||
+                targetOrEvent === 'PostToolUse' ||
+                targetOrEvent === 'SessionStart');
+        const target = refForm
+            ? this.codexHookScriptPath(eventTypeOrPath, targetOrEvent)
+            : targetOrEvent;
+        const eventType = refForm
+            ? targetOrEvent
+            : eventTypeOrPath;
+        const statePath = refForm
+            ? eventTypeOrPath
+            : statePathOrSchema;
+        const effectiveSchema = refForm
+            ? statePathOrSchema
+            : schema;
+        const dest = this.resolve(target);
+        const resolved = this.resolve(statePath);
+        const content = this.generateCodexHookScript(eventType, resolved, effectiveSchema);
+        await atomicWriteFile(dest, content);
+        return dest;
+    }
+    /* ------------------------------------------------------------------ */
+    /*  Internal helpers                                                   */
+    /* ------------------------------------------------------------------ */
+    /** Resolve a `string | StatePathRef` via `resolveStatePath` (throws on `..`). */
+    resolve(target) {
+        return typeof target === 'string'
+            ? target
+            : resolveStatePath(target.root, target.name);
+    }
+    /** Shared injection body for injection-only hooks (read + emit context). */
+    buildInjection(sp) {
+        return [
+            'const fs = require("fs");',
+            `const stateFilePath = ${sp};`,
+            'let state = {};',
+            'try {',
+            '  if (fs.existsSync(stateFilePath)) {',
+            '    state = JSON.parse(fs.readFileSync(stateFilePath, "utf-8"));',
+            '  }',
+            '} catch (e) { state = {}; }',
+            'const output = {',
+            '  hookSpecificOutput: {',
+            '    additionalContext: "Current skill state (JSON): " + JSON.stringify(state)',
+            '  }',
+            '};',
+            'process.stdout.write(JSON.stringify(output));',
+        ];
+    }
+    /** PostToolUse body: extract, validate (if schema given), merge, persist. */
+    buildPostToolUse(sp, schema) {
+        const fence = '`' + '`' + '`';
+        const schemaJson = JSON.stringify(schema);
+        return [
+            '// Codex hook: PostToolUse',
+            '// Extracts state_patch from the tool_response, validates it against the',
+            '// embedded schema (when provided), applies the null-deletion merge, and',
+            '// saves. Malformed output is rejected and never persisted.',
+            'const fs = require("fs");',
+            `const stateFilePath = ${sp};`,
+            `const schema = ${schemaJson};`,
+            '',
+            'function isPlainObject(v) {',
+            '  return typeof v === "object" && v !== null && !Array.isArray(v);',
+            '}',
+            '',
+            'function mergePatch(base, patch) {',
+            '  function mergeInto(result, patchObj) {',
+            '    for (const key of Object.keys(patchObj)) {',
+            '      const value = patchObj[key];',
+            '      if (value === null) {',
+            '        delete result[key];',
+            '      } else if (isPlainObject(value) && isPlainObject(result[key])) {',
+            '        result[key] = mergeInto({ ...result[key] }, value);',
+            '      } else {',
+            '        result[key] = value;',
+            '      }',
+            '    }',
+            '    return result;',
+            '  }',
+            '  return mergeInto({ ...base }, patch);',
+            '}',
+            '',
+            'function validatePatchAgainstSchema(patch) {',
+            '  for (const key of Object.keys(patch)) {',
+            '    const field = schema[key];',
+            '    if (!field) {',
+            '      return "Unknown key: " + key;',
+            '    }',
+            '    const value = patch[key];',
+            '    if (value === null) continue;',
+            '    const expected = field.type;',
+            '    let ok = false;',
+            '    if (expected === "string") ok = typeof value === "string";',
+            '    else if (expected === "number") ok = typeof value === "number";',
+            '    else if (expected === "boolean") ok = typeof value === "boolean";',
+            '    else if (expected === "array") ok = Array.isArray(value);',
+            '    else if (expected === "object") ok = isPlainObject(value);',
+            '    if (!ok) {',
+            '      return "Invalid type for field \'" + key + "\': expected " + expected +',
+            '        ", got " + (Array.isArray(value) ? "array" : typeof value);',
+            '    }',
+            '  }',
+            '  return null;',
+            '}',
+            '',
+            'function isJsonObjectWithStatePatch(value) {',
+            '  return value !== null &&',
+            '    typeof value === "object" &&',
+            '    !Array.isArray(value) &&',
+            '    value.state_patch !== null &&',
+            '    typeof value.state_patch === "object" &&',
+            '    !Array.isArray(value.state_patch);',
+            '}',
+            '',
+            'function tryParseStandaloneJson(text) {',
+            '  const trimmed = String(text).trim();',
+            '  try {',
+            '    const parsed = JSON.parse(trimmed);',
+            '    if (isJsonObjectWithStatePatch(parsed)) return parsed;',
+            '  } catch (e) {}',
+            '  const first = trimmed.indexOf("{");',
+            '  const last = trimmed.lastIndexOf("}");',
+            '  if (first !== -1 && last > first) {',
+            '    try {',
+            '      const parsed = JSON.parse(trimmed.slice(first, last + 1));',
+            '      if (isJsonObjectWithStatePatch(parsed)) return parsed;',
+            '    } catch (e) {}',
+            '  }',
+            '  return null;',
+            '}',
+            '',
+            'function extractPatchString(content) {',
+            '  if (typeof content !== "string") return null;',
+            '  const match = content.match(/' + fence + 'json\\s*\\n?([\\s\\S]*?)\\n?\\s*' + fence + '/);',
+            '  if (match) {',
+            '    try {',
+            '      const parsed = JSON.parse(match[1]);',
+            '      if (isJsonObjectWithStatePatch(parsed)) return parsed;',
+            '    } catch (e) {}',
+            '  }',
+            '  return tryParseStandaloneJson(content);',
+            '}',
+            '',
+            'function readResponseText(response) {',
+            '  if (response === null || response === undefined) return "";',
+            '  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 JSON.stringify(response);',
+            '}',
+            '',
+            'let state = {};',
+            'try {',
+            '  if (fs.existsSync(stateFilePath)) {',
+            '    state = JSON.parse(fs.readFileSync(stateFilePath, "utf-8"));',
+            '  }',
+            '} catch (e) { state = {}; }',
+            'let input = "";',
+            'process.stdin.setEncoding("utf-8");',
+            'process.stdin.on("data", (chunk) => { input += chunk; });',
+            'process.stdin.on("end", () => {',
+            '  const output = {};',
+            '  try {',
+            '    const parsed = JSON.parse(input);',
+            '    const response = parsed.tool_response ?? parsed.content ?? "";',
+            '    const text = readResponseText(response);',
+            '    let json;',
+            '    if (isPlainObject(response) && isPlainObject(response.state_patch)) {',
+            '      json = response;',
+            '    } else {',
+            '      json = extractPatchString(text);',
+            '    }',
+            '    if (json && json.state_patch && typeof json.state_patch === "object" && !Array.isArray(json.state_patch)) {',
+            '      const validationError = validatePatchAgainstSchema(json.state_patch);',
+            '      if (validationError) {',
+            '        output.error = validationError;',
+            '        process.stdout.write(JSON.stringify(output));',
+            '        return;',
+            '      }',
+            '      state = mergePatch(state, json.state_patch);',
+            '      fs.writeFileSync(stateFilePath, JSON.stringify(state, null, 2));',
+            '    }',
+            '  } catch (e) {',
+            '    output.error = "Failed to process PostToolUse input: " + e.message;',
+            '  }',
+            '  process.stdout.write(JSON.stringify(output));',
+            '});',
+        ].join('\n');
+    }
+}
+//# sourceMappingURL=codex-adapter.js.map

package/dist/codex-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-adapter.js","sourceRoot":"","sources":["../src/codex-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EACL,eAAe,EACf,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAU1B;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,gBAAgB,EAAE,oBAAoB;IACtC,WAAW,EAAE,eAAe;IAC5B,YAAY,EAAE,uBAAuB;CAC7B,CAAC;AAsBX;;;;;;;GAOG;AACH,MAAM,OAAO,YAAY;IACd,IAAI,GAAG,OAAO,CAAC;IAExB;;;;;OAKG;IACH,uBAAuB,CACrB,SAAgC,EAChC,OAAgC;QAEhC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzC,MAAM,IAAI,GAAG,OAAO,EAAE,IAAI,CAAC;QAE3B,MAAM,QAAQ,GAAa;YACzB,uCAAuC;YACvC,EAAE;YACF,wEAAwE;YACxE,qCAAqC,QAAQ,OAAO;YACpD,EAAE;YACF,YAAY,QAAQ,mDAAmD;YACvE,uEAAuE;YACvE,EAAE;YACF,yEAAyE;YACzE,iCAAiC;YACjC,EAAE;YACF,SAAS;YACT,GAAG;YACH,8EAA8E;YAC9E,gCAAgC;YAChC,GAAG;YACH,KAAK;YACL,EAAE;YACF,yEAAyE;YACzE,mEAAmE;YACnE,wEAAwE;YACxE,0CAA0C;YAC1C,2CAA2C;SAC5C,CAAC;QAEF,IAAI,IAAI,EAAE,CAAC;YACT,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,uBAAuB,EAAE,EAAE,CAAC,CAAC;YAC/C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBACxD,QAAQ,CAAC,IAAI,CACX,OAAO,IAAI,OAAO,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,WAAW,IAAI,gBAAgB,EAAE,CAC1E,CAAC;YACJ,CAAC;QACH,CAAC;QAED,IAAI,OAAO,EAAE,gBAAgB,KAAK,KAAK,EAAE,CAAC;YACxC,QAAQ,CAAC,IAAI,CACX,EAAE,EACF,yEAAyE,EACzE,wEAAwE,EACxE,mDAAmD,EACnD,0CAA0C,CAC3C,CAAC;QACJ,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACpC,CAAC;IAED;;;;;OAKG;IACH,sBAAsB,CAAC,SAAgC;QACrD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzC,OAAO;YACL,4CAA4C;YAC5C,EAAE;YACF,eAAe,QAAQ,kCAAkC;YACzD,6EAA6E;YAC7E,qEAAqE;YACrE,sEAAsE;YACtE,6DAA6D;YAC7D,EAAE;YACF,wEAAwE;SACzE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IA0BD,uBAAuB,CACrB,SAAyB,EACzB,cAAqC,EACrC,MAAiC;QAEjC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QAC9C,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAEpC,IAAI,SAAS,KAAK,aAAa,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC,gBAAgB,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC;QACjD,CAAC;QACD,mEAAmE;QACnE,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;QACxC,OAAO;YACL,kBACE,SAAS,KAAK,cAAc;gBAC1B,CAAC,CAAC,iCAAiC;gBACnC,CAAC,CAAC,kBACN,EAAE;YACF,sEAAsE;YACtE,6DAA6D;YAC7D,GAAG,OAAO;SACX,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;IAED;;;;;;;OAOG;IACH,wBAAwB,CACtB,SAAgC,EAChC,OAAiC;QAEjC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzC,MAAM,cAAc,GAAG,CAAC,SAAyB,EAAU,EAAE,CAC3D,QAAQ,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC;QAE1E,MAAM,mBAAmB,GAAG,OAAO,EAAE,mBAAmB,IAAI,SAAS,CAAC;QACtE,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,CAAC;QAEjC,MAAM,GAAG,GAAG;YACV,WAAW,EACT,uGAAuG;YACzG,KAAK,EAAE;gBACL,gBAAgB,EAAE;oBAChB;wBACE,KAAK,EAAE;4BACL;gCACE,IAAI,EAAE,SAAS;gCACf,OAAO,EACL,OAAO,IAAI,cAAc,CAAC,kBAAkB,CAAC;gCAC/C,aAAa,EAAE,uBAAuB;6BACvC;yBACF;qBACF;iBACF;gBACD,YAAY,EAAE;oBACZ;wBACE,OAAO,EAAE,mBAAmB;wBAC5B,KAAK,EAAE;4BACL;gCACE,IAAI,EAAE,SAAS;gCACf,OAAO,EAAE,OAAO,IAAI,cAAc,CAAC,cAAc,CAAC;gCAClD,aAAa,EAAE,2CAA2C;6BAC3D;yBACF;qBACF;iBACF;gBACD,WAAW,EAAE;oBACX;wBACE,KAAK,EAAE;4BACL;gCACE,IAAI,EAAE,SAAS;gCACf,OAAO,EAAE,OAAO,IAAI,cAAc,CAAC,aAAa,CAAC;gCACjD,aAAa,EAAE,8BAA8B;6BAC9C;yBACF;qBACF;iBACF;aACF;SACF,CAAC;QAEF,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;IAC7C,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,mBAAmB,CACjB,SAAgC,EAChC,SAAyB;QAEzB,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,IAAI,IAAI,wBAAwB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACrF,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,mBAAmB,CACvB,MAA6B,EAC7B,SAAgC,EAChC,OAAgC;QAEhC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,uBAAuB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAChE,MAAM,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,oBAAoB,CACxB,MAA6B,EAC7B,SAAgC,EAChC,OAAiC;QAEjC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,wBAAwB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QACjE,MAAM,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IAmBD,KAAK,CAAC,mBAAmB,CACvB,aAAqD,EACrD,eAAuD,EACvD,iBAAoE,EACpE,MAAiC;QAEjC,MAAM,OAAO,GACX,OAAO,aAAa,KAAK,QAAQ;YACjC,CAAC,aAAa,KAAK,kBAAkB;gBACnC,aAAa,KAAK,aAAa;gBAC/B,aAAa,KAAK,cAAc,CAAC,CAAC;QAEtC,MAAM,MAAM,GAA0B,OAAO;YAC3C,CAAC,CAAC,IAAI,CAAC,mBAAmB,CACtB,eAAwC,EACxC,aAA+B,CAChC;YACH,CAAC,CAAE,aAAuC,CAAC;QAC7C,MAAM,SAAS,GAAmB,OAAO;YACvC,CAAC,CAAE,aAAgC;YACnC,CAAC,CAAE,eAAkC,CAAC;QACxC,MAAM,SAAS,GAA0B,OAAO;YAC9C,CAAC,CAAE,eAAyC;YAC5C,CAAC,CAAE,iBAA2C,CAAC;QACjD,MAAM,eAAe,GAAyC,OAAO;YACnE,CAAC,CAAE,iBAA0D;YAC7D,CAAC,CAAC,MAAM,CAAC;QAEX,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzC,MAAM,OAAO,GAAG,IAAI,CAAC,uBAAuB,CAC1C,SAAS,EACT,QAAQ,EACR,eAAe,CAChB,CAAC;QACF,MAAM,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,wEAAwE;IACxE,yEAAyE;IACzE,wEAAwE;IAExE,iFAAiF;IACzE,OAAO,CAAC,MAA6B;QAC3C,OAAO,OAAO,MAAM,KAAK,QAAQ;YAC/B,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC;IAED,4EAA4E;IACpE,cAAc,CAAC,EAAU;QAC/B,OAAO;YACL,2BAA2B;YAC3B,yBAAyB,EAAE,GAAG;YAC9B,iBAAiB;YACjB,OAAO;YACP,uCAAuC;YACvC,kEAAkE;YAClE,KAAK;YACL,6BAA6B;YAC7B,kBAAkB;YAClB,yBAAyB;YACzB,+EAA+E;YAC/E,KAAK;YACL,IAAI;YACJ,+CAA+C;SAChD,CAAC;IACJ,CAAC;IAED,6EAA6E;IACrE,gBAAgB,CAAC,EAAU,EAAE,MAA+B;QAClE,MAAM,KAAK,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;QAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAE1C,OAAO;YACL,4BAA4B;YAC5B,0EAA0E;YAC1E,0EAA0E;YAC1E,6DAA6D;YAC7D,2BAA2B;YAC3B,yBAAyB,EAAE,GAAG;YAC9B,kBAAkB,UAAU,GAAG;YAC/B,EAAE;YACF,6BAA6B;YAC7B,oEAAoE;YACpE,GAAG;YACH,EAAE;YACF,oCAAoC;YACpC,0CAA0C;YAC1C,gDAAgD;YAChD,oCAAoC;YACpC,6BAA6B;YAC7B,6BAA6B;YAC7B,wEAAwE;YACxE,6DAA6D;YAC7D,gBAAgB;YAChB,8BAA8B;YAC9B,SAAS;YACT,OAAO;YACP,oBAAoB;YACpB,KAAK;YACL,yCAAyC;YACzC,GAAG;YACH,EAAE;YACF,8CAA8C;YAC9C,2CAA2C;YAC3C,gCAAgC;YAChC,mBAAmB;YACnB,qCAAqC;YACrC,OAAO;YACP,+BAA+B;YAC/B,mCAAmC;YACnC,kCAAkC;YAClC,qBAAqB;YACrB,gEAAgE;YAChE,qEAAqE;YACrE,uEAAuE;YACvE,+DAA+D;YAC/D,gEAAgE;YAChE,gBAAgB;YAChB,+EAA+E;YAC/E,qEAAqE;YACrE,OAAO;YACP,KAAK;YACL,gBAAgB;YAChB,GAAG;YACH,EAAE;YACF,8CAA8C;YAC9C,4BAA4B;YAC5B,kCAAkC;YAClC,8BAA8B;YAC9B,mCAAmC;YACnC,8CAA8C;YAC9C,wCAAwC;YACxC,GAAG;YACH,EAAE;YACF,yCAAyC;YACzC,wCAAwC;YACxC,SAAS;YACT,yCAAyC;YACzC,4DAA4D;YAC5D,kBAAkB;YAClB,uCAAuC;YACvC,0CAA0C;YAC1C,uCAAuC;YACvC,WAAW;YACX,kEAAkE;YAClE,8DAA8D;YAC9D,oBAAoB;YACpB,KAAK;YACL,gBAAgB;YAChB,GAAG;YACH,EAAE;YACF,wCAAwC;YACxC,iDAAiD;YACjD,iCAAiC,GAAG,KAAK,GAAG,kCAAkC,GAAG,KAAK,GAAG,KAAK;YAC9F,gBAAgB;YAChB,WAAW;YACX,4CAA4C;YAC5C,8DAA8D;YAC9D,oBAAoB;YACpB,KAAK;YACL,2CAA2C;YAC3C,GAAG;YACH,EAAE;YACF,uCAAuC;YACvC,+DAA+D;YAC/D,sDAAsD;YACtD,kCAAkC;YAClC,wEAAwE;YACxE,kEAAkE;YAClE,sCAAsC;YACtC,KAAK;YACL,oCAAoC;YACpC,GAAG;YACH,EAAE;YACF,iBAAiB;YACjB,OAAO;YACP,uCAAuC;YACvC,kEAAkE;YAClE,KAAK;YACL,6BAA6B;YAC7B,iBAAiB;YACjB,qCAAqC;YACrC,2DAA2D;YAC3D,iCAAiC;YACjC,sBAAsB;YACtB,SAAS;YACT,uCAAuC;YACvC,oEAAoE;YACpE,8CAA8C;YAC9C,eAAe;YACf,2EAA2E;YAC3E,wBAAwB;YACxB,cAAc;YACd,wCAAwC;YACxC,OAAO;YACP,iHAAiH;YACjH,6EAA6E;YAC7E,8BAA8B;YAC9B,yCAAyC;YACzC,uDAAuD;YACvD,iBAAiB;YACjB,SAAS;YACT,oDAAoD;YACpD,wEAAwE;YACxE,OAAO;YACP,iBAAiB;YACjB,yEAAyE;YACzE,KAAK;YACL,iDAAiD;YACjD,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACf,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './codex-adapter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+// @skillstate/codex — OpenAI Codex platform adapter.
+export * from './codex-adapter.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,cAAc,oBAAoB,CAAC"}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@skillstate/codex",
+  "version": "2.0.0",
+  "description": "OpenAI Codex platform adapter for the skillstate runtime.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@skillstate/core": "^2.0.0"
+  }
+}