@thehammer/danx-session-telemetry 0.1.17 → 0.1.19

package/dist/activity-observer.d.ts

@@ -11,36 +11,43 @@
  *
  * Claude Code's `SubagentStart` / `SubagentStop` hooks carry strictly more (an
  * `agent_type` before the sub-agent has written anything, and — the part this
- * module cannot supply — a FINISH). Those hooks ship from the danxbot plugin in
- * the claude-plugins repo, and DX-3284 builds them, next. They were not built in
- * DX-2954 itself, but not because a plugin change cannot ship from a danxbot
- * card: DX-2954's own `transcript_path` change shipped as claude-plugins
- * `c0c134d`. Keying the running set solely on them before they exist would ship
- * a set that is permanently empty (`subagent_count` 0 on every dispatch, a
- * REGRESSION against the transcript-derived counter this replaced).
+ * module cannot supply — a FINISH). They ship from the danxbot plugin in the
+ * claude-plugins repo (DX-3284, `danxbot/scripts/activity-report.mjs`), run the
+ * `activity` subcommand of `@thehammer/danx-dashboard-mcp`, and reach the server
+ * through `POST /api/plan-sessions/me/activity` — which writes the SAME
+ * `dispatch_activities` rows through the same one server writer.
  *
- * So the transcript is the producer, and the hooks are an ENRICHMENT layered on
- * the same rows:
+ * The transcript stays the producer because it needs no hook to be installed: a
+ * session with no plugin, and every WORKER dispatch, still gets a start row for
+ * each sub-agent from here. The hooks are an ENRICHMENT layered on the same rows:
  *
  * | Signal | Sub-agent start | Sub-agent finish | Background script |
  * |---|---|---|---|
  * | Transcript (here) | file discovered | dispatch terminal (`finishOpenActivities`) | not visible |
- * | Hooks (DX-3284) | `SubagentStart` | `SubagentStop` | `PostToolUse` start; end at dispatch terminal (no documented completion event) |
+ * | Hooks (DX-3284, operator sessions) | `SubagentStart` | `SubagentStop` | `PostToolUse` start; end at dispatch terminal (no documented completion event) |
  *
