agent-profiler 0.1.0 → 1.0.0

package/README.md

@@ -0,0 +1,66 @@
+# agent-profiler
+
+Local-first profiling for AI coding agents.
+
+`agent-profiler` captures local Cursor and Codex hook events into SQLite so you can inspect recent sessions, setup state, and always-on context overhead without sending data to a remote service.
+
+## Requirements
+
+- Node.js 22 or newer
+- macOS, Linux, or another environment supported by `better-sqlite3`
+
+## Install
+
+For one-off commands, use `npx`:
+
+```bash
+npx agent-profiler --help
+npx agent-profiler last
+```
+
+For persistent hook installation, install the package so `agent-profiler` is available on `PATH`:
+
+```bash
+npm install -g agent-profiler
+agent-profiler --help
+```
+
+## Quick Start
+
+Initialize hooks for Cursor:
+
+```bash
+agent-profiler init cursor --mode prod
+```
+
+Initialize hooks for Codex:
+
+```bash
+agent-profiler init codex --mode prod
+```
+
+Inspect the resulting setup and the latest captured session:
+
+```bash
+agent-profiler status
+agent-profiler last
+agent-profiler audit context
+```
+
+## `npx` vs `--mode prod`
+
+- `npx agent-profiler ...` is great for one-off inspection commands.
+- `agent-profiler init <source> --mode prod` writes persistent hook commands that expect `agent-profiler` to be installed on `PATH`.
+- `--mode dev` is meant for local development in this repository and writes absolute `node <repo>/dist/cli.js ...` hook commands instead.
+
+## Commands
+
+- `agent-profiler init <cursor|codex>`: install hook wiring for a supported source
+- `agent-profiler hook <source> <eventName>`: ingest one hook payload from stdin
+- `agent-profiler status`: inspect local setup and ingest state
+- `agent-profiler last`: summarize the most recent observed session
+- `agent-profiler audit context`: estimate always-on context token footprint
+
+## Releases
+
+Releases are automated with semantic-release. Pull requests run CI plus canary publishing, and pushes to `main` publish to npm and create a GitHub release.

package/dist/cli.js

@@ -1,20 +1,21 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { getAuditContextReport, runAuditContext } from "./commands/auditContext.js";
+import { getAuditContextReport, runAuditContext, } from "./commands/auditContext.js";
 import { runHook } from "./commands/hook.js";
 import { runInit } from "./commands/init.js";
 import { getLastReport, runLast } from "./commands/last.js";
 import { getStatusReport, runStatus } from "./commands/status.js";
+import { getPackageVersion } from "./core/packageMeta.js";
 const program = new Command();
 program
     .name("agent-profiler")
     .description("Local-first profiling for AI coding agents.")
-    .version("0.1.0");
+    .version(getPackageVersion());
 program
     .command("init")
     .description("Initialize Agent Profiler for a supported source.")
     .argument("<source>", "supported: cursor | codex")
