@thehammer/danx-dashboard-mcp 0.1.185 → 0.1.187

package/dist/activity.js

@@ -0,0 +1,243 @@
+/**
+ * `danx-dashboard-mcp activity <SubagentStart|SubagentStop|PostToolUse> <event-at>` — the
+ * ONE-SHOT client of `POST /api/plan-sessions/me/activity` (DX-3284).
+ *
+ * WHO RUNS IT. The danxbot Claude Code plugin's `SubagentStart`, `SubagentStop` and
+ * `PostToolUse` (matcher `Bash`) hooks (`danxbot/scripts/activity-report.mjs` in
+ * claude-plugins), all registered `async: true`. The plugin runs the INSTALLED package
+ * with `node` (DX-3811), never a cold `npx`, and pipes the hook's own JSON envelope on
+ * stdin. This module owns what each event MEANS for the session's running set; the plugin
+ * decides only whether to call at all (a plan-connected session, a background Bash call).
+ *
+ * THE THREE EVENTS (the Claude Code hooks reference, `code.claude.com/docs/en/hooks`):
+ *
+ * | Event          | Reports                                                          | Key                        |
+ * |----------------|------------------------------------------------------------------|----------------------------|
+ * | `SubagentStart`| an `agent` activity, running                                     | `agent-<agent_id>`         |
+ * | `SubagentStop` | the same activity, FINISHED                                      | `agent-<agent_id>`         |
+ * | `PostToolUse`  | a `bash` activity, running — only for `Bash` with                | `tool_use_id`              |
+ * |                | `tool_input.run_in_background: true`                             |                            |
+ *
+ * THE SUB-AGENT KEY. A sub-agent's transcript is `<session>/subagents/agent-<agent_id>.jsonl`,
+ * and the transcript producer (`createActivityObserver`) keys its row on that file's
+ * basename, `agent-<agent_id>`. Reporting the bare `agent_id` would upsert a SECOND row for
+ * the same sub-agent, so the hook-side key is the same basename: the two producers converge
+ * on one row. The hooks docs disagree on whether `agent_id` already carries the `agent-`
+ * prefix, so {@link subagentActivityId} normalizes both forms to the one key.
+ *
+ * KNOWN LIMITS (DX-3284, pinned in `plan-session-activity.test.ts`):
+ *   - a sub-agent RESUMED after its SubagentStop reports a second start, but the server's
+ *     first finish wins, so the row stays closed;
+ *   - a SubagentStop with no `agent_id` (Claude Code's internal agents) is refused below, and
+ *     the plugin leaves a failure trace. One WITH an id but no recorded start is
+ *     indistinguishable from a stop that beat its (async) start, so it is recorded as an
+ *     already-finished row — it never counts as running. (`transcript_path` cannot supply it: on these events it is the MAIN session's
+ * transcript — only `SubagentStop`'s `agent_transcript_path` names the sub-agent's own, and
+ * it is used below to REFUSE a mismatch, never to guess one.)
+ *
+ * THERE IS NO "BACKGROUND SHELL FINISHED" EVENT. None of the documented hook events fires
+ * when a `run_in_background` Bash command ends (verified against the full event list on
+ * DX-2954's Step 0 note; `TaskCreated` / `TaskCompleted` are the `TaskCreate` tool, not a
+ * shell). A `bash` activity therefore gets a start here and no finish: its end comes from
+ * the dispatch's own terminal write (`finishOpenActivities`), never from inferring one out
+ * of transcript lines. Until then it reads as running and silent, which is the honest
+ * signal. Do not "fix" this with a proxy event.
+ *
+ * THE EVENT TIME is the hook's own, captured by the plugin when the hook FIRED and passed
+ * as `<event-at>` — never this process's clock, which starts only after the (possibly
+ * cold) install step. The server's upsert is monotone in every field, so hooks that finish
+ * out of order, or one that fires twice, still reach the same row.
+ *
+ * THE CONTRACT (identical to `background-work`, so the plugin treats both alike):
+ *   - print EXACTLY ONE JSON line on stdout and ALWAYS exit 0 — a hook has no business
+ *     spamming the session with a stack trace;
+ *   - `{"ok":true,"runningActivities":<n>}` on success;
+ *   - `{"ok":false,"reason":"<why>"}` otherwise. `no_connection_record` and
+ *     `session_not_connected` are the ordinary "this session is not on a plan" answers;
+ *   - human-readable diagnostics go to stderr only.
+ *
+ * THE CREDENTIAL — the SAME resolver `bridge` uses (`resolveSessionOptions`): the URL,
+ * credential source and credential come from the connection record this session's own MCP
+ * server wrote on `plan_connect`, never from this process's ambient env (DX-2862).
+ */
+import { win32 } from "node:path";
+import { readFileSync } from "node:fs";
+import { parseEventAtArg } from "./background-work.js";
+import { resolveSessionOptions, sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.js";
+export const ACTIVITY_SUBCOMMAND = "activity";
+export const ACTIVITY_PATH = "/api/plan-sessions/me/activity";
+/** How long this one-shot call may take before it counts as a timeout. */
+export const ACTIVITY_REQUEST_TIMEOUT_MS = 5_000;
+/** The hook events this subcommand accepts, exactly as Claude Code names them in `hook_event_name`. */
+export const ACTIVITY_HOOK_EVENTS = ["SubagentStart", "SubagentStop", "PostToolUse"];
+const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${ACTIVITY_SUBCOMMAND} <${ACTIVITY_HOOK_EVENTS.join("|")}> <event-at ISO-8601 UTC>  (the hook's JSON envelope on stdin)`;
+const SUBAGENT_PREFIX = "agent-";
+/**
+ * A sub-agent's transcript file basename — the key `createActivityObserver` reports it under.
+ *
+ * DX-3284: the hooks documentation shows `agent_id` BOTH ways — SubagentStart's example carries
+ * the `agent-` prefix (`agent-abc123`), SubagentStop's does not (`def456`, against the file
+ * `agent-def456.jsonl`). The key is `agent-` + the id with ONE leading `agent-` stripped, so both
+ * forms converge on the transcript producer's row; keying on the raw id would leave a phantom
+ * `agent-agent-<id>` row that no stop ever closes.
+ */
+export function subagentActivityId(agentId) {
+    const bare = agentId.startsWith(SUBAGENT_PREFIX) ? agentId.slice(SUBAGENT_PREFIX.length) : agentId;
+    return `${SUBAGENT_PREFIX}${bare}`;
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value !== "";
+}
+/**
+ * One hook envelope -> the ONE `ActivityChange` it stands for, or the reason it stands for
+ * none. Pure: `eventAtMs` is the hook's own event time.
+ */
+export function activityChangeFromHook(event, envelope, eventAtMs) {
+    if (typeof envelope !== "object" || envelope === null || Array.isArray(envelope)) {
+        return { ok: false, reason: "bad_envelope" };
+    }
+    const e = envelope;
+    // The envelope names the event it was fired for; a mismatch is a wiring bug, not data.
+    if (e.hook_event_name !== undefined && e.hook_event_name !== event) {
+        return { ok: false, reason: "event_mismatch" };
+    }
+    if (event === "PostToolUse") {
+        const input = e.tool_input;
+        if (e.tool_name !== "Bash" || typeof input !== "object" || input === null) {
+            return { ok: false, reason: "not_background_bash" };
+        }
+        const toolInput = input;
+        if (toolInput.run_in_background !== true)
+            return { ok: false, reason: "not_background_bash" };
+        if (!nonEmptyString(e.tool_use_id))
+            return { ok: false, reason: "no_tool_use_id" };
+        return {
+            ok: true,
+            change: {
+                kind: "bash",
+                activityId: e.tool_use_id,
+                agentType: null,
+                description: nonEmptyString(toolInput.description) ? toolInput.description : null,
+                startedAt: eventAtMs,
+                // No hook ever refreshes or ends a background shell (see the module docblock), so
+                // its liveness is its start and `finishedAt` stays null until the dispatch ends.
+                lastActivityAt: eventAtMs,
+                finishedAt: null,
+            },
+        };
+    }
+    // A SubagentStop from one of Claude Code's own internal agents carries no `agent_id`: it names
+    // no activity, so it is refused here (the plugin leaves a failure trace) and nothing is
+    // written — a stop must never invent a row.
+    if (!nonEmptyString(e.agent_id) || e.agent_id === SUBAGENT_PREFIX)
+        return { ok: false, reason: "no_agent_id" };
+    const activityId = subagentActivityId(e.agent_id);
+    if (event === "SubagentStop" && e.agent_transcript_path !== undefined) {
+        // The one place the hook names the sub-agent's own file: if it disagrees with the
+        // key derived from `agent_id`, this process would upsert a duplicate row. Refuse.
+        const file = typeof e.agent_transcript_path === "string" ? win32.basename(e.agent_transcript_path, ".jsonl") : null;
+        if (file !== activityId)
+            return { ok: false, reason: "agent_id_mismatch" };
+    }
+    return {
+        ok: true,
+        change: {
+            kind: "agent",
+            activityId,
+            agentType: nonEmptyString(e.agent_type) ? e.agent_type : null,
+            description: null,
+            startedAt: eventAtMs,
+            lastActivityAt: eventAtMs,
+            finishedAt: event === "SubagentStop" ? eventAtMs : null,
+        },
+    };
+}
+/**
+ * One authenticated POST, with a hard timeout, classified into the output shape this
+ * subcommand always prints — never a throw. Status is checked before any body is parsed
+ * (an HTML 5xx page must read as `http_error`, not `bad_response`); only a 409 needs its
+ * body, to tell "no plan" from "a worker's session".
+ */
+export async function postActivity(options, change, deps) {
+    const sent = await sendSessionRequest(options, ACTIVITY_PATH, { method: "POST", body: JSON.stringify({ activities: [change] }) }, deps);
+    if ("reason" in sent)
+        return sent;
+    const { status, text } = sent;
+    if (status === 401 || status === 403)
+        return { ok: false, reason: "unauthorized" };
+    if (status === 409) {
+        const parsed = tryParseJsonBody(text);
+        const error = parsed.ok ? parsed.body?.error : undefined;
+        if (error === "session_not_connected" || error === "session_is_worker")
+            return { ok: false, reason: error };
+        return { ok: false, reason: "http_error" };
+    }
+    if (status < 200 || status >= 300)
+        return { ok: false, reason: "http_error" };
+    const parsed = tryParseJsonBody(text);
+    if (!parsed.ok)
+        return { ok: false, reason: "bad_response" };
+    const body = parsed.body;
+    if (typeof body?.runningActivities !== "number")
+        return { ok: false, reason: "bad_response" };
+    return { ok: true, runningActivities: body.runningActivities };
+}
+/** The bin's `activity` subcommand, wired to the real process. Always resolves to exit code 0. */
+export async function runActivityCommand(argv, env = process.env, 
+/** Test seam: the home the session's connection record is read from. */
+resolveFrom = {}, 
+/** Test seam: the hook envelope's text (the real process reads stdin). */
+readEnvelope = () => readFileSync(0, "utf8")) {
+    const write = (output) => {
+        process.stdout.write(`${JSON.stringify(output)}\n`);
+    };
+    const usageFailure = (detail) => {
+        write({ ok: false, reason: "usage" });
+        process.stderr.write(`${detail}\n${USAGE}\n`);
+        return 0;
+    };
+    if (argv.length !== 2)
+        return usageFailure("expected exactly two arguments");
+    const event = ACTIVITY_HOOK_EVENTS.includes(argv[0]) ? argv[0] : null;
+    if (event === null)
+        return usageFailure(`unknown hook event "${argv[0]}"`);
+    const eventAt = parseEventAtArg(argv[1]);
+    if (typeof eventAt === "object")
+        return usageFailure(eventAt.error);
+    let envelope;
+    try {
+        envelope = JSON.parse(readEnvelope());
+    }
+    catch {
+        write({ ok: false, reason: "bad_envelope" });
+        process.stderr.write("the hook envelope on stdin is not JSON\n");
+        return 0;
+    }
+    const mapped = activityChangeFromHook(event, envelope, Date.parse(eventAt));
+    if (!mapped.ok) {
+        write(mapped);
+        process.stderr.write(`${event} envelope reports no activity: ${mapped.reason}\n`);
+        return 0;
+    }
+    // The connection record is this session's: an envelope for ANOTHER session must never
+    // be reported under it.
+    const envelopeSession = envelope.session_id;
+    if (envelopeSession !== undefined && envelopeSession !== env.CLAUDE_CODE_SESSION_ID) {
+        write({ ok: false, reason: "session_mismatch" });
+        process.stderr.write("the envelope's session_id is not CLAUDE_CODE_SESSION_ID\n");
+        return 0;
+    }
+    const resolved = await resolveSessionOptions(env, resolveFrom, USAGE);
+    if (!resolved.ok) {
+        // A session that never `plan_connect`-ed has no connection record: the ordinary
+        // "not on a plan" case, silent for the plugin.
+        write(resolved.output);
+        process.stderr.write(`${resolved.detail}\n`);
+        return 0;
+    }
+    write(await postActivity(resolved.options, mapped.change, {
+        fetch: (input, init) => fetch(input, init),
+        requestTimeoutMs: ACTIVITY_REQUEST_TIMEOUT_MS,
+    }));
+    return 0;
+}

package/dist/index.js

@@ -75,6 +75,7 @@
 import { isEntrypointModule } from "./entrypoint.js";
 import { BRIDGE_SUBCOMMAND, runBridgeCommand } from "./bridge.js";
 import { BACKGROUND_WORK_SUBCOMMAND, runBackgroundWorkCommand } from "./background-work.js";
+import { ACTIVITY_SUBCOMMAND, runActivityCommand } from "./activity.js";
 import { EVENT_TEXT_SUBCOMMAND, runEventTextCommand } from "./event-text.js";
 import { resolveDeclaredCredential } from "./credential.js";
 import { recordSessionConnectionAfterConnect } from "./session-connection.js";
@@ -485,6 +486,15 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
             process.exit(0);
         });
     }