- * **Until DX-3284 lands, "running" over-counts.** With no finish signal, every
- * sub-agent this dispatch ever started stays in the running set until the
- * dispatch itself ends, and the silent-too-long warning fires
- * `RUNNING_ACTIVITY_SILENT_AFTER_MS` after a sub-agent that has in fact
- * finished. `SubagentStop` is what closes that gap.
+ * **Where "running" closes.** An operator session's sub-agent closes at its
+ * `SubagentStop` hook. A WORKER dispatch has no hook reporting yet
+ * (`/me/activity` refuses a worker's session id as `session_is_worker`), so its
+ * sub-agents stay in the running set until the dispatch itself ends, and the
+ * silent-too-long warning fires `RUNNING_ACTIVITY_SILENT_AFTER_MS` after a
+ * sub-agent that has in fact finished. A worker-side `SubagentStop` report is the
+ * fix, and is not built.
  *
  * ## Why the two producers cannot double-count
  *
  * Every row is an upsert keyed `(dispatch_id, kind, activity_id)`, and BOTH
  * producers derive `activity_id` from the same thing: the sub-agent's transcript
- * file basename. The watcher has it directly; a hook has it as the basename of
- * its `transcript_path`. That is also the key the ledger credits the sub-agent's
- * tokens under, which is how per-sub-agent tokens join to the running set
- * without this table carrying a token column.
+ * file basename, `agent-<agent_id>`. The watcher has it directly; a hook has the
+ * `agent_id` and builds the same basename from it (`subagentActivityId` in
+ * danx-dashboard-mcp's `activity.ts`, which also strips an `agent-` prefix the hooks docs show
+ * on some `agent_id`s so both forms reach this key). A hook's `transcript_path` is NOT the
+ * sub-agent's file — on these events it is the MAIN session's transcript, and only
+ * `SubagentStop` also carries the sub-agent's own as `agent_transcript_path`,
+ * which the subcommand uses to refuse a key that disagrees. That basename is also
+ * the key the ledger credits the sub-agent's tokens under, which is how
+ * per-sub-agent tokens join to the running set without this table carrying a
+ * token column.
  *
  * ## What this module deliberately does NOT do
  *
@@ -49,7 +56,7 @@
  * indistinguishable from a slow one. Guessing a finish from an idle gap would
  * mark a long-thinking sub-agent as complete. So open rows are closed exactly
  * once, at the dispatch's own terminal transition (`finishOpenActivities`),
- * unless DX-3284's `SubagentStop` hook closes a row first.
+ * unless the `SubagentStop` hook (DX-3284) closes a row first.
  */
 import type { ActivityChange } from "./stats-wire.js";
 import type { EntryMeta, SourceDiscoveredInfo } from "./session-log-watcher.js";

package/dist/session-log-watcher.d.ts

@@ -111,9 +111,9 @@ export interface SessionLogWatcherOptions {
      * This is the transcript-side producer of the dispatch's running set. It
      * reports the sub-agent's ledger source key, which is the same value its
      * `dispatch_activities.activity_id` and its per-source token total join on —
-     * so a hook-side producer reporting the same sub-agent by its
-     * `transcript_path` resolves to this same id and upserts the SAME row rather
-     * than a duplicate.
+     * so a hook-side producer reporting the same sub-agent by its `agent_id`
+     * (`agent-` + the id, DX-3284) resolves to this same id and upserts the SAME
+     * row rather than a duplicate.
      *
      * Fired once per source, from the discovery pass, for sub-agent files only —
      * never for the main transcript, which is the dispatch itself, not an activity

package/dist/stats-wire.d.ts

@@ -61,12 +61,14 @@ export type SourceCursorReports = Record<string, SourceCursorReport>;
  * DX-2954 — the running set's two kinds. `agent` is a sub-agent, produced from
  * the TRANSCRIPT: one row per sub-agent transcript file the session-log watcher
  * discovers (`packages/danx-session-telemetry/src/activity-observer.ts`; orchestrator decision, DX-2954
- * comment 8004). `bash` is a background script; nothing produces it yet — the
- * hook-side producer (`PostToolUse` on a backgrounded Bash call) is DX-3284's.
- * No hook event observes a background shell FINISHING (verified against the
- * hooks reference — see the Step 0 note on DX-2954), so an open row of either
- * kind is closed by the dispatch's own terminal write, never by inferring an
- * end from transcript lines.
+ * comment 8004), and — for an operator session — from the plugin's
+ * `SubagentStart` / `SubagentStop` hooks, which add the finish. `bash` is a
+ * background script, produced only by the plugin's `PostToolUse` hook on a
+ * backgrounded Bash call (DX-3284; the transcript cannot see it). No hook event
+ * observes a background shell FINISHING (verified against the hooks reference —
+ * see the Step 0 note on DX-2954), so an open `bash` row is closed by the
+ * dispatch's own terminal write, never by inferring an end from transcript
+ * lines.
  */
 export declare const ACTIVITY_KINDS: readonly ["agent", "bash"];
 export type ActivityKind = (typeof ACTIVITY_KINDS)[number];
@@ -76,12 +78,13 @@ export type ActivityKind = (typeof ACTIVITY_KINDS)[number];
  * fires twice, or a batch resent after a failed flush, must not duplicate it.
  *
  * `activityId` for a sub-agent is its transcript file's basename
- * (`agent-<hash>`) — the SAME value the ledger credits its tokens under as
+ * (`agent-<agent_id>`) — the SAME value the ledger credits its tokens under as
  * `source`, which is how per-sub-agent tokens join to the running set without
- * this table carrying a token column. Any future producer (DX-3284's hooks)
- * must derive it the same way — the basename of the hook's `transcript_path`,
- * never the hook's `agent_id` — or it upserts a duplicate row. For a
- * background script it is the Bash call's `tool_use_id`.
+ * this table carrying a token column. A hook producer builds it from the hook's
+ * `agent_id` as `agent-${agent_id}` (never the bare `agent_id`, and never from
+ * `transcript_path`, which on these events is the MAIN session's transcript) or
+ * it upserts a duplicate row. For a background script it is the Bash call's
+ * `tool_use_id`.
  */
 export interface ActivityChange {
     kind: ActivityKind;

package/dist/stats-wire.js

@@ -9,12 +9,14 @@ export const STATS_BATCH_CAP = 500;
  * DX-2954 — the running set's two kinds. `agent` is a sub-agent, produced from
  * the TRANSCRIPT: one row per sub-agent transcript file the session-log watcher
  * discovers (`packages/danx-session-telemetry/src/activity-observer.ts`; orchestrator decision, DX-2954
- * comment 8004). `bash` is a background script; nothing produces it yet — the
- * hook-side producer (`PostToolUse` on a backgrounded Bash call) is DX-3284's.
- * No hook event observes a background shell FINISHING (verified against the
- * hooks reference — see the Step 0 note on DX-2954), so an open row of either
- * kind is closed by the dispatch's own terminal write, never by inferring an
- * end from transcript lines.
+ * comment 8004), and — for an operator session — from the plugin's
+ * `SubagentStart` / `SubagentStop` hooks, which add the finish. `bash` is a
+ * background script, produced only by the plugin's `PostToolUse` hook on a
+ * backgrounded Bash call (DX-3284; the transcript cannot see it). No hook event
+ * observes a background shell FINISHING (verified against the hooks reference —
+ * see the Step 0 note on DX-2954), so an open `bash` row is closed by the
+ * dispatch's own terminal write, never by inferring an end from transcript
+ * lines.
  */
 export const ACTIVITY_KINDS = ["agent", "bash"];
 export function chunkEntries(entries, cap = STATS_BATCH_CAP) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-session-telemetry",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Shared Claude Code transcript collector (DX-2962) — incremental JSONL tailing for the danxbot worker and the danx-dashboard-mcp desktop bridge, so both run identical collector code.",
   "license": "MIT",
   "type": "module",