@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 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
- ## 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
42
+ ```bash
43
+ npx -y @ascenda-one/claude-code-hooks pair --tool-type cli_agent
44
+ ```
47
45
 
48
- Same loose-coupling model as every Ascenda tool — pair once, reuse the credentials:
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
- # Dev only, without a phone:
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
- Export the printed values (tokens also land in `~/.ascenda/tokens/`):
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
- 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>"
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` (machine-wide) or `<repo>/.codex/hooks.json` (per project). Inline `config.toml` form works too:
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-hook UserPromptSubmit"
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
- npm run test # unit tests for the mapping
82
- npm run test:sample # pipes a sample PostToolUse payload through the CLI
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
- Then run a Codex session and confirm events arrive on the backend.
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
 
@@ -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.5",
5
5
  "description": "OpenAI Codex hooks adapter for Ascenda AI workload telemetry",
6
6
  "repository": {
7
7
  "type": "git",