@gethmy/mcp 2.23.0 → 2.25.0

package/src/config.ts

@@ -1,6 +1,6 @@
 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";
 
 export interface HarmonyConfig {
   apiKey: string | null;
@@ -45,6 +45,38 @@ export function getLocalConfigPath(cwd?: string): string {
   return join(cwd || process.cwd(), LOCAL_CONFIG_FILENAME);
 }
 
+/**
+ * Find the nearest `.harmony-mcp.json` at or above `cwd` (card #893).
+ *
+ * The old behaviour looked in the exact cwd and nowhere else, so a server
+ * started from a package directory or a git worktree never saw the repo's pin
+ * and fell back to the global config **silently** — the active workspace then
+ * had nothing to do with the repo you were in.
+ *
+ * Two directories are deliberately skipped, however deep the walk goes:
+ *
+ * - **the home directory** — a stray file there would capture every session in
+ *   every repo, and `~/.harmony-mcp/config.json` is already the global pin;
+ * - **the filesystem root** — same reasoning, machine-wide.
+ *
+ * Returns `null` when no ancestor carries one.
+ */
+export function findLocalConfigPath(cwd?: string): string | null {
+  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(): HarmonyConfig {
   return {
     apiKey: null,
@@ -107,9 +139,9 @@ export function saveConfig(config: Partial<HarmonyConfig>): void {
 }
 
 export function loadLocalConfig(cwd?: string): LocalConfig | null {
-  const localConfigPath = getLocalConfigPath(cwd);
+  const localConfigPath = findLocalConfigPath(cwd);
 
-  if (!existsSync(localConfigPath)) {
+  if (localConfigPath === null) {
     return null;
   }
 
@@ -129,7 +161,10 @@ export function saveLocalConfig(
   config: Partial<LocalConfig>,
   cwd?: string,
 ): void {
-  const localConfigPath = getLocalConfigPath(cwd);
+  // Write back to the file we READ, not to the cwd: a `set_project_context`
+  // issued from a package directory must update the repo's pin rather than
+  // strand a second config file the repo root never looks at (card #893).
+  const localConfigPath = findLocalConfigPath(cwd) ?? getLocalConfigPath(cwd);
 
   const existingConfig = loadLocalConfig(cwd) || {
     workspaceId: null,
@@ -146,7 +181,9 @@ export function saveLocalConfig(
 }
 
 export function hasLocalConfig(cwd?: string): boolean {
-  return existsSync(getLocalConfigPath(cwd));
+  // Same walk as `loadLocalConfig`, or this reports "no local config" for a
+  // session an ancestor file actually governs.
+  return findLocalConfigPath(cwd) !== null;
 }
 
 /**
@@ -185,48 +222,185 @@ export function setUserEmail(email: string | null): void {
 }
 
 export interface SetContextOptions {
+  /** Force a write to the repo-local `.harmony-mcp.json` (creating it). */
   local?: boolean;
+  /**
+   * Force a write to the global `~/.harmony-mcp/config.json`, even when a local
+   * file exists. Setup uses this to mirror the chosen context into the global
+   * default; without it the mirror would land back in the local file it just
+   * wrote, leaving every server started from another directory with no context.
+   */
+  global?: boolean;
   cwd?: string;
 }
 
-export function setActiveWorkspace(
-  workspaceId: string | null,
+/** The active context is ONE pair. A project always names its workspace. */
+export interface ActiveContext {
+  projectId: string | null;
+  workspaceId: string | null;
+}
+
+/**
+ * Set the active project and workspace together (card #893).
+ *
+ * This is the ONLY way to set an active project, deliberately: the two ids used
+ * to be written by separate functions, so a project could end up active in a
+ * workspace it does not belong to. Every workspace-scoped tool then read the
+ * wrong workspace and said nothing — `harmony_list_playbook` returned 0 while
+ * the project's real workspace held 4.
+ *
+ * Callers always have both values: the `#shortId` resolver returns the card's
+ * project WITH its `workspaceId`, and `harmony_set_project_context` looks the
+ * project up before writing.
+ */
+export function setActiveContext(
+  context: ActiveContext,
   options?: SetContextOptions,
 ): void {
-  if (options?.local) {
-    saveLocalConfig({ workspaceId }, options.cwd);
+  // WRITE WHERE THE READ RESOLVES. `getActiveProjectId` / `getActiveWorkspaceId`
+  // are local-first, so writing to the global config while a local file exists
+  // made the write invisible: `harmony_set_project_context` answered
+  // `success: true` and every later read still returned the local pin. Worse,
+  // a workspace switch then wrote `activeProjectId: null` into the GLOBAL file
+  // off a locally-read comparison, wiping the active project of every *other*
+  // repo that has no local pin.
+  //
+  // `options.local: true` forces a local write (setup creates the file before
+  // it exists) and `options.global: true` forces a global one (setup ALSO
+  // mirrors the choice into the global default, so a server started from
+  // another directory has a context at all). With neither, the presence of a
+  // local file decides.
+  if (options?.global) {
+    saveConfig({
+      activeWorkspaceId: context.workspaceId,
+      activeProjectId: context.projectId,
+    });
+    return;
+  }
+  const localPath = findLocalConfigPath(options?.cwd);
+  if (options?.local || localPath !== null) {
+    saveLocalConfig(
+      { workspaceId: context.workspaceId, projectId: context.projectId },
+      options?.cwd,
+    );
   } else {
-    saveConfig({ activeWorkspaceId: workspaceId });
+    saveConfig({
+      activeWorkspaceId: context.workspaceId,
+      activeProjectId: context.projectId,
+    });
   }
 }
 
-export function setActiveProject(
-  projectId: string | null,
+/**
+ * Switch the active workspace.
+ *
+ * Switching to a DIFFERENT workspace clears the active project, because we
+ * cannot know whether that project lives in the new workspace — and assuming it
+ * does is exactly what produced the mismatch this function exists to prevent.
+ * Clearing fails safe: the next `#shortId` resolve re-establishes the pair.
+ * Re-setting the same workspace is a no-op for the project.
+ */
+export function setActiveWorkspace(
+  workspaceId: string | null,
   options?: SetContextOptions,
 ): void {
-  if (options?.local) {
-    saveLocalConfig({ projectId }, options.cwd);
-  } else {
-    saveConfig({ activeProjectId: projectId });
-  }
+  const currentWorkspaceId = getActiveWorkspaceId(options?.cwd);
+  const keepProject = currentWorkspaceId === workspaceId;
+  setActiveContext(
+    {
+      workspaceId,
+      projectId: keepProject ? getActiveProjectId(options?.cwd) : null,
+    },
+    options,
+  );
 }
 
-export function getActiveWorkspaceId(cwd?: string): string | null {
-  // Local config takes precedence over global
+/**
+ * The active pair, read from ONE source (card #893).
+ *
+ * A local `.harmony-mcp.json` wins **as a whole file**, not field by field. The
+ * two ids used to fall back to the global config independently, which quietly
+ * re-created the very mismatch this card removes: `saveLocalConfig` omits null
+ * values, so writing `projectId: null` locally did not clear the project — it
+ * unmasked the GLOBAL one and paired it with the local workspace. A workspace
+ * switch then produced `{new workspace, unrelated global project}` and
+ * `describeActiveContext` called it consistent, because both halves were
+ * non-null.
+ *
+ * So: local file present ⇒ both ids come from it, and a missing key means
+ * `null`, never "ask the global config". One source, one pair.
+ */
+function readActiveContext(cwd?: string): ActiveContext {
   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,
+  };
+}
+
+export function getActiveWorkspaceId(cwd?: string): string | null {
+  return readActiveContext(cwd).workspaceId;
 }
 
 export function getActiveProjectId(cwd?: string): string | null {
-  // Local config takes precedence over global
-  const localConfig = loadLocalConfig(cwd);
-  if (localConfig?.projectId) {
-    return localConfig.projectId;
+  return readActiveContext(cwd).projectId;
+}
+
+/** The active pair plus whether it holds together. See {@link getActiveContext}. */
+export interface ActiveContextReport extends ActiveContext {
+  consistent: boolean;
+  /** Human-readable reason when `consistent` is false; null otherwise. */
+  note: string | null;
+}
+
+/**
+ * Read the active pair and say whether it is coherent (card #893).
+ *
+ * `setActiveContext` keeps the pair whole from now on, but a config written
+ * before this shipped can still carry a project with no workspace. Report that
+ * instead of quietly resolving it — a silently wrong workspace is the failure
+ * mode this whole change exists to end.
+ */
+export function getActiveContext(cwd?: string): ActiveContextReport {
+  return describeActiveContext({
+    projectId: getActiveProjectId(cwd),
+    workspaceId: getActiveWorkspaceId(cwd),
+  });
+}
+
+/**
+ * The consistency rule itself, pure and transport-independent.
+ *
+ * `harmony_get_context` calls this rather than re-deriving the rule inline: the
+ * remote transport holds its pair in memory, not in a config file, so the file
+ * reader above cannot serve it — but both must answer the same question the
+ * same way. One rule, two callers.
+ */
+export function describeActiveContext(
+  context: ActiveContext,
+): ActiveContextReport {
+  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 };
 }
 
 export function isConfigured(): boolean {

package/src/playbook-metric-warnings.ts

@@ -0,0 +1,56 @@
+import {
+  declaredGateMetricsFromAgents,
+  referencedGateMetrics,
+  type WorkspaceAgent,
+} from "@harmony/shared";
+
+/**
+ * Non-blocking warnings for a playbook write whose `custom` gates name metrics
+ * no reporting agent in the workspace declares (card #922). The write always
+ * succeeds — a metric name can legitimately precede its declaration — but the
+ * author learns about the mismatch NOW, not after the first bound card burns a
+ * stage run on it. Inert until at least one agent has reported its declared
+ * names (an older daemon, or none running, must never raise a false alarm).
+ */
+export function playbookMetricWarnings(
+  agents: ReadonlyArray<Pick<WorkspaceAgent, "declared_gate_metrics">>,
+  steps: unknown,
+): string[] {
+  if (!Array.isArray(steps)) return [];
+  const declared = declaredGateMetricsFromAgents(agents);
+  if (!declared.known) return [];
+
+  const warnings: string[] = [];
+  const seen = new Set<string>();
+  for (const ref of referencedGateMetrics({ steps, steps_version: 2 })) {
+    if (declared.names.has(ref.metric) || seen.has(ref.metric)) continue;
+    seen.add(ref.metric);
+    warnings.push(
+      `Gate metric "${ref.metric}" (stage "${ref.stageName}") is not declared by any agent in this workspace — a stage run gating on it will hold until a daemon declares it under agent.playbooks.metrics.${ref.metric}.`,
+    );
+  }
+  return warnings;
+}
+
+/**
+ * Fetch the workspace's agents and compute the warnings, swallowing every
+ * error: the playbook write already succeeded, and a warning lookup must never
+ * turn that success into a tool failure.
+ */
+export async function collectPlaybookMetricWarnings(
+  client: {
+    listWorkspaceAgents(
+      workspaceId: string,
+    ): Promise<{ agents: WorkspaceAgent[] }>;
+  },
+  workspaceId: string | undefined,
+  steps: unknown,
+): Promise<string[]> {
+  if (!workspaceId || !Array.isArray(steps)) return [];
+  try {
+    const { agents } = await client.listWorkspaceAgents(workspaceId);
+    return playbookMetricWarnings(agents, steps);
+  } catch {
+    return [];
+  }
+}

package/src/prompt-builder.ts

@@ -402,8 +402,6 @@ export interface GeneratePromptOptions {
   contextOptions?: Partial<PromptContextOptions>;
   customConstraints?: string;
   memories?: MemoryData[];
-  /** Pre-assembled context string from context assembly engine */
-  assembledContext?: string;
   /** Assembly ID for manifest tracking */
   assemblyId?: string;
 }
@@ -414,15 +412,8 @@ export interface GeneratePromptOptions {
 export function generatePrompt(
   options: GeneratePromptOptions,
 ): GeneratedPrompt {
-  const {
-    card,
-    column,
-    variant,
-    customConstraints,
-    memories,
-    assembledContext,
-    assemblyId,
-  } = options;
+  const { card, column, variant, customConstraints, memories, assemblyId } =
+    options;
 
   // Merge context options with defaults
   const contextOpts: PromptContextOptions = {
@@ -537,11 +528,7 @@ export function generatePrompt(
   });
 
   // Relevant memories from knowledge graph
-  if (assembledContext) {
-    // Use pre-assembled context from context assembly engine
-    sections.push(`\n${assembledContext}`);
-  } else if (memories && memories.length > 0) {
-    // Fallback: legacy memory format
+  if (memories && memories.length > 0) {
     sections.push(`\n## Relevant Memories`);
     sections.push(
       `*${memories.length} memories recalled from knowledge graph:*`,
@@ -556,12 +543,7 @@ export function generatePrompt(
   }
 
   // "One Thing" synthesis — highest-leverage next action
-  const oneThingLine = synthesizeOneThing(
-    card,
-    subtasks,
-    links,
-    assembledContext,
-  );
+  const oneThingLine = synthesizeOneThing(card, subtasks, links);
   if (oneThingLine) {
     sections.push(`\n## Recommended Next Step\n${oneThingLine}`);
   }
@@ -590,9 +572,7 @@ Keep \`currentTask\` specific (e.g., "Refactoring auth middleware" not "Working
 
   const prompt = sections.join("\n");
 
-  const memoryCount = assembledContext
-    ? (assembledContext.match(/^### /gm) || []).length
-    : memories?.length || 0;
+  const memoryCount = memories?.length ?? 0;
 
   return {
     prompt,
@@ -616,69 +596,7 @@ Keep \`currentTask\` specific (e.g., "Refactoring auth middleware" not "Working
 }
 
 /**
- * Extract session insights from assembled context string.
- * Parses session summaries, blockers, and progress data.
- */
-function extractSessionInsights(assembledContext: string): {
-  lastSessionStatus: "completed" | "paused" | null;
-  lastSessionTask: string | null;
-  lastSessionProgress: number | null;
-  blockers: string[];
-  procedureNextStep: string | null;
-} {
-  const result = {
-    lastSessionStatus: null as "completed" | "paused" | null,
-    lastSessionTask: null as string | null,
-    lastSessionProgress: null as number | null,
-    blockers: [] as string[],
-    procedureNextStep: null as string | null,
-  };
-
-  // Find the most recent session summary with status
-  const sessionMatches = assembledContext.match(
-    /### Session:.*?\n([\s\S]*?)(?=\n###|\n## |\n---|\n\*Assembly|$)/g,
-  );
-  if (sessionMatches && sessionMatches.length > 0) {
-    const latest = sessionMatches[0];
-    if (/Completed work on/i.test(latest)) {
-      result.lastSessionStatus = "completed";
-    } else if (/Paused work on|status:\s*paused/i.test(latest)) {
-      result.lastSessionStatus = "paused";
-    }
-    const taskMatch = latest.match(/Final task:\s*(.+)/);
-    if (taskMatch) result.lastSessionTask = taskMatch[1].trim();
-    const progressMatch = latest.match(/Progress:\s*(\d+)%/);
-    if (progressMatch)
-      result.lastSessionProgress = parseInt(progressMatch[1], 10);
-  }
-
-  // Extract blockers from context
-  const blockerMatches = assembledContext.match(
-    /(?:blocker|blocked by|blocking):\s*(.+)/gi,
-  );
-  if (blockerMatches) {
-    result.blockers = blockerMatches.map((m) =>
-      m.replace(/(?:blocker|blocked by|blocking):\s*/i, "").trim(),
-    );
-  }
-
-  // Extract next procedure step (first uncompleted step)
-  const stepMatches = assembledContext.match(
-    /^\d+\.\s+(?!.*\*\*\[key step\]\*\*.*✓)(.+?)(?:\s*\*\*\[key step\]\*\*)?$/gm,
-  );
-  if (stepMatches && stepMatches.length > 0) {
-    result.procedureNextStep = stepMatches[0]
-      .replace(/^\d+\.\s+/, "")
-      .replace(/\s*\*\*\[key step\]\*\*.*$/, "")
-      .trim();
-  }
-
-  return result;
-}
-
-/**
- * Synthesize the single highest-leverage next action from card state
- * and assembled context (session history, blockers, procedures).
+ * Synthesize the single highest-leverage next action from card state.
  * Inspired by ArtemXTech's "One Thing" pattern in /recall.
  */
 function synthesizeOneThing(
@@ -689,7 +607,6 @@ function synthesizeOneThing(
     display_type: string;
     direction: "outgoing" | "incoming";
   }>,
-  assembledContext?: string,
 ): string | null {
   // Priority 1: Card is already done
   if (card.done) return null;
@@ -703,25 +620,7 @@ function synthesizeOneThing(
     return `Unblock first: resolve #${blocker.target_card.short_id} "${blocker.target_card.title}" which is blocking this card.`;
   }
 
-  // Extract session insights from assembled context
-  const session = assembledContext
-    ? extractSessionInsights(assembledContext)
-    : null;
-
-  // Priority 3: Blockers detected in session context
-  if (session?.blockers && session.blockers.length > 0) {
-    return `Resolve blocker: ${session.blockers[0]}`;
-  }
-
-  // Priority 4: Previous session was paused — resume where it left off
-  if (session?.lastSessionStatus === "paused" && session.lastSessionTask) {
-    const progress = session.lastSessionProgress
-      ? ` (was ${session.lastSessionProgress}% complete)`
-      : "";
-    return `Resume previous session${progress}: "${session.lastSessionTask}".`;
-  }
-
-  // Priority 5: Has subtasks — find the first incomplete one
+  // Priority 3: Has subtasks — find the first incomplete one
   if (subtasks.length > 0) {
     const completed = subtasks.filter((s) => s.completed).length;
     if (completed === subtasks.length) {
@@ -733,17 +632,7 @@ function synthesizeOneThing(
     }
   }
 
-  // Priority 6: Procedure has a next step
-  if (session?.procedureNextStep) {
-    return `Follow procedure: ${session.procedureNextStep}`;
-  }
-
-  // Priority 7: Previous session completed — build on it
-  if (session?.lastSessionStatus === "completed" && session.lastSessionTask) {
-    return `Previous session completed ("${session.lastSessionTask}"). Review results and continue with remaining work.`;
-  }
-
-  // Priority 8: High/urgent priority with due date
+  // Priority 4: High/urgent priority with due date
   if (
     card.due_date &&
     (card.priority === "urgent" || card.priority === "high")
@@ -751,7 +640,7 @@ function synthesizeOneThing(
     return `High-priority task with deadline ${card.due_date}. Start implementation immediately.`;
   }
 
-  // Priority 9: Has description — start working
+  // Priority 5: Has description — start working
   if (card.description) {
     return "Analyze the description, identify the approach, and begin implementation.";
   }

package/src/read-consumer.ts

@@ -0,0 +1,16 @@
+// Read-consumer labels for `record_entity_reads` (migration
+// 20260828120000_knowledge_entity_reads.sql).
+//
+// Duplicated in `supabase/functions/_shared/read-consumer.ts` rather than
+// shared via `packages/harmony-shared`: this package has no dependency on
+// `@harmony/shared` (so it could not import the type from there), and
+// `packages/mobile` DOES depend on `@harmony/shared` (so adding it there
+// would drag mobile's typecheck CI into a change mobile never uses). Both
+// copies must match the SQL `CHECK` constraint exactly — six values, no more.
+export type ReadConsumer =
+  | "agent-prompt"
+  | "assistant"
+  | "mcp-tool"
+  | "analyze"
+  | "search"
+  | "browse";

package/src/remote.ts

@@ -468,7 +468,7 @@ function baseDeps(
   | "getClient"
   | "getActiveProjectId"
   | "getActiveWorkspaceId"
-  | "setActiveProject"
+  | "setActiveContext"
   | "setActiveWorkspace"
 > {
   return {
@@ -523,10 +523,21 @@ function createUserContext(apiKey: string, keyInfo: TokenInfo): UserContext {
     getClient: () => ctx.sweepClient,
     getActiveProjectId: () => ctx.activeProjectId,
     getActiveWorkspaceId: () => ctx.activeWorkspaceId,
-    setActiveProject: (id) => {
-      ctx.activeProjectId = id;
+    setActiveContext: (context) => {
+      // Assign UNCONDITIONALLY, null included. Skipping a null workspace here
+      // would leave the project active inside the PREVIOUS workspace — the
+      // exact mismatch #893 removes — while the tool's reply claims it was
+      // cleared, and `harmony_get_context` calls the pair consistent because
+      // both halves are non-null.
+      ctx.activeProjectId = context.projectId;
+      ctx.activeWorkspaceId = context.workspaceId;
+      // A cleared workspace must NOT stay pinned, or the request-scoped
+      // fallback to the grant's own workspace can never take over again.
+      ctx.workspacePinned = Boolean(context.workspaceId);
     },
     setActiveWorkspace: (id) => {
+      // Switching workspace drops a project we cannot vouch for (#893).
+      if (ctx.activeWorkspaceId !== id) ctx.activeProjectId = null;
       ctx.activeWorkspaceId = id;
       ctx.workspacePinned = true;
     },
@@ -622,11 +633,28 @@ function buildRequestScope(
     getActiveWorkspaceId: () => view.workspaceId,
     // Write through: the snapshot keeps this request consistent, the context
     // carries the selection to the next one.
-    setActiveProject: (id) => {
-      view.projectId = id;
-      ctx.activeProjectId = id;
+    setActiveContext: (context) => {
+      view.projectId = context.projectId;
+      ctx.activeProjectId = context.projectId;
+      // The project's own workspace pins the scope too — carrying the project
+      // without it is what let the two drift apart (#893). A NULL workspace is
+      // written through as well: ignoring it would silently keep the previous
+      // workspace under the new project, which is the mismatch itself, and the
+      // caller has already been told the workspace was cleared.
+      view.workspaceId = context.workspaceId;
+      ctx.activeWorkspaceId = context.workspaceId;
+      // Unpin on a clear, so the next request falls back to the grant's own
+      // workspace instead of being stuck on a null it can never leave.
+      ctx.workspacePinned = Boolean(context.workspaceId);
     },
     setActiveWorkspace: (id) => {
+      // Switching workspace drops a project we cannot vouch for (#893): we
+      // don't know whether it lives in the new one, and assuming it does is
+      // precisely the mismatch this guards against.
+      if (ctx.activeWorkspaceId !== id) {
+        view.projectId = null;
+        ctx.activeProjectId = null;
+      }
       view.workspaceId = id;
       ctx.activeWorkspaceId = id;
       // An explicit choice outranks the token's primary workspace from here on.