@gethmy/mcp 2.20.0 → 2.21.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
@@ -1005,9 +1025,12 @@ export const TOOLS = {
       '`target: "artifact"` hosts a self-contained HTML doc (text/html, max 2MB) linked to ' +
       "exactly one of cardId/planId/workspaceId, rendered in-app in a sandboxed iframe. Provide " +
       "the bytes as `filePath` (local, direct-to-storage) or `base64Data` (small-file fallback). " +
-      "Returns the attachment/artifact + a signed URL (artifact: use harmony_share_artifact for a " +
-      "public link). Large files on the hosted MCP server: use harmony_request_upload_url + " +
-      "harmony_finalize_upload instead.",
+      "Returns the attachment/artifact. An artifact comes back with TWO URLs, and the difference " +
+      "matters: `app_url` is the durable in-app permalink — this is the one to hand a person, it " +
+      "never expires and requires them to log in as a workspace member — while `signed_url` only " +
+      "renders the document in-app and dies within the hour, so never pass it on. To share with " +
+      "someone OUTSIDE the workspace, mint a public link with harmony_share_artifact. Large files " +
+      "on the hosted MCP server: use harmony_request_upload_url + harmony_finalize_upload instead.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1119,7 +1142,9 @@ export const TOOLS = {
       "enforces size + content-type (magic-byte sniff, never the declared type) + an optional " +
       'sha256 integrity check, deleting and failing on any mismatch. `target: "card_attachment"` ' +
       '(cardId, storagePath, fileName) or `target: "artifact"` (storagePath + the same one of ' +
-      "cardId/planId/workspaceId used for the upload URL). Returns the attachment/artifact + a signed URL.",
+      "cardId/planId/workspaceId used for the upload URL). Returns the attachment/artifact + a signed " +
+      "URL; an artifact also carries `app_url`, the durable in-app permalink — hand that one to a " +
+      "person, never the short-lived `signed_url`.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1182,7 +1207,7 @@ export const TOOLS = {
   },
   harmony_share_artifact: {
     description:
-      "Create a public, unauthenticated share link for a hosted artifact. Anyone with the link can view the rendered HTML without a Harmony account. Returns the share token and the full public URL.",
+      "Create a public, unauthenticated share link for a hosted artifact. Anyone with the link can view the rendered HTML without a Harmony account. Returns the share token and the full public URL. Only needed for a recipient OUTSIDE the workspace — for a teammate, hand over the `app_url` the upload already returned instead of exposing the document publicly.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1531,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: {
@@ -1622,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: {
@@ -2609,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
     }
@@ -2642,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(() => {});
           }
@@ -3987,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 };
     }
@@ -4007,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, {
@@ -4095,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 };
     }
 

package/src/tui/setup.ts

@@ -515,14 +515,29 @@ async function getAgentFiles(
 
 This project uses Harmony for task management. When working on tasks:
 
+## Agent identity — always identify as yourself
+
+Every \`harmony_start_agent_session\` call passes \`agentIdentifier\` + \`agentName\`. **Use your own
+identity, never a hardcoded one from this file.** AGENTS.md is a cross-runtime convention file, so
+more than one kind of agent will read it; the board shows agents as teammates, and a session
+attributed to the wrong runtime misattributes the work in front of the whole team.
+
+- \`agentIdentifier\` — a stable kebab-case id for the runtime you actually are
+- \`agentName\` — its human-readable name
+
+Known values: \`claude-code\` / "Claude Code", \`codex\` / "OpenAI Codex", \`cursor\` / "Cursor",
+\`claude-desktop\` / "Claude Desktop". If you are a runtime not listed here, use your own name rather
+than borrowing the closest entry.
+
 ## Starting Work on a Card
 
 When given a card reference (e.g., #42 or a card name), follow this workflow:
 
-1. Use \`harmony_get_card_by_short_id\` or \`harmony_search_cards\` to find the card
+1. Use \`harmony_get_card\` or \`harmony_search_cards\` to find the card
 2. Move the card to "In Progress" using \`harmony_move_card\`
 3. Add the "agent" label using \`harmony_add_label_to_card\`
-4. Start a session with \`harmony_start_agent_session\` (agentIdentifier: "codex", agentName: "OpenAI Codex")
+4. Start a session with \`harmony_start_agent_session\`, passing **your own** \`agentIdentifier\` +
+   \`agentName\` (see "Agent identity" above)
 5. Show the card details to the user
 6. Use \`harmony_generate_prompt\` to get guidance, then implement the solution
 7. Update progress periodically with \`harmony_update_agent_progress\`
@@ -533,7 +548,8 @@ When given a card reference (e.g., #42 or a card name), follow this workflow:
 Before implementing a plan or feature, check if it maps to an existing Harmony card:
 
 1. Use \`harmony_search_cards\` with keywords from the task description
-2. If a match is found, call \`harmony_start_agent_session\` (agentIdentifier: "claude-code", agentName: "Claude Code", moveToColumn: "In Progress", addLabels: ["agent"])
+2. If a match is found, call \`harmony_start_agent_session\` with **your own** \`agentIdentifier\` +
+   \`agentName\` (see "Agent identity" above), plus \`moveToColumn: "In Progress"\`, \`addLabels: ["agent"]\`
 3. Update progress with \`harmony_update_agent_progress\` at milestones
 4. When done, call \`harmony_end_agent_session\` with status: "completed", moveToColumn: "Review"