-    .option("--mode <mode>", "init mode: dev or prod", "dev")
+    .option("--mode <mode>", "init mode: dev or prod (prod requires `agent-profiler` on PATH)", "dev")
     .action((source, options) => {
     const allowed = ["cursor", "codex"];
     if (!allowed.includes(source)) {
@@ -60,7 +61,7 @@ program
 program
     .command("status")
     .description("Show local Agent Profiler setup and ingest status.")
-    .option("--mode <mode>", "status mode: dev or prod", "dev")
+    .option("--mode <mode>", "status mode: dev or prod (prod expects a global install on PATH)", "dev")
     .option("--json", "Output status as JSON")
     .action((options) => {
     if (options.mode !== "dev" && options.mode !== "prod") {

package/dist/commands/init.js

@@ -250,6 +250,10 @@ export function runInit(source, mode = "dev") {
     console.log(`Config:   ${configPath}`);
     console.log(`Database: ${resolvedDbPath}`);
     console.log(`Hooks:    ${hooksPath}`);
+    if (mode === "prod") {
+        console.log("Note:     Prod mode requires a real `agent-profiler` install on PATH.");
+        console.log("          Use `npx agent-profiler ...` for one-off commands only.");
+    }
     if (usedFallbackConfigPath) {
         console.log("Note:     Could not write home config in this environment; wrote local config instead.");
     }

package/dist/commands/status.js

@@ -105,19 +105,31 @@ function getCursorSetupStatus(configPath, mode) {
     const sampleCommand = hookEntryCommand(hooks.beforeSubmitPrompt);
     if (mode === "dev") {
         if (!sampleCommand.startsWith("node ")) {
-            return { state: "partial", note: "dev mode expects hooks to use `node <abs>/dist/cli.js ...`" };
+            return {
+                state: "partial",
+                note: "dev mode expects hooks to use `node <abs>/dist/cli.js ...`",
+            };
         }
         const cliPath = sampleCommand.split(" ")[1];
         if (!cliPath || !fs.existsSync(cliPath)) {
-            return { state: "partial", note: "dev hook CLI path is missing or invalid" };
+            return {
+                state: "partial",
+                note: "dev hook CLI path is missing or invalid",
+            };
         }
     }
     else {
         if (!sampleCommand.startsWith("agent-profiler ")) {
-            return { state: "partial", note: "prod mode expects hooks to use `agent-profiler ...`" };
+            return {
+                state: "partial",
+                note: "prod mode expects hooks to use `agent-profiler ...` from a real install on PATH",
+            };
         }
         if (!commandExistsInPath("agent-profiler")) {
-            return { state: "partial", note: "`agent-profiler` is not on PATH" };
+            return {
+                state: "partial",
+                note: "`agent-profiler` is not on PATH; `npx` only covers one-off commands",
+            };
         }
     }
     return { state: "yes", note: "configured via init" };
@@ -148,23 +160,38 @@ function getCodexSetupStatus(configPath, mode) {
         }
     }
     if (!sampleCommand) {
-        return { state: "partial", note: "could not find agent-profiler command in Codex hooks" };
+        return {
+            state: "partial",
+            note: "could not find agent-profiler command in Codex hooks",
+        };
     }
     if (mode === "dev") {
         if (!sampleCommand.startsWith("node ")) {
-            return { state: "partial", note: "dev mode expects hooks to use `node <abs>/dist/cli.js ...`" };
+            return {
+                state: "partial",
+                note: "dev mode expects hooks to use `node <abs>/dist/cli.js ...`",
+            };
         }
         const cliPath = sampleCommand.split(" ")[1];
         if (!cliPath || !fs.existsSync(cliPath)) {
-            return { state: "partial", note: "dev hook CLI path is missing or invalid" };
+            return {
+                state: "partial",
+                note: "dev hook CLI path is missing or invalid",
+            };
         }
     }
     else {
         if (!sampleCommand.startsWith("agent-profiler ")) {
-            return { state: "partial", note: "prod mode expects hooks to use `agent-profiler ...`" };
+            return {
+                state: "partial",
+                note: "prod mode expects hooks to use `agent-profiler ...` from a real install on PATH",
+            };
         }
         if (!commandExistsInPath("agent-profiler")) {
-            return { state: "partial", note: "`agent-profiler` is not on PATH" };
+            return {
+                state: "partial",
+                note: "`agent-profiler` is not on PATH; `npx` only covers one-off commands",
+            };
         }
     }
     return { state: "yes", note: "configured via init" };

package/dist/core/db.js

@@ -56,27 +56,122 @@ export function applySchema(db) {
     const schemaSql = fs.readFileSync(SCHEMA_PATH, "utf8");
     db.exec(schemaSql);
     migrateEventsSchema(db);
+    migrateInteractionSpansSchema(db);
 }
-function migrateEventsSchema(db) {
-    const columns = db.prepare(`PRAGMA table_info(events)`).all();
+function migrateTableColumns(db, tableName, columnsToAdd) {
+    const columns = db.prepare(`PRAGMA table_info(${tableName})`).all();
     const names = new Set(columns.map((c) => c.name));
-    const add = (sql, colName) => {
-        if (!names.has(colName)) {
-            db.exec(sql);
-            names.add(colName);
+    for (const column of columnsToAdd) {
+        if (!names.has(column.name)) {
+            db.exec(column.sql);
+            names.add(column.name);
         }
-    };
-    add(`ALTER TABLE events ADD COLUMN workspace_path TEXT`, "workspace_path");
-    add(`ALTER TABLE events ADD COLUMN git_repo_root TEXT`, "git_repo_root");
-    add(`ALTER TABLE events ADD COLUMN git_repo_name TEXT`, "git_repo_name");
-    add(`ALTER TABLE events ADD COLUMN git_branch TEXT`, "git_branch");
-    add(`ALTER TABLE events ADD COLUMN interaction_kind TEXT`, "interaction_kind");
-    add(`ALTER TABLE events ADD COLUMN correlation_id TEXT`, "correlation_id");
-    add(`ALTER TABLE events ADD COLUMN tool_canonical_name TEXT`, "tool_canonical_name");
-    add(`ALTER TABLE events ADD COLUMN mcp_server TEXT`, "mcp_server");
-    add(`ALTER TABLE events ADD COLUMN mcp_tool TEXT`, "mcp_tool");
-    add(`ALTER TABLE events ADD COLUMN payload_byte_length INTEGER`, "payload_byte_length");
-    add(`ALTER TABLE events ADD COLUMN prompt_fingerprint TEXT`, "prompt_fingerprint");
+    }
+}
+function migrateEventsSchema(db) {
+    migrateTableColumns(db, "events", [
+        { name: "workspace_path", sql: `ALTER TABLE events ADD COLUMN workspace_path TEXT` },
+        {
+            name: "workspace_home_rel_path",
+            sql: `ALTER TABLE events ADD COLUMN workspace_home_rel_path TEXT`,
+        },
+        {
+            name: "workspace_display_path",
+            sql: `ALTER TABLE events ADD COLUMN workspace_display_path TEXT`,
+        },
+        { name: "git_repo_root", sql: `ALTER TABLE events ADD COLUMN git_repo_root TEXT` },
+        {
+            name: "git_repo_root_home_rel_path",
+            sql: `ALTER TABLE events ADD COLUMN git_repo_root_home_rel_path TEXT`,
+        },
+        {
+            name: "git_repo_root_display_path",
+            sql: `ALTER TABLE events ADD COLUMN git_repo_root_display_path TEXT`,
+        },
+        { name: "git_repo_name", sql: `ALTER TABLE events ADD COLUMN git_repo_name TEXT` },
+        { name: "git_branch", sql: `ALTER TABLE events ADD COLUMN git_branch TEXT` },
+        {
+            name: "interaction_kind",
+            sql: `ALTER TABLE events ADD COLUMN interaction_kind TEXT`,
+        },
+        { name: "correlation_id", sql: `ALTER TABLE events ADD COLUMN correlation_id TEXT` },
+        {
+            name: "tool_canonical_name",
+            sql: `ALTER TABLE events ADD COLUMN tool_canonical_name TEXT`,
+        },
+        { name: "mcp_server", sql: `ALTER TABLE events ADD COLUMN mcp_server TEXT` },
+        { name: "mcp_tool", sql: `ALTER TABLE events ADD COLUMN mcp_tool TEXT` },
+        {
+            name: "payload_byte_length",
+            sql: `ALTER TABLE events ADD COLUMN payload_byte_length INTEGER`,
+        },
+        {
+            name: "prompt_fingerprint",
+            sql: `ALTER TABLE events ADD COLUMN prompt_fingerprint TEXT`,
+        },
+    ]);
+}
+function migrateInteractionSpansSchema(db) {
+    migrateTableColumns(db, "interaction_spans", [
+        { name: "turn_id", sql: `ALTER TABLE interaction_spans ADD COLUMN turn_id TEXT` },
+        {
+            name: "tool_canonical_name",
+            sql: `ALTER TABLE interaction_spans ADD COLUMN tool_canonical_name TEXT`,
+        },
+        { name: "mcp_server", sql: `ALTER TABLE interaction_spans ADD COLUMN mcp_server TEXT` },
+        { name: "mcp_tool", sql: `ALTER TABLE interaction_spans ADD COLUMN mcp_tool TEXT` },
+        {
+            name: "pre_event_id",
+            sql: `ALTER TABLE interaction_spans ADD COLUMN pre_event_id INTEGER`,
+        },
+        {
+            name: "post_event_id",
+            sql: `ALTER TABLE interaction_spans ADD COLUMN post_event_id INTEGER`,
+        },
+        {
+            name: "failure_event_id",
+            sql: `ALTER TABLE interaction_spans ADD COLUMN failure_event_id INTEGER`,
+        },
+        {
+            name: "arg_token_estimate",
+            sql: `ALTER TABLE interaction_spans ADD COLUMN arg_token_estimate INTEGER DEFAULT 0`,
+        },
+        {
+            name: "result_token_estimate",
+            sql: `ALTER TABLE interaction_spans ADD COLUMN result_token_estimate INTEGER DEFAULT 0`,
+        },
+        {
+            name: "workspace_path",
+            sql: `ALTER TABLE interaction_spans ADD COLUMN workspace_path TEXT`,
+        },
+        {
+            name: "workspace_home_rel_path",
+            sql: `ALTER TABLE interaction_spans ADD COLUMN workspace_home_rel_path TEXT`,
+        },
+        {
+            name: "workspace_display_path",
+            sql: `ALTER TABLE interaction_spans ADD COLUMN workspace_display_path TEXT`,
+        },
+        {
+            name: "git_repo_root",
+            sql: `ALTER TABLE interaction_spans ADD COLUMN git_repo_root TEXT`,
+        },
+        {
+            name: "git_repo_root_home_rel_path",
+            sql: `ALTER TABLE interaction_spans ADD COLUMN git_repo_root_home_rel_path TEXT`,
+        },
+        {
+            name: "git_repo_root_display_path",
+            sql: `ALTER TABLE interaction_spans ADD COLUMN git_repo_root_display_path TEXT`,
+        },
+        {
+            name: "git_repo_name",
+            sql: `ALTER TABLE interaction_spans ADD COLUMN git_repo_name TEXT`,
+        },
+        { name: "git_branch", sql: `ALTER TABLE interaction_spans ADD COLUMN git_branch TEXT` },
+        { name: "started_at", sql: `ALTER TABLE interaction_spans ADD COLUMN started_at TEXT` },
+        { name: "completed_at", sql: `ALTER TABLE interaction_spans ADD COLUMN completed_at TEXT` },
+    ]);
     db.exec(`CREATE INDEX IF NOT EXISTS idx_events_workspace ON events(workspace_path, created_at)`);
     db.exec(`CREATE INDEX IF NOT EXISTS idx_events_interaction_kind ON events(interaction_kind, created_at)`);
     db.exec(`CREATE INDEX IF NOT EXISTS idx_events_correlation ON events(correlation_id, session_id)`);
@@ -85,6 +180,9 @@ function migrateEventsSchema(db) {
     db.exec(`CREATE INDEX IF NOT EXISTS idx_spans_session ON interaction_spans(session_key, started_at)`);
 }
 export function insertEvent(db, event, payloadHash, workspaceGit, derived) {
+    // Keep raw payloads verbatim for forensics and stable hashes; path redaction is a
+    // separate privacy decision from the derived `~/...` metadata stored alongside them.
+    const rawPayloadJson = JSON.stringify(event.rawPayload);
     const stmt = db.prepare(`
     INSERT INTO events (
       created_at,
@@ -101,7 +199,11 @@ export function insertEvent(db, event, payloadHash, workspaceGit, derived) {
       payload_hash,
       raw_payload,
       workspace_path,
+      workspace_home_rel_path,
+      workspace_display_path,
       git_repo_root,
+      git_repo_root_home_rel_path,
+      git_repo_root_display_path,
       git_repo_name,
       git_branch,
       interaction_kind,
@@ -112,9 +214,9 @@ export function insertEvent(db, event, payloadHash, workspaceGit, derived) {
       payload_byte_length,
       prompt_fingerprint
     )
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `);
-    const info = stmt.run(new Date().toISOString(), event.source, event.sourceEvent, event.repoPath ?? null, event.sessionId ?? null, event.turnId ?? null, event.model ?? null, event.role, event.estimatedInputTokens, event.estimatedOutputTokens, event.estimatedTotalTokens, payloadHash, JSON.stringify(event.rawPayload), workspaceGit.workspacePath, workspaceGit.gitRepoRoot, workspaceGit.gitRepoName, workspaceGit.gitBranch, derived.interactionKind, derived.correlationId, derived.toolCanonicalName, derived.mcpServer, derived.mcpTool, derived.payloadByteLength, derived.promptFingerprint);
+    const info = stmt.run(new Date().toISOString(), event.source, event.sourceEvent, event.repoPath ?? null, event.sessionId ?? null, event.turnId ?? null, event.model ?? null, event.role, event.estimatedInputTokens, event.estimatedOutputTokens, event.estimatedTotalTokens, payloadHash, rawPayloadJson, workspaceGit.workspacePath, workspaceGit.workspaceHomeRelPath, workspaceGit.workspaceDisplayPath, workspaceGit.gitRepoRoot, workspaceGit.gitRepoRootHomeRelPath, workspaceGit.gitRepoRootDisplayPath, workspaceGit.gitRepoName, workspaceGit.gitBranch, derived.interactionKind, derived.correlationId, derived.toolCanonicalName, derived.mcpServer, derived.mcpTool, derived.payloadByteLength, derived.promptFingerprint);
     return Number(info.lastInsertRowid);
 }
 /**
@@ -143,19 +245,21 @@ export function mergeInteractionSpan(db, eventId, normalized, workspaceGit, deri
         tool_canonical_name, mcp_server, mcp_tool,
         pre_event_id, post_event_id, failure_event_id,
         arg_token_estimate, result_token_estimate,
-        workspace_path, git_repo_root, git_repo_name, git_branch,
+        workspace_path, workspace_home_rel_path, workspace_display_path,
+        git_repo_root, git_repo_root_home_rel_path, git_repo_root_display_path,
+        git_repo_name, git_branch,
         started_at, completed_at
       )
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
         if (derived.toolPhase === "pre") {
-            ins.run(sessionKey, source, derived.correlationId, normalized.turnId ?? null, toolName, mcpS, mcpT, eventId, null, null, argTok, 0, workspaceGit.workspacePath, workspaceGit.gitRepoRoot, workspaceGit.gitRepoName, workspaceGit.gitBranch, now, null);
+            ins.run(sessionKey, source, derived.correlationId, normalized.turnId ?? null, toolName, mcpS, mcpT, eventId, null, null, argTok, 0, workspaceGit.workspacePath, workspaceGit.workspaceHomeRelPath, workspaceGit.workspaceDisplayPath, workspaceGit.gitRepoRoot, workspaceGit.gitRepoRootHomeRelPath, workspaceGit.gitRepoRootDisplayPath, workspaceGit.gitRepoName, workspaceGit.gitBranch, now, null);
         }
         else if (derived.toolPhase === "post") {
-            ins.run(sessionKey, source, derived.correlationId, normalized.turnId ?? null, toolName, mcpS, mcpT, null, eventId, null, 0, resTok, workspaceGit.workspacePath, workspaceGit.gitRepoRoot, workspaceGit.gitRepoName, workspaceGit.gitBranch, null, now);
+            ins.run(sessionKey, source, derived.correlationId, normalized.turnId ?? null, toolName, mcpS, mcpT, null, eventId, null, 0, resTok, workspaceGit.workspacePath, workspaceGit.workspaceHomeRelPath, workspaceGit.workspaceDisplayPath, workspaceGit.gitRepoRoot, workspaceGit.gitRepoRootHomeRelPath, workspaceGit.gitRepoRootDisplayPath, workspaceGit.gitRepoName, workspaceGit.gitBranch, null, now);
         }
         else {
-            ins.run(sessionKey, source, derived.correlationId, normalized.turnId ?? null, toolName, mcpS, mcpT, null, null, eventId, 0, resTok, workspaceGit.workspacePath, workspaceGit.gitRepoRoot, workspaceGit.gitRepoName, workspaceGit.gitBranch, null, now);
+            ins.run(sessionKey, source, derived.correlationId, normalized.turnId ?? null, toolName, mcpS, mcpT, null, null, eventId, 0, resTok, workspaceGit.workspacePath, workspaceGit.workspaceHomeRelPath, workspaceGit.workspaceDisplayPath, workspaceGit.gitRepoRoot, workspaceGit.gitRepoRootHomeRelPath, workspaceGit.gitRepoRootDisplayPath, workspaceGit.gitRepoName, workspaceGit.gitBranch, null, now);
         }
         return;
     }
@@ -164,33 +268,57 @@ export function mergeInteractionSpan(db, eventId, normalized, workspaceGit, deri
         pre_event_id = COALESCE(pre_event_id, ?),
         started_at = COALESCE(started_at, ?),
         arg_token_estimate = ?,
+        workspace_path = COALESCE(workspace_path, ?),
+        workspace_home_rel_path = COALESCE(workspace_home_rel_path, ?),
+        workspace_display_path = COALESCE(workspace_display_path, ?),
+        git_repo_root = COALESCE(git_repo_root, ?),
+        git_repo_root_home_rel_path = COALESCE(git_repo_root_home_rel_path, ?),
+        git_repo_root_display_path = COALESCE(git_repo_root_display_path, ?),
+        git_repo_name = COALESCE(git_repo_name, ?),
+        git_branch = COALESCE(git_branch, ?),
         tool_canonical_name = COALESCE(tool_canonical_name, ?),
         mcp_server = COALESCE(mcp_server, ?),
         mcp_tool = COALESCE(mcp_tool, ?),
         turn_id = COALESCE(turn_id, ?)
-      WHERE id = ?`).run(eventId, now, Math.max(existing.arg_token_estimate, argTok), toolName, mcpS, mcpT, normalized.turnId ?? null, existing.id);
+      WHERE id = ?`).run(eventId, now, Math.max(existing.arg_token_estimate, argTok), workspaceGit.workspacePath, workspaceGit.workspaceHomeRelPath, workspaceGit.workspaceDisplayPath, workspaceGit.gitRepoRoot, workspaceGit.gitRepoRootHomeRelPath, workspaceGit.gitRepoRootDisplayPath, workspaceGit.gitRepoName, workspaceGit.gitBranch, toolName, mcpS, mcpT, normalized.turnId ?? null, existing.id);
     }
     else if (derived.toolPhase === "post") {
         db.prepare(`UPDATE interaction_spans SET
         post_event_id = COALESCE(post_event_id, ?),
         completed_at = COALESCE(completed_at, ?),
         result_token_estimate = ?,
+        workspace_path = COALESCE(workspace_path, ?),
+        workspace_home_rel_path = COALESCE(workspace_home_rel_path, ?),
+        workspace_display_path = COALESCE(workspace_display_path, ?),
+        git_repo_root = COALESCE(git_repo_root, ?),
+        git_repo_root_home_rel_path = COALESCE(git_repo_root_home_rel_path, ?),
+        git_repo_root_display_path = COALESCE(git_repo_root_display_path, ?),
+        git_repo_name = COALESCE(git_repo_name, ?),
+        git_branch = COALESCE(git_branch, ?),
         tool_canonical_name = COALESCE(tool_canonical_name, ?),
         mcp_server = COALESCE(mcp_server, ?),
         mcp_tool = COALESCE(mcp_tool, ?),
         turn_id = COALESCE(turn_id, ?)
-      WHERE id = ?`).run(eventId, now, Math.max(existing.result_token_estimate, resTok), toolName, mcpS, mcpT, normalized.turnId ?? null, existing.id);
+      WHERE id = ?`).run(eventId, now, Math.max(existing.result_token_estimate, resTok), workspaceGit.workspacePath, workspaceGit.workspaceHomeRelPath, workspaceGit.workspaceDisplayPath, workspaceGit.gitRepoRoot, workspaceGit.gitRepoRootHomeRelPath, workspaceGit.gitRepoRootDisplayPath, workspaceGit.gitRepoName, workspaceGit.gitBranch, toolName, mcpS, mcpT, normalized.turnId ?? null, existing.id);
     }
     else {
         db.prepare(`UPDATE interaction_spans SET
         failure_event_id = COALESCE(failure_event_id, ?),
         completed_at = COALESCE(completed_at, ?),
         result_token_estimate = ?,
+        workspace_path = COALESCE(workspace_path, ?),
+        workspace_home_rel_path = COALESCE(workspace_home_rel_path, ?),
+        workspace_display_path = COALESCE(workspace_display_path, ?),
+        git_repo_root = COALESCE(git_repo_root, ?),
+        git_repo_root_home_rel_path = COALESCE(git_repo_root_home_rel_path, ?),
+        git_repo_root_display_path = COALESCE(git_repo_root_display_path, ?),
+        git_repo_name = COALESCE(git_repo_name, ?),
+        git_branch = COALESCE(git_branch, ?),
         tool_canonical_name = COALESCE(tool_canonical_name, ?),
         mcp_server = COALESCE(mcp_server, ?),
         mcp_tool = COALESCE(mcp_tool, ?),
         turn_id = COALESCE(turn_id, ?)
-      WHERE id = ?`).run(eventId, now, Math.max(existing.result_token_estimate, resTok), toolName, mcpS, mcpT, normalized.turnId ?? null, existing.id);
+      WHERE id = ?`).run(eventId, now, Math.max(existing.result_token_estimate, resTok), workspaceGit.workspacePath, workspaceGit.workspaceHomeRelPath, workspaceGit.workspaceDisplayPath, workspaceGit.gitRepoRoot, workspaceGit.gitRepoRootHomeRelPath, workspaceGit.gitRepoRootDisplayPath, workspaceGit.gitRepoName, workspaceGit.gitBranch, toolName, mcpS, mcpT, normalized.turnId ?? null, existing.id);
     }
 }
 export function getLastEventSummary(db) {
@@ -237,7 +365,11 @@ export function getEventsForLatestSession(db) {
             estimated_total_tokens AS estimatedTotalTokens,
             raw_payload AS rawPayload,
             workspace_path AS workspacePath,
+            workspace_home_rel_path AS workspaceHomeRelPath,
+            workspace_display_path AS workspaceDisplayPath,
             git_repo_root AS gitRepoRoot,
+            git_repo_root_home_rel_path AS gitRepoRootHomeRelPath,
+            git_repo_root_display_path AS gitRepoRootDisplayPath,
             git_repo_name AS gitRepoName,
             git_branch AS gitBranch
           FROM events
@@ -262,7 +394,11 @@ export function getEventsForLatestSession(db) {
             estimated_total_tokens AS estimatedTotalTokens,
             raw_payload AS rawPayload,
             workspace_path AS workspacePath,
+            workspace_home_rel_path AS workspaceHomeRelPath,
+            workspace_display_path AS workspaceDisplayPath,
             git_repo_root AS gitRepoRoot,
+            git_repo_root_home_rel_path AS gitRepoRootHomeRelPath,
+            git_repo_root_display_path AS gitRepoRootDisplayPath,
             git_repo_name AS gitRepoName,
             git_branch AS gitBranch
           FROM events

package/dist/core/gitWorkspace.js

@@ -1,3 +1,4 @@
+import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 function trimmedOrNull(value) {
@@ -12,6 +13,35 @@ function asRecord(value) {
     }
     return {};
 }
+function toSlashPath(relativePath) {
+    return relativePath.split(path.sep).join("/");
+}
+function deriveHomePath(absolutePath) {
+    if (!absolutePath) {
+        return { homeRelPath: null, displayPath: null };
+    }
+    const homeDir = trimmedOrNull(os.homedir());
+    if (!homeDir) {
+        return { homeRelPath: null, displayPath: null };
+    }
+    const normalizedHome = path.normalize(homeDir);
+    const normalizedPath = path.normalize(absolutePath);
+    const relativePath = path.relative(normalizedHome, normalizedPath);
+    if (!relativePath) {
+        return { homeRelPath: ".", displayPath: "~" };
+    }
+    if (path.isAbsolute(relativePath)) {
+        return { homeRelPath: null, displayPath: null };
+    }
+    if (relativePath === ".." || relativePath.startsWith(`..${path.sep}`)) {
+        return { homeRelPath: null, displayPath: null };
+    }
+    const slashPath = toSlashPath(relativePath);
+    return {
+        homeRelPath: slashPath,
+        displayPath: `~/${slashPath}`,
+    };
+}
 /**
  * Absolute path for “where this event ran”: adapter repoPath, then common payload cwd keys, then process.cwd().
  */
@@ -52,22 +82,33 @@ function gitOutput(workspacePath, args) {
  * Best-effort git context for `workspacePath`. Non-repo → git* fields null; `workspacePath` still set.
  */
 export function resolveWorkspaceGitMeta(workspacePath) {
-    const inside = gitOutput(workspacePath, ["rev-parse", "--is-inside-work-tree"]);
+    const normalizedWorkspacePath = path.normalize(workspacePath);
+    const workspaceHomePath = deriveHomePath(normalizedWorkspacePath);
+    const inside = gitOutput(normalizedWorkspacePath, ["rev-parse", "--is-inside-work-tree"]);
     if (inside !== "true") {
         return {
-            workspacePath,
+            workspacePath: normalizedWorkspacePath,
+            workspaceHomeRelPath: workspaceHomePath.homeRelPath,
+            workspaceDisplayPath: workspaceHomePath.displayPath,
             gitRepoRoot: null,
+            gitRepoRootHomeRelPath: null,
+            gitRepoRootDisplayPath: null,
             gitRepoName: null,
             gitBranch: null,
         };
     }
-    const root = gitOutput(workspacePath, ["rev-parse", "--show-toplevel"]);
-    const branch = gitOutput(workspacePath, ["rev-parse", "--abbrev-ref", "HEAD"]);
+    const root = gitOutput(normalizedWorkspacePath, ["rev-parse", "--show-toplevel"]);
+    const branch = gitOutput(normalizedWorkspacePath, ["rev-parse", "--abbrev-ref", "HEAD"]);
     const gitRepoRoot = root ? path.normalize(root) : null;
+    const gitRepoRootHomePath = deriveHomePath(gitRepoRoot);
     const gitRepoName = gitRepoRoot ? path.basename(gitRepoRoot) : null;
     return {
-        workspacePath,
+        workspacePath: normalizedWorkspacePath,
+        workspaceHomeRelPath: workspaceHomePath.homeRelPath,
+        workspaceDisplayPath: workspaceHomePath.displayPath,
         gitRepoRoot,
+        gitRepoRootHomeRelPath: gitRepoRootHomePath.homeRelPath,
+        gitRepoRootDisplayPath: gitRepoRootHomePath.displayPath,
         gitRepoName,
         gitBranch: branch,
     };

package/dist/core/packageMeta.js

@@ -0,0 +1,20 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+let cachedPackageMeta = null;
+function readPackageMeta() {
+    if (cachedPackageMeta)
+        return cachedPackageMeta;
+    const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    try {
+        cachedPackageMeta = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    }
+    catch {
+        cachedPackageMeta = {};
+    }
+    return cachedPackageMeta;
+}
+export function getPackageVersion() {
+    return readPackageMeta().version ?? "0.0.0";
+}

package/dist/core/schema.sql

@@ -14,7 +14,11 @@ CREATE TABLE IF NOT EXISTS events (
   payload_hash TEXT NOT NULL,
   raw_payload TEXT NOT NULL,
   workspace_path TEXT,
+  workspace_home_rel_path TEXT,
+  workspace_display_path TEXT,
   git_repo_root TEXT,
+  git_repo_root_home_rel_path TEXT,
+  git_repo_root_display_path TEXT,
   git_repo_name TEXT,
   git_branch TEXT,
   interaction_kind TEXT,
@@ -41,7 +45,11 @@ CREATE TABLE IF NOT EXISTS interaction_spans (
   arg_token_estimate INTEGER DEFAULT 0,
   result_token_estimate INTEGER DEFAULT 0,
   workspace_path TEXT,
+  workspace_home_rel_path TEXT,
+  workspace_display_path TEXT,
   git_repo_root TEXT,
+  git_repo_root_home_rel_path TEXT,
+  git_repo_root_display_path TEXT,
   git_repo_name TEXT,
   git_branch TEXT,
   started_at TEXT,