@gethmy/mcp 2.23.0 → 2.25.0

package/dist/lib/oauth-refresh.js

@@ -17,7 +17,7 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 // src/config.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join, parse, resolve } from "node:path";
 function getConfigDir() {
   return join(homedir(), ".harmony-mcp");
 }
@@ -27,6 +27,22 @@ function getConfigPath() {
 function getLocalConfigPath(cwd) {
   return join(cwd || process.cwd(), LOCAL_CONFIG_FILENAME);
 }
+function findLocalConfigPath(cwd) {
+  const home = resolve(homedir());
+  let dir = resolve(cwd || process.cwd());
+  const { root } = parse(dir);
+  for (;; ) {
+    if (dir !== home && dir !== root) {
+      const candidate = join(dir, LOCAL_CONFIG_FILENAME);
+      if (existsSync(candidate))
+        return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir)
+      return null;
+    dir = parent;
+  }
+}
 function emptyConfig() {
   return {
     apiKey: null,
@@ -78,8 +94,8 @@ function saveConfig(config) {
   });
 }
 function loadLocalConfig(cwd) {
-  const localConfigPath = getLocalConfigPath(cwd);
-  if (!existsSync(localConfigPath)) {
+  const localConfigPath = findLocalConfigPath(cwd);
+  if (localConfigPath === null) {
     return null;
   }
   try {
@@ -94,7 +110,7 @@ function loadLocalConfig(cwd) {
   }
 }
 function saveLocalConfig(config, cwd) {
-  const localConfigPath = getLocalConfigPath(cwd);
+  const localConfigPath = findLocalConfigPath(cwd) ?? getLocalConfigPath(cwd);
   const existingConfig = loadLocalConfig(cwd) || {
     workspaceId: null,
     projectId: null
@@ -108,7 +124,7 @@ function saveLocalConfig(config, cwd) {
   writeFileSync(localConfigPath, JSON.stringify(cleanConfig, null, 2));
 }
 function hasLocalConfig(cwd) {
-  return existsSync(getLocalConfigPath(cwd));
+  return findLocalConfigPath(cwd) !== null;
 }
 function getActiveCredential() {
   const config = loadConfig();
@@ -133,33 +149,69 @@ function getUserEmail() {
 function setUserEmail(email) {
   saveConfig({ userEmail: email });
 }
-function setActiveWorkspace(workspaceId, options) {
-  if (options?.local) {
-    saveLocalConfig({ workspaceId }, options.cwd);
-  } else {
-    saveConfig({ activeWorkspaceId: workspaceId });
+function setActiveContext(context, options) {
+  if (options?.global) {
+    saveConfig({
+      activeWorkspaceId: context.workspaceId,
+      activeProjectId: context.projectId
+    });
+    return;
   }
-}
-function setActiveProject(projectId, options) {
-  if (options?.local) {
-    saveLocalConfig({ projectId }, options.cwd);
+  const localPath = findLocalConfigPath(options?.cwd);
+  if (options?.local || localPath !== null) {
+    saveLocalConfig({ workspaceId: context.workspaceId, projectId: context.projectId }, options?.cwd);
   } else {
-    saveConfig({ activeProjectId: projectId });
+    saveConfig({
+      activeWorkspaceId: context.workspaceId,
+      activeProjectId: context.projectId
+    });
   }
 }
-function getActiveWorkspaceId(cwd) {
+function setActiveWorkspace(workspaceId, options) {
+  const currentWorkspaceId = getActiveWorkspaceId(options?.cwd);
+  const keepProject = currentWorkspaceId === workspaceId;
+  setActiveContext({
+    workspaceId,
+    projectId: keepProject ? getActiveProjectId(options?.cwd) : null
+  }, options);
+}
+function readActiveContext(cwd) {
   const localConfig = loadLocalConfig(cwd);
-  if (localConfig?.workspaceId) {
-    return localConfig.workspaceId;
+  if (localConfig) {
+    return {
+      workspaceId: localConfig.workspaceId ?? null,
+      projectId: localConfig.projectId ?? null
+    };
   }
-  return loadConfig().activeWorkspaceId;
+  const globalConfig = loadConfig();
+  return {
+    workspaceId: globalConfig.activeWorkspaceId,
+    projectId: globalConfig.activeProjectId
+  };
+}
+function getActiveWorkspaceId(cwd) {
+  return readActiveContext(cwd).workspaceId;
 }
 function getActiveProjectId(cwd) {
-  const localConfig = loadLocalConfig(cwd);
-  if (localConfig?.projectId) {
-    return localConfig.projectId;
+  return readActiveContext(cwd).projectId;
+}
+function getActiveContext(cwd) {
+  return describeActiveContext({
+    projectId: getActiveProjectId(cwd),
+    workspaceId: getActiveWorkspaceId(cwd)
+  });
+}
+function describeActiveContext(context) {
+  const { projectId, workspaceId } = context;
+  if (projectId && !workspaceId) {
+    return {
+      projectId,
+      workspaceId,
+      consistent: false,
+      note: `An active project (${projectId}) is set with no active workspace, so ` + "workspace-scoped tools cannot resolve one from it. Re-set it with " + "harmony_set_project_context, or pass workspaceId explicitly."
+    };
   }
-  return loadConfig().activeProjectId;
+  return { projectId, workspaceId, consistent: true, note: null };
 }
 function isConfigured() {
   const config = loadConfig();
@@ -238,7 +290,7 @@ function lockPath() {
   return join2(getConfigDir(), LOCK_FILENAME);
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 async function withRefreshLock(fn) {
   const path = lockPath();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethmy/mcp",
-  "version": "2.23.0",
+  "version": "2.25.0",
   "description": "MCP server for Harmony, the shared surface for human–agent teams — agents claim cards, report progress, and move work on your board.",
   "publishConfig": {
     "access": "public"

package/src/api-client.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import {
   type AgentRunEventDraft,
   type Comment,
@@ -9,6 +10,7 @@ import {
   type WorkspaceAgent,
 } from "@harmony/shared";
 import { getApiKey, getApiUrl } from "./config.js";
+import type { ReadConsumer } from "./read-consumer.js";
 
 export interface ApiResponse<T = unknown> {
   success?: boolean;
@@ -49,6 +51,27 @@ function getRetryDelay(attempt: number): number {
 
 const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 
+/**
+ * Build the recall query for a card. The title alone was the whole query, which
+ * is too thin to rank against. The description is capped because a card body
+ * runs to 10,000 characters, the embedding truncates at END, and an uncapped
+ * body drowns the title it is meant to sharpen.
+ */
+export function buildMemoryQuery(
+  title: string,
+  description: string | null | undefined,
+): string {
+  const DESCRIPTION_CAP = 600;
+  const trimmedTitle = title.trim();
+  const trimmedBody = (description ?? "").trim();
+
+  if (!trimmedTitle && !trimmedBody) return "";
+  if (!trimmedTitle) return trimmedBody.slice(0, DESCRIPTION_CAP);
+  if (!trimmedBody) return trimmedTitle;
+
+  return `${trimmedTitle}\n${trimmedBody.slice(0, DESCRIPTION_CAP)}`;
+}
+
 // Semaphore for concurrency control
 class Semaphore {
   private permits: number;
@@ -532,7 +555,17 @@ export class HarmonyApiClient {
   /** Register/upsert this daemon's virtual agent. Idempotent by (workspace, identifier). */
   async registerWorkspaceAgent(
     workspaceId: string,
-    data: { identifier: string; name: string; color?: string },
+    data: {
+      identifier: string;
+      name: string;
+      color?: string;
+      /**
+       * Gate metric NAMES the daemon declares under `agent.playbooks.metrics`
+       * (#922) — names only, never the commands behind them. Omit to leave the
+       * stored report untouched.
+       */
+      declaredGateMetrics?: string[];
+    },
   ): Promise<{ agent: WorkspaceAgent }> {
     return this.request("POST", `/workspaces/${workspaceId}/agents`, data);
   }
@@ -1097,6 +1130,15 @@ export class HarmonyApiClient {
        * working); the MCP tool dispatch defaults to `interactive`.
        */
       driver?: "daemon" | "interactive" | "script";
+      /**
+       * When a human budget decision is pending on this session, as an ISO
+       * timestamp (card #915). A run START passes `null` explicitly: the route
+       * REUSES a live session row, so a card whose previous run parked would
+       * otherwise inherit that park's deadline — the panel offering Continue
+       * over a run that is already going again, and the sweep exemption
+       * masking a genuinely dead run for the rest of the window.
+       */
+      awaitingDecisionUntil?: string | null;
     },
   ): Promise<{
     session: unknown;
@@ -1147,6 +1189,53 @@ export class HarmonyApiClient {
     );
   }
 
+  /**
+   * Post a human's durable answer to a parked run's budget question (card
+   * #915): grant more turns and continue, or stop and hand the card back.
+   *
+   * Unlike pause/resume/stop — an ephemeral Realtime broadcast nothing hears
+   * once the daemon is offline — this MUST survive a daemon restart hours
+   * later, so it lands as a `budget_decision` row rather than a broadcast.
+   * The server resolves which run to decide for from the card's one active
+   * session; the caller does not (and, deciding from the board, cannot) name
+   * a session id.
+   */
+  async postBudgetDecision(
+    cardId: string,
+    data: {
+      decision: "continue" | "stop";
+      extraTurns: number;
+      message?: string;
+    },
+  ): Promise<{ id: string; seq: number; createdAt: string }> {
+    return this.request("POST", `/cards/${cardId}/budget-decisions`, data);
+  }
+
+  /**
+   * Drain `budget_decision` events for a card since `sinceIso` (card #915).
+   * Keyed on card + time, not session + seq like `getPendingMessages`: the
+   * daemon asking on startup may not know the session id of a run it parked
+   * hours or days earlier, but it always knows the card.
+   */
+  async getBudgetDecisions(
+    cardId: string,
+    sinceIso: string,
+  ): Promise<{
+    decisions: Array<{
+      decision: "continue" | "stop";
+      extraTurns: number;
+      message?: string;
+      createdAt: string;
+    }>;
+  }> {
+    const params = new URLSearchParams();
+    params.set("sinceIso", sinceIso);
+    return this.request(
+      "GET",
+      `/cards/${cardId}/budget-decisions?${params.toString()}`,
+    );
+  }
+
   async updateAgentProgress(
     cardId: string,
     data: {
@@ -1205,6 +1294,16 @@ export class HarmonyApiClient {
        * deferred the respawn by 10 minutes (#770). Reply carries `stopped: true`.
        */
       implicitCreate?: boolean;
+      /**
+       * Set while the session waits for a human budget decision (#915),
+       * cleared (null) once one arrives. Exempts the row from the daemon's
+       * stale-session sweep until this instant — a parked run's deliberate
+       * silence would otherwise read as abandonment well before a person can
+       * answer. ISO timestamp string; the daemon-side mirror
+       * (`StateStore.parkRun`'s `awaitingDecisionUntil`) is the same instant
+       * in epoch ms, not this string.
+       */
+      awaitingDecisionUntil?: string | null;
     },
   ): Promise<{
     session: unknown;
@@ -1351,6 +1450,9 @@ export class HarmonyApiClient {
     // Opt in to agent-run episodes (default excluded, #677). Only the daemon's
     // own rolling-episode lookup should set this.
     include_episodes?: boolean;
+    /** Read-accounting label (task 4) — omitted means the read is not
+     * recorded. Callers that know their own identity should pass it. */
+    consumer?: ReadConsumer;
   }): Promise<{ entities: unknown[]; count: number }> {
     const params = new URLSearchParams();
     params.set("workspace_id", options.workspace_id);
@@ -1367,6 +1469,7 @@ export class HarmonyApiClient {
     if (options.offset !== undefined)
       params.set("offset", String(options.offset));
     if (options.include_superseded) params.set("include_superseded", "true");
+    if (options.consumer) params.set("consumer", options.consumer);
     if (options.include_episodes) params.set("include_episodes", "true");
     return this.request("GET", `/memory/entities?${params.toString()}`);
   }
@@ -1419,9 +1522,17 @@ export class HarmonyApiClient {
     // Opt in to agent-run episodes (default excluded server-side, #677). The
     // daemon sets this when looking up its own rolling implement/review episode.
     includeEpisodes?: boolean;
+    /** Read-accounting label (task 4) — omitted means the read is not
+     * recorded. Callers that know their own identity should pass it. */
+    consumer?: ReadConsumer;
   }): Promise<{ entities: unknown[] }> {
     // Over-fetch beyond topK so client-side filters (multi-type, memory_tier,
     // tags) have headroom — matches the MCP server's recall path (server.ts).
+    // `consumer` is deliberately NOT forwarded on this over-fetch: the server
+    // would record read-accounting for every over-fetched row, not just the
+    // ones actually delivered. Instead we record the delivered set below,
+    // after client-side filtering and the topK trim (mirrors the mcp-tool
+    // path in server.ts).
     const fetchLimit = Math.max(options.topK ?? 3, 50);
     let entities: Array<Record<string, unknown>> = [];
 
@@ -1483,6 +1594,21 @@ export class HarmonyApiClient {
       entities = entities.slice(0, options.topK);
     }
 
+    // Read accounting: record only the entities actually delivered to the
+    // caller, after all client-side filtering and the topK trim — never the
+    // larger over-fetched candidate pool the calls above deliberately left
+    // unrecorded. Best-effort; a recording failure must not fail the recall.
+    if (options.consumer) {
+      const deliveredIds = entities
+        .map((e) => e.id)
+        .filter((id): id is string => typeof id === "string");
+      if (deliveredIds.length > 0) {
+        this.batchTouchMemoryEntities(deliveredIds, options.consumer).catch(
+          () => {},
+        );
+      }
+    }
+
     return { entities };
   }
 
@@ -1496,9 +1622,16 @@ export class HarmonyApiClient {
 
   async batchTouchMemoryEntities(
     entityIds: string[],
+    /** Read-accounting label (task 4, fix round 1). Omitted → the route keeps
+     * its original increment-only `batch_touch_knowledge_entities` behaviour
+     * (legacy context-assembly callers). Given → the route instead records
+     * through `record_entity_reads`, the same path the search chokepoint
+     * uses, so this touch is properly attributed rather than anonymous. */
+    consumer?: ReadConsumer,
   ): Promise<{ success: boolean; count: number }> {
     return this.request("POST", "/memory/entities/batch-touch", {
       entity_ids: entityIds,
+      ...(consumer ? { consumer } : {}),
     });
   }
 
@@ -1533,6 +1666,16 @@ export class HarmonyApiClient {
       tags?: string[];
       include_superseded?: boolean;
       include_episodes?: boolean;
+      /** Read-accounting label (task 4) — omitted means the read is not
+       * recorded (there is deliberately no server-side default: it used to
+       * default to "search" and inflated access_count on every
+       * `harmony_remember` write-side probe). Callers that know their own
+       * identity (harmony_recall) should pass it explicitly. */
+      consumer?: ReadConsumer;
+      /** Per-prompt-build id (task 6b) — shared by every read row recorded
+       * during one `generateCardPrompt` call, so a card can later show which
+       * memories shaped its prompt. */
+      assembly_id?: string;
     },
   ): Promise<{ entities: unknown[]; count: number }> {
     const params = new URLSearchParams();
@@ -1546,7 +1689,9 @@ export class HarmonyApiClient {
     // matches against the canonical `tags_normalized` column (#299).
     for (const tag of options?.tags ?? []) params.append("tags", tag);
     if (options?.include_superseded) params.set("include_superseded", "true");
+    if (options?.consumer) params.set("consumer", options.consumer);
     if (options?.include_episodes) params.set("include_episodes", "true");
+    if (options?.assembly_id) params.set("assembly_id", options.assembly_id);
     return this.request("GET", `/memory/search?${params.toString()}`);
   }
 
@@ -1558,12 +1703,16 @@ export class HarmonyApiClient {
     type?: string;
     limit?: number;
     include_episodes?: boolean;
+    /** Read-accounting label (task 4) — omitted means the read is not
+     * recorded. Callers that know their own identity should pass it. */
+    consumer?: ReadConsumer;
   }): Promise<{ entities: unknown[]; count: number }> {
     const params = new URLSearchParams();
     params.set("workspace_id", options.workspace_id);
     if (options.project_id) params.set("project_id", options.project_id);
     if (options.type) params.set("type", options.type);
     if (options.limit !== undefined) params.set("limit", String(options.limit));
+    if (options.consumer) params.set("consumer", options.consumer);
     if (options.include_episodes) params.set("include_episodes", "true");
     return this.request("GET", `/memory/index?${params.toString()}`);
   }
@@ -1574,12 +1723,16 @@ export class HarmonyApiClient {
     type?: string;
     limit?: number;
     include_episodes?: boolean;
+    /** Read-accounting label (task 4) — omitted means the read is not
+     * recorded. Callers that know their own identity should pass it. */
+    consumer?: ReadConsumer;
   }): Promise<string> {
     const params = new URLSearchParams();
     params.set("workspace_id", options.workspace_id);
     if (options.project_id) params.set("project_id", options.project_id);
     if (options.type) params.set("type", options.type);
     if (options.limit !== undefined) params.set("limit", String(options.limit));
+    if (options.consumer) params.set("consumer", options.consumer);
     if (options.include_episodes) params.set("include_episodes", "true");
     return this.requestRaw(
       "GET",
@@ -1668,6 +1821,9 @@ export class HarmonyApiClient {
       type?: string;
       limit?: number;
       include_episodes?: boolean;
+      /** Read-accounting label (task 4) — omitted means the read is not
+       * recorded. Callers that know their own identity should pass it. */
+      consumer?: ReadConsumer;
     },
   ): Promise<string> {
     const params = new URLSearchParams();
@@ -1677,6 +1833,7 @@ export class HarmonyApiClient {
     if (options?.type) params.set("type", options.type);
     if (options?.limit !== undefined)
       params.set("limit", String(options.limit));
+    if (options?.consumer) params.set("consumer", options.consumer);
     if (options?.include_episodes) params.set("include_episodes", "true");
     return this.requestRaw(
       "GET",
@@ -1978,18 +2135,22 @@ export class HarmonyApiClient {
     // Phase 0 (memory architecture v2): full context assembly removed.
     // Use the basic memory search path so callers still get _some_ memory
     // hints. Phase 1 will reintroduce a session-scoped working memory layer.
-    const assembledContextStr: string | undefined = undefined;
-    const assemblyId: string | undefined = undefined;
+
+    // One id per prompt build. Every read row recorded during this build carries
+    // it, which is what lets a card show the memories that shaped its prompt.
+    const assemblyId = randomUUID();
     let memories: MemoryItem[] | undefined;
 
     try {
       if (options.workspaceId && cardData.title) {
         const memoryResult = await this.searchMemoryEntities(
           options.workspaceId,
-          cardData.title,
+          buildMemoryQuery(cardData.title, cardData.description),
           {
             project_id: options.projectId,
             limit: 5,
+            consumer: "agent-prompt",
+            assembly_id: assemblyId,
           },
         );
         if (memoryResult.entities?.length > 0) {
@@ -2015,7 +2176,6 @@ export class HarmonyApiClient {
       contextOptions: options.contextOptions,
       customConstraints: options.customConstraints,
       memories,
-      assembledContext: assembledContextStr,
       assemblyId,
     });
 
@@ -2148,6 +2308,9 @@ export class HarmonyApiClient {
     description?: string;
     steps?: unknown;
     triggerType?: string;
+    /** Auto-bind rule (#892); validated server-side, passed through as-is. */
+    autoBind?: unknown;
+    catalogId?: string;
   }): Promise<{ playbook: unknown }> {
     return this.request("POST", "/playbooks", data);
   }
@@ -2160,6 +2323,9 @@ export class HarmonyApiClient {
       steps?: unknown;
       enabled?: boolean;
       state?: string;
+      triggerType?: string;
+      /** `null` clears the rule; absent leaves it untouched (#892). */
+      autoBind?: unknown;
     },
   ): Promise<{ playbook: unknown }> {
     return this.request("PATCH", `/playbooks/${playbookId}`, updates);

package/src/cli.ts

@@ -3,10 +3,11 @@ import { createRequire } from "node:module";
 import { program } from "commander";
 import {
   areSkillsInstalled,
+  findLocalConfigPath,
+  getActiveContext,
   getActiveProjectId,
   getActiveWorkspaceId,
   getConfigPath,
-  getLocalConfigPath,
   hasLocalConfig,
   isConfigured,
   loadConfig,
@@ -85,7 +86,9 @@ program
       console.log("\nContext:");
 
       if (hasLocal) {
-        console.log(`  Local config: ${getLocalConfigPath()}`);
+        // The file that is actually READ, which since #893 may be an ancestor's
+        // — printing the cwd path would name a file that does not exist.
+        console.log(`  Local config: ${findLocalConfigPath()}`);
         console.log(
           `    Workspace: ${localConfig?.workspaceId || "(not set)"}`,
         );
@@ -103,16 +106,14 @@ program
       // Show effective (active) context
       const effectiveWorkspace = getActiveWorkspaceId();
       const effectiveProject = getActiveProjectId();
-      const wsSource = localConfig?.workspaceId
-        ? "local"
-        : globalConfig.activeWorkspaceId
-          ? "global"
-          : "";
-      const projSource = localConfig?.projectId
-        ? "local"
-        : globalConfig.activeProjectId
-          ? "global"
-          : "";
+      // The local file wins as a WHOLE file (#893), so the source is the file,
+      // not the field: with a local config in scope BOTH ids come from it, and
+      // a key it omits reads as unset rather than falling through to global.
+      // Reporting "global" for such a field would describe a fallback that no
+      // longer happens.
+      const contextSource = hasLocal ? "local" : "global";
+      const wsSource = effectiveWorkspace ? contextSource : "";
+      const projSource = effectiveProject ? contextSource : "";
 
       console.log("\n  Active (effective):");
       console.log(
@@ -121,6 +122,14 @@ program
       console.log(
         `    Project: ${effectiveProject || "(not set)"}${projSource ? ` ← ${projSource}` : ""}`,
       );
+
+      // Say it out loud when the pair does not hold together (#893). A project
+      // with no workspace leaves every workspace-scoped tool guessing, and this
+      // status output is where a person looks when one of them misbehaves.
+      const report = getActiveContext();
+      if (!report.consistent && report.note) {
+        console.log(`\n  ⚠ ${report.note}`);
+      }
     } else {
       console.log("Status: Not configured\n");
       console.log("Run: npx @gethmy/mcp setup");