@ascenda-one/codex-hooks 0.1.3 → 0.1.4

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 CHANGED
@@ -21,68 +21,87 @@ 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
- ## Installation
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+** and npm
30
- - A paired Ascenda `toolInstallationId` + `eventWriteToken` (from an IDE extension pair, or [pairing-sim](../ascenda-pairing-sim/) `e2e --tool-type cli_agent` on Dev)
29
+ - Node.js **20+**
30
+ - A pairing to reuse (see [Pair first](#pair-first) below)
31
31
 
32
- ### 1. Build and install the hook CLI
32
+ ### 1. Run the published CLI
33
33
 
34
- ```bash
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
- cd ascenda-codex-hooks
40
- npm run build
41
- npm link
36
+ ```bash
37
+ npx @ascenda-one/codex-hooks --help
42
38
  ```
43
39
 
44
- Confirm: `which ascenda-codex-hook`.
40
+ ### 2. Pair first
45
41
 
46
- ### 2. Obtain pairing credentials
47
-
48
- Same loose-coupling model as every Ascenda tool — pair once, reuse the credentials:
42
+ This package shows no QR code; it reuses a pairing made elsewhere. Pair in the
43
+ [VS Code/Cursor extension](../ascenda-vscode-extension-telemetry/)
44
+ (**Ascenda: Connect App**), run **Ascenda: Show Status**, and export the id:
49
45
 
50
46
  ```bash
51
- # Dev only, without a phone:
52
- cd ../ascenda-pairing-sim
53
- node dist/cli.js e2e --tool-type cli_agent --name "Codex CLI"
47
+ export ASCENDA_TOOL_INSTALLATION_ID="cli_agent:<uuid>"
54
48
  ```
55
49
 
56
- Export the printed values (tokens also land in `~/.ascenda/tokens/`):
50
+ Add it to your shell profile. The write token is read from
51
+ `~/.ascenda/tokens/`, written at pairing time. **Without this variable every
52
+ hook invocation exits with `Missing ASCENDA_TOOL_INSTALLATION_ID`.**
53
+
54
+ On a Dev backend with no phone:
57
55
 
58
56
  ```bash
59
- export ASCENDA_API_BASE_URL="https://app-asc-dev-api-aue.azurewebsites.net" # or http://localhost:5002 / https://api.ascenda.one
60
- export ASCENDA_TOOL_INSTALLATION_ID="cli_agent:<uuid>"
61
- export ASCENDA_EVENT_WRITE_TOKEN="<eventWriteToken>"
57
+ cd ../ascenda-pairing-sim && npm run build
58
+ node dist/cli.js e2e --tool-type cli_agent --name "Codex CLI"
62
59
  ```
63
60
 
61
+ `ASCENDA_API_BASE_URL` defaults to `https://api.ascenda.one`; set it to
62
+ `http://localhost:5002` or the Azure Dev host for development.
63
+
64
64
  ### 3. Register hooks in Codex
65
65
 
66
- Merge [`examples/hooks.json`](./examples/hooks.json) into `~/.codex/hooks.json` (machine-wide) or `<repo>/.codex/hooks.json` (per project). Inline `config.toml` form works too:
66
+ Merge [`examples/hooks.json`](./examples/hooks.json) into `~/.codex/hooks.json`
67
+ (machine-wide) or `<repo>/.codex/hooks.json` (per project). Inline `config.toml`
68
+ form works too:
67
69
 
68
70
  ```toml
69
71
  [[hooks.UserPromptSubmit]]
70
72
  [[hooks.UserPromptSubmit.hooks]]
71
73
  type = "command"
72
- command = "ascenda-codex-hook UserPromptSubmit"
74
+ command = "npx -y @ascenda-one/codex-hooks UserPromptSubmit"
73
75
  timeout = 10
74
76
  ```
75
77
 
76
- If `ascenda-codex-hook` is not on Codex's PATH, use the absolute path to the binary.
77
-
78
78
  ### 4. Verify
79
79
 
80
+ Run a Codex session and confirm events arrive on the backend — or simply that
81
+ the hook exits `0`, which it always does (see the safety contract above).
82
+
83
+ ## Build from source
84
+
85
+ Not needed to use this — npm ships it prebuilt. It is here so you can verify
86
+ what runs.
87
+
80
88
  ```bash
81
- npm run test # unit tests for the mapping
82
- npm run test:sample # pipes a sample PostToolUse payload through the CLI
89
+ # from the repo root (workspace install + shared packages first)
90
+ npm install
91
+ npm run build:shared
92
+
93
+ cd ascenda-codex-hooks
94
+ npm run build
95
+ npm link # exposes `ascenda-codex-hook`
96
+ which ascenda-codex-hook
97
+
98
+ npm run test # unit tests for the mapping
99
+ npm run test:sample # pipes a sample PostToolUse payload through the CLI
83
100
  ```
84
101
 
85
- Then run a Codex session and confirm events arrive on the backend.
102
+ A local build exposes the binary as `ascenda-codex-hook` — substitute it for
103
+ `npx -y @ascenda-one/codex-hooks` in the hook config above. If it is not on
104
+ Codex's PATH, use the absolute path to the binary.
86
105
 
87
106
  ## Supported Codex hook events
88
107
 
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "hooks": {
3
- "SessionStart": [{ "hooks": [{ "type": "command", "command": "ascenda-codex-hook SessionStart", "timeout": 10 }] }],
4
- "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "ascenda-codex-hook UserPromptSubmit", "timeout": 10 }] }],
5
- "PreToolUse": [{ "hooks": [{ "type": "command", "command": "ascenda-codex-hook PreToolUse", "timeout": 10 }] }],
6
- "PostToolUse": [{ "hooks": [{ "type": "command", "command": "ascenda-codex-hook PostToolUse", "timeout": 10 }] }],
7
- "PreCompact": [{ "hooks": [{ "type": "command", "command": "ascenda-codex-hook PreCompact", "timeout": 10 }] }],
8
- "PostCompact": [{ "hooks": [{ "type": "command", "command": "ascenda-codex-hook PostCompact", "timeout": 10 }] }],
9
- "Stop": [{ "hooks": [{ "type": "command", "command": "ascenda-codex-hook Stop", "timeout": 10 }] }]
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
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "publishConfig": { "access": "public" },
3
3
  "name": "@ascenda-one/codex-hooks",
4
- "version": "0.1.3",
4
+ "version": "0.1.4",
5
5
  "description": "OpenAI Codex hooks adapter for Ascenda AI workload telemetry",
6
6
  "repository": {
7
7
  "type": "git",