@skillstate/codex 2.0.1 → 2.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +105 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# @skillstate/codex
|
|
4
|
+
|
|
5
|
+
**OpenAI Codex CLI adapter for the @skillstate/core runtime — AGENTS.md amendments plus lifecycle hook scripts.**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/@skillstate/codex)
|
|
8
|
+
[](https://www.npmjs.com/package/@skillstate/codex)
|
|
9
|
+
[](https://github.com/vitalykuzyaev/skillstate)
|
|
10
|
+
[](https://github.com/vitalykuzyaev/skillstate/blob/main/LICENSE)
|
|
11
|
+
|
|
12
|
+
</div>
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
`@skillstate/codex` bridges the paper-exact runtime ([`@skillstate/core`](../core))
|
|
17
|
+
into **OpenAI Codex CLI** sessions. It generates an `AGENTS.md` amendment that
|
|
18
|
+
puts the agent in state-based execution mode, plus a `hooks.json` document and
|
|
19
|
+
per-event hook scripts that inject the state on prompt submit and persist the
|
|
20
|
+
`state_patch` after tool use.
|
|
21
|
+
|
|
22
|
+
> **@non-paper** — no adapters exist in arXiv 2608.26263v3. This adapter is an
|
|
23
|
+
> additive integration, not part of the paper.
|
|
24
|
+
|
|
25
|
+
## Installation
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm i @skillstate/core @skillstate/codex
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Requires Node.js >= 20. TypeScript types are bundled.
|
|
32
|
+
|
|
33
|
+
## Quick start
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
import { CodexAdapter } from '@skillstate/codex';
|
|
37
|
+
import { INTERCODE_CTF_SPEC } from '@skillstate/core/schemas';
|
|
38
|
+
|
|
39
|
+
const adapter = new CodexAdapter();
|
|
40
|
+
|
|
41
|
+
// AGENTS.md amendment: read .skillstate.json each step, discard reasoning,
|
|
42
|
+
// emit a two-key state_patch/action JSON block:
|
|
43
|
+
const agentsMd = adapter.generateCodexAmendments('./.skillstate.json');
|
|
44
|
+
|
|
45
|
+
// Standalone "read the state file" instruction block (skill / system prompt):
|
|
46
|
+
const stateRead = adapter.generateCodexStateRead('./.skillstate.json');
|
|
47
|
+
|
|
48
|
+
// Codex hooks.json: inject state on UserPromptSubmit, re-inject after
|
|
49
|
+
// compaction (SessionStart matcher: compact), persist state_patch on PostToolUse:
|
|
50
|
+
const hooksJson = adapter.generateCodexHooksConfig('./.skillstate.json');
|
|
51
|
+
|
|
52
|
+
// Canonical hook-script path for a given event. Both generateCodexHooksConfig
|
|
53
|
+
// and saveCodexHookScript use this single convention so hooks.json commands
|
|
54
|
+
// and on-disk scripts ALWAYS agree by filename:
|
|
55
|
+
const script = adapter.codexHookScriptPath('./.skillstate.json', 'PostToolUse');
|
|
56
|
+
// -> path/to/.codex-.skillstate-post-tool-use.cjs
|
|
57
|
+
|
|
58
|
+
// Generate one hook script and persist it to the canonical path:
|
|
59
|
+
const scriptPath = await adapter.saveCodexHookScript('PostToolUse', './.skillstate.json');
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## API / Exports
|
|
63
|
+
|
|
64
|
+
Root path `@skillstate/codex` exports `CodexAdapter`, plus the shared
|
|
65
|
+
constants/types `CODEX_HOOK_SCRIPT_SUFFIX`, `CodexHookEvent`,
|
|
66
|
+
`CodexHookEventSuffix`, `CodexAmendmentsOptions`, `CodexHooksConfigOptions`.
|
|
67
|
+
|
|
68
|
+
- `new CodexAdapter()` — `name = 'codex'`.
|
|
69
|
+
- `generateCodexAmendments(statePath, options?): string` — AGENTS.md amendment
|
|
70
|
+
(`CodexAmendmentsOptions.spec` and `.includeHooksNote`).
|
|
71
|
+
- `generateCodexStateRead(statePath): string` — standalone state-read block.
|
|
72
|
+
- `generateCodexHookScript(eventType, statePath, schema?): string` —
|
|
73
|
+
`CodexHookEvent` is `'UserPromptSubmit' | 'PostToolUse' | 'SessionStart'`.
|
|
74
|
+
`PostToolUse` reads `tool_response` from stdin, extracts `state_patch`,
|
|
75
|
+
validates it, and merges it. Accepts raw paths or `{ root, name }` refs.
|
|
76
|
+
- `generateCodexHooksConfig(statePath, options?): string` —
|
|
77
|
+
`CodexHooksConfigOptions.command` and `.sessionStartMatcher`.
|
|
78
|
+
- `codexHookScriptPath(statePath, eventType): string` — canonical `.cjs` path.
|
|
79
|
+
- `saveCodexAmendments(target, statePath, options?): Promise<string>`,
|
|
80
|
+
`saveCodexHooksConfig(target, statePath, options?): Promise<string>`,
|
|
81
|
+
`saveCodexHookScript(eventType, statePath, schema?): Promise<string>`
|
|
82
|
+
(or the explicit-`target` overload) — atomic writes returning the destination.
|
|
83
|
+
|
|
84
|
+
## Notes
|
|
85
|
+
|
|
86
|
+
- **Honest limitation.** Codex has no `messages.transform` equivalent, so host
|
|
87
|
+
history is never trimmed — true O(1) is not possible. The hooks keep state
|
|
88
|
+
injected per prompt and persisted per tool call; the `AGENTS.md` amendment
|
|
89
|
+
tells the model to trust the state file over the conversation.
|
|
90
|
+
- `PostToolUse` accepts both fenced ```json blocks and a standalone (unfenced)
|
|
91
|
+
JSON object, and tolerates wrappers such as `Here is: {...}`. Malformed
|
|
92
|
+
outputs are rejected and never persisted.
|
|
93
|
+
- Depends on [`@skillstate/core`](../core) for `atomicWriteFile`,
|
|
94
|
+
`resolveStatePath`, and the `ProceduralSpec` type.
|
|
95
|
+
|
|
96
|
+
## Related
|
|
97
|
+
|
|
98
|
+
- Paper: [arXiv:2608.26263](https://arxiv.org/abs/2608.26263).
|
|
99
|
+
- Core runtime: [`@skillstate/core`](../core).
|
|
100
|
+
- [`state.md`](../../state.md) — design notes.
|
|
101
|
+
- Other adapters: `@skillstate/claude`, `@skillstate/opencode`, `@skillstate/mcp`.
|
|
102
|
+
|
|
103
|
+
## License
|
|
104
|
+
|
|
105
|
+
[MIT](LICENSE) © 2026 Vitaly Kuzyaev
|