@gethmy/mcp 2.20.1 → 2.22.0

package/src/server.ts

@@ -19,6 +19,7 @@ import {
 } from "./api-client.js";
 import {
   AUTO_START_TRIGGERS,
+  type ClientInfo,
   destroyAutoSession,
   initAutoSession,
   markExplicit,
@@ -317,6 +318,18 @@ export interface ToolDeps {
    * shared auto-session entry. Omitted on stdio (single user → default scope).
    */
   getScopeId?: () => string;
+  /**
+   * MCP client identity for the caller, when the transport remembered one.
+   *
+   * A stateless `tools/call` carries no handshake, so `getClientVersion()` is
+   * undefined there and this is the only thing auto-session can attribute the
+   * work to (#297). Resolved per request, which makes it per *OAuth grant* on
+   * the hosted path (#774) — the scope-level `clientInfoGetter` cannot be,
+   * because a user's second client re-runs `initAutoSession` for the same scope
+   * and overwrites it (last-initializer-wins). Omitted on stdio, which reads
+   * identity straight off the in-scope `Server`.
+   */
+  getClientInfo?: () => ClientInfo | null;
 }
 
 // --- Memory Session Tracking ---
@@ -532,8 +545,15 @@ async function flushMemoryActions(
       agentIdentifier: session.agentIdentifier,
       agentName: session.agentName,
       recentActions: session.allActions,
+      // A bookkeeping flush of memory actions is the last thing that should mint
+      // a session on a card a human stopped (#770).
+      implicitCreate: true,
     });
 
+    // Cleared even when the write was refused (`{session: null, stopped: true}`
+    // resolves rather than throwing). Deliberate: the bar never lapses, so these
+    // buffered display-only actions can never be written — retaining them would
+    // just re-attempt the same refusal on every later flush.
     session.dirty = false;
   } catch (err) {
     // Fire-and-forget: log but don't propagate
@@ -1536,7 +1556,7 @@ export const TOOLS = {
   },
   harmony_update_agent_progress: {
     description:
-      "Update progress on an active agent session. Use to report progress percentage, current task, blockers, or status changes.",
+      "Update progress on an active agent session. Use to report progress percentage, current task, blockers, or status changes. Check the reply: `session: null` with `stopped: true` means a human stopped this card's run, so reporting progress will no longer open a session here (card #770) — stop work if you were mid-run, and read `recovery` for the one legitimate way back. Otherwise a session is always returned: this call opens one if none is live.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1627,7 +1647,7 @@ export const TOOLS = {
   },
   harmony_get_pending_messages: {
     description:
-      "Drain queued steering messages a teammate sent to your live agent session (card #473). Call at your progress checkpoints with the session id from harmony_start_agent_session and the highest seq you've already consumed; returns user messages with seq > sinceSeq, oldest first. Fold them into your next step and advance sinceSeq to the largest returned seq so each is handled exactly once.",
+      "Drain queued steering messages a teammate sent to your live agent session, and check whether that session is still live (cards #473, #770). Call at your progress checkpoints with the session id from harmony_start_agent_session and the highest seq you've already consumed; returns user messages with seq > sinceSeq, oldest first. Fold them into your next step and advance sinceSeq to the largest returned seq so each is handled exactly once. Two liveness flags come back and mean different things: `stopped` (a human pressed Stop) is TERMINAL — stop work at once, make no further edits, commits, pushes, or progress writes, don't move the card, and report what you had done and where any uncommitted work lives. `sessionStale` only means your session id went stale (usually the 30-minute inactivity cron) — nobody stopped you, so do NOT abandon the work: open a fresh session with harmony_start_agent_session and carry on with its new id. (Distinct from harmony_move_card's `sessionEnded`, which means the move deliberately closed your session.)",
     inputSchema: {
       type: "object",
       properties: {
@@ -2614,11 +2634,15 @@ export function registerHandlers(server: Server, deps: ToolDeps): void {
       // the hosted/OAuth path, not just stdio (card #297).
       // Optional-chained: the pre-hook is best-effort and must never throw into
       // tool dispatch if a transport/wrapper doesn't expose getClientVersion.
+      // `getClientInfo` covers the stateless case, where the handshake this
+      // reads is on a different request entirely (#774).
       const cv = server.getClientVersion?.();
       trackActivity(cardIdArg, {
         autoStart: isAutoStartTrigger,
         client: deps.getClient(),
-        clientInfo: cv ? { name: cv.name, version: cv.version } : undefined,
+        clientInfo: cv
+          ? { name: cv.name, version: cv.version }
+          : (deps.getClientInfo?.() ?? undefined),
         scopeId: deps.getScopeId?.(),
       }).catch(() => {}); // fire-and-forget
     }
@@ -2647,7 +2671,7 @@ export function registerHandlers(server: Server, deps: ToolDeps): void {
               client: deps.getClient(),
               clientInfo: cv
                 ? { name: cv.name, version: cv.version }
-                : undefined,
+                : (deps.getClientInfo?.() ?? undefined),
               scopeId: deps.getScopeId?.(),
             }).catch(() => {});
           }
@@ -3992,8 +4016,21 @@ async function handleToolCall(
         ),
         ...(mergedRecentActions && { recentActions: mergedRecentActions }),
         ...(runActivity.length > 0 && { runActivity }),
+        // Reporting progress must never resurrect a run a human stopped (#770).
+        // This is THE call the surviving client makes at every checkpoint, so it
+        // is both the resurrection vector and the earliest place to hand that
+        // client the news that it was stopped.
+        implicitCreate: true,
       });
 
+      // This handler never sends `noCreate`, so the create branch either creates
+      // a row or refuses — meaning a null session here can only be the human-stop
+      // refusal. Drop it from auto-session tracking so the 60s heartbeat stops
+      // beating a card we're barred from writing to.
+      if (result.session === null) {
+        untrack(cardId, deps.getScopeId?.());
+      }
+
       // Phase 0 (memory architecture v2): mid-session learning extraction removed.
       return { success: true, midSessionLearnings: 0, ...result };
     }
@@ -4012,8 +4049,13 @@ async function handleToolCall(
       await flushMemoryActions(client, cardId);
       cleanupMemorySession(cardId);
 
-      // End the session — tolerate failure (e.g., session already ended or not found)
-      let result: { session: unknown } = { session: null };
+      // End the session — tolerate failure (e.g., session already ended or not found).
+      // Typed off the client so the `ended`/`reason` discriminator (#769) reaches the
+      // tool payload by contract, not by accident of the spread below. Left absent
+      // here on purpose: a throw means we don't know what the server did.
+      let result: Awaited<ReturnType<typeof client.endAgentSession>> = {
+        session: null,
+      };
       let sessionEndError: string | null = null;
       try {
         result = await client.endAgentSession(cardId, {
@@ -4100,6 +4142,54 @@ async function handleToolCall(
         sessionId,
         sinceSeq,
       );
+
+      // Hoist the verdict out of the nested `session` object and say what it
+      // obliges (#770). The poll is the one call a stopped MCP/human client is
+      // guaranteed to make — Stop's Realtime broadcast has no consumer for
+      // `agent_id == null` sessions — so the news has to be impossible to skim
+      // past here.
+      //
+      // Two outcomes, deliberately NOT merged. Only a human Stop is terminal; a
+      // row the 30-minute stale cron closed (or one that vanished) just means the
+      // session id is stale. Telling an agent to abandon its work in that case
+      // would destroy a healthy run — a `blocked` session waiting on a user's
+      // answer is not heartbeated, so it reaches the cron routinely.
+      const stoppedByHuman = result.session?.stoppedByHuman === true;
+      const ended = result.session?.ended === true;
+      // Either verdict means stop beating this card: `ended` because the row is
+      // gone, `stoppedByHuman` because we're about to tell the client to stand
+      // down. Gating on `ended` alone would leave the 60s heartbeat polling a card
+      // this very call declared terminal.
+      if (ended || stoppedByHuman) {
+        untrack(cardId, deps.getScopeId?.());
+      }
+      if (stoppedByHuman) {
+        return {
+          success: true,
+          ...result,
+          stopped: true,
+          stopReason: "human_stopped" as const,
+          instruction:
+            "A human stopped this run — stop work now. Make no further edits, commits, pushes, or progress writes, and do not move the card. Commit any uncommitted work in place so it isn't lost, then report to the user what you completed, what is unfinished, and the branch holding it.",
+        };
+      }
+      if (ended) {
+        // Deliberately NOT `sessionEnded` — `harmony_move_card` already returns a
+        // field by that name meaning "I ended your session for you", which is
+        // close to the opposite of this. Two tools answering the same word with
+        // near-inverse meanings is how a client ends up re-opening a session it
+        // just intentionally closed.
+        return {
+          success: true,
+          ...result,
+          sessionStale: true,
+          staleReason: result.session?.status,
+          instruction:
+            'This session id is no longer live (it was closed as "' +
+            (result.session?.status ?? "missing") +
+            '") — but nobody stopped you. Do NOT abandon the work. Open a fresh session with harmony_start_agent_session, use its new id for later polls, and carry on.',
+        };
+      }
       return { success: true, ...result };
     }