From c9e078b827bd068f2eb0da6bdbfc59b54a183376 Mon Sep 17 00:00:00 2001 From: Lucas Proxmox Date: Thu, 5 Nov 2026 15:25:55 +0100 Subject: [PATCH 1/3] feat(commands): record Bash command timing per project, with trends - command_runs (migration 058): one row per Bash tool.complete / tool.fail, recorded at ingestion: signature (program + up to two plain words, never the command), mode (foreground / background / moved after the timeout), time the session waited, start-to-finish duration, outcome and exit code. No developer or project column (both from sessions at read time, so retention anonymization applies); rows cascade away with their event. - New event command.background_complete (plugin 0.38.0) settles background commands with their real finish time and exit code; only the sender's own running rows change. - cleanSignature re-checks the shape and falls back to the program; private sessions store the program only. - /api/commands/summary, /trend, /projects: by command and project, team or own, never per developer. A teammate's session that is not shared counts under its program, and a project filter matches only visible sessions. - Dashboard: Commands page and a Command timing section on each project page (time waited, median/p95/max, slower or faster than the period before, the trend of one command). - scripts/command-runs-backfill.ts fills the table from stored Bash events. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 15 + CLAUDE.md | 32 +- .../backend/scripts/command-runs-backfill.ts | 107 +++++++ .../src/db/__tests__/commandQueries.test.ts | 261 +++++++++++++++++ packages/backend/src/db/commandQueries.ts | 274 ++++++++++++++++++ .../src/db/migrations/058_command_runs.sql | 42 +++ packages/backend/src/index.ts | 6 +- .../routes/__tests__/events.contract.test.ts | 35 +++ .../src/routes/__tests__/events.test.ts | 85 ++++++ packages/backend/src/routes/commands.ts | 60 ++++ packages/backend/src/routes/events.ts | 20 +- packages/backend/src/utils/eventSchemas.ts | 30 ++ packages/dashboard/src/App.tsx | 2 + .../dashboard/src/components/LiveFeed.tsx | 1 + .../dashboard/src/components/app-sidebar.tsx | 2 + .../components/commands/CommandTimings.tsx | 270 +++++++++++++++++ .../src/components/commands/CommandsView.tsx | 48 +++ .../src/components/commands/format.ts | 18 ++ .../components/projects/ProjectDrillDown.tsx | 6 + .../dashboard/src/hooks/useCommandsData.ts | 37 +++ packages/dashboard/src/index.css | 3 + packages/dashboard/src/lib/eventDisplay.ts | 10 + packages/shared/src/commands.ts | 63 ++++ packages/shared/src/events.ts | 20 +- packages/shared/src/index.ts | 1 + 25 files changed, 1444 insertions(+), 4 deletions(-) create mode 100644 packages/backend/scripts/command-runs-backfill.ts create mode 100644 packages/backend/src/db/__tests__/commandQueries.test.ts create mode 100644 packages/backend/src/db/commandQueries.ts create mode 100644 packages/backend/src/db/migrations/058_command_runs.sql create mode 100644 packages/backend/src/routes/commands.ts create mode 100644 packages/dashboard/src/components/commands/CommandTimings.tsx create mode 100644 packages/dashboard/src/components/commands/CommandsView.tsx create mode 100644 packages/dashboard/src/components/commands/format.ts create mode 100644 packages/dashboard/src/hooks/useCommandsData.ts create mode 100644 packages/shared/src/commands.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 71cdcf2..997748e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Added +- **Command timing.** Every Bash command Claude runs is now a row in + `command_runs` (migration 058): its signature (the program and up to two + plain words, such as `bun run build`; never the command itself), whether it + ran in the foreground, the background, or was moved there after its + timeout, how long the session waited on it, its start-to-finish duration, + and the outcome. Background commands are settled by the new + `command.background_complete` event from plugin 0.38.0, which reports when + each one finished and its exit code. `/api/commands/summary`, `/trend` and + `/projects` aggregate by command and project (team or own, never per + developer; a teammate's session that is not shared counts under its program + only), and the new **Commands** page and a section on each project page show + which commands the sessions wait on most and whether they are getting + slower. `scripts/command-runs-backfill.ts` fills the table from stored + events (program only, since older plugins sent nothing more). + - **Voiced audio ends cleanly.** `/api/ai/voice-audio` rewrites the speech service's WAV into a plain 44-byte-header PCM file with its real sizes (Kokoro streams its WAV with `0xFFFFFFFF` sizes and a LIST chunk, so players diff --git a/CLAUDE.md b/CLAUDE.md index f1362fd..9dfd4ea 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -93,6 +93,9 @@ WebSocket message types: `event.new`, `session.update`, `developer.update`. | `/api/ai/voice-summary` | POST | Spoken text for the plugin's voice features (`trigger`, `project`, optional `tool`/`detail`/`last_message`/`session_id`/`label`), starting with the session's label (`project, topic` from the caller's own session title, else branch; a sent `label` is reused as is, so the name never changes) and returning it as `label`: one sentence for the announcer, or with `trigger: "reply"` a summary of Claude's reply for `/devscope:voice auto`, as detailed as the optional `length` asks (`short` one sentence ≤ 20 words, `normal` 2-3 sentences ≤ 50 words, `long` 4-6 sentences ≤ 110 words; `REPLY_LENGTHS`); stateless, only token usage is recorded as `voice_summary`. The plugin never calls it for `private` sessions | | `/api/ai/voice-audio` | POST | That text (or one piece of a `/devscope:voice explain` explanation) as WAV (`text`, optional `model` = a `TTS_SERVICES` name, Kokoro `voice`, `speed`, `volume`, `pad_ms` trailing silence, default 400), rewritten as a canonical PCM WAV with real sizes (`services/wav.ts`), voiced by the homelab speech services; 503 when none is configured or all fail, so the plugin falls back to a local voice. Own 20/min bucket, no Gemini budget | | `/api/sessions/usage/backfill` | POST | Exact token usage per transcript and model from `/devscope:backfill-usage` (`{items: [{transcriptId, sessionId?, byModel}]}`, max 500); only the caller's own sessions are updated, the rest are counted as `skipped` | +| `/api/commands/summary?days=&scope=team\|me&group=signature\|program&project=&limit=` | GET | Bash commands by time the sessions waited on them, with p50/p95/max duration, failures, background/moved counts and the period before for comparison (see Command timing) | +| `/api/commands/trend?days=&scope=&group=&project=&command=&bucket=day\|week` | GET | One command's (or all commands') runs, p50/p95 and time waited per day or week | +| `/api/commands/projects?days=` | GET | Projects with command runs the caller may see, for the project filter | | `/api/health` | GET | Health check + WS client count | | `/ws` | WS | Real-time event stream | @@ -100,7 +103,7 @@ WebSocket message types: `event.new`, `session.update`, `developer.update`. Two flavors of auth — pick one per route: -- **API key (`x-api-key` header)** — the plugin path. Required by `/api/events` and the plugin-accessible routes (`/api/ai`, `/api/insights`, `/api/patterns`, `/api/playbooks`, `/api/skills`, `/api/topology`, `/api/workflow-profiles`, `/api/friction`, `/api/sessions`, `/api/similar`, `/api/live`). Keys are minted via better-auth's `auth.api.createApiKey({ body: { userId, name } })`; the dashboard exposes this at Settings → API Keys, but there's no UI before you have a session. +- **API key (`x-api-key` header)** — the plugin path. Required by `/api/events` and the plugin-accessible routes (`/api/ai`, `/api/insights`, `/api/patterns`, `/api/playbooks`, `/api/skills`, `/api/topology`, `/api/workflow-profiles`, `/api/friction`, `/api/sessions`, `/api/similar`, `/api/live`, `/api/commands`). Keys are minted via better-auth's `auth.api.createApiKey({ body: { userId, name } })`; the dashboard exposes this at Settings → API Keys, but there's no UI before you have a session. - **Session cookie** — what the dashboard uses. Sign-in via `/api/auth/sign-in/email` returns a session cookie. Most dashboard routes go through `orgScopeMiddleware`, which reads `session.activeOrganizationId` to scope queries. Two traps that bite manual testers: @@ -218,6 +221,33 @@ Session tokens and cost (migration 055, `db/tokenUsageQueries.ts`). Costs are ** - **Backfill from disk:** `/devscope:backfill-usage` uploads exact totals for transcripts still on the developer's machine. Claude Code deletes transcripts after `cleanupPeriodDays` (30 by default), so older sessions keep the estimate. - **Pricing:** `token_cost_usd()` and the rows in 055; runbook in `packages/backend/docs/token-pricing.md`. Sessions with no `model` (pre-037) are priced at the `*` fallback (Sonnet-4 rates), which understates Opus-era usage. +## Command timing + +How long the Bash commands Claude runs take, per project and over time (`command_runs`, migration 058, +`db/commandQueries.ts`, `routes/commands.ts`, dashboard `components/commands/`). + +- **Rows** come from Bash `tool.complete` / `tool.fail` at ingestion (`recordCommandRun`, in + `runPostInsertHandlers`, so it never blocks or fails ingestion). Key: Claude Code's `tool_use_id` (plugin + 0.38.0+), else `event:` with `legacy_timing` set. `wait_ms` is the event's `duration` (Claude + Code's `duration_ms` since plugin 0.38.0; before that the plugin's own timer, which mixed up parallel + calls); the start is the event timestamp minus it. +- **Signature, never the command.** The plugin sends `commandSignature` (`_ds_command_signature`: program + + up to two plain words, the third only after a group word like `run`/`compose`/`pr`; private mode the + program only). `cleanSignature` re-checks the shape and falls back to the program, and private sessions + store the program whatever was sent. Older plugins only have `toolSubcommand` (the first word). +- **Background commands.** PostToolUse fires when a command is backgrounded (`run_in_background` → + `background`; a timeout or the user → `moved`), so the row starts as `running` with `duration_ms` NULL. The + plugin finds the settling in the transcript (`queue-operation` enqueue of a ``) at Stop + and SessionEnd and sends `command.background_complete`; `settleBackgroundCommands` updates only the + sender's own running rows, by `tool_use_id` (not session). +- **Privacy.** No developer or project column: both come from `sessions` at read time, so retention + anonymization applies, and the row cascades away with its event. Reads aggregate by command and project + only; a signature or project is named only for sessions the viewer may see (`visibleSessionSql`), the rest + count under their program, and a `project` filter matches only visible sessions. `scope=me` is the + caller's own ids in the org (no `developerId` parameter). +- **Backfill:** `scripts/command-runs-backfill.ts` (dry run by default, `--write`) runs stored Bash events + through `recordCommandRun`; idempotent. + ## Server voice The plugin's voice announcer speaks through `/api/ai/voice-audio`, so users get a natural voice without installing a model. Both voice endpoints live in `routes/voice.ts` (mounted under `/api/ai`; the Gemini guard and rate limiter are shared with `routes/ai.ts` via `routes/aiGuards.ts`). diff --git a/packages/backend/scripts/command-runs-backfill.ts b/packages/backend/scripts/command-runs-backfill.ts new file mode 100644 index 0000000..eb882e7 --- /dev/null +++ b/packages/backend/scripts/command-runs-backfill.ts @@ -0,0 +1,107 @@ +/** + * Fill command_runs (migration 058) from the Bash tool.complete / tool.fail + * events already stored, so command trends start with history rather than + * from the day of the deploy. + * + * Each event goes through the same recordCommandRun as live ingestion: the + * signature is sanitized the same way and private sessions keep only the + * program. History predates plugin 0.38.0, so rows carry the program only + * (toolSubcommand) and legacy_timing (the old plugin timer, which mixed up + * parallel calls of one session). Background commands from that time were + * recorded at the moment they were backgrounded and count as finished there. + * + * DATA SAFETY. Only inserts into command_runs; ON CONFLICT DO NOTHING, so it + * is idempotent and never touches rows ingestion already wrote. Events that + * retention has purged are gone, and so are their rows. + * + * Usage: + * DATABASE_URL=... bun run scripts/command-runs-backfill.ts # dry run: report only + * DATABASE_URL=... bun run scripts/command-runs-backfill.ts --write # insert the rows + */ + +import { SQL } from "bun"; +import type { DevscopeEvent } from "@devscope/shared"; +import { recordCommandRun } from "../src/db/commandQueries"; + +const BATCH = 500; + +function parseArgs(argv: string[]) { + const out = { write: false }; + for (const a of argv) { + if (a === "--write") out.write = true; + else { + console.error(`Unknown argument: ${a}`); + process.exit(2); + } + } + return out; +} + +async function main() { + const { write } = parseArgs(process.argv.slice(2)); + const url = process.env.DATABASE_URL; + if (!url) { + console.error("DATABASE_URL is required"); + process.exit(2); + } + const sql = new SQL(url); + + const [counts] = (await sql` + SELECT + COUNT(*)::INT AS events, + COUNT(cr.event_id)::INT AS already, + MIN(e.created_at) AS first_at + FROM events e + LEFT JOIN command_runs cr ON cr.event_id = e.id + WHERE e.event_type IN ('tool.complete', 'tool.fail') + AND e.payload->>'toolName' = 'Bash' + `) as Array<{ events: number; already: number; first_at: Date | null }>; + console.log( + `Bash tool events: ${counts!.events} (since ${counts!.first_at?.toISOString?.() ?? "-"}), ` + + `already in command_runs: ${counts!.already}, to add: ${counts!.events - counts!.already}`, + ); + if (!write) { + console.log("Dry run. Re-run with --write to insert."); + await sql.close(); + return; + } + + let cursor: { at: Date; id: string } | null = null; + let added = 0; + for (;;) { + const rows = (await sql` + SELECT e.id, e.session_id, e.event_type, e.payload, e.created_at + FROM events e + WHERE e.event_type IN ('tool.complete', 'tool.fail') + AND e.payload->>'toolName' = 'Bash' + AND NOT EXISTS (SELECT 1 FROM command_runs cr WHERE cr.event_id = e.id) + AND (${cursor?.at ?? null}::timestamptz IS NULL + OR (e.created_at, e.id) > (${cursor?.at ?? null}::timestamptz, ${cursor?.id ?? ""})) + ORDER BY e.created_at, e.id + LIMIT ${BATCH} + `) as Array<{ id: string; session_id: string; event_type: string; payload: unknown; created_at: Date }>; + if (rows.length === 0) break; + for (const r of rows) { + const payload = typeof r.payload === "string" ? JSON.parse(r.payload) : r.payload; + await recordCommandRun(sql, { + id: r.id, + sessionId: r.session_id, + eventType: r.event_type, + timestamp: new Date(r.created_at).toISOString(), + payload, + } as unknown as DevscopeEvent); + } + added += rows.length; + const last = rows[rows.length - 1]!; + cursor = { at: last.created_at, id: last.id }; + console.log(` ${added} processed`); + } + const [after] = (await sql`SELECT COUNT(*)::INT AS n FROM command_runs`) as Array<{ n: number }>; + console.log(`Done. command_runs now has ${after!.n} rows.`); + await sql.close(); +} + +main().catch((e) => { + console.error(e); + process.exit(1); +}); diff --git a/packages/backend/src/db/__tests__/commandQueries.test.ts b/packages/backend/src/db/__tests__/commandQueries.test.ts new file mode 100644 index 0000000..1b1ab84 --- /dev/null +++ b/packages/backend/src/db/__tests__/commandQueries.test.ts @@ -0,0 +1,261 @@ +/** + * Bash command timing (migration 058, commandQueries.ts). + * + * `cleanSignature` is pure and always runs. The rest is gated on + * TEST_DATABASE_URL, like tokenUsage.test.ts: + * + * TEST_DATABASE_URL=postgres://devscope:devscope@localhost:5432/devscope_test \ + * bun test packages/backend/src/db/__tests__/commandQueries.test.ts + */ +import { afterAll, beforeAll, describe, expect, test } from "bun:test"; +import type { DevscopeEvent } from "@devscope/shared"; +import { initializeDatabase } from "../schema"; +import { + cleanSignature, + getCommandProjects, + getCommandSummary, + getCommandTrend, + recordCommandRun, + settleBackgroundCommands, +} from "../commandQueries"; + +describe("cleanSignature", () => { + test("keeps signatures the plugin produces", () => { + expect(cleanSignature("bun run build")).toBe("bun run build"); + expect(cleanSignature("npm run test:unit")).toBe("npm run test:unit"); + expect(cleanSignature("Docker Compose up")).toBe("docker compose up"); + expect(cleanSignature("deploy.sh")).toBe("deploy.sh"); + }); + + test("reduces anything else to its program, never command text", () => { + expect(cleanSignature("rm -rf /home/someone/secret")).toBe("rm"); + expect(cleanSignature("git commit -m hello world")).toBe("git"); + expect(cleanSignature("a b c d")).toBe("a"); + expect(cleanSignature("/usr/bin/env")).toBe("usrbinenv"); + expect(cleanSignature(" ")).toBeNull(); + expect(cleanSignature(42)).toBeNull(); + }); +}); + +const dbUrl = process.env.TEST_DATABASE_URL; +const d = dbUrl ? describe : describe.skip; + +d("command_runs — ingestion, background settling, reads", () => { + let sqlPromise: ReturnType | null = null; + const getSql = () => (sqlPromise ??= initializeDatabase(dbUrl!)); + + const run = crypto.randomUUID().slice(0, 8); + const devA = `t-cmd-a-${run}`; // the viewer + const devB = `t-cmd-b-${run}`; // teammate, does not share + const devC = `t-cmd-c-${run}`; // teammate, shares + const sA = `t-cmd-sa-${run}`; + const sB = `t-cmd-sb-${run}`; + const sC = `t-cmd-sc-${run}`; + const sP = `t-cmd-sp-${run}`; // devA, private + const projX = `proj-x-${run}`; + const projSecret = `proj-secret-${run}`; + const all = [devA, devB, devC]; + + let n = 0; + async function bash( + sessionId: string, + payload: Record, + opts: { eventType?: "tool.complete" | "tool.fail"; at?: Date } = {}, + ) { + const sql = await getSql(); + const id = `t-cmd-ev-${run}-${++n}`; + const at = (opts.at ?? new Date()).toISOString(); + const eventType = opts.eventType ?? "tool.complete"; + await sql`INSERT INTO events (id, session_id, event_type, payload, created_at) + VALUES (${id}, ${sessionId}, ${eventType}, ${{ toolName: "Bash", ...payload }}::jsonb, ${at}::timestamptz)`; + await recordCommandRun(sql, { + id, sessionId, eventType, timestamp: at, payload: { toolName: "Bash", ...payload }, + developerId: "", developerName: "", projectPath: "", projectName: "", + } as unknown as DevscopeEvent); + return id; + } + async function row(toolUseId: string) { + const sql = await getSql(); + const [r] = await sql`SELECT * FROM command_runs WHERE tool_use_id = ${toolUseId}`; + return r as any; + } + const daysAgo = (d: number) => new Date(Date.now() - d * 86_400_000); + const tid = (name: string) => `toolu_${name}_${run}`; + + beforeAll(async () => { + const sql = await getSql(); + for (const [dev, share] of [[devA, false], [devB, false], [devC, true]] as const) { + await sql`INSERT INTO developers (id, name, email, share_details) VALUES (${dev}, ${dev}, ${dev + "@t"}, ${share})`; + } + for (const [id, dev, project, privacy] of [ + [sA, devA, projX, "standard"], + [sB, devB, projSecret, "standard"], + [sC, devC, projX, "standard"], + [sP, devA, "redacted", "private"], + ] as const) { + await sql`INSERT INTO sessions (id, developer_id, project_path, project_name, privacy_mode) + VALUES (${id}, ${dev}, ${"/p/" + project}, ${project}, ${privacy})`; + } + }); + + afterAll(async () => { + const sql = await getSql(); + const sessions = [sA, sB, sC, sP]; + for (const s of sessions) { + await sql`DELETE FROM command_runs WHERE session_id = ${s}`; + await sql`DELETE FROM events WHERE session_id = ${s}`; + await sql`DELETE FROM sessions WHERE id = ${s}`; + } + for (const dev of all) await sql`DELETE FROM developers WHERE id = ${dev}`; + }); + + test("a foreground command: started duration_ms before the event, settled", async () => { + await bash(sA, { duration: 10_000, toolUseId: tid("fg"), commandSignature: "bun test" }, { at: daysAgo(1) }); + const r = await row(tid("fg")); + expect([r.signature, r.program, r.mode, r.outcome, r.wait_ms, r.duration_ms, r.legacy_timing]) + .toEqual(["bun test", "bun", "foreground", "success", 10_000, 10_000, false]); + expect(new Date(r.finished_at).getTime() - new Date(r.started_at).getTime()).toBe(10_000); + }); + + test("failures, interrupts, subagents", async () => { + await bash(sA, { duration: 500, toolUseId: tid("fail"), commandSignature: "bun test" }, { eventType: "tool.fail" }); + await bash(sA, { duration: 50, toolUseId: tid("intr"), commandSignature: "bun test", isInterrupt: true }, { eventType: "tool.fail" }); + await bash(sA, { duration: 50, toolUseId: tid("sub"), commandSignature: "ls", agentId: "agent-1" }); + expect((await row(tid("fail"))).outcome).toBe("failure"); + expect((await row(tid("intr"))).outcome).toBe("interrupted"); + expect((await row(tid("sub"))).in_subagent).toBe(true); + }); + + test("older plugins: keyed by event id, signature from toolSubcommand, legacy timing", async () => { + const id = await bash(sA, { duration: 300, toolSubcommand: "cargo" }); + const r = await row(`event:${id}`); + expect([r.signature, r.legacy_timing]).toEqual(["cargo", true]); + }); + + test("command text never reaches the signature; private sessions keep the program", async () => { + await bash(sA, { duration: 1, toolUseId: tid("junk"), commandSignature: "curl -H 'x-api-key: secret' http://x" }); + await bash(sP, { duration: 1, toolUseId: tid("priv"), commandSignature: "docker compose up" }); + expect((await row(tid("junk"))).signature).toBe("curl"); + expect((await row(tid("priv"))).signature).toBe("docker"); + }); + + test("recording is idempotent per tool_use_id, and ignores other tools", async () => { + await bash(sA, { duration: 999, toolUseId: tid("fg"), commandSignature: "bun test" }); + expect((await row(tid("fg"))).wait_ms).toBe(10_000); + const sql = await getSql(); + await recordCommandRun(sql, { + id: "x", sessionId: sA, eventType: "tool.complete", timestamp: new Date().toISOString(), + payload: { toolName: "Read", toolUseId: tid("read") }, + } as unknown as DevscopeEvent); + expect(await row(tid("read"))).toBeUndefined(); + }); + + test("background: running until settled, only by its own developer, once", async () => { + const at = new Date(Date.now() - 60_000); + await bash(sA, { duration: 20, toolUseId: tid("bg"), commandSignature: "bun run dev", backgroundTaskId: "b1", runInBackground: true }, { at }); + await bash(sA, { duration: 120_000, toolUseId: tid("moved"), commandSignature: "bun test", backgroundTaskId: "b2" }, { at }); + let r = await row(tid("bg")); + expect([r.mode, r.outcome, r.wait_ms, r.duration_ms, r.finished_at]).toEqual(["background", "running", 20, null, null]); + expect((await row(tid("moved"))).mode).toBe("moved"); + + const sql = await getSql(); + const finishedAt = new Date(at.getTime() + 45_000).toISOString(); + expect(await settleBackgroundCommands(sql, devB, [{ toolUseId: tid("bg"), status: "completed", exitCode: 0, finishedAt }])).toBe(0); + expect(await settleBackgroundCommands(sql, devA, [ + { toolUseId: tid("bg"), status: "completed", exitCode: 0, finishedAt }, + { toolUseId: tid("moved"), status: "failed", exitCode: 1, finishedAt }, + { toolUseId: tid("unknown"), status: "completed", finishedAt }, + ])).toBe(2); + r = await row(tid("bg")); + expect([r.outcome, r.exit_code, r.duration_ms]).toEqual(["success", 0, 45_020]); + expect([(await row(tid("moved"))).outcome, (await row(tid("moved"))).exit_code]).toEqual(["failure", 1]); + expect(await settleBackgroundCommands(sql, devA, [{ toolUseId: tid("bg"), status: "killed", finishedAt }])).toBe(0); + }); + + test("the row goes with its event (retention)", async () => { + const id = await bash(sA, { duration: 5, toolUseId: tid("gone"), commandSignature: "ls" }); + const sql = await getSql(); + await sql`DELETE FROM events WHERE id = ${id}`; + expect(await row(tid("gone"))).toBeUndefined(); + }); + + describe("reads", () => { + beforeAll(async () => { + await bash(sC, { duration: 30_000, toolUseId: tid("c1"), commandSignature: "bun test" }); + await bash(sB, { duration: 90_000, toolUseId: tid("b1"), commandSignature: "make deploy" }); + await bash(sB, { duration: 80_000, toolUseId: tid("b2"), commandSignature: "make deploy" }); + // The period before (days 30-60) for comparison, and out of range. + await bash(sA, { duration: 4_000, toolUseId: tid("old"), commandSignature: "bun test" }, { at: daysAgo(40) }); + await bash(sA, { duration: 4_000, toolUseId: tid("ancient"), commandSignature: "bun test" }, { at: daysAgo(90) }); + }); + const scope = (over: Partial[1]> = {}) => + ({ devIds: all, viewerDevIds: [devA], days: 30, project: null, ...over }); + + test("summary: by time waited, a hidden teammate's runs only under their program", async () => { + const sql = await getSql(); + const s = await getCommandSummary(sql, scope(), "signature"); + const by = Object.fromEntries(s.commands.map((c) => [c.command, c])); + expect(Object.keys(by)).not.toContain("make deploy"); + expect(by.make.runs).toBe(2); + expect(by.make.wait_ms).toBe(170_000); + expect(s.commands[0]!.command).toBe("make"); + const bunTest = by["bun test"]!; + // fg 10s, fail 0.5s, interrupt 0.05s, moved 120s (settled as failed above), + // teammate C's 30s (shared) + expect([bunTest.runs, bunTest.failures, bunTest.interrupted, bunTest.moved_runs]).toEqual([5, 2, 1, 1]); + expect(bunTest.prev_runs).toBe(1); + expect(bunTest.max_ms).toBeGreaterThanOrEqual(120_000); + expect(by["bun run dev"]!.background_runs).toBe(1); + expect(s.totals.prev_runs).toBe(1); + expect(s.totals.runs).toBe(s.commands.reduce((a, c) => a + c.runs, 0)); + }); + + test("the teammate sees their own signature", async () => { + const sql = await getSql(); + const s = await getCommandSummary(sql, scope({ viewerDevIds: [devB] }), "signature"); + expect(s.commands.map((c) => c.command)).toContain("make deploy"); + }); + + test("a project filter matches only sessions the viewer may see", async () => { + const sql = await getSql(); + const secret = await getCommandSummary(sql, scope({ project: projSecret }), "signature"); + expect(secret.commands).toEqual([]); + const x = await getCommandSummary(sql, scope({ project: projX }), "signature"); + expect(x.commands.find((c) => c.command === "bun test")!.runs).toBe(5); + expect(x.commands.map((c) => c.command)).not.toContain("make"); + }); + + test("group by program; scope me", async () => { + const sql = await getSql(); + const prog = await getCommandSummary(sql, scope(), "program"); + expect(prog.commands.find((c) => c.command === "bun")!.runs).toBe(6); // 5 bun test + bun run dev + const me = await getCommandSummary(sql, scope({ devIds: [devA] }), "signature"); + expect(me.commands.find((c) => c.command === "bun test")!.runs).toBe(4); + expect(me.commands.map((c) => c.command)).not.toContain("make"); + }); + + test("trend: one point per day, filtered by command", async () => { + const sql = await getSql(); + const t = await getCommandTrend(sql, scope(), "signature", "bun test", "day"); + expect(t.points.length).toBeGreaterThanOrEqual(30); + expect(t.points.reduce((a, p) => a + p.runs, 0)).toBe(5); + expect(t.points.at(-1)!.bucket).toBe(new Date().toISOString().slice(0, 10)); + const weeks = await getCommandTrend(sql, scope(), "signature", null, "week"); + expect(weeks.points.length).toBeLessThanOrEqual(6); + }); + + test("projects: only the ones the viewer may see", async () => { + const sql = await getSql(); + const p = (await getCommandProjects(sql, scope())).map((r) => r.project); + expect(p).toContain(projX); + expect(p).not.toContain(projSecret); + expect(p).not.toContain("redacted"); + }); + + test("no developers: empty, without a query", async () => { + const sql = await getSql(); + expect((await getCommandSummary(sql, scope({ devIds: [] }), "signature")).commands).toEqual([]); + expect((await getCommandTrend(sql, scope({ devIds: [] }), "signature", null, "day")).points).toEqual([]); + }); + }); +}); diff --git a/packages/backend/src/db/commandQueries.ts b/packages/backend/src/db/commandQueries.ts new file mode 100644 index 0000000..0671c04 --- /dev/null +++ b/packages/backend/src/db/commandQueries.ts @@ -0,0 +1,274 @@ +import type { SQL } from "bun"; +import type { + CommandGroup, + CommandProjectRow, + CommandSummary, + CommandSummaryRow, + CommandTrend, + CommandTrendPoint, + DevscopeEvent, +} from "@devscope/shared"; +import { inList, visibleSessionSql } from "./utils"; + +// Bash command timing (command_runs, migration 058). Ingestion turns each Bash +// tool.complete / tool.fail into a row; command.background_complete settles the +// background ones. Reads aggregate by command and project, never by developer: +// a signature or project is named only for sessions the viewer may see, the +// rest count under their program (like toolSubcommand in the tool topology). + +const MAX_MS = 2_147_483_647; + +/** A signature the plugin's `_ds_command_signature` could have produced. */ +const SIGNATURE = /^[a-z0-9._+-]{1,40}( [a-z][a-z0-9_:-]{0,23}){0,2}$/; + +/** + * The stored signature: what the plugin sent when it has the expected shape, + * else its first word reduced to program characters. Defence in depth: the + * column must never hold command text, whatever a plugin sends. + */ +export function cleanSignature(raw: unknown): string | null { + if (typeof raw !== "string") return null; + const s = raw.trim().toLowerCase().replace(/\s+/g, " "); + if (SIGNATURE.test(s)) return s; + const program = (s.split(" ")[0] ?? "").replace(/[^a-z0-9._+-]/g, "").slice(0, 40); + return program || null; +} + +function clampMs(v: unknown): number { + const n = Number(v); + return Number.isFinite(n) && n > 0 ? Math.min(Math.round(n), MAX_MS) : 0; +} + +/** Record a Bash tool.complete / tool.fail. Idempotent per tool_use_id. */ +export async function recordCommandRun(sql: SQL, event: DevscopeEvent): Promise { + if (event.eventType !== "tool.complete" && event.eventType !== "tool.fail") return; + const p = (event.payload ?? {}) as Record; + if (p.toolName !== "Bash") return; + + const signature = cleanSignature(p.commandSignature) ?? cleanSignature(p.toolSubcommand) ?? "unknown"; + const program = signature.split(" ")[0]!; + const hasId = typeof p.toolUseId === "string" && p.toolUseId.length > 0; + const toolUseId = hasId ? (p.toolUseId as string) : `event:${event.id}`; + const background = typeof p.backgroundTaskId === "string" && p.backgroundTaskId.length > 0; + const mode = background ? (p.runInBackground === true ? "background" : "moved") : "foreground"; + const failed = event.eventType === "tool.fail"; + const outcome = failed ? (p.isInterrupt === true ? "interrupted" : "failure") : background ? "running" : "success"; + const waitMs = clampMs(p.duration); + // PostToolUse fires when the command ends (or is backgrounded): the event's + // timestamp is that moment, and the start is `duration` before it. + const endedAt = new Date(event.timestamp); + const startedAt = new Date(endedAt.getTime() - waitMs).toISOString(); + const settled = !background || failed; + + // Private sessions keep the program only, whatever the plugin sent. + await sql` + INSERT INTO command_runs ( + tool_use_id, event_id, session_id, program, signature, in_subagent, mode, + started_at, wait_ms, duration_ms, outcome, finished_at, legacy_timing + ) + SELECT + ${toolUseId}, ${event.id}, s.id, ${program}, + CASE WHEN s.privacy_mode = 'private' THEN ${program} ELSE ${signature} END, + ${typeof p.agentId === "string" && p.agentId.length > 0}, ${mode}, + ${startedAt}::timestamptz, ${waitMs}, ${settled ? waitMs : null}, + ${outcome}, ${settled ? endedAt.toISOString() : null}::timestamptz, ${!hasId} + FROM sessions s + WHERE s.id = ${event.sessionId} + ON CONFLICT DO NOTHING`; +} + +export interface SettledCommand { + toolUseId: string; + status: string; + exitCode?: number; + finishedAt: string; +} + +const SETTLED_OUTCOME: Record = { + completed: "success", + failed: "failure", + killed: "killed", +}; + +/** + * Settle background commands from command.background_complete. Only the + * sender's own running rows change, matched by tool_use_id rather than session + * (the report can arrive under another DevScope session id after /clear). + */ +export async function settleBackgroundCommands( + sql: SQL, + developerId: string, + commands: SettledCommand[], +): Promise { + let settled = 0; + for (const c of commands.slice(0, 200)) { + const finished = new Date(c.finishedAt); + if (Number.isNaN(finished.getTime())) continue; + const outcome = SETTLED_OUTCOME[c.status] ?? "failure"; + const rows = await sql` + UPDATE command_runs cr + SET finished_at = ${finished.toISOString()}::timestamptz, + duration_ms = LEAST(${MAX_MS}, GREATEST(cr.wait_ms, + ROUND(EXTRACT(EPOCH FROM (${finished.toISOString()}::timestamptz - cr.started_at)) * 1000)))::INT, + outcome = ${outcome}, + exit_code = ${Number.isInteger(c.exitCode) ? c.exitCode! : null} + FROM sessions s + WHERE cr.tool_use_id = ${c.toolUseId} + AND cr.outcome = 'running' + AND s.id = cr.session_id + AND s.developer_id = ${developerId} + RETURNING cr.tool_use_id`; + settled += (rows as unknown[]).length; + } + return settled; +} + +// --- Reads ----------------------------------------------------------------- + +export interface CommandReadScope { + /** Developers whose runs count (the org's, or the caller's own in it). */ + devIds: string[]; + /** The viewer's own developer ids: decides what may be named. */ + viewerDevIds: string[]; + days: number; + project: string | null; +} + +/** + * Runs in the scope since `sinceDays` ago, with `command` and `project` as + * this viewer may see them. A named project filter only matches sessions the + * viewer may see, so it cannot reveal where a hidden session ran. + */ +function scopedRuns( + sql: SQL, + scope: CommandReadScope, + group: CommandGroup, + sinceDays: number, +) { + const vis = visibleSessionSql(scope.viewerDevIds); + return sql` + SELECT + CASE WHEN ${group} = 'program' THEN cr.program + WHEN ${vis} THEN cr.signature + ELSE cr.program END AS command, + cr.mode, cr.outcome, cr.wait_ms, cr.duration_ms, cr.started_at + FROM command_runs cr + JOIN sessions s ON s.id = cr.session_id + WHERE s.developer_id IN (${inList(scope.devIds)}) + AND cr.started_at >= NOW() - make_interval(days => ${sinceDays}) + AND (${scope.project}::text IS NULL OR (${vis} AND s.project_name = ${scope.project}))`; +} + +export async function getCommandSummary( + sql: SQL, + scope: CommandReadScope, + group: CommandGroup, + limit = 50, +): Promise> { + const empty = { + days: scope.days, + group, + project: scope.project, + totals: { runs: 0, wait_ms: 0, prev_runs: 0, prev_wait_ms: 0 }, + commands: [] as CommandSummaryRow[], + }; + if (scope.devIds.length === 0) return empty; + + const rows = (await sql` + WITH runs AS (${scopedRuns(sql, scope, group, scope.days * 2)}), + tagged AS ( + SELECT *, started_at >= NOW() - make_interval(days => ${scope.days}) AS cur FROM runs + ) + SELECT + command, + COUNT(*) FILTER (WHERE cur)::INT AS runs, + COUNT(*) FILTER (WHERE cur AND outcome = 'failure')::INT AS failures, + COUNT(*) FILTER (WHERE cur AND outcome = 'interrupted')::INT AS interrupted, + COUNT(*) FILTER (WHERE cur AND mode = 'background')::INT AS background_runs, + COUNT(*) FILTER (WHERE cur AND mode = 'moved')::INT AS moved_runs, + COUNT(*) FILTER (WHERE cur AND outcome = 'running')::INT AS running, + (percentile_cont(0.5) WITHIN GROUP (ORDER BY duration_ms) FILTER (WHERE cur))::FLOAT8 AS p50_ms, + (percentile_cont(0.95) WITHIN GROUP (ORDER BY duration_ms) FILTER (WHERE cur))::FLOAT8 AS p95_ms, + (MAX(duration_ms) FILTER (WHERE cur))::FLOAT8 AS max_ms, + COALESCE(SUM(wait_ms) FILTER (WHERE cur), 0)::FLOAT8 AS wait_ms, + COALESCE(SUM(duration_ms) FILTER (WHERE cur), 0)::FLOAT8 AS total_ms, + COUNT(*) FILTER (WHERE NOT cur)::INT AS prev_runs, + (percentile_cont(0.5) WITHIN GROUP (ORDER BY duration_ms) FILTER (WHERE NOT cur))::FLOAT8 AS prev_p50_ms, + COALESCE(SUM(wait_ms) FILTER (WHERE NOT cur), 0)::FLOAT8 AS prev_wait_ms + FROM tagged + GROUP BY command + HAVING COUNT(*) FILTER (WHERE cur) > 0 + ORDER BY wait_ms DESC, runs DESC, command + `) as CommandSummaryRow[]; + + const totals = { runs: 0, wait_ms: 0, prev_runs: 0, prev_wait_ms: 0 }; + for (const r of rows) { + totals.runs += r.runs; + totals.wait_ms += r.wait_ms; + } + // Previous-period totals include commands that did not run this period. + const [prev] = (await sql` + WITH runs AS (${scopedRuns(sql, scope, group, scope.days * 2)}) + SELECT COUNT(*)::INT AS prev_runs, COALESCE(SUM(wait_ms), 0)::FLOAT8 AS prev_wait_ms + FROM runs WHERE started_at < NOW() - make_interval(days => ${scope.days}) + `) as Array<{ prev_runs: number; prev_wait_ms: number }>; + totals.prev_runs = prev?.prev_runs ?? 0; + totals.prev_wait_ms = prev?.prev_wait_ms ?? 0; + + return { ...empty, totals, commands: rows.slice(0, limit) }; +} + +export async function getCommandTrend( + sql: SQL, + scope: CommandReadScope, + group: CommandGroup, + command: string | null, + bucket: "day" | "week", +): Promise> { + const base = { bucket, command, project: scope.project }; + if (scope.devIds.length === 0) return { ...base, points: [] }; + const points = (await sql` + WITH runs AS (${scopedRuns(sql, scope, group, scope.days)}), + picked AS (SELECT * FROM runs WHERE ${command}::text IS NULL OR command = ${command}), + buckets AS ( + SELECT generate_series( + date_trunc(${bucket}, NOW() - make_interval(days => ${scope.days})), + date_trunc(${bucket}, NOW()), + ('1 ' || ${bucket})::interval + ) AS bucket + ) + SELECT + to_char(b.bucket, 'YYYY-MM-DD') AS bucket, + COUNT(p.started_at)::INT AS runs, + COUNT(p.started_at) FILTER (WHERE p.outcome = 'failure')::INT AS failures, + (percentile_cont(0.5) WITHIN GROUP (ORDER BY p.duration_ms))::FLOAT8 AS p50_ms, + (percentile_cont(0.95) WITHIN GROUP (ORDER BY p.duration_ms))::FLOAT8 AS p95_ms, + COALESCE(SUM(p.wait_ms), 0)::FLOAT8 AS wait_ms + FROM buckets b + LEFT JOIN picked p ON date_trunc(${bucket}, p.started_at) = b.bucket + GROUP BY b.bucket + ORDER BY b.bucket + `) as CommandTrendPoint[]; + return { ...base, points }; +} + +/** Projects with command runs the viewer may see, busiest first. */ +export async function getCommandProjects( + sql: SQL, + scope: Omit, +): Promise { + if (scope.devIds.length === 0) return []; + const vis = visibleSessionSql(scope.viewerDevIds); + return (await sql` + SELECT s.project_name AS project, COUNT(*)::INT AS runs, COALESCE(SUM(cr.wait_ms), 0)::FLOAT8 AS wait_ms + FROM command_runs cr + JOIN sessions s ON s.id = cr.session_id + WHERE s.developer_id IN (${inList(scope.devIds)}) + AND cr.started_at >= NOW() - make_interval(days => ${scope.days}) + AND ${vis} + AND s.project_name IS NOT NULL AND s.project_name NOT IN ('', 'redacted') + GROUP BY s.project_name + ORDER BY wait_ms DESC + LIMIT 100 + `) as CommandProjectRow[]; +} diff --git a/packages/backend/src/db/migrations/058_command_runs.sql b/packages/backend/src/db/migrations/058_command_runs.sql new file mode 100644 index 0000000..6299a97 --- /dev/null +++ b/packages/backend/src/db/migrations/058_command_runs.sql @@ -0,0 +1,42 @@ +-- Bash command timing: one row per Bash tool call, derived from tool.complete / +-- tool.fail at ingestion (db/commandQueries.ts), so slow and slowing commands +-- can be found per project over time. +-- +-- No command text is stored. `signature` is what the plugin sends as +-- commandSignature (plugin 0.38.0+): the program and up to two plain words +-- ("bun run build", "docker compose up"); older plugins only send the program +-- (toolSubcommand). Reads name a signature or project only for sessions the +-- viewer may see (visibleSessionPredicate); other sessions count under their +-- program. +-- +-- There is no developer_id or project column: both come from `sessions` at read +-- time, so retention anonymization applies. The row cascades away with its +-- event, so it never outlives the retention window of the event it came from. +CREATE TABLE IF NOT EXISTS command_runs ( + -- Claude Code's tool_use_id; `event:` for plugins that do not send one. + tool_use_id TEXT PRIMARY KEY, + event_id TEXT NOT NULL UNIQUE REFERENCES events(id) ON DELETE CASCADE, + session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE, + program TEXT NOT NULL, + signature TEXT NOT NULL, + in_subagent BOOLEAN NOT NULL DEFAULT FALSE, + -- foreground: Claude waited for it to finish. background: run_in_background. + -- moved: started in the foreground, backgrounded after its timeout or by the user. + mode TEXT NOT NULL CHECK (mode IN ('foreground', 'background', 'moved')), + started_at TIMESTAMPTZ NOT NULL, + -- How long the session waited on it: all of a foreground command, and for a + -- background one the time until it was backgrounded. + wait_ms INTEGER NOT NULL CHECK (wait_ms >= 0), + -- Start to finish. NULL while a background command is still running (or was + -- never reported as settled). + duration_ms INTEGER CHECK (duration_ms >= 0), + outcome TEXT NOT NULL CHECK (outcome IN ('success', 'failure', 'interrupted', 'running', 'killed')), + exit_code INTEGER, + finished_at TIMESTAMPTZ, + -- Timed by the plugin's own clock (no duration_ms from Claude Code), which + -- before plugin 0.38.0 mixed up parallel calls of one session. + legacy_timing BOOLEAN NOT NULL DEFAULT FALSE +); + +CREATE INDEX IF NOT EXISTS idx_command_runs_started ON command_runs (started_at); +CREATE INDEX IF NOT EXISTS idx_command_runs_session ON command_runs (session_id); diff --git a/packages/backend/src/index.ts b/packages/backend/src/index.ts index 79a69d8..675817e 100644 --- a/packages/backend/src/index.ts +++ b/packages/backend/src/index.ts @@ -48,6 +48,7 @@ import { nudgesRoutes } from "./routes/nudges"; import { promptSimilarityRoutes } from "./routes/promptSimilarity"; import { similarRoutes } from "./routes/similar"; import { liveRoutes } from "./routes/live"; +import { commandsRoutes } from "./routes/commands"; import { orgScopeMiddleware } from "./middleware/orgScope"; import { rateLimitMiddleware, getClientIp } from "./middleware/rateLimit"; import { apiKeyRateLimitRetryAfter, apiKeyRateLimitRetryAfterFromError } from "./middleware/apiKeyRateLimit"; @@ -233,7 +234,7 @@ app.use("/api/events", requireApiKeyOrSession); // Plugin-facing routes: accept API keys or session cookies // This allows plugin commands (e.g. /devscope:ask, /devscope:review) to call these endpoints -const pluginAccessiblePrefixes = ["/api/ai", "/api/insights", "/api/patterns", "/api/playbooks", "/api/skills", "/api/topology", "/api/workflow-profiles", "/api/friction", "/api/sessions", "/api/nudges", "/api/prompts", "/api/similar", "/api/live"]; +const pluginAccessiblePrefixes = ["/api/ai", "/api/insights", "/api/patterns", "/api/playbooks", "/api/skills", "/api/topology", "/api/workflow-profiles", "/api/friction", "/api/sessions", "/api/nudges", "/api/prompts", "/api/similar", "/api/live", "/api/commands"]; for (const prefix of pluginAccessiblePrefixes) { app.use(`${prefix}/*`, requireApiKeyOrSession); app.use(prefix, requireApiKeyOrSession); @@ -342,6 +343,8 @@ app.use("/api/live/next-prompts", rateLimitMiddleware({ keyFn: (c) => (c.get("user" as never) as any)?.id ?? getClientIp(c), })); app.use("/api/live/*", orgScopeMiddleware(sql)); +app.use("/api/commands/*", orgScopeMiddleware(sql)); +app.use("/api/commands", orgScopeMiddleware(sql)); app.route("/api/events", eventsRoutes(sql)); app.route("/api/sessions", sessionsRoutes(sql)); @@ -368,6 +371,7 @@ app.route("/api/nudges", nudgesRoutes(sql)); app.route("/api/prompts", promptSimilarityRoutes(sql)); app.route("/api/similar", similarRoutes(sql)); app.route("/api/live", liveRoutes(sql)); +app.route("/api/commands", commandsRoutes(sql)); app.get("/api/health", (c) => c.json({ status: "ok", clients: getClientCount() }) diff --git a/packages/backend/src/routes/__tests__/events.contract.test.ts b/packages/backend/src/routes/__tests__/events.contract.test.ts index 06bc122..298aa19 100644 --- a/packages/backend/src/routes/__tests__/events.contract.test.ts +++ b/packages/backend/src/routes/__tests__/events.contract.test.ts @@ -132,6 +132,10 @@ function transformToolComplete(raw: Record) { }; if (raw.tool_input != null) payload.toolInput = raw.tool_input; if (raw.tool_result != null) payload.toolResult = raw.tool_result; + // Plugin 0.38.0+, Bash only: Claude Code's tool_use_id and a command + // signature (fixtures from before carry neither). + if (raw.tool_use_id) payload.toolUseId = raw.tool_use_id; + if (raw.tool_name === "Bash" && raw.tool_use_id) payload.commandSignature = "echo"; return envelope("tool.complete", payload); } @@ -370,6 +374,8 @@ describe("plugin↔backend wire contract (DEV-88)", () => { "plugin.setup", // Added in plugin 0.35.0. "model.first_use", + // Added in plugin 0.38.0. + "command.background_complete", ].sort(), ); }); @@ -378,6 +384,35 @@ describe("plugin↔backend wire contract (DEV-88)", () => { // Negative cases: deliberately malformed payloads must fail // ------------------------------------------------------------------------- + // command.background_complete is built from the transcript, not from a hook + // input, so it has no fixture: this mirrors _ds_report_bg_commands + + // scripts/bg_commands.py (tests/commands/run.sh on the plugin side). + test("command.background_complete (plugin 0.38.0) parses against strict schema", () => { + const event = envelope("command.background_complete", { + commands: [ + { toolUseId: "toolu_1", taskId: "b5r0fuwka", status: "completed", exitCode: 0, finishedAt: "2026-11-03T09:04:08.224Z" }, + { toolUseId: "toolu_2", taskId: "b6", status: "killed", finishedAt: "2026-11-03T09:05:00.000Z" }, + ], + }); + expect(strictEventSchema.safeParse(event).success).toBe(true); + }); + + test("command.background_complete rejects extra fields (no command text)", () => { + const broken = envelope("command.background_complete", { + commands: [{ toolUseId: "toolu_1", status: "completed", finishedAt: "2026-11-03T09:04:08.224Z", summary: "Background command x" }], + }); + expect(strictEventSchema.safeParse(broken).success).toBe(false); + }); + + test("tool.complete accepts the Bash timing fields (plugin 0.38.0)", () => { + const event = envelope("tool.complete", { + toolName: "Bash", success: true, duration: 45000, isInterrupt: false, + toolUseId: "toolu_1", commandSignature: "bun run dev", + backgroundTaskId: "b1", runInBackground: true, + }); + expect(strictEventSchema.safeParse(event).success).toBe(true); + }); + test("session.start missing startType is rejected", () => { const broken = envelope("session.start", { // startType intentionally omitted diff --git a/packages/backend/src/routes/__tests__/events.test.ts b/packages/backend/src/routes/__tests__/events.test.ts index eb14dc3..0f87d7c 100644 --- a/packages/backend/src/routes/__tests__/events.test.ts +++ b/packages/backend/src/routes/__tests__/events.test.ts @@ -59,6 +59,13 @@ mock.module("../../utils/ethicsAudit", () => ({ logEthicsEvent: mock(() => {}), })); +const mockRecordCommandRun = mock(() => Promise.resolve()); +const mockSettleBackgroundCommands = mock(() => Promise.resolve(0)); +mock.module("../../db/commandQueries", () => ({ + recordCommandRun: mockRecordCommandRun, + settleBackgroundCommands: mockSettleBackgroundCommands, +})); + // Import AFTER mocks are registered const { eventsRoutes } = await import("../events"); @@ -297,6 +304,19 @@ describe("POST /events", () => { expect(res.status).not.toBe(400); }); + test("accepts eventType command.background_complete (added in plugin 0.38.0)", async () => { + const sql = makeMockSql(); + const app = buildApp(sql); + + const res = await app.request("/", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(validEvent({ eventType: "command.background_complete", payload: { commands: [] } })), + }); + + expect(res.status).not.toBe(400); + }); + // Pre-0.15.0 plugins stay installed and keep sending these; dropping them // from the enum would turn their events into 400s. test.each(["worktree.create", "worktree.remove"])( @@ -1661,3 +1681,68 @@ describe("token usage on response.complete", () => { expect(mockUpdateSessionTokens).toHaveBeenCalledTimes(1); }); }); + +describe("command timing (command_runs)", () => { + beforeEach(() => { + mockRecordCommandRun.mockClear(); + mockSettleBackgroundCommands.mockClear(); + mockInsertEvent.mockImplementation(() => Promise.resolve({ stored: true })); + }); + + const post = (app: Hono, body: unknown) => + app.request("/", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }); + + test("records every tool.complete and tool.fail", async () => { + const app = buildApp(makeMockSql([{ status: "active", developer_id: ALICE_DEV_ID }])); + for (const eventType of ["tool.complete", "tool.fail"]) { + const res = await post(app, validEvent({ + id: `evt-${eventType}`, + eventType, + payload: { toolName: "Bash", duration: 1200, toolUseId: "toolu_1", commandSignature: "bun test" }, + })); + expect(res.status).toBe(200); + } + expect(mockRecordCommandRun).toHaveBeenCalledTimes(2); + const [, event] = mockRecordCommandRun.mock.calls[0] as unknown as [unknown, any]; + expect(event.developerId).toBe(ALICE_DEV_ID); + expect(event.payload.commandSignature).toBe("bun test"); + }); + + test("a failing recordCommandRun does not fail ingestion", async () => { + mockRecordCommandRun.mockImplementationOnce(() => Promise.reject(new Error("db down"))); + const app = buildApp(makeMockSql([{ status: "active", developer_id: ALICE_DEV_ID }])); + const res = await post(app, validEvent({ eventType: "tool.complete", payload: { toolName: "Bash" } })); + expect(res.status).toBe(200); + }); + + test("a duplicate event is not recorded twice", async () => { + mockInsertEvent.mockImplementationOnce(() => Promise.resolve({ stored: false })); + const app = buildApp(makeMockSql([{ status: "active", developer_id: ALICE_DEV_ID }])); + await post(app, validEvent({ eventType: "tool.complete", payload: { toolName: "Bash" } })); + expect(mockRecordCommandRun).not.toHaveBeenCalled(); + }); + + test("command.background_complete settles the sender's own runs", async () => { + const app = buildApp(makeMockSql([{ status: "active", developer_id: ALICE_DEV_ID }])); + const commands = [ + { toolUseId: "toolu_bg", taskId: "b1", status: "completed", exitCode: 0, finishedAt: "2026-03-03T12:05:00.000Z" }, + ]; + const res = await post(app, validEvent({ eventType: "command.background_complete", payload: { commands } })); + expect(res.status).toBe(200); + expect(mockSettleBackgroundCommands).toHaveBeenCalledTimes(1); + const [, devId, settled] = mockSettleBackgroundCommands.mock.calls[0] as unknown as [unknown, string, unknown]; + expect(devId).toBe(ALICE_DEV_ID); + expect(settled).toEqual(commands); + expect(mockRecordCommandRun).not.toHaveBeenCalled(); + }); + + test("a malformed command.background_complete settles nothing", async () => { + const app = buildApp(makeMockSql([{ status: "active", developer_id: ALICE_DEV_ID }])); + const res = await post(app, validEvent({ + eventType: "command.background_complete", + payload: { commands: [{ toolUseId: "toolu_bg", status: "completed", finishedAt: "x", command: "rm -rf /" }] }, + })); + expect(res.status).toBe(200); + expect(mockSettleBackgroundCommands).not.toHaveBeenCalled(); + }); +}); diff --git a/packages/backend/src/routes/commands.ts b/packages/backend/src/routes/commands.ts new file mode 100644 index 0000000..0640b2e --- /dev/null +++ b/packages/backend/src/routes/commands.ts @@ -0,0 +1,60 @@ +import type { SQL } from "bun"; +import { Hono } from "hono"; +import type { CommandGroup, CommandScope } from "@devscope/shared"; +import { getCommandProjects, getCommandSummary, getCommandTrend } from "../db/commandQueries"; +import { getOrgDevIds, getOwnOrgDevIds, getViewerDevIds } from "../services/visibility"; + +// Bash command timing (command_runs, migration 058): which commands the +// sessions wait on, per project, over time. Every answer is about commands and +// projects; none carries a developer. `scope=me` is the caller's own runs in +// the active org (there is no developerId parameter, so nobody can ask for a +// colleague's), `team` the org's. + +function intParam(v: string | undefined, def: number, min: number, max: number): number { + const n = Number(v); + return Number.isFinite(n) ? Math.min(Math.max(Math.floor(n), min), max) : def; +} + +function textParam(v: string | undefined, max = 200): string | null { + const s = (v ?? "").trim(); + return s ? s.slice(0, max) : null; +} + +export function commandsRoutes(sql: SQL) { + const app = new Hono(); + + async function readScope(c: any) { + const scope: CommandScope = c.req.query("scope") === "me" ? "me" : "team"; + const group: CommandGroup = c.req.query("group") === "program" ? "program" : "signature"; + const days = intParam(c.req.query("days"), 30, 1, 365); + const project = textParam(c.req.query("project")); + const viewerDevIds = await getViewerDevIds(sql, c); + const devIds = scope === "me" ? await getOwnOrgDevIds(sql, c) : getOrgDevIds(c); + return { scope, group, days, project, viewerDevIds, devIds }; + } + + /** Commands by time waited on them, with the period before for comparison. */ + app.get("/summary", async (c) => { + const s = await readScope(c); + const limit = intParam(c.req.query("limit"), 50, 1, 200); + const summary = await getCommandSummary(sql, s, s.group, limit); + return c.json({ ...summary, scope: s.scope }); + }); + + /** One command (or all of them) per day or week. */ + app.get("/trend", async (c) => { + const s = await readScope(c); + const bucket = c.req.query("bucket") === "week" ? "week" : "day"; + const command = textParam(c.req.query("command"), 100); + const trend = await getCommandTrend(sql, s, s.group, command, bucket); + return c.json({ ...trend, days: s.days }); + }); + + /** Projects with command runs the caller may see, for the project filter. */ + app.get("/projects", async (c) => { + const s = await readScope(c); + return c.json(await getCommandProjects(sql, s)); + }); + + return app; +} diff --git a/packages/backend/src/routes/events.ts b/packages/backend/src/routes/events.ts index f7d53f3..300d225 100644 --- a/packages/backend/src/routes/events.ts +++ b/packages/backend/src/routes/events.ts @@ -17,7 +17,8 @@ import { finalizeTokenSegment, applyUsageSnapshot, } from "../db"; -import { usageSnapshotSchema } from "../utils/eventSchemas"; +import { commandBackgroundCompletePayloadSchema, usageSnapshotSchema } from "../utils/eventSchemas"; +import { recordCommandRun, settleBackgroundCommands } from "../db/commandQueries"; import { broadcastToOrg } from "../ws/handler"; import { autoLinkDeveloperToOrg, autoLinkUserToDeveloper, computeDeveloperId } from "../services/developerLink"; import { broadcastSessionUpdate, getViewerDevIds, redactEvent, visibilityForRow } from "../services/visibility"; @@ -61,6 +62,8 @@ const eventSchema = z.object({ "plugin.setup", // Added in plugin 0.35.0. "model.first_use", + // Added in plugin 0.38.0. + "command.background_complete", ]), payload: z.record(z.unknown()), }); @@ -227,6 +230,21 @@ export function eventsRoutes(sql: SQL) { } } + // Bash command timing (command_runs, migration 058). Never blocks ingestion. + if (event.eventType === "tool.complete" || event.eventType === "tool.fail") { + await recordCommandRun(sql, event).catch((e) => + console.error("[commands] recordCommandRun failed:", (e as Error).message), + ); + } + if (event.eventType === "command.background_complete") { + const parsed = commandBackgroundCompletePayloadSchema.safeParse(event.payload); + if (parsed.success) { + await settleBackgroundCommands(sql, event.developerId, parsed.data.commands).catch((e) => + console.error("[commands] settleBackgroundCommands failed:", (e as Error).message), + ); + } + } + // Track per-session stuck state for the proactive nudge layer if (event.eventType === "tool.fail" || event.eventType === "tool.complete") { const tp = event.payload as any; diff --git a/packages/backend/src/utils/eventSchemas.ts b/packages/backend/src/utils/eventSchemas.ts index 0c9f381..9d5e151 100644 --- a/packages/backend/src/utils/eventSchemas.ts +++ b/packages/backend/src/utils/eventSchemas.ts @@ -151,6 +151,11 @@ const toolEventPayloadBase = { errorMessage: z.string().optional(), isInterrupt: z.boolean().optional(), agentId: z.string().nullable().optional(), + // Bash only, plugin 0.38.0+ (command_runs, migration 058). + toolUseId: z.string().max(200).optional(), + commandSignature: z.string().max(200).optional(), + backgroundTaskId: z.string().max(100).optional(), + runInBackground: z.boolean().optional(), ...privacyAnnotations, } as const; @@ -360,6 +365,29 @@ const modelFirstUsePayloadSchema = z }) .strict(); +/** + * `_ds_report_bg_commands` (Stop / SessionEnd, plugin 0.38.0+): background + * Bash commands that settled, read from the transcript by bg_commands.py. + */ +export const commandBackgroundCompletePayloadSchema = z + .object({ + commands: z + .array( + z + .object({ + toolUseId: z.string().min(1).max(200), + taskId: z.string().max(100).optional(), + status: z.string().max(20), + exitCode: z.number().int().optional(), + finishedAt: z.string().min(1).max(50), + }) + .strict(), + ) + .max(200), + ...privacyAnnotations, + }) + .strict(); + /** `permission-denied.sh` — PermissionDenied. */ const permissionDeniedPayloadSchema = z .object({ @@ -443,6 +471,8 @@ export const payloadSchemasByEventType = { "plugin.setup": pluginSetupPayloadSchema, // Added in plugin 0.35.0. "model.first_use": modelFirstUsePayloadSchema, + // Added in plugin 0.38.0. + "command.background_complete": commandBackgroundCompletePayloadSchema, } as const; export type EventTypeKey = keyof typeof payloadSchemasByEventType; diff --git a/packages/dashboard/src/App.tsx b/packages/dashboard/src/App.tsx index f6b9d3b..a66d204 100644 --- a/packages/dashboard/src/App.tsx +++ b/packages/dashboard/src/App.tsx @@ -12,6 +12,7 @@ import { InsightsView } from "@/components/insights/InsightsView"; import { SessionDetail } from "@/components/session/SessionDetail"; import { FailuresView } from "@/components/failures/FailuresView"; import { ProjectsView } from "@/components/projects/ProjectsView"; +import { CommandsView } from "@/components/commands/CommandsView"; import { AiView } from "@/components/ai/AiView"; import { AuthPage } from "@/components/auth/AuthPage"; import { OnboardingWizard } from "@/components/onboarding/OnboardingWizard"; @@ -90,6 +91,7 @@ function AppContent() { + diff --git a/packages/dashboard/src/components/LiveFeed.tsx b/packages/dashboard/src/components/LiveFeed.tsx index 0f0eaa9..8ce2c50 100644 --- a/packages/dashboard/src/components/LiveFeed.tsx +++ b/packages/dashboard/src/components/LiveFeed.tsx @@ -206,6 +206,7 @@ function buildFeedItems(events: FeedEvent[]): FeedItem[] { case "directory.added": case "plugin.setup": case "model.first_use": + case "command.background_complete": flushTools(); items.push({ kind: "event", key: event.id, event }); break; diff --git a/packages/dashboard/src/components/app-sidebar.tsx b/packages/dashboard/src/components/app-sidebar.tsx index 9319087..372c436 100644 --- a/packages/dashboard/src/components/app-sidebar.tsx +++ b/packages/dashboard/src/components/app-sidebar.tsx @@ -20,6 +20,7 @@ import { Shield, Lightbulb, Search, + Timer, } from "lucide-react"; import { useActivityStore } from "@/stores/activityStore"; import { authClient } from "@/lib/auth-client"; @@ -140,6 +141,7 @@ const BASE_NAV_GROUPS: NavGroup[] = [ items: [ { path: "/dashboard/metrics", label: "Metrics", icon: BarChart3 }, { path: "/dashboard/projects", label: "Projects", icon: FolderOpen }, + { path: "/dashboard/commands", label: "Commands", icon: Timer }, { path: "/dashboard/claudemd", label: "CLAUDE.md", icon: FileText }, ], }, diff --git a/packages/dashboard/src/components/commands/CommandTimings.tsx b/packages/dashboard/src/components/commands/CommandTimings.tsx new file mode 100644 index 0000000..76f259c --- /dev/null +++ b/packages/dashboard/src/components/commands/CommandTimings.tsx @@ -0,0 +1,270 @@ +import { useState, type ReactNode } from "react"; +import { ArrowDown, ArrowUp, Minus } from "lucide-react"; +import { + CartesianGrid, + Line, + LineChart, + ResponsiveContainer, + Tooltip, + XAxis, + YAxis, +} from "recharts"; +import type { CommandGroup, CommandScope, CommandSummary, CommandTrend } from "@devscope/shared"; +import { useCommandsData } from "@/hooks/useCommandsData"; +import { ButtonGroup, ButtonGroupItem } from "@/components/ui/button-group"; +import { MetricCard } from "@/components/ui/metric-card"; +import { ChartCard } from "@/components/insights/ChartCard"; +import { AXIS_STYLE, GRID_STYLE } from "@/components/insights/charts/chartConfig"; +import { + Table, + TableBody, + TableCell, + TableHead, + TableHeader, + TableRow, +} from "@/components/ui/table"; +import { cn } from "@/lib/utils"; +import { formatMs, percentChange } from "./format"; + +// One hue for both lines (p50 solid, p95 dashed): they are two levels of the +// same measure, so line style, the legend and the tooltip carry identity. +// --cmd-trend is set per theme in index.css (validated on both surfaces). +const TREND_COLOR = "var(--cmd-trend)"; + +/** Change in a duration: up is slower, so it reads as worse. */ +function SlowerFaster({ value }: { value: number | null }) { + if (value === null) return –; + if (Math.abs(value) < 5) { + return ( + + + same + + ); + } + const slower = value > 0; + const Icon = slower ? ArrowUp : ArrowDown; + return ( + + + {slower ? "+" : ""} + {value}% {slower ? "slower" : "faster"} + + ); +} + +interface TrendTooltipProps { + active?: boolean; + label?: string | number; + payload?: ReadonlyArray<{ payload?: CommandTrend["points"][number] }>; +} + +function TrendTooltip({ active, label, payload }: TrendTooltipProps) { + const p = payload?.[0]?.payload; + if (!active || !p) return null; + return ( +
+

{String(label)}

+ {p.runs === 0 ? ( +

No runs

+ ) : ( + <> +

+ Median: {formatMs(p.p50_ms)} +

+

+ p95: {formatMs(p.p95_ms)} +

+

+ Runs: {p.runs} + {p.failures > 0 && <> · failed {p.failures}} +

+

+ Waited: {formatMs(p.wait_ms)} +

+ + )} +
+ ); +} + +function LegendKey({ dashed, label }: { dashed?: boolean; label: string }) { + return ( + + + + + {label} + + ); +} + +interface CommandTimingsProps { + days: number; + /** Limit to one project (the project page); null for all projects. */ + project: string | null; + /** More filters for the same row (the page's project and date pickers). */ + filters?: ReactNode; +} + +/** + * Which Bash commands the sessions wait on and whether they are getting + * slower: totals, a table by time waited, and the trend of one command. + */ +export function CommandTimings({ days, project, filters }: CommandTimingsProps) { + const [scope, setScope] = useState("team"); + const [group, setGroup] = useState("signature"); + const [picked, setPicked] = useState(null); + + const summary = useCommandsData("summary", { days, project, scope, group }); + const commands = summary.data?.commands ?? []; + // The picked command, if it is still in the list, else the top one. + const selected = commands.find((c) => c.command === picked)?.command ?? commands[0]?.command ?? null; + const bucket = days > 60 ? "week" : "day"; + const trend = useCommandsData( + "trend", + { days, project, scope, group, command: selected, bucket }, + selected !== null, + ); + + const totals = summary.data?.totals; + const runsDelta = totals ? percentChange(totals.runs, totals.prev_runs) : null; + const waitDelta = totals ? percentChange(totals.wait_ms, totals.prev_wait_ms) : null; + const moved = commands.reduce((a, c) => a + c.moved_runs, 0); + const failures = commands.reduce((a, c) => a + c.failures, 0); + + return ( +
+
+ + setScope("team")}>Team + setScope("me")}>You + + + setGroup("signature")}>Commands + setGroup("program")}>Programs + + {filters} +
+ +
+ 0 ? formatMs(totals.prev_wait_ms) : undefined} + /> + 0 ? totals.prev_runs.toLocaleString() : undefined} + delta={runsDelta ?? undefined} + /> + + +
+ {waitDelta !== null && ( +

+ Waiting time vs the {days} days before: +

+ )} + + + {commands.length === 0 ? ( +
+ No Bash commands recorded{project ? " for this project" : ""} in this period. +
+ ) : ( + // w-0 min-w-full: the table scrolls inside the card instead of + // widening the page on narrow screens. +
+ + + + Command + Runs + Median + p95 + Max + Waited + Median vs before + Failed + + + + {commands.map((c) => ( + setPicked(c.command)} + className={cn("cursor-pointer", c.command === selected && "bg-accent/60")} + aria-selected={c.command === selected} + > + + {c.command} + {c.background_runs > 0 && ( + + {c.background_runs} bg + + )} + {c.running > 0 && ( + + {c.running} unfinished + + )} + + {c.runs} + {formatMs(c.p50_ms)} + {formatMs(c.p95_ms)} + {formatMs(c.max_ms)} + {formatMs(c.wait_ms)} + + = 3 ? percentChange(c.p50_ms, c.prev_p50_ms) : null} /> + + + {c.failures > 0 ? `${Math.round((c.failures / c.runs) * 100)}%` : "–"} + + + ))} + +
+
+ )} +
+ + {selected && ( + + + +
+ } + > + + + + v.slice(5)} minTickGap={24} /> + formatMs(v)} /> + + + + + + + )} + + ); +} diff --git a/packages/dashboard/src/components/commands/CommandsView.tsx b/packages/dashboard/src/components/commands/CommandsView.tsx new file mode 100644 index 0000000..8ceead2 --- /dev/null +++ b/packages/dashboard/src/components/commands/CommandsView.tsx @@ -0,0 +1,48 @@ +import { useState } from "react"; +import type { CommandProjectRow } from "@devscope/shared"; +import { useDateRange } from "@/hooks/useDateRange"; +import { useCommandsData } from "@/hooks/useCommandsData"; +import { DateRangePicker } from "@/components/ui/date-range-picker"; +import { PageHeader } from "@/components/ui/page-header"; +import { CommandTimings } from "./CommandTimings"; + +/** /dashboard/commands: Bash command timing across projects, or one project. */ +export function CommandsView() { + const { days } = useDateRange(); + const [project, setProject] = useState(null); + const projects = useCommandsData("projects", { days }); + + return ( +
+ + + + + + } + /> +
+ ); +} diff --git a/packages/dashboard/src/components/commands/format.ts b/packages/dashboard/src/components/commands/format.ts new file mode 100644 index 0000000..f70693a --- /dev/null +++ b/packages/dashboard/src/components/commands/format.ts @@ -0,0 +1,18 @@ +/** 850 ms · 12.3 s · 4m 05s · 1h 12m */ +export function formatMs(ms: number | null | undefined): string { + if (ms === null || ms === undefined || !Number.isFinite(ms)) return "–"; + if (ms < 1000) return `${Math.round(ms)} ms`; + if (ms < 10_000) return `${(ms / 1000).toFixed(1)} s`; + // Round once, then split, so 3m 59.6s reads 4m 00s rather than 3m 60s. + const total = Math.round(ms / 1000); + if (total < 60) return `${total} s`; + if (total < 3600) return `${Math.floor(total / 60)}m ${String(total % 60).padStart(2, "0")}s`; + const minutes = Math.round(total / 60); + return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, "0")}m`; +} + +/** Percent change from `before` to `now`, or null when there is no baseline. */ +export function percentChange(now: number | null, before: number | null): number | null { + if (now === null || before === null || before <= 0) return null; + return Math.round(((now - before) / before) * 100); +} diff --git a/packages/dashboard/src/components/projects/ProjectDrillDown.tsx b/packages/dashboard/src/components/projects/ProjectDrillDown.tsx index d404c6d..83696a5 100644 --- a/packages/dashboard/src/components/projects/ProjectDrillDown.tsx +++ b/packages/dashboard/src/components/projects/ProjectDrillDown.tsx @@ -18,6 +18,7 @@ import { TableRow, } from "@/components/ui/table"; import { ChartCard } from "@/components/insights/ChartCard"; +import { CommandTimings } from "@/components/commands/CommandTimings"; interface ProjectDrillDownProps { projectName: string; @@ -85,6 +86,11 @@ export function ProjectDrillDown({ projectName, onBack }: ProjectDrillDownProps) + +
+

Command timing

+ +
); } diff --git a/packages/dashboard/src/hooks/useCommandsData.ts b/packages/dashboard/src/hooks/useCommandsData.ts new file mode 100644 index 0000000..7d17a6a --- /dev/null +++ b/packages/dashboard/src/hooks/useCommandsData.ts @@ -0,0 +1,37 @@ +import { useEffect, useState } from "react"; +import { apiFetch } from "@/lib/api"; + +/** GET /api/commands/ with query params; refetches when they change. */ +export function useCommandsData( + endpoint: "summary" | "trend" | "projects", + params: Record, + enabled = true, +) { + const qs = new URLSearchParams(); + for (const [k, v] of Object.entries(params)) { + if (v !== null && v !== undefined && v !== "") qs.set(k, String(v)); + } + const url = `/api/commands/${endpoint}?${qs.toString()}`; + const [data, setData] = useState(null); + const [loadedUrl, setLoadedUrl] = useState(null); + + useEffect(() => { + if (!enabled) return; + let cancelled = false; + apiFetch(url) + .then((r) => (r.ok ? r.json() : null)) + .then((d) => { + if (cancelled) return; + setData(d as T | null); + setLoadedUrl(url); + }) + .catch(() => { + if (!cancelled) setLoadedUrl(url); + }); + return () => { + cancelled = true; + }; + }, [url, enabled]); + + return { data: loadedUrl === url ? data : null, loading: enabled && loadedUrl !== url }; +} diff --git a/packages/dashboard/src/index.css b/packages/dashboard/src/index.css index ef3c32d..765ec48 100644 --- a/packages/dashboard/src/index.css +++ b/packages/dashboard/src/index.css @@ -79,9 +79,12 @@ --sidebar-accent-foreground: oklch(0.205 0 0); --sidebar-border: oklch(0.922 0 0); --sidebar-ring: oklch(0.708 0 0); + /* Command timing trend line (validated against the light surface). */ + --cmd-trend: #2a78d6; } .dark { + --cmd-trend: #3987e5; --background: oklch(0.145 0 0); --foreground: oklch(0.985 0 0); --card: oklch(0.205 0 0); diff --git a/packages/dashboard/src/lib/eventDisplay.ts b/packages/dashboard/src/lib/eventDisplay.ts index 32bb8b6..510e7df 100644 --- a/packages/dashboard/src/lib/eventDisplay.ts +++ b/packages/dashboard/src/lib/eventDisplay.ts @@ -44,6 +44,8 @@ export const EVENT_COLORS: Record = { "plugin.setup": "border-sky-500/30 bg-sky-500/5", // Added in plugin 0.35.0 "model.first_use": "border-fuchsia-500/50 bg-fuchsia-500/10", + // Added in plugin 0.38.0 + "command.background_complete": "border-slate-500/30 bg-slate-500/5", }; export const EVENT_LABELS: Record = { @@ -80,6 +82,8 @@ export const EVENT_LABELS: Record = { "plugin.setup": "Plugin Setup", // Added in plugin 0.35.0 "model.first_use": "New Model", + // Added in plugin 0.38.0 + "command.background_complete": "Background Command Finished", }; export function getEventSummary(event: FeedEvent): string { @@ -178,6 +182,12 @@ export function getEventSummary(event: FeedEvent): string { const prev = p.previousModel ? ` (from ${String(p.previousModel)})` : ""; return model ? `First use of ${model}${prev}` : "First use of a model"; } + case "command.background_complete": { + const commands = Array.isArray(p.commands) ? (p.commands as Array<{ status?: string }>) : []; + const failed = commands.filter((c) => c.status !== "completed").length; + const what = commands.length === 1 ? "1 background command" : `${commands.length} background commands`; + return failed > 0 ? `${what} finished, ${failed} failed or stopped` : `${what} finished`; + } default: return event.eventType; } diff --git a/packages/shared/src/commands.ts b/packages/shared/src/commands.ts new file mode 100644 index 0000000..2dfedf4 --- /dev/null +++ b/packages/shared/src/commands.ts @@ -0,0 +1,63 @@ +// Bash command timing (command_runs, migration 058; /api/commands). +// Rows carry commands and projects, never developers. + +export type CommandScope = "team" | "me"; +export type CommandGroup = "signature" | "program"; + +/** One command (signature or program) over the period, with the period before for comparison. */ +export interface CommandSummaryRow { + /** "bun run build"; a teammate's session that is not shared counts under its program ("bun"). */ + command: string; + runs: number; + failures: number; + interrupted: number; + /** run_in_background */ + background_runs: number; + /** started in the foreground and moved to the background (timeout or user) */ + moved_runs: number; + /** background commands not reported as settled */ + running: number; + p50_ms: number | null; + p95_ms: number | null; + max_ms: number | null; + /** time the sessions waited on it (foreground time, plus time until backgrounding) */ + wait_ms: number; + /** start-to-finish time of every run that finished */ + total_ms: number; + prev_runs: number; + prev_p50_ms: number | null; + prev_wait_ms: number; +} + +export interface CommandSummary { + days: number; + scope: CommandScope; + group: CommandGroup; + project: string | null; + totals: { runs: number; wait_ms: number; prev_runs: number; prev_wait_ms: number }; + commands: CommandSummaryRow[]; +} + +export interface CommandTrendPoint { + /** bucket start, ISO date */ + bucket: string; + runs: number; + failures: number; + p50_ms: number | null; + p95_ms: number | null; + wait_ms: number; +} + +export interface CommandTrend { + days: number; + bucket: "day" | "week"; + command: string | null; + project: string | null; + points: CommandTrendPoint[]; +} + +export interface CommandProjectRow { + project: string; + runs: number; + wait_ms: number; +} diff --git a/packages/shared/src/events.ts b/packages/shared/src/events.ts index 29d1f69..430da23 100644 --- a/packages/shared/src/events.ts +++ b/packages/shared/src/events.ts @@ -34,7 +34,9 @@ export type EventType = | "directory.added" | "plugin.setup" // Added in plugin 0.35.0: the first time a model is used on a machine. - | "model.first_use"; + | "model.first_use" + // Added in plugin 0.38.0: background Bash commands that settled. + | "command.background_complete"; export interface DevscopeEvent { id: string; @@ -127,6 +129,22 @@ export interface ToolEventPayload { errorMessage?: string; isInterrupt?: boolean; agentId?: string | null; + // Bash only, plugin 0.38.0+ (see command_runs, migration 058). + toolUseId?: string; + commandSignature?: string; + backgroundTaskId?: string; + runInBackground?: boolean; +} + +/** command.background_complete: background Bash commands that settled since the last report. */ +export interface CommandBackgroundCompletePayload { + commands: Array<{ + toolUseId: string; + taskId?: string; + status: "completed" | "failed" | "killed" | string; + exitCode?: number; + finishedAt: string; + }>; } export interface AgentEventPayload { diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts index 090db13..857f68f 100644 --- a/packages/shared/src/index.ts +++ b/packages/shared/src/index.ts @@ -9,3 +9,4 @@ export * from "./topology"; export * from "./workflowProfiles"; export * from "./similarity"; export * from "./live"; +export * from "./commands"; From b6d05bf45198aac479a90adce1ab54a2f482812c Mon Sep 17 00:00:00 2001 From: Lucas Proxmox Date: Thu, 5 Nov 2026 15:34:13 +0100 Subject: [PATCH 2/3] fix(commands): totals cover every command; drop stale data on fetch errors - CommandSummary.totals now also carries failures and moved_runs, summed over every command before the list is cut to `limit`, so the "Failed" and "Hit the timeout" cards no longer under-count past 50 commands. - useCommandsData clears data when a request rejects, so a failed fetch for new filters never shows the previous filters' results. Both from CodeRabbit review on #95. Co-Authored-By: Claude Opus 5.5 --- packages/backend/src/db/__tests__/commandQueries.test.ts | 5 +++++ packages/backend/src/db/commandQueries.ts | 7 +++++-- .../dashboard/src/components/commands/CommandTimings.tsx | 4 ++-- packages/dashboard/src/hooks/useCommandsData.ts | 4 +++- packages/shared/src/commands.ts | 3 ++- 5 files changed, 17 insertions(+), 6 deletions(-) diff --git a/packages/backend/src/db/__tests__/commandQueries.test.ts b/packages/backend/src/db/__tests__/commandQueries.test.ts index 1b1ab84..0c3cacc 100644 --- a/packages/backend/src/db/__tests__/commandQueries.test.ts +++ b/packages/backend/src/db/__tests__/commandQueries.test.ts @@ -208,6 +208,11 @@ d("command_runs — ingestion, background settling, reads", () => { expect(by["bun run dev"]!.background_runs).toBe(1); expect(s.totals.prev_runs).toBe(1); expect(s.totals.runs).toBe(s.commands.reduce((a, c) => a + c.runs, 0)); + // Totals cover every command, also those cut off by `limit`. + const cut = await getCommandSummary(sql, scope(), "signature", 1); + expect(cut.commands.length).toBe(1); + expect([cut.totals.runs, cut.totals.failures, cut.totals.moved_runs]) + .toEqual([s.totals.runs, s.commands.reduce((a, c) => a + c.failures, 0), 1]); }); test("the teammate sees their own signature", async () => { diff --git a/packages/backend/src/db/commandQueries.ts b/packages/backend/src/db/commandQueries.ts index 0671c04..307d95e 100644 --- a/packages/backend/src/db/commandQueries.ts +++ b/packages/backend/src/db/commandQueries.ts @@ -169,7 +169,7 @@ export async function getCommandSummary( days: scope.days, group, project: scope.project, - totals: { runs: 0, wait_ms: 0, prev_runs: 0, prev_wait_ms: 0 }, + totals: { runs: 0, wait_ms: 0, failures: 0, moved_runs: 0, prev_runs: 0, prev_wait_ms: 0 }, commands: [] as CommandSummaryRow[], }; if (scope.devIds.length === 0) return empty; @@ -201,10 +201,13 @@ export async function getCommandSummary( ORDER BY wait_ms DESC, runs DESC, command `) as CommandSummaryRow[]; - const totals = { runs: 0, wait_ms: 0, prev_runs: 0, prev_wait_ms: 0 }; + // Summed over every command before the list is cut to `limit`. + const totals = { runs: 0, wait_ms: 0, failures: 0, moved_runs: 0, prev_runs: 0, prev_wait_ms: 0 }; for (const r of rows) { totals.runs += r.runs; totals.wait_ms += r.wait_ms; + totals.failures += r.failures; + totals.moved_runs += r.moved_runs; } // Previous-period totals include commands that did not run this period. const [prev] = (await sql` diff --git a/packages/dashboard/src/components/commands/CommandTimings.tsx b/packages/dashboard/src/components/commands/CommandTimings.tsx index 76f259c..c280bd3 100644 --- a/packages/dashboard/src/components/commands/CommandTimings.tsx +++ b/packages/dashboard/src/components/commands/CommandTimings.tsx @@ -134,8 +134,8 @@ export function CommandTimings({ days, project, filters }: CommandTimingsProps) const totals = summary.data?.totals; const runsDelta = totals ? percentChange(totals.runs, totals.prev_runs) : null; const waitDelta = totals ? percentChange(totals.wait_ms, totals.prev_wait_ms) : null; - const moved = commands.reduce((a, c) => a + c.moved_runs, 0); - const failures = commands.reduce((a, c) => a + c.failures, 0); + const moved = totals?.moved_runs ?? 0; + const failures = totals?.failures ?? 0; return (
diff --git a/packages/dashboard/src/hooks/useCommandsData.ts b/packages/dashboard/src/hooks/useCommandsData.ts index 7d17a6a..8ddb8d6 100644 --- a/packages/dashboard/src/hooks/useCommandsData.ts +++ b/packages/dashboard/src/hooks/useCommandsData.ts @@ -26,7 +26,9 @@ export function useCommandsData( setLoadedUrl(url); }) .catch(() => { - if (!cancelled) setLoadedUrl(url); + if (cancelled) return; + setData(null); // never show the previous filter's results as this one's + setLoadedUrl(url); }); return () => { cancelled = true; diff --git a/packages/shared/src/commands.ts b/packages/shared/src/commands.ts index 2dfedf4..3fd812d 100644 --- a/packages/shared/src/commands.ts +++ b/packages/shared/src/commands.ts @@ -34,7 +34,8 @@ export interface CommandSummary { scope: CommandScope; group: CommandGroup; project: string | null; - totals: { runs: number; wait_ms: number; prev_runs: number; prev_wait_ms: number }; + /** Over every command, not only the `limit` returned. */ + totals: { runs: number; wait_ms: number; failures: number; moved_runs: number; prev_runs: number; prev_wait_ms: number }; commands: CommandSummaryRow[]; } From c3cacf263be95f51c24286bf346441ea32c5e867 Mon Sep 17 00:00:00 2001 From: Lucas Proxmox Date: Thu, 5 Nov 2026 15:50:07 +0100 Subject: [PATCH 3/3] fix(commands): only programs with subcommands keep words in a signature cleanSignature now stores more than the program only for programs that take subcommands (MULTI, the same list as the plugin's multi), so an operand such as a file name (`cat confidential`) can never be stored, whatever a plugin sends. From CodeRabbit review on DowLucas/devscope-plugin#49. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 9 +++---- .../src/db/__tests__/commandQueries.test.ts | 3 +++ packages/backend/src/db/commandQueries.ts | 24 +++++++++++++++---- 3 files changed, 28 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 9dfd4ea..0b3ceba 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -231,10 +231,11 @@ How long the Bash commands Claude runs take, per project and over time (`command 0.38.0+), else `event:` with `legacy_timing` set. `wait_ms` is the event's `duration` (Claude Code's `duration_ms` since plugin 0.38.0; before that the plugin's own timer, which mixed up parallel calls); the start is the event timestamp minus it. -- **Signature, never the command.** The plugin sends `commandSignature` (`_ds_command_signature`: program + - up to two plain words, the third only after a group word like `run`/`compose`/`pr`; private mode the - program only). `cleanSignature` re-checks the shape and falls back to the program, and private sessions - store the program whatever was sent. Older plugins only have `toolSubcommand` (the first word). +- **Signature, never the command.** The plugin sends `commandSignature` (`_ds_command_signature`: quotes and + heredocs removed; program + up to two plain words only for programs that take subcommands, the third only + after a group word like `run`/`compose`/`pr`; any other program alone; private mode the program only). + `cleanSignature` re-checks the shape and the same subcommand list (`MULTI`, keep in sync with the + plugin's `multi`) and falls back to the program, and private sessions store the program whatever was sent. Older plugins only have `toolSubcommand` (the first word). - **Background commands.** PostToolUse fires when a command is backgrounded (`run_in_background` → `background`; a timeout or the user → `moved`), so the row starts as `running` with `duration_ms` NULL. The plugin finds the settling in the transcript (`queue-operation` enqueue of a ``) at Stop diff --git a/packages/backend/src/db/__tests__/commandQueries.test.ts b/packages/backend/src/db/__tests__/commandQueries.test.ts index 0c3cacc..a8ca81c 100644 --- a/packages/backend/src/db/__tests__/commandQueries.test.ts +++ b/packages/backend/src/db/__tests__/commandQueries.test.ts @@ -31,6 +31,9 @@ describe("cleanSignature", () => { expect(cleanSignature("rm -rf /home/someone/secret")).toBe("rm"); expect(cleanSignature("git commit -m hello world")).toBe("git"); expect(cleanSignature("a b c d")).toBe("a"); + // Words after a program without subcommands are operands. + expect(cleanSignature("cat confidential")).toBe("cat"); + expect(cleanSignature("ssh prod-db")).toBe("ssh"); expect(cleanSignature("/usr/bin/env")).toBe("usrbinenv"); expect(cleanSignature(" ")).toBeNull(); expect(cleanSignature(42)).toBeNull(); diff --git a/packages/backend/src/db/commandQueries.ts b/packages/backend/src/db/commandQueries.ts index 307d95e..7a23eed 100644 --- a/packages/backend/src/db/commandQueries.ts +++ b/packages/backend/src/db/commandQueries.ts @@ -22,15 +22,31 @@ const MAX_MS = 2_147_483_647; const SIGNATURE = /^[a-z0-9._+-]{1,40}( [a-z][a-z0-9_:-]{0,23}){0,2}$/; /** - * The stored signature: what the plugin sent when it has the expected shape, - * else its first word reduced to program characters. Defence in depth: the - * column must never hold command text, whatever a plugin sends. + * Programs whose next word names what they do (a subcommand, script, target or + * tool), the only ones whose signature may have more than one word. The same + * list as `multi` in the plugin's `_ds_command_signature`: change both. + */ +const MULTI = new Set([ + "git", "gh", "glab", "docker", "podman", "kubectl", "helm", "terraform", "tofu", + "npm", "pnpm", "yarn", "bun", "bunx", "npx", "deno", "cargo", "rustup", + "go", "uv", "uvx", "pip", "pip3", "poetry", "pdm", "hatch", "conda", + "brew", "apt", "apt-get", "dnf", "systemctl", "journalctl", "make", "just", "task", + "claude", "gcloud", "aws", "az", "fly", "flyctl", "vercel", "wrangler", "supabase", + "firebase", "dotnet", "mvn", "gradle", "gradlew", "mix", "rails", "bundle", "rake", + "composer", "swift", "xcodebuild", "zig", "nix", +]); + +/** + * The stored signature: what the plugin sent when it has the expected shape + * (more than one word only for a program in MULTI), else its first word + * reduced to program characters. Defence in depth: the column must never hold + * command text, whatever a plugin sends. */ export function cleanSignature(raw: unknown): string | null { if (typeof raw !== "string") return null; const s = raw.trim().toLowerCase().replace(/\s+/g, " "); - if (SIGNATURE.test(s)) return s; const program = (s.split(" ")[0] ?? "").replace(/[^a-z0-9._+-]/g, "").slice(0, 40); + if (SIGNATURE.test(s) && (!s.includes(" ") || MULTI.has(program))) return s; return program || null; }