+    else if (subcommand === ACTIVITY_SUBCOMMAND) {
+        // DX-3284 — the same hook-only contract as background-work: a rejection prints one
+        // failure line and exits 0, so an async hook never surfaces a stack trace.
+        runActivityCommand(rest).then((code) => process.exit(code), (err) => {
+            console.error(`[danx-dashboard-mcp] activity fatal: ${err.message}`);
+            process.stdout.write(`${JSON.stringify({ ok: false, reason: "fatal" })}\n`);
+            process.exit(0);
+        });
+    }
     else if (subcommand === EVENT_TEXT_SUBCOMMAND) {
         // DX-3421 (was DX-3366's `mantra` subcommand) — unlike background-work, a
         // rejection here is a genuine fatal (never expected: runEventTextCommand
@@ -498,7 +508,7 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
     }
     else if (subcommand !== undefined) {
         console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only ones are ` +
-            `"${BRIDGE_SUBCOMMAND}", "${BACKGROUND_WORK_SUBCOMMAND}", and "${EVENT_TEXT_SUBCOMMAND}")`);
+            `"${BRIDGE_SUBCOMMAND}", "${BACKGROUND_WORK_SUBCOMMAND}", "${ACTIVITY_SUBCOMMAND}", and "${EVENT_TEXT_SUBCOMMAND}")`);
         process.exit(2);
     }
     else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.185",
+  "version": "0.1.187",
   "description": "Stdio MCP server fronting danxbot's dashboard API for agents (operator sessions and dispatched workers alike): the generic danxbot_api/danxbot_api_list/danxbot_api_spec tools reach any route the caller's credential may call, plus dedicated agent-specific tools (plan_connect, danxbot_complete, and other per-dispatch lifecycle callbacks) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
-    "@thehammer/danx-session-telemetry": "0.1.17",
+    "@thehammer/danx-session-telemetry": "0.1.19",
     "zod": "^3.25.76"
   },
   "devDependencies": {