@codazen/harmonica-mcp 0.24.0 → 0.25.1

package/dist/index.js

@@ -22214,6 +22214,127 @@ function formatNoteDetail(note) {
   return parts.join("\n");
 }
 
+// ../../libs/harmonica-services/src/mcp/formatters/session-formatter.ts
+var TYPE_LABELS2 = {
+  planning: "Planning",
+  implementation: "Implementation",
+  triage: "Triage",
+  assessment: "Assessment",
+  composition: "Composition",
+  baseline: "Baseline"
+};
+var STATUS_LABELS = {
+  running: "Running",
+  succeeded: "Succeeded",
+  failed: "Failed",
+  timed_out: "Timed Out",
+  cancelled: "Cancelled"
+};
+var EVENT_TAIL_LIMIT = 10;
+function formatSessionSummary(session) {
+  const type = TYPE_LABELS2[session.sessionType] ?? session.sessionType;
+  const status = STATUS_LABELS[session.status] ?? session.status;
+  const duration3 = session.endedAt ? ` \xB7 ${formatRelativeWindow(session.startedAt, session.endedAt)}` : "";
+  const scope = formatScopeSuffix(session);
+  const actor = session.actorPersona ? ` \xB7 ${session.actorPersona}` : "";
+  return `- **${type}** (${session.sessionId}) [${status}]${actor}${duration3}${scope}`;
+}
+function formatSessionList(sessions, scopeLabel) {
+  if (sessions.length === 0) {
+    return `No sessions found for ${scopeLabel}.`;
+  }
+  const grouped = /* @__PURE__ */ new Map();
+  for (const s of sessions) {
+    const bucket = grouped.get(s.status) ?? [];
+    bucket.push(s);
+    grouped.set(s.status, bucket);
+  }
+  const parts = [`**${sessions.length} session${sessions.length === 1 ? "" : "s"}** (${scopeLabel})`, ""];
+  for (const [status, items] of grouped) {
+    parts.push(`### ${STATUS_LABELS[status] ?? status} (${items.length})`);
+    for (const item of items) {
+      parts.push(formatSessionSummary(item));
+    }
+    parts.push("");
+  }
+  return parts.join("\n").trimEnd();
+}
+function formatSessionDetail(session) {
+  const type = TYPE_LABELS2[session.sessionType] ?? session.sessionType;
+  const status = STATUS_LABELS[session.status] ?? session.status;
+  const parts = [
+    `# Session: ${session.sessionId}`,
+    "",
+    `**Type:** ${type}`,
+    `**Status:** ${status}`,
+    `**Project:** ${session.projectId}`,
+    `**Actor:** ${session.actor.agentPersona}${session.actor.agentRole ? ` (${session.actor.agentRole})` : ""}`
+  ];
+  if (session.actor.initiator) {
+    const i = session.actor.initiator;
+    parts.push(`**Initiated by:** ${i.type}/${i.id}${i.name ? ` (${i.name})` : ""}`);
+  }
+  if (session.beatId) parts.push(`**Beat:** ${session.beatId}`);
+  if (session.beatVersionId) parts.push(`**Beat Version:** ${session.beatVersionId}`);
+  if (session.revisionId) parts.push(`**Revision:** ${session.revisionId}`);
+  if (session.triggerSource) parts.push(`**Trigger:** ${session.triggerSource}`);
+  parts.push("");
+  parts.push(`**Started:** ${session.startedAt}`);
+  if (session.endedAt) parts.push(`**Ended:** ${session.endedAt}`);
+  if (session.metrics) {
+    parts.push("", "### Metrics");
+    const m = session.metrics;
+    if (m.durationMs != null) parts.push(`- Duration: ${formatDurationMs(m.durationMs)}`);
+    if (m.toolCallCount != null) parts.push(`- Tool calls: ${m.toolCallCount}`);
+    if (m.inputTokens != null) parts.push(`- Input tokens: ${m.inputTokens}`);
+    if (m.outputTokens != null) parts.push(`- Output tokens: ${m.outputTokens}`);
+    if (m.totalTokens != null) parts.push(`- Total tokens: ${m.totalTokens}`);
+    if (m.estimatedCostUsd != null) parts.push(`- Est. cost: $${m.estimatedCostUsd.toFixed(4)}`);
+  }
+  if (session.errorMessage) {
+    parts.push("", "### Error");
+    parts.push(session.errorMessage);
+  }
+  const toolEvents = session.toolEvents ?? [];
+  if (toolEvents.length > 0) {
+    parts.push("", `### Tool Events (showing last ${Math.min(toolEvents.length, EVENT_TAIL_LIMIT)} of ${toolEvents.length})`);
+    for (const ev of toolEvents.slice(-EVENT_TAIL_LIMIT)) {
+      const dur = ev.durationMs != null ? ` (${ev.durationMs}ms)` : "";
+      const result = ev.resultStatus ? ` \u2014 ${ev.resultStatus}` : "";
+      parts.push(`- [${ev.index}] ${ev.toolName}${result}${dur}`);
+    }
+  }
+  const textEvents = session.textEvents ?? [];
+  if (textEvents.length > 0) {
+    parts.push("", `### Text Events (${textEvents.length})`);
+    for (const ev of textEvents.slice(-EVENT_TAIL_LIMIT)) {
+      const preview = ev.content.length > 160 ? `${ev.content.slice(0, 160)}\u2026` : ev.content;
+      parts.push(`- [${ev.index}] ${preview}`);
+    }
+  }
+  parts.push("", `_Created: ${session.createdAt}_`);
+  return parts.join("\n");
+}
+function formatScopeSuffix(session) {
+  const parts = [];
+  if ("beatId" in session && session.beatId) parts.push(`Beat: ${session.beatId}`);
+  if ("revisionId" in session && session.revisionId) parts.push(`Rev: ${session.revisionId}`);
+  return parts.length > 0 ? ` [${parts.join(" \xB7 ")}]` : "";
+}
+function formatRelativeWindow(startedAt, endedAt) {
+  const ms = new Date(endedAt).getTime() - new Date(startedAt).getTime();
+  if (!Number.isFinite(ms) || ms < 0) return "";
+  return formatDurationMs(ms);
+}
+function formatDurationMs(ms) {
+  if (ms < 1e3) return `${ms}ms`;
+  const seconds = Math.round(ms / 1e3);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  const remSec = seconds % 60;
+  return remSec === 0 ? `${minutes}m` : `${minutes}m ${remSec}s`;
+}
+
 // ../../libs/harmonica-services/src/mcp/tools/beat-tools.ts
 function registerBeatTools(server, ctx, client) {
   server.tool(
@@ -24862,11 +24983,141 @@ function registerRevisionLifecycleTools(server, ctx, client) {
   );
 }
 
+// ../../libs/harmonica-services/src/mcp/tools/session-tools.ts
+var SESSION_STATUSES = ["running", "succeeded", "failed", "timed_out", "cancelled"];
+var SESSION_TYPES = ["planning", "implementation", "triage", "assessment", "composition", "baseline"];
+function registerSessionTools(server, ctx, client) {
+  server.tool(
+    "get_session",
+    'Get full details of an agent Session by ID \u2014 type, status, actor, scoping links (beat/revision), metrics, structured result, and the recent tool/text events. Use this when the user asks "what did that session do?" or to inspect a specific agent run.',
+    {
+      sessionId: external_exports.string().min(1).describe("The Session ID (sess-<uuid>)")
+    },
+    async ({ sessionId }) => {
+      const session = await client.getSession(sessionId);
+      if (!session) {
+        return {
+          content: [{ type: "text", text: `Session not found: ${sessionId}` }],
+          isError: true
+        };
+      }
+      return { content: [{ type: "text", text: formatSessionDetail(session) }] };
+    }
+  );
+  server.tool(
+    "list_project_sessions",
+    'List agent Sessions in a project, optionally filtered by status, type, or whether terminal sessions are included. Use this to answer "show me sessions in this project" or to find recent runs across all beats.',
+    {
+      projectId: external_exports.string().min(1).describe("The project ID"),
+      status: external_exports.enum(SESSION_STATUSES).optional().describe("Filter by status: running, succeeded, failed, timed_out, cancelled"),
+      sessionType: external_exports.enum(SESSION_TYPES).optional().describe("Filter by session type"),
+      includeTerminal: external_exports.boolean().optional().describe("Include terminal sessions (succeeded/failed/timed_out/cancelled). Default false.")
+    },
+    async ({ projectId, status, sessionType, includeTerminal }) => {
+      const sessions = await client.listProjectSessions(projectId, {
+        status,
+        sessionType,
+        includeTerminal
+      });
+      return {
+        content: [
+          { type: "text", text: formatSessionList(sessions, `project ${projectId}`) }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "list_beat_sessions",
+    'List agent Sessions scoped to a Beat. Use this to see every agent run that touched a specific capability \u2014 useful for "what work has been done on this beat?" investigations.',
+    {
+      beatId: external_exports.string().min(1).describe("The Beat ID (e.g., PROJ-B-001)"),
+      status: external_exports.enum(SESSION_STATUSES).optional().describe("Filter by status"),
+      sessionType: external_exports.enum(SESSION_TYPES).optional().describe("Filter by session type"),
+      includeTerminal: external_exports.boolean().optional().describe("Include terminal sessions. Default false.")
+    },
+    async ({ beatId, status, sessionType, includeTerminal }) => {
+      const sessions = await client.listBeatSessions(beatId, {
+        status,
+        sessionType,
+        includeTerminal
+      });
+      return {
+        content: [
+          { type: "text", text: formatSessionList(sessions, `beat ${beatId}`) }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "list_revision_sessions",
+    'List agent Sessions scoped to a specific Revision. Use this when a user asks "what did the agent do on this PR/revision?" \u2014 typically planning and implementation sessions.',
+    {
+      revisionId: external_exports.string().min(1).describe("The Revision ID (rev-<uuid>)"),
+      status: external_exports.enum(SESSION_STATUSES).optional().describe("Filter by status"),
+      sessionType: external_exports.enum(SESSION_TYPES).optional().describe("Filter by session type"),
+      includeTerminal: external_exports.boolean().optional().describe("Include terminal sessions. Default false.")
+    },
+    async ({ revisionId, status, sessionType, includeTerminal }) => {
+      const sessions = await client.listRevisionSessions(revisionId, {
+        status,
+        sessionType,
+        includeTerminal
+      });
+      return {
+        content: [
+          { type: "text", text: formatSessionList(sessions, `revision ${revisionId}`) }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "cancel_session",
+    "Cancel a running agent Session. Idempotent \u2014 calling cancel on a session that is already terminal (succeeded, failed, timed_out, cancelled) returns the existing record unchanged. Use this to stop a runaway agent or free up budget.",
+    {
+      sessionId: external_exports.string().min(1).describe("The Session ID to cancel"),
+      reason: external_exports.string().optional().describe("Why the session is being cancelled (audit trail)")
+    },
+    async ({ sessionId, reason }) => {
+      try {
+        const session = await client.cancelSession(sessionId, {
+          actor: {
+            type: "human",
+            id: ctx.user.userId,
+            ...ctx.user.name && { name: ctx.user.name },
+            ...ctx.user.email && { email: ctx.user.email }
+          },
+          reason
+        });
+        if (!session) {
+          return {
+            content: [{ type: "text", text: `Session not found: ${sessionId}` }],
+            isError: true
+          };
+        }
+        return {
+          content: [{ type: "text", text: formatSessionDetail(session) }]
+        };
+      } catch (err) {
+        return {
+          content: [
+            { type: "text", text: `Failed to cancel session: ${err instanceof Error ? err.message : String(err)}` }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+}
+
 // ../../libs/harmonica-services/src/mcp/tools/snapshot-tools.ts
 var import_promises = require("node:fs/promises");
 var import_node_os = require("node:os");
 var import_node_path = require("node:path");
-var SNAPSHOT_VERSION = 1;
+
+// ../../libs/harmonica-services/src/project-snapshot.constants.ts
+var SNAPSHOT_VERSION = 2;
+
+// ../../libs/harmonica-services/src/mcp/tools/snapshot-tools.ts
 function registerSnapshotTools(server, ctx, client) {
   server.tool(
     "export_project_snapshot",
@@ -24978,7 +25229,16 @@ function normalizeSnapshot(raw) {
     taskIndex: raw.taskIndex ?? [],
     submissions: raw.submissions ?? [],
     submissionIndex: raw.submissionIndex ?? [],
-    promptLogs: raw.promptLogs ?? []
+    promptLogs: raw.promptLogs ?? [],
+    beatVersions: raw.beatVersions ?? [],
+    beatBeatVersionIndex: raw.beatBeatVersionIndex ?? [],
+    projectBeatVersionIndex: raw.projectBeatVersionIndex ?? [],
+    beatVersionDropAssignments: raw.beatVersionDropAssignments ?? [],
+    drops: raw.drops ?? [],
+    teamspaceDropIndex: raw.teamspaceDropIndex ?? [],
+    deliverables: raw.deliverables ?? [],
+    teamspaceDeliverableIndex: raw.teamspaceDeliverableIndex ?? [],
+    projectDeliverableIndex: raw.projectDeliverableIndex ?? []
   };
 }
 async function resolveSnapshotInput(input) {
@@ -25667,6 +25927,7 @@ function registerAllTools(server, ctx, client) {
   registerTeamspaceTools(server, ctx, client);
   registerDeliverableTools(server, ctx, client);
   registerDropTools(server, ctx, client);
+  registerSessionTools(server, ctx, client);
   registerOnboardingTools(server, ctx, client);
 }
 
@@ -26202,6 +26463,40 @@ function createHttpClient(config2) {
       }
       return { success: true };
     },
+    // Sessions (B-150). All three list methods point at the same flat
+    // `GET /api/sessions?<scope>=` endpoint — the DataClient interface
+    // surfaces three methods because the data layer has three DDB index
+    // partitions, but the REST surface is unified per the project-level
+    // "avoid nested/duplicate routes" guidance.
+    getSession: (sessionId) => request("GET", `/api/sessions/${encodeURIComponent(sessionId)}`),
+    listProjectSessions: async (projectId, options) => {
+      const params = new URLSearchParams();
+      params.set("projectId", projectId);
+      if (options?.status) params.set("status", options.status);
+      if (options?.sessionType) params.set("sessionType", options.sessionType);
+      if (options?.includeTerminal) params.set("includeTerminal", "true");
+      const result = await request("GET", `/api/sessions?${params.toString()}`);
+      return result ?? [];
+    },
+    listBeatSessions: async (beatId, options) => {
+      const params = new URLSearchParams();
+      params.set("beatId", beatId);
+      if (options?.status) params.set("status", options.status);
+      if (options?.sessionType) params.set("sessionType", options.sessionType);
+      if (options?.includeTerminal) params.set("includeTerminal", "true");
+      const result = await request("GET", `/api/sessions?${params.toString()}`);
+      return result ?? [];
+    },
+    listRevisionSessions: async (revisionId, options) => {
+      const params = new URLSearchParams();
+      params.set("revisionId", revisionId);
+      if (options?.status) params.set("status", options.status);
+      if (options?.sessionType) params.set("sessionType", options.sessionType);
+      if (options?.includeTerminal) params.set("includeTerminal", "true");
+      const result = await request("GET", `/api/sessions?${params.toString()}`);
+      return result ?? [];
+    },
+    cancelSession: (sessionId, options) => request("POST", `/api/sessions/${encodeURIComponent(sessionId)}/cancel`, { reason: options.reason }),
     // Tasks
     getTask: async (taskId) => {
       return request("GET", `/api/tasks/${encodeURIComponent(taskId)}`);
@@ -26743,7 +27038,7 @@ function loadConfig() {
   };
 }
 async function main() {
-  console.error(`[harmonica-mcp] v${"0.24.0"} starting\u2026`);
+  console.error(`[harmonica-mcp] v${"0.25.1"} starting\u2026`);
   const config2 = loadConfig();
   const client = createHttpClient({
     apiBaseUrl: config2.apiBaseUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codazen/harmonica-mcp",
-  "version": "0.24.0",
+  "version": "0.25.1",
   "description": "MCP server for Harmonica — connect Claude to your Harmonica projects",
   "license": "MIT",
   "bin": {