@ascenda-one/codex-hooks 0.1.3 → 0.1.5
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 +50 -28
- package/examples/hooks.json +7 -7
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -21,68 +21,90 @@ Identity: Codex rides the canonical `cli_agent` toolType/source (the backend reg
|
|
|
21
21
|
|
|
22
22
|
Codex **awaits** command hooks and treats **exit code 2 as blocking** the user's action. This adapter therefore always exits `0` and caps every HTTP call at 3 s (`ASCENDA_HTTP_TIMEOUT_MS` to change): telemetry failures surface as a one-line `systemMessage` or stderr note and never stall or block the engineer.
|
|
23
23
|
|
|
24
|
-
##
|
|
24
|
+
## Install
|
|
25
25
|
|
|
26
26
|
### Prerequisites
|
|
27
27
|
|
|
28
28
|
- [Codex CLI](https://developers.openai.com/codex) with hooks support (v0.117+)
|
|
29
|
-
- Node.js **20+**
|
|
30
|
-
- A
|
|
29
|
+
- Node.js **20+**
|
|
30
|
+
- A pairing to reuse (see [Pair first](#pair-first) below)
|
|
31
31
|
|
|
32
|
-
### 1.
|
|
32
|
+
### 1. Run the published CLI
|
|
33
33
|
|
|
34
|
-
|
|
35
|
-
# from the repo root (workspace install + shared packages first)
|
|
36
|
-
npm install
|
|
37
|
-
npm run build:shared
|
|
34
|
+
No clone, no build — the package is on npm:
|
|
38
35
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
npm link
|
|
36
|
+
```bash
|
|
37
|
+
npx @ascenda-one/codex-hooks --help
|
|
42
38
|
```
|
|
43
39
|
|
|
44
|
-
|
|
40
|
+
### 2. Pair first
|
|
45
41
|
|
|
46
|
-
|
|
42
|
+
```bash
|
|
43
|
+
npx -y @ascenda-one/claude-code-hooks pair --tool-type cli_agent
|
|
44
|
+
```
|
|
47
45
|
|
|
48
|
-
|
|
46
|
+
It prints a 6-digit code — confirm it in the Ascenda app under
|
|
47
|
+
**Connections → Ingest telemetry** — then saves the write token to
|
|
48
|
+
`~/.ascenda/tokens/` and prints the export line:
|
|
49
49
|
|
|
50
50
|
```bash
|
|
51
|
-
#
|
|
52
|
-
cd ../ascenda-pairing-sim
|
|
53
|
-
node dist/cli.js e2e --tool-type cli_agent --name "Codex CLI"
|
|
51
|
+
export ASCENDA_TOOL_INSTALLATION_ID="cli_agent:<uuid>" # printed by `pair`
|
|
54
52
|
```
|
|
55
53
|
|
|
56
|
-
|
|
54
|
+
Add it to your shell profile. **Without this variable every hook invocation
|
|
55
|
+
exits with `Missing ASCENDA_TOOL_INSTALLATION_ID`.**
|
|
56
|
+
|
|
57
|
+
On a Dev backend with no phone:
|
|
57
58
|
|
|
58
59
|
```bash
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
export ASCENDA_EVENT_WRITE_TOKEN="<eventWriteToken>"
|
|
60
|
+
cd ../ascenda-pairing-sim && npm run build
|
|
61
|
+
node dist/cli.js e2e --tool-type cli_agent --name "Codex CLI"
|
|
62
62
|
```
|
|
63
63
|
|
|
64
|
+
`ASCENDA_API_BASE_URL` defaults to `https://api.ascenda.one`; set it to
|
|
65
|
+
`http://localhost:5002` or the Azure Dev host for development.
|
|
66
|
+
|
|
64
67
|
### 3. Register hooks in Codex
|
|
65
68
|
|
|
66
|
-
Merge [`examples/hooks.json`](./examples/hooks.json) into `~/.codex/hooks.json`
|
|
69
|
+
Merge [`examples/hooks.json`](./examples/hooks.json) into `~/.codex/hooks.json`
|
|
70
|
+
(machine-wide) or `<repo>/.codex/hooks.json` (per project). Inline `config.toml`
|
|
71
|
+
form works too:
|
|
67
72
|
|
|
68
73
|
```toml
|
|
69
74
|
[[hooks.UserPromptSubmit]]
|
|
70
75
|
[[hooks.UserPromptSubmit.hooks]]
|
|
71
76
|
type = "command"
|
|
72
|
-
command = "ascenda-codex-
|
|
77
|
+
command = "npx -y @ascenda-one/codex-hooks UserPromptSubmit"
|
|
73
78
|
timeout = 10
|
|
74
79
|
```
|
|
75
80
|
|
|
76
|
-
If `ascenda-codex-hook` is not on Codex's PATH, use the absolute path to the binary.
|
|
77
|
-
|
|
78
81
|
### 4. Verify
|
|
79
82
|
|
|
83
|
+
Run a Codex session and confirm events arrive on the backend — or simply that
|
|
84
|
+
the hook exits `0`, which it always does (see the safety contract above).
|
|
85
|
+
|
|
86
|
+
## Build from source
|
|
87
|
+
|
|
88
|
+
Not needed to use this — npm ships it prebuilt. It is here so you can verify
|
|
89
|
+
what runs.
|
|
90
|
+
|
|
80
91
|
```bash
|
|
81
|
-
|
|
82
|
-
npm
|
|
92
|
+
# from the repo root (workspace install + shared packages first)
|
|
93
|
+
npm install
|
|
94
|
+
npm run build:shared
|
|
95
|
+
|
|
96
|
+
cd ascenda-codex-hooks
|
|
97
|
+
npm run build
|
|
98
|
+
npm link # exposes `ascenda-codex-hook`
|
|
99
|
+
which ascenda-codex-hook
|
|
100
|
+
|
|
101
|
+
npm run test # unit tests for the mapping
|
|
102
|
+
npm run test:sample # pipes a sample PostToolUse payload through the CLI
|
|
83
103
|
```
|
|
84
104
|
|
|
85
|
-
|
|
105
|
+
A local build exposes the binary as `ascenda-codex-hook` — substitute it for
|
|
106
|
+
`npx -y @ascenda-one/codex-hooks` in the hook config above. If it is not on
|
|
107
|
+
Codex's PATH, use the absolute path to the binary.
|
|
86
108
|
|
|
87
109
|
## Supported Codex hook events
|
|
88
110
|
|
package/examples/hooks.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"hooks": {
|
|
3
|
-
"SessionStart": [{ "hooks": [{ "type": "command", "command": "ascenda-codex-
|
|
4
|
-
"UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "ascenda-codex-
|
|
5
|
-
"PreToolUse": [{ "hooks": [{ "type": "command", "command": "ascenda-codex-
|
|
6
|
-
"PostToolUse": [{ "hooks": [{ "type": "command", "command": "ascenda-codex-
|
|
7
|
-
"PreCompact": [{ "hooks": [{ "type": "command", "command": "ascenda-codex-
|
|
8
|
-
"PostCompact": [{ "hooks": [{ "type": "command", "command": "ascenda-codex-
|
|
9
|
-
"Stop": [{ "hooks": [{ "type": "command", "command": "ascenda-codex-
|
|
3
|
+
"SessionStart": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/codex-hooks SessionStart", "timeout": 10 }] }],
|
|
4
|
+
"UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/codex-hooks UserPromptSubmit", "timeout": 10 }] }],
|
|
5
|
+
"PreToolUse": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/codex-hooks PreToolUse", "timeout": 10 }] }],
|
|
6
|
+
"PostToolUse": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/codex-hooks PostToolUse", "timeout": 10 }] }],
|
|
7
|
+
"PreCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/codex-hooks PreCompact", "timeout": 10 }] }],
|
|
8
|
+
"PostCompact": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/codex-hooks PostCompact", "timeout": 10 }] }],
|
|
9
|
+
"Stop": [{ "hooks": [{ "type": "command", "command": "npx -y @ascenda-one/codex-hooks Stop", "timeout": 10 }] }]
|
|
10
10
|
}
|
|
11
11
|
}
|
package/package.json
CHANGED