@gethmy/mcp 3.2.0 → 3.4.0

package/src/server.ts

@@ -28,6 +28,10 @@ import {
   trackActivity,
   untrack,
 } from "./auto-session.js";
+import {
+  chooseCommentSession,
+  readDeclaredRunSession,
+} from "./comment-session.js";
 import {
   describeActiveContext,
   getActiveProjectId,
@@ -69,7 +73,19 @@ import {
 } from "./memory-session.js";
 import { lintTags, normalizeTags } from "./memory-tags.js";
 import { onboardNewUser } from "./onboard.js";
+import {
+  findPlanTask,
+  linkedReport,
+  type PlanTaskLinkReport,
+  type PlanTaskRow,
+  unlinkedReport,
+} from "./plan-task-link.js";
 import { collectPlaybookMetricWarnings } from "./playbook-metric-warnings.js";
+import {
+  beginHookTimeline,
+  endHookTimeline,
+  stopAllRunEventForwarders,
+} from "./run-event-forwarder.js";
 import { stripSkillPreamble } from "./skills.js";
 
 // --- Signed-upload handshake (artifacts & card attachments) ---
@@ -357,6 +373,18 @@ interface MemorySessionState {
   // without a round-trip. May be undefined if the start endpoint did not
   // return an id (older clients) — `scope: 'session'` will then refuse.
   agentSessionId?: string;
+  /**
+   * The tenant this session was recorded under (`ToolDeps.getScopeId`) —
+   * `undefined` on stdio, where one process serves one user.
+   *
+   * `memorySessions` is keyed by card id ALONE and lives at module scope, so on
+   * the hosted transport (`remote.ts`, one process for every user) a lookup can
+   * hand back another user's session for the same card. Anything that CLAIMS
+   * the tracked session must compare this first — see `comment-session.ts`
+   * (#1035), where claiming a stranger's id means a 403 rather than a wrong
+   * name on a comment.
+   */
+  scopeId?: string;
   memoryReadCount: number;
   pendingActions: { action: string; ts: string }[];
   allActions: { action: string; ts: string }[];
@@ -489,12 +517,14 @@ function initMemorySession(
   agentIdentifier: string,
   agentName: string,
   agentSessionId?: string,
+  scopeId?: string,
 ): void {
   memorySessions.set(cardId, {
     cardId,
     agentIdentifier,
     agentName,
     agentSessionId,
+    scopeId,
     memoryReadCount: 0,
     pendingActions: [],
     allActions: [],
@@ -660,6 +690,16 @@ export const TOOLS = {
           description:
             "Plan ID to link this card to (optional). Links the card to that plan via its plan_id.",
         },
+        planTaskId: {
+          type: "string",
+          description:
+            "Id of the plan CRITERION this card is created to fulfil (optional; requires `planId`). " +
+            "Sets both directions at once: the card's plan_id, and the criterion's card_id — the " +
+            "return leg a card outcome needs to reach the plan. Read the ids from harmony_get_plan's " +
+            "`tasks`. A criterion that is not in the named plan refuses the whole call, so no card is " +
+            "created on a false premise; a failure to write the return leg AFTER the card exists " +
+            "keeps the card and reports it in `planTask` instead.",
+        },
         attachments: {
           type: "array",
           description:
@@ -2326,6 +2366,44 @@ export const TOOLS = {
     },
   },
 
+  harmony_link_plan_task: {
+    description:
+      "Point a plan CRITERION at the card that fulfils it, and/or set the criterion's status. " +
+      "A plan task is a success criterion, not a work item: `cards.plan_id` says which plan a card " +
+      "belongs to, and this sets the return leg the plan needs to show real progress instead of " +
+      "guessing from board-column names. Use it to repair a link, to re-point a criterion at a " +
+      "different card, or to mark a criterion `completed` once its card actually delivered it. " +
+      "Leave a criterion the card did NOT deliver open — an open criterion is the signal. " +
+      "Linking a card that belongs to no plan yet also adopts it into this one (reported as " +
+      "`cardPlanAdopted`), and linking a card that already belongs to a DIFFERENT plan is " +
+      "refused — move it with harmony_update_card first, so the two directions cannot drift.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        planId: { type: "string", description: "Plan ID owning the criterion" },
+        taskId: {
+          type: "string",
+          description:
+            "Criterion id, from harmony_get_plan's `tasks`. Must belong to `planId`.",
+        },
+        cardId: {
+          type: "string",
+          description:
+            "Card that fulfils this criterion. Must live in the plan's own project, and " +
+            "must belong to this plan or to no plan yet — a card already in another plan " +
+            "is refused rather than silently re-pointed.",
+        },
+        status: {
+          type: "string",
+          enum: ["pending", "in_progress", "completed"],
+          description:
+            "Criterion status. Set `completed` only when the card demonstrably delivered it.",
+        },
+      },
+      required: ["planId", "taskId"],
+    },
+  },
+
   // ============ PLAYBOOK TOOLS (Method/Loop layer) ============
 
   harmony_list_playbook: {
@@ -2435,6 +2513,25 @@ export const TOOLS = {
     },
   },
 
+  harmony_delete_playbook: {
+    // The description carries the cascade because that is where the model
+    // reads it (card #856). Deprecating is the reversible verb and is named
+    // first on purpose: it is almost always the right one, and it is already
+    // available through harmony_update_playbook.
+    description:
+      "Permanently delete a playbook. IRREVERSIBLE and cascading: its version snapshots and run history are deleted with it, and every card currently running it is unbound — the card stays on the board and keeps its column, but loses its playbook, its pinned version and its stage pointer, so the agent daemon stops treating it as a stage card. Prefer harmony_update_playbook with state='deprecated' unless the playbook should never have existed: a deprecated playbook stays applicable to in-flight cards and is only hidden from new applies. Requires the playbook's creator or a workspace owner/admin — and an ARMED playbook (triggerType 'auto') takes an owner/admin even from its creator, because removing it stops the workspace's automation for everyone. Anyone else is refused and the playbook is left alone. Returns unboundCardCount (the exact number of cards it unbound) and unboundCards (up to 50 of them by id, short_id, title and the stage each one lost).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        playbookId: {
+          type: "string",
+          description: "Playbook ID to delete (UUID)",
+        },
+      },
+      required: ["playbookId"],
+    },
+  },
+
   // ============ ONBOARDING TOOLS ============
   harmony_signup: {
     description:
@@ -2819,7 +2916,12 @@ async function resolveColumnByName(
   return col;
 }
 
-async function handleToolCall(
+/**
+ * Exported for tests (card #1038). A pure helper proves its own signature and nothing
+ * about the call site — the two-direction plan link is only real if THIS switch performs
+ * both writes, so the wiring needs a test that drives the tool by name.
+ */
+export async function handleToolCall(
   name: string,
   args: Record<string, unknown>,
   deps: ToolDeps,
@@ -2877,17 +2979,66 @@ async function handleToolCall(
               )
               .parse(args.attachments)
           : [];
+      // Plan criterion ↔ card, both directions in one call (card #1038).
+      const planId = args.planId
+        ? z.string().uuid().parse(args.planId)
+        : undefined;
+      const planTaskId = args.planTaskId
+        ? z.string().uuid().parse(args.planTaskId)
+        : undefined;
+      if (planTaskId && !planId) {
+        throw new Error(
+          "planTaskId requires planId: no route resolves a plan from a criterion id alone. " +
+            "Pass the plan the criterion belongs to — harmony_get_plan returns both.",
+        );
+      }
+      // Refuse BEFORE the card exists. A criterion that is not in the named plan means the
+      // caller is pointing at the wrong thing, and a card created on that premise is worse
+      // than no card. A failure AFTER the card exists is handled the other way round below.
+      let criterion: PlanTaskRow | undefined;
+      if (planTaskId && planId) {
+        const { tasks } = await client.getPlan(planId);
+        const found = findPlanTask(tasks, planTaskId);
+        if (!found.ok) throw new Error(found.reason);
+        criterion = found.task;
+      }
+
       const result = await client.createCard(projectId, {
         title,
         columnId: args.columnId as string | undefined,
         description: args.description as string | undefined,
         priority: args.priority as string | undefined,
         assigneeId: args.assigneeId as string | undefined,
-        planId: args.planId as string | undefined,
+        planId,
       });
 
+      const newCardId = (result.card as { id?: string } | null)?.id;
+
+      // The return leg. Never throws: the card is the expensive artifact, and a missing
+      // link is repairable with harmony_link_plan_task. Reported, never swallowed.
+      let planTask: PlanTaskLinkReport | undefined;
+      if (criterion && planId) {
+        if (!newCardId) {
+          planTask = unlinkedReport(
+            planId,
+            criterion,
+            new Error("no card id was returned to link against"),
+          );
+        } else {
+          try {
+            await client.updatePlanTask(planId, criterion.id, {
+              cardId: newCardId,
+            });
+            planTask = linkedReport(planId, criterion, newCardId);
+          } catch (err) {
+            planTask = unlinkedReport(planId, criterion, err);
+          }
+        }
+      }
+      const planTaskField = planTask ? { planTask } : {};
+
       if (attachments.length === 0) {
-        return { success: true, ...result };
+        return { success: true, ...result, ...planTaskField };
       }
 
       // Attach reference files (e.g. a prompt screenshot) to the freshly
@@ -2895,11 +3046,11 @@ async function handleToolCall(
       // runs only after createCard returns. A bad attachment must never lose
       // the card — per-file failures are captured and reported alongside the
       // successes rather than throwing out the whole create.
-      const cardId = (result.card as { id?: string } | null)?.id;
-      if (!cardId) {
+      if (!newCardId) {
         return {
           success: true,
           ...result,
+          ...planTaskField,
           attachmentWarning:
             "Card created, but attachments were skipped: no card id was returned to upload against.",
         };
@@ -2907,7 +3058,7 @@ async function handleToolCall(
       const attachmentResults = await Promise.all(
         attachments.map(async (file) => {
           try {
-            const uploaded = await attachFileToCard(client, cardId, file);
+            const uploaded = await attachFileToCard(client, newCardId, file);
             return { ok: true as const, attachment: uploaded.attachment };
           } catch (err) {
             return {
@@ -2918,7 +3069,12 @@ async function handleToolCall(
           }
         }),
       );
-      return { success: true, ...result, attachments: attachmentResults };
+      return {
+        success: true,
+        ...result,
+        ...planTaskField,
+        attachments: attachmentResults,
+      };
     }
 
     case "harmony_update_card": {
@@ -3700,38 +3856,54 @@ async function handleToolCall(
         args.replyToId !== undefined
           ? z.string().uuid().parse(args.replyToId)
           : undefined;
-      // Name our OWN session on this card when this process started one, so the
-      // attribution is exact rather than inferred.
+      // Name our OWN session, or say plainly that we hold none (#1035).
       //
-      // LIMIT, so nobody reads more into this than it does: when this is
-      // undefined the server does NOT post sessionless — it falls back to "any
-      // session this user has on this card" (`createComment` in
-      // supabase/functions/harmony-api/handler.ts), which is true of every
-      // concurrent run of the same account. So the borrowed attribution
-      // measured on card #1029 is still reachable, and closing it needs the
-      // daemon to name its session too, at which point that fallback can go.
-      // Until then it must stay: a daemon-run agent cannot call
-      // `harmony_start_agent_session` (the daemon owns the lifecycle and
-      // disables it), and the session id is not in its environment either, so
-      // this lookup is always empty there. Declaring "sessionless" on an empty
-      // lookup would strip the session from EVERY daemon agent comment and
-      // `isDaemonAuthoredComment` would stop recognising the daemon's own
-      // contract and handoff artifacts.
+      // The server no longer infers either way: the `card_id` + `user_id`
+      // fallback in `createComment` is gone, because it was true of every
+      // concurrent run of the same account and a second run inherited the
+      // first one's attribution (measured on card #1029). So this call is now
+      // the whole answer, and `chooseCommentSession` is where it is decided —
+      // read that module for why an absent declaration is an ANSWER here and
+      // was a guess there.
       //
-      // Also note the explicit branch accepts any of the caller's sessions on
-      // the card regardless of `ended_at`, where the implicit one applies
-      // `pickAgentCommentSession`'s swept-session grace window (#771). Naming
-      // our own session is the stronger evidence — this process IS that run —
-      // so the wider window is intended here.
-      const agentSessionId = getMemorySession(cardId)?.agentSessionId;
+      // Two declarations, never an observation: the session THIS process
+      // started (`memorySessions`, the interactive `/hmy` path, checked against
+      // the caller's tenant), and the one the daemon put in this process's
+      // environment for the run it serves (the daemon path, which needs one
+      // because `harmony_start_agent_session` is denied on a daemon run).
+      //
+      // Note the explicit branch on the server accepts any of the caller's own
+      // sessions on the card regardless of `ended_at`. That is deliberate and
+      // it is what replaced #771's swept-session grace window: a run the
+      // silence sweep cut off still names its own id and its last report is
+      // still a run artifact, with no time bound, because naming the session is
+      // knowledge where the window was a guess.
+      const sessionChoice = chooseCommentSession({
+        cardId,
+        tracked: getMemorySession(cardId),
+        callerScopeId: deps.getScopeId?.(),
+        declared: readDeclaredRunSession(),
+      });
       const result = await client.addComment(cardId, body, {
         commentType,
         supersedesId,
         confirmsId,
         replyToId,
-        agentSessionId,
+        agentSessionId:
+          sessionChoice.kind === "session"
+            ? sessionChoice.agentSessionId
+            : undefined,
       });
-      return { success: true, ...result };
+      return {
+        success: true,
+        ...result,
+        // Said out loud rather than left to be inferred from the row: a
+        // sessionless comment is a legal shape (#1033) and a degraded one, and
+        // an agent that expected its run to be named should be able to see
+        // that it was not.
+        sessionAttribution:
+          sessionChoice.kind === "session" ? sessionChoice.source : "none",
+      };
     }
 
     case "harmony_get_comments": {
@@ -4091,7 +4263,25 @@ async function handleToolCall(
       // backend session id so working-memory writes (`scope: 'session'`) bind
       // to the same `card_agent_context` row that progress/end calls target.
       const agentSessionId = (result.session as { id?: string } | null)?.id;
-      initMemorySession(cardId, agentIdentifier, agentName, agentSessionId);
+      // The scope is recorded WITH the session, so a later read can tell "mine"
+      // from "the same card, a different user on this hosted process" (#1035).
+      initMemorySession(
+        cardId,
+        agentIdentifier,
+        agentName,
+        agentSessionId,
+        deps.getScopeId?.(),
+      );
+
+      // Publish the session on disk and start draining the `PostToolUse` hook's
+      // spool (#874). This is what gives an MCP session a tool-call timeline
+      // instead of one row per progress checkpoint. It no-ops on a daemon run
+      // and on any failure — see `beginHookTimeline`.
+      beginHookTimeline({
+        cardId,
+        agentSessionId,
+        getClient: () => client,
+      });
 
       return {
         success: true,
@@ -4207,6 +4397,11 @@ async function handleToolCall(
       await flushMemoryActions(client, cardId);
       cleanupMemorySession(cardId);
 
+      // Drain the hook spool and unpublish while the session row still accepts
+      // appends (#874). Ordered before `endAgentSession` for that reason: the
+      // last tool calls of a run are the ones a reader most wants.
+      await endHookTimeline(cardId);
+
       // 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
@@ -5249,7 +5444,11 @@ async function handleToolCall(
     }
 
     case "harmony_get_plan": {
-      let result: { plan: unknown; tasks: unknown[] } | null = null;
+      let result: {
+        plan: unknown;
+        tasks: unknown[];
+        foreign_criteria?: unknown[];
+      } | null = null;
 
       if (args.planId) {
         const planId = z.string().uuid().parse(args.planId);
@@ -5257,7 +5456,14 @@ async function handleToolCall(
       } else if (args.cardId) {
         const cardId = z.string().uuid().parse(args.cardId);
         result = await client.getPlanByCardId(cardId);
-        if (!result) {
+        // Three distinct answers, and they must stay distinct. The route
+        // normalises "nothing to report" to `{plan: null, tasks: []}` rather
+        // than a null body, so a truthiness check alone cannot tell the clean
+        // no-plan card from the divergent one.
+        if (
+          !result ||
+          (result.plan == null && !result.foreign_criteria?.length)
+        ) {
           return {
             success: true,
             plan: null,
@@ -5265,6 +5471,27 @@ async function handleToolCall(
             message: "No plan linked to this card",
           };
         }
+        // The card belongs to no plan, yet some criterion elsewhere names it (#1054).
+        // Reporting that as "no plan linked" is the silence this card was filed for,
+        // one level up from the daemon: a person asking which plan a card serves must
+        // be told the two directions disagree, and which end to repair.
+        // `result.foreign_criteria?.length` is the whole predicate: the route
+        // always answers with an object, so `result.plan == null` is also true
+        // for the ordinary "this card is in no plan" case. Without the second
+        // half, every plan-less card was told plan criteria point at it and
+        // handed a repair instruction for a problem it did not have — the
+        // card's own failure mode inverted.
+        if (result.plan == null && result.foreign_criteria?.length) {
+          return {
+            success: true,
+            plan: null,
+            tasks: [],
+            divergentCriteria: result.foreign_criteria ?? [],
+            message:
+              "This card belongs to no plan, but plan criteria point at it. " +
+              "Repair it with harmony_update_card (planId) or harmony_link_plan_task.",
+          };
+        }
       } else {
         throw new Error("Either planId or cardId must be provided");
       }
@@ -5273,6 +5500,11 @@ async function handleToolCall(
         success: true,
         plan: result.plan,
         tasks: result.tasks,
+        // Criteria naming this card from a plan it does not belong to — a data error,
+        // reported rather than folded into `tasks` (#1054). Omitted when there are none.
+        ...(result.foreign_criteria?.length
+          ? { divergentCriteria: result.foreign_criteria }
+          : {}),
       };
     }
 
@@ -5297,6 +5529,54 @@ async function handleToolCall(
       return { success: true, plan: result.plan };
     }
 
+    case "harmony_link_plan_task": {
+      // The return leg on its own (card #1038): repair a link, re-point a criterion, or
+      // mark one delivered. `harmony_create_card` writes it at birth; this is every other
+      // moment, and it is what a completion path calls to close the loop.
+      const planId = z.string().uuid().parse(args.planId);
+      const taskId = z.string().uuid().parse(args.taskId);
+      const cardId = args.cardId
+        ? z.string().uuid().parse(args.cardId)
+        : undefined;
+      const status = args.status
+        ? z.enum(["pending", "in_progress", "completed"]).parse(args.status)
+        : undefined;
+      if (!cardId && !status) {
+        throw new Error("Nothing to do: pass cardId, status, or both.");
+      }
+
+      // Same fail-closed read as the create path — the criterion has to be in THIS plan.
+      // The route scopes its update by plan_id too, but a rejection that names the
+      // mistake beats a zero-row update surfacing as an opaque database error.
+      const { tasks } = await client.getPlan(planId);
+      const found = findPlanTask(tasks, taskId);
+      if (!found.ok) throw new Error(found.reason);
+
+      // Linking also maintains the card's own `plan_id` server-side (#1054) — see the
+      // "which direction carries the truth" note in `_shared/plan-task-card-scope.ts`.
+      // A card that belongs to a DIFFERENT plan is refused there, so this call can throw
+      // where it used to succeed and leave the two columns disagreeing.
+      const result = await client.updatePlanTask(planId, taskId, {
+        cardId,
+        status,
+      });
+      return {
+        success: true,
+        planTask: {
+          planId,
+          taskId,
+          criterion: found.task.content ?? null,
+          ...(cardId
+            ? linkedReport(planId, found.task, cardId)
+            : { linked: found.task.card_id != null }),
+          ...(cardId && result.cardPlanAdopted
+            ? { cardPlanAdopted: true }
+            : {}),
+          ...(status ? { status } : {}),
+        },
+      };
+    }
+
     case "harmony_advance_plan": {
       // Simplified: just archive the plan
       const planId = z.string().uuid().parse(args.planId);
@@ -5435,6 +5715,26 @@ async function handleToolCall(
       };
     }
 
+    case "harmony_delete_playbook": {
+      const playbookId = z.string().uuid().parse(args.playbookId);
+      // No `confirm` argument, deliberately. Every other destructive tool here
+      // (harmony_delete_card, harmony_delete_column — which deletes its cards)
+      // takes none, and a flag the caller chooses is not a bound: the model
+      // that decided to delete also supplies the confirmation. What actually
+      // holds is the route's creator-or-admin check, the description above
+      // pointing at deprecate, and this reply naming what was unbound.
+      const result = await client.deletePlaybook(playbookId);
+      // The count is the server's exact one; the list is its capped sample. Do
+      // not derive the count from the list — that silently under-reports the
+      // blast radius on exactly the playbook where it matters most.
+      return {
+        success: true,
+        playbook: result.playbook,
+        unboundCardCount: result.unboundCardCount,
+        unboundCards: result.unboundCards,
+      };
+    }
+
     // Deprecated (#612) — see harmony_run_playbook above.
     case "harmony_save_card_as_playbook":
       return deprecatedRemovedToolResult("harmony_save_card_as_playbook");
@@ -5616,6 +5916,14 @@ export class HarmonyMCPServer {
       } catch {
         // Best-effort
       }
+      try {
+        // Drain any tool calls the hook spooled but the timer had not posted,
+        // and remove the on-disk pointers so a later hook cannot route to a
+        // session this process took with it (#874).
+        await stopAllRunEventForwarders();
+      } catch {
+        // Best-effort
+      }
       destroyAutoSession();
       process.exit(exitCode);
     };

package/src/tui/setup.ts

@@ -106,6 +106,9 @@ const SAFE_HARMONY_TOOLS = [
   "harmony_create_plan",
   "harmony_update_plan",
   "harmony_advance_plan",
+  // Points a plan criterion at the card that fulfils it, or marks it delivered.
+  // Non-destructive and re-pointable, and the completion path calls it per card.
+  "harmony_link_plan_task",
   "harmony_remember",
   "harmony_relate",
   "harmony_update_memory",