session-collab-mcp 2.2.0 → 2.3.0

package/README.md

@@ -64,6 +64,7 @@ session-collab-http --host 127.0.0.1 --port 8765
 # CLI wrapper (convenience REST client)
 session-collab health
 session-collab tools
+session-collab doctor
 session-collab call --name collab_session_start --args '{"project_root":"/repo","name":"demo"}'
 ```
 
@@ -101,9 +102,11 @@ The MCP tools give you a stable collaboration workflow across providers:
 
 1. Start a session with `collab_session_start`
 2. Check files with `collab_claim(action="check")`
-3. Reserve files with `collab_claim(action="create")`
-4. Save important context with `collab_memory_save`
-5. End the session with `collab_session_end`
+3. Reserve files with `collab_claim(action="create")`; conflicting claims are blocked by default
+4. Update visible progress with `collab_session_update`
+5. Save important context with `collab_memory_save`
+6. Release claims with `collab_claim(action="release")`
+7. End the session with `collab_session_end`
 
 ### Working Memory
 
@@ -145,13 +148,14 @@ Configure behavior with `collab_config`:
 
 ## MCP Tools Reference
 
-### Session Management (5 tools)
+### Session Management
 
 | Tool | Purpose |
 |------|---------|
 | `collab_session_start` | Register a new session |
 | `collab_session_end` | End session and release all claims |
-| `collab_session_list` | List active sessions |
+| `collab_session_list` | List active sessions with current task and active claim summaries |
+| `collab_session_update` | Update heartbeat, current task, todos, and progress |
 | `collab_config` | Configure session behavior |
 | `collab_status` | Get session status summary |
 
@@ -159,7 +163,7 @@ Configure behavior with `collab_config`:
 
 | Tool | Actions |
 |------|---------|
-| `collab_claim` | `create`, `check`, `release`, `list` (check: `exclude_self` defaults to true) |
+| `collab_claim` | `create`, `check`, `release`, `list` (check: `exclude_self` defaults to true; create blocks conflicts unless `allow_conflicts=true`) |
 
 ### Working Memory (3 tools)
 
@@ -187,6 +191,7 @@ Configure behavior with `collab_config`:
 
 - `POST /v1/sessions/start` → `collab_session_start`
 - `POST /v1/sessions/end` → `collab_session_end`
+- `POST /v1/sessions/update` → `collab_session_update`
 - `GET /v1/sessions` → `collab_session_list`
 - `POST /v1/config` → `collab_config`
 - `GET /v1/status` → `collab_status`
@@ -217,11 +222,16 @@ Configure behavior with `collab_config`:
 # Session A starts working
 collab_session_start(project_root="/my/project", name="feature-auth")
 collab_claim(session_id="session-a", action="create", files=["src/auth.ts"], intent="Adding JWT support")
+collab_session_update(session_id="session-a", current_task="Adding JWT support")
 
 # Session B checks before editing
 collab_claim(session_id="session-b", action="check", files=["src/auth.ts"])
 # Result: "CONFLICT: src/auth.ts is claimed by 'feature-auth'"
 
+# create is also safe by default; use allow_conflicts=true only after coordination
+collab_claim(session_id="session-b", action="create", files=["src/auth.ts"], intent="Coordinated auth work")
+# Result: "Claim not created. 1 conflict(s) detected."
+
 # If you want to include your own claims in the check
 collab_claim(session_id="session-a", action="check", files=["src/auth.ts"], exclude_self=false)
 
@@ -334,6 +344,8 @@ npm run start:dev    # Start in development mode
 npm run typecheck    # Run TypeScript type checking
 npm run lint         # Run ESLint
 npm run test         # Run tests with Vitest
+npm run test:http    # Run HTTP integration tests
+npm run test:release # Run release gate: typecheck, lint, tests, HTTP tests, npm pack dry-run
 ```
 
 ### HTTP Integration Tests
@@ -341,7 +353,15 @@ npm run test         # Run tests with Vitest
 HTTP integration tests require a local listen port. Enable them with:
 
 ```bash
-SESSION_COLLAB_HTTP_TESTS=true npx vitest run src/http/__tests__/server-integration.test.ts
+npm run test:http
+```
+
+### HTTP CLI Doctor
+
+When using the HTTP server, validate the running server with:
+
+```bash
+session-collab doctor --base-url http://127.0.0.1:8765
 ```
 
 ### Historical Notes
@@ -372,6 +392,15 @@ session-collab-mcp/
 
 ## Changelog
 
+### v2.3.0
+
+- Add `collab_session_update` for heartbeat, current task, todo, and progress reporting
+- Enrich `collab_session_list` with current task and active claim summaries
+- Make `collab_claim(action="create")` block conflicts by default; use `allow_conflicts=true` only after coordination
+- Add `session-collab doctor` for HTTP server health and tool-surface checks
+- Add `npm run test:http` and `npm run test:release` release gates
+- Update dev test tooling to clear npm audit findings
+
 ### v2.1.0
 
 - Add HTTP server + CLI wrapper for universal AI CLI usage

package/dist/{chunk-SOUW3JSS.js → chunk-TFGXE3EI.js}

@@ -161,12 +161,13 @@ var SERVER_INSTRUCTIONS = `
 
 Coordinate sessions and persist context across conversations.
 
-## 10 Core Tools
+## Core Tools
 
-### Session (5 tools)
+### Session
 - \`collab_session_start\`: Start session with project_root
 - \`collab_session_end\`: End session, release claims
-- \`collab_session_list\`: List active sessions
+- \`collab_session_list\`: List active sessions and their active claim summaries
+- \`collab_session_update\`: Update heartbeat, current task, todos, and progress
 - \`collab_config\`: Configure session behavior
 - \`collab_status\`: Get session status and summary
 
@@ -187,10 +188,11 @@ Coordinate sessions and persist context across conversations.
 
 1. **On start**: \`collab_session_start\` with project_root
 2. **Before editing**: \`collab_claim\` action="check"
-3. **For changes**: \`collab_claim\` action="create"
+3. **For changes**: \`collab_claim\` action="create" (blocked by default if another active session conflicts)
 4. **Save context**: \`collab_memory_save\` for important findings
-5. **When done**: \`collab_claim\` action="release"
-6. **On end**: \`collab_session_end\`
+5. **While working**: \`collab_session_update\` with current_task/todos
+6. **When done**: \`collab_claim\` action="release"
+7. **On end**: \`collab_session_end\`
 
 ## Memory Categories
 
@@ -4334,6 +4336,39 @@ async function listSessions(db, params = {}) {
   const result = await db.prepare(query).bind(...bindings).all();
   return result.results;
 }
+async function updateSessionHeartbeat(db, id, statusUpdate) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  let progress = null;
+  let todosJson = null;
+  if (statusUpdate?.todos) {
+    const total = statusUpdate.todos.length;
+    const completed = statusUpdate.todos.filter((t) => t.status === "completed").length;
+    progress = {
+      completed,
+      total,
+      percentage: total > 0 ? Math.round(completed / total * 100) : 0
+    };
+    todosJson = JSON.stringify(statusUpdate.todos);
+  }
+  let query = "UPDATE sessions SET last_heartbeat = ?";
+  const bindings = [now];
+  if (statusUpdate?.current_task !== void 0) {
+    query += ", current_task = ?";
+    bindings.push(statusUpdate.current_task);
+  }
+  if (progress) {
+    query += ", progress = ?";
+    bindings.push(JSON.stringify(progress));
+  }
+  if (todosJson) {
+    query += ", todos = ?";
+    bindings.push(todosJson);
+  }
+  query += " WHERE id = ? AND status = 'active'";
+  bindings.push(id);
+  const result = await db.prepare(query).bind(...bindings).run();
+  return result.meta.changes > 0;
+}
 async function endSession(db, id, release_claims = "abandon") {
   const claimStatus = release_claims === "complete" ? "completed" : "abandoned";
   await db.prepare("UPDATE claims SET status = ?, updated_at = ? WHERE session_id = ? AND status = 'active'").bind(claimStatus, (/* @__PURE__ */ new Date()).toISOString(), id).run();
@@ -4998,7 +5033,8 @@ var claimCreateSchema = external_exports.object({
   symbols: symbolClaimsArraySchema.optional(),
   intent: external_exports.string().min(1, "intent is required"),
   scope: claimScopeSchema.optional(),
-  priority: external_exports.number().min(0).max(100).optional()
+  priority: external_exports.number().min(0).max(100).optional(),
+  allow_conflicts: external_exports.boolean().optional()
 }).refine(
   (data) => data.files && data.files.length > 0 || data.symbols && data.symbols.length > 0,
   { message: "Either files or symbols must be provided" }
@@ -5104,6 +5140,14 @@ function validationError(message) {
 }
 
 // src/mcp/tools/session.ts
+function parseJsonField(value) {
+  if (!value) return null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
 var sessionTools = [
   {
     name: "collab_session_start",
@@ -5159,6 +5203,39 @@ var sessionTools = [
       }
     }
   },
+  {
+    name: "collab_session_update",
+    description: "Update session heartbeat, current task, todos, and progress.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        session_id: {
+          type: "string",
+          description: "Session ID to update"
+        },
+        current_task: {
+          type: "string",
+          description: "Current work summary"
+        },
+        todos: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              content: { type: "string" },
+              status: {
+                type: "string",
+                enum: ["pending", "in_progress", "completed"]
+              }
+            },
+            required: ["content", "status"]
+          },
+          description: "Current todo state for progress reporting"
+        }
+      },
+      required: ["session_id"]
+    }
+  },
   {
     name: "collab_config",
     description: "Configure session behavior.",
@@ -5308,7 +5385,17 @@ Decisions:
             id: session.id,
             name: session.name,
             status: session.status,
+            current_task: session.current_task,
+            progress: parseJsonField(session.progress),
+            todos: parseJsonField(session.todos),
             active_claims: claims.length,
+            claims: claims.map((c) => ({
+              id: c.id,
+              files: c.files,
+              intent: c.intent,
+              priority: getPriorityLevel(c.priority),
+              created_at: c.created_at
+            })),
             last_heartbeat: session.last_heartbeat
           };
         })
@@ -5318,6 +5405,34 @@ Decisions:
         total: sessionsWithClaims.length
       });
     }
+    case "collab_session_update": {
+      const validation = validateInput(statusUpdateSchema, args);
+      if (!validation.success) {
+        return validationError(validation.error);
+      }
+      const input = validation.data;
+      const sessionResult = await validateActiveSession(db, input.session_id);
+      if (!sessionResult.valid) {
+        return sessionResult.error;
+      }
+      const updated = await updateSessionHeartbeat(db, input.session_id, {
+        current_task: input.current_task,
+        todos: input.todos
+      });
+      if (!updated) {
+        return errorResponse(ERROR_CODES.SESSION_NOT_FOUND, "Session not found");
+      }
+      const session = await getSession(db, input.session_id);
+      return successResponse({
+        success: true,
+        session_id: input.session_id,
+        current_task: session?.current_task ?? null,
+        progress: parseJsonField(session?.progress ?? null),
+        todos: parseJsonField(session?.todos ?? null),
+        last_heartbeat: session?.last_heartbeat ?? null,
+        message: "Session updated."
+      });
+    }
     case "collab_config": {
       const validation = validateInput(configSchema, args);
       if (!validation.success) {
@@ -5457,6 +5572,10 @@ var claimTools = [
           type: "boolean",
           description: "Force release even if not owner (for release action)"
         },
+        allow_conflicts: {
+          type: "boolean",
+          description: "Explicitly create a claim even when conflicts are detected (for create action)"
+        },
         summary: {
           type: "string",
           description: "Release summary (for release action)"
@@ -5492,6 +5611,21 @@ async function handleClaimTool(db, name, args) {
       }
       const symbolFiles = (input.symbols ?? []).map((symbol) => symbol.file);
       const files = Array.from(/* @__PURE__ */ new Set([...input.files ?? [], ...symbolFiles]));
+      const conflicts = await checkConflicts(db, files, input.session_id, input.symbols);
+      if (conflicts.length > 0 && !input.allow_conflicts) {
+        return successResponse({
+          success: false,
+          status: "blocked_by_conflicts",
+          files,
+          symbols: input.symbols ?? [],
+          conflicts: conflicts.map((c) => ({
+            session_name: c.session_name,
+            file: c.file_path,
+            intent: c.intent
+          })),
+          message: `Claim not created. ${conflicts.length} conflict(s) detected. Coordinate before proceeding.`
+        });
+      }
       const { claim } = await createClaim(db, {
         session_id: input.session_id,
         files,
@@ -5516,7 +5650,6 @@ Files: ${files.join(", ")}`,
         related_claim_id: claim.id,
         metadata: { claim_id: claim.id, files }
       });
-      const conflicts = await checkConflicts(db, files, input.session_id, input.symbols);
       if (conflicts.length > 0) {
         return successResponse({
           success: true,
@@ -6101,4 +6234,4 @@ export {
   getMcpTools,
   handleMcpRequest
 };
-//# sourceMappingURL=chunk-SOUW3JSS.js.map
+//# sourceMappingURL=chunk-TFGXE3EI.js.map