@ascenda-one/claude-code-hooks 0.1.8 → 0.1.9

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
@@ -101,6 +101,8 @@ Optional environment:
101
101
  | `ASCENDA_EVENT_WRITE_TOKEN_FILE` | Override token file path (default `~/.ascenda/tokens/<toolInstallationId>`) |
102
102
  | `ASCENDA_SESSION_ID` | Stable session id across hooks |
103
103
  | `ASCENDA_WORKSPACE_HASH` | Opaque workspace hash if you set one |
104
+ | `ASCENDA_STATE_FILE` | Override the send journal path (default `~/.ascenda/state/<toolInstallationId>.json`) |
105
+ | `ASCENDA_DISABLE_FAILURE_NOTICE` | `true` silences the one-time in-session notice about a collector that has stopped delivering |
104
106
 
105
107
  On first run the CLI seeds `~/.ascenda/tokens/<toolInstallationId>` so
106
108
  **tool-scoped renew** can persist rotated tokens without you editing anything.
@@ -130,11 +132,52 @@ for machine-wide coverage:
130
132
 
131
133
  ### Verify
132
134
 
133
- Start Claude Code in a project with hooks configured, submit a prompt or run a
134
- tool, and confirm events reach the backend (or simply that the hook exits `0`).
135
+ ```bash
136
+ npx -y @ascenda-one/claude-code-hooks doctor
137
+ ```
138
+
139
+ `doctor` prints the installation id, the token's presence and age, the last
140
+ recorded send outcome, and the result of a live round trip against the real
141
+ ingest endpoint. It is the first thing to run when the Ascenda app shows a
142
+ connected tool that is not producing data.
143
+
144
+ A telemetry failure never blocks your turn: **every hook invocation exits `0`**,
145
+ including one that failed to send. Do not read the exit code — or stderr, which
146
+ Claude Code discards for a hook that exits `0` — as evidence of anything. Read
147
+ the journal instead.
148
+
149
+ ### When the collector stops sending
150
+
151
+ Every send attempt — success included — is recorded to
152
+ `~/.ascenda/state/<toolInstallationId>.json`:
153
+
154
+ ```json
155
+ {
156
+ "lastAttemptAt": "2026-08-17T08:05:17.436Z",
157
+ "lastSuccessAt": "2026-08-17T08:05:04.782Z",
158
+ "lastOutcome": "auth_failed",
159
+ "consecutiveFailures": 1,
160
+ "httpStatus": 401,
161
+ "errorCode": "invalid_token",
162
+ "failingSince": "2026-08-17T08:05:17.436Z"
163
+ }
164
+ ```
135
165
 
136
- Exit codes: `3` on auth failure (re-pair), `2` on missing consent (renew in the
137
- Ascenda app). A telemetry failure never blocks your turn.
166
+ Successes are recorded deliberately. If only failures were written, an absent
167
+ journal would mean both "healthy" and "never ran" — and telling those apart is
168
+ the entire problem. A `lastAttemptAt` that is minutes old with
169
+ `"lastOutcome": "accepted"` is positive evidence of health; one that is hours
170
+ stale means the collector is not running at all, which is a different fault with
171
+ a different fix.
172
+
173
+ When an installation transitions into a failing state, the next `SessionStart`
174
+ or `PostToolUse` adds **one** line of context to the session naming the cause
175
+ and offering `doctor` and `pair`. It appears once per outage, not once per tool
176
+ call, and never repeats until the collector has recovered and failed again.
177
+
178
+ `lastSeenAt` in the Ascenda app cannot substitute for any of this: it cannot
179
+ distinguish a dead token from a night's sleep, because both are "no events".
180
+ Only the collector knows it tried and was refused.
138
181
 
139
182
  ## Build from source
140
183
 
@@ -9,10 +9,15 @@ export class AscendaClient {
9
9
  source: "claude_code",
10
10
  eventWriteToken: config.eventWriteToken,
11
11
  tokenFilePath: config.tokenFilePath,
12
+ stateFilePath: config.stateFilePath,
12
13
  sessionId: config.sessionId,
13
14
  workspaceHash: config.workspaceHash
14
15
  });
15
16
  }
17
+ /** The journal entry written by the most recent {@link send}. */
18
+ get state() {
19
+ return this.sender.state;
20
+ }
16
21
  async send(mapped) {
17
22
  return this.sender.send(mapped);
18
23
  }
@@ -1 +1 @@
1
- {"version":3,"file":"ascendaClient.js","sourceRoot":"","sources":["../src/ascendaClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAI3D,OAAO,EAAE,eAAe,IAAI,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE9E,MAAM,OAAO,aAAa;IACP,MAAM,CAAqB;IAE5C,YAAY,MAAyB;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,kBAAkB,CAAC;YACnC,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;YAC7C,MAAM,EAAE,aAAa;YACrB,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,aAAa,EAAE,MAAM,CAAC,aAAa;SACpC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAA0B;QACnC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,eAAe;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;IACvC,CAAC;CACF"}
1
+ {"version":3,"file":"ascendaClient.js","sourceRoot":"","sources":["../src/ascendaClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAI3D,OAAO,EAAE,eAAe,IAAI,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAE9E,MAAM,OAAO,aAAa;IACP,MAAM,CAAqB;IAE5C,YAAY,MAAyB;QACnC,IAAI,CAAC,MAAM,GAAG,IAAI,kBAAkB,CAAC;YACnC,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;YAC7C,MAAM,EAAE,aAAa;YACrB,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,aAAa,EAAE,MAAM,CAAC,aAAa;SACpC,CAAC,CAAC;IACL,CAAC;IAED,iEAAiE;IACjE,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,MAA0B;QACnC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,eAAe;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;IACvC,CAAC;CACF"}