@ascenda-one/claude-code-hooks 0.1.15 → 0.1.16

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
@@ -126,11 +126,14 @@ Code. The token itself is never copied around — every CLI tool reads it from
126
126
  the file `pair` wrote. (The editor extension's pairing cannot be reused here:
127
127
  its token lives in the editor's private secret storage.)
128
128
 
129
- > **On this route the variable is required.** Without it — and without the
130
- > `~/.ascenda/credentials.json` that `setup` writes — every hook invocation
131
- > exits saying so. The adapter refuses to guess rather than silently mint a
132
- > second, unpaired identity that would fragment your telemetry across two
133
- > installations.
129
+ > **When the variable is absent** — and it is absent for any app launched from
130
+ > the Dock, Finder or Spotlight, which never see a shell profile — the hooks
131
+ > fall back to the `~/.ascenda/credentials.json` that `setup` writes, and then
132
+ > to the token store: when `~/.ascenda/tokens/` holds exactly one `claude_code`
133
+ > token, its filename is the id. With none, or several, every hook invocation
134
+ > records a `skipped_no_installation_id` attempt in the journal and exits
135
+ > saying so. The adapter refuses to guess rather than silently mint a second,
136
+ > unpaired identity that would fragment your telemetry across two installations.
134
137
 
135
138
  On a Dev backend with no phone, [pairing-sim](../ascenda-pairing-sim/) stands in
136
139
  for the app:
@@ -151,6 +154,8 @@ Optional environment:
151
154
  | `ASCENDA_WORKSPACE_HASH` | Override only. By default the hook derives this from the payload's own `cwd`: a machine-salted hash of the checkout folder's basename (never the path itself) |
152
155
  | `ASCENDA_PROJECT_HASH` | Override only. Defaults to the salted hash of the canonical repository's basename — a git worktree folds into the repo it was created from |
153
156
  | `ASCENDA_STATE_FILE` | Override the send journal path (default `~/.ascenda/state/<toolInstallationId>.json`) |
157
+ | `ASCENDA_OUTBOX_FILE` | Override the outbox path (default `~/.ascenda/state/<toolInstallationId>.outbox.jsonl`) |
158
+ | `ASCENDA_OUTBOX_DRAIN` | `true` lets the next hook re-send queued events. **Off by default** until the ingest endpoint is confirmed to dedupe live events on `idempotencyKey`; see "When the collector cannot reach Ascenda" |
154
159
  | `ASCENDA_DISABLE_FAILURE_NOTICE` | `true` silences the one-time in-session notice about a collector that has stopped delivering |
155
160
 
156
161
  On first run the CLI seeds `~/.ascenda/tokens/<toolInstallationId>` so
@@ -185,9 +190,10 @@ for machine-wide coverage:
185
190
  npx -y @ascenda-one/claude-code-hooks doctor
186
191
  ```
187
192
 
188
- `doctor` prints the installation id, the token's presence and age, the last
189
- recorded send outcome, and the result of a live round trip against the real
190
- ingest endpoint. It is the first thing to run when the Ascenda app shows a
193
+ `doctor` prints the installation id and where it came from (environment,
194
+ credentials file, or the token store on disk), the token's presence and age,
195
+ the last recorded send outcome, any sends skipped for want of an installation
196
+ id, and the result of a live round trip against the real ingest endpoint. It is the first thing to run when the Ascenda app shows a
191
197
  connected tool that is not producing data.
192
198
 
193
199
  A telemetry failure never blocks your turn: **every hook invocation exits `0`**,
@@ -228,6 +234,64 @@ call, and never repeats until the collector has recovered and failed again.
228
234
  distinguish a dead token from a night's sleep, because both are "no events".
229
235
  Only the collector knows it tried and was refused.
230
236
 
237
+ ### When the collector cannot reach Ascenda
238
+
239
+ A send that fails without a verdict — the endpoint unreachable, a timeout, a
240
+ `429` or `5xx` — is retried once after 250 ms and then **kept**, not dropped.
241
+ The payload is appended to an outbox next to the journal:
242
+
243
+ ```
244
+ ~/.ascenda/state/<toolInstallationId>.outbox.jsonl
245
+ ```
246
+
247
+ one JSON line per event, exactly as it would have gone on the wire, plus the
248
+ time it was queued. Anything longer than a blip — a laptop waking from sleep,
249
+ a VPN reconnecting, a captive portal, a slow network on a train — used to lose
250
+ every event for its duration with no copy anywhere. Now it costs nothing but
251
+ delay. A rejection *with* a verdict (`400`, `401`, `403`) is not queued:
252
+ replaying it cannot change the answer.
253
+
254
+ The next hook invocation drains the outbox, oldest first, one batch of up to
255
+ 100 per invocation and never with a backoff loop — the hook is on your
256
+ critical path, and the invocation after that is usually seconds away. An
257
+ entry is deleted when the server answers `accepted` **or** `duplicate`; a
258
+ duplicate means the server already had it, which is the point of the
259
+ `idempotencyKey` every event carries. If the door refuses again, the pass stops
260
+ with everything still on disk, and the live event joins the queue instead of
261
+ knocking on a door that just said no.
262
+
263
+ > **Sending from the outbox is off by default.** Set `ASCENDA_OUTBOX_DRAIN=true`
264
+ > to enable it. A drain against an ingest endpoint that does not yet dedupe
265
+ > live events on `idempotencyKey` would land every queued event a second
266
+ > time — the exact double-count that blocked this queue until the key existed.
267
+ > Until the deployed backend is confirmed to answer a replay with `duplicate`,
268
+ > events are queued, bounded and reported, but not re-sent.
269
+
270
+ The outbox is bounded: 10,000 entries and 7 days. When a bound evicts, the
271
+ discard is recorded in the journal as `"lastOutcome": "outbox_discarded"` with
272
+ a cumulative `outboxDiscarded` block — how many, when, why, and how far back
273
+ the loss reaches. It survives every later success, because a gap that has
274
+ since closed is still a gap in the data.
275
+
276
+ `doctor` reads all of this:
277
+
278
+ ```
279
+ Outbox ~/.ascenda/state/claude_code_….outbox.jsonl
280
+ Outbox depth 37 waiting — oldest queued 2026-09-03T01:12:08.114Z (3h 41m ago)
281
+ Outbox drain off (queued events are kept and bounded, not sent) — ASCENDA_OUTBOX_DRAIN
282
+ Outbox discarded 12 total; last 12 at 2026-09-02T… (12 age, reaching back to 2026-08-25T…)
283
+ ```
284
+
285
+ A non-empty outbox is the honest health answer. `consecutiveFailures` resets
286
+ on the first success after an outage; the outbox says events from that outage
287
+ are still on this machine.
288
+
289
+ Hooks overlap — Claude Code fires `PreToolUse` and `PostToolUse` from separate
290
+ processes — so appends use `O_APPEND` (whole lines, never fragments) and a
291
+ drain takes the file by renaming it out from under concurrent appenders. An
292
+ entry is never deleted before the server has confirmed it; a drain that dies
293
+ mid-way leaves a claim file that the next drain sweeps back in.
294
+
231
295
  ## Build from source
232
296
 
233
297
  Not needed to use this — both routes above ship prebuilt. It is here because
@@ -288,6 +352,17 @@ Notification -> (skipped — no catalog event)
288
352
 
289
353
  Metadata-only telemetry. Does not send raw prompts, responses, code, file names, repository names, branch names, or terminal output.
290
354
 
355
+ Repository and branch identity travel only as machine-salted digests, derived
356
+ in the hook process and never as text: `workspaceHash` and `projectHash` from
357
+ the checkout's and repository's folder names, and `metadata.branchHash` from
358
+ the branch the checkout is on. The salt is random per machine, stored at
359
+ `~/.ascenda/salt`, and never transmitted — without it, a digest of a name from
360
+ a short list is recoverable by guessing. A branch name is low-entropy in
361
+ exactly that way, so the branch digest is not a security boundary; it is what
362
+ lets work be grouped by branch on the other side without the name itself
363
+ leaving the machine. On a detached HEAD, outside a checkout, or with no
364
+ readable salt the key is omitted entirely rather than sent blank.
365
+
291
366
  Correction detection uses local pattern matching on prompt text in the hook process only — classified metadata (`reason: repeated_reprompting`) is sent; raw prompt text is not.
292
367
 
293
368
  ## Roadmap
@@ -10,6 +10,7 @@ export class AscendaClient {
10
10
  eventWriteToken: config.eventWriteToken,
11
11
  tokenFilePath: config.tokenFilePath,
12
12
  stateFilePath: config.stateFilePath,
13
+ outboxFilePath: config.outboxFilePath,
13
14
  sessionId: config.sessionId,
14
15
  workspaceHash: config.workspaceHash,
15
16
  projectHash: config.projectHash
@@ -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,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,WAAW,EAAE,MAAM,CAAC,WAAW;SAChC,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"}
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,cAAc,EAAE,MAAM,CAAC,cAAc;YACrC,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,aAAa,EAAE,MAAM,CAAC,aAAa;YACnC,WAAW,EAAE,MAAM,CAAC,WAAW;SAChC,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"}