@opsee/mcp-server 0.9.32 → 0.9.34

package/src/utils/format/user.ts

@@ -0,0 +1,14 @@
+import type { User } from "../../../gen/api/v1/models_pb.js";
+
+export function formatUser(u: User): string {
+  const lines = [`${u.fullName} (${u.email})`];
+  lines.push(`  ID: ${u.id}`);
+  if (u.flattenedRoles?.length) lines.push(`  Roles: ${u.flattenedRoles.join(", ")}`);
+  return lines.join("\n");
+}
+
+export function formatUserList(users: User[]): string {
+  if (users.length === 0) return "No users found.";
+  const header = `Found ${users.length} user(s):\n`;
+  return header + users.map((u, i) => `${i + 1}. ${formatUser(u)}`).join("\n\n");
+}

package/src/utils/format.ts

@@ -1,634 +1,4 @@
-import type { Task, Project, Cycle, DocPage, DocSpace, Milestone, MilestoneTask, User, Label, TaskLabel, Comment, TaskDependency, Initiative, InitiativeMemoryEntry, TaskPullRequest } from "../../gen/api/v1/models_pb.js";
-import { TaskDependencyType } from "../../gen/api/v1/models_pb.js";
-import type { InitiativeGraph, InitiativeSlice, ReconcileChangeset } from "../../gen/api/v1/initiative_pb.js";
-import { Code, ConnectError } from "@connectrpc/connect";
-
-export function formatProject(p: Project): string {
-  const lines = [
-    `${p.name} (${p.shortName})`,
-    `  Slug: ${p.slug}`,
-  ];
-  if (p.description) lines.push(`  Description: ${p.description}`);
-  lines.push(`  Active: ${p.isActive ? "Yes" : "No"}`);
-  lines.push(`  ID: ${p.id}`);
-  return lines.join("\n");
-}
-
-export function formatProjectList(projects: Project[]): string {
-  if (projects.length === 0) return "No projects found.";
-  const header = `Found ${projects.length} project(s):\n`;
-  return (
-    header +
-    projects.map((p, i) => `${i + 1}. ${formatProject(p)}`).join("\n\n")
-  );
-}
-
-export function formatTask(t: Task, opts: { full?: boolean } = {}): string {
-  const lines = [`[${t.identifier}] ${t.title}`];
-
-  const status = t.boardColumn?.name || "Unknown";
-  const priority = t.taskPriority?.name || "None";
-  const type = t.taskType?.name || "Unknown";
-  lines.push(`  Status: ${status} | Priority: ${priority} | Type: ${type}`);
-
-  const assignee = t.assignedUser?.fullName || "Unassigned";
-  const cycle = t.cycle?.name || "None";
-  const milestone = t.milestone?.name || "None";
-  lines.push(`  Assignee: ${assignee} | Cycle: ${cycle} | Milestone: ${milestone}`);
-
-  const parent = t.parentTaskId ? `#${t.parentTaskId}` : "—";
-  lines.push(`  Parent: ${parent}`);
-
-  if (t.storyPoints) lines.push(`  Story Points: ${t.storyPoints}`);
-  if (t.estimatedHours) lines.push(`  Estimated Hours: ${t.estimatedHours}`);
-
-  if (t.description) {
-    const desc =
-      !opts.full && t.description.length > 200
-        ? t.description.substring(0, 200) + "..."
-        : t.description;
-    lines.push(`  Description: ${desc}`);
-  }
-
-  if (t.dueDate) {
-    lines.push(`  Due: ${new Date(Number(t.dueDate.seconds) * 1000).toISOString().split("T")[0]}`);
-  }
-
-  lines.push(`  ID: ${t.id}`);
-  return lines.join("\n");
-}
-
-interface TaskListMeta {
-  totalCount?: number;
-  page?: number;
-  hasMore?: boolean;
-  nextPage?: number;
-}
-
-export function formatTaskList(tasks: Task[], projectNameOrMeta?: string | TaskListMeta): string {
-  if (tasks.length === 0) return "No tasks found.";
-
-  // Support both old signature (projectName: string) and new signature (meta: TaskListMeta)
-  const isMetaObject = projectNameOrMeta && typeof projectNameOrMeta === 'object';
-  const meta = isMetaObject ? projectNameOrMeta as TaskListMeta : undefined;
-  const projectName = !isMetaObject ? projectNameOrMeta as string | undefined : undefined;
-
-  const lines: string[] = [];
-
-  // Pagination metadata header
-  if (meta?.totalCount !== undefined) {
-    const pageInfo = meta.page ? `page ${meta.page}` : '';
-    const totalInfo = `${meta.totalCount} total`;
-    const header = [pageInfo, totalInfo].filter(Boolean).join(', ');
-    lines.push(`Tasks (${header}):`);
-    if (meta.hasMore && meta.nextPage) {
-      lines.push(`(Use page: ${meta.nextPage} to fetch the next 50 tasks)`);
-    }
-    lines.push('');
-  } else {
-    // Original header format
-    const header = projectName
-      ? `Found ${tasks.length} task(s) in project "${projectName}":\n`
-      : `Found ${tasks.length} task(s):\n`;
-    lines.push(header.trimEnd());
-    lines.push('');
-  }
-
-  // Task list
-  tasks.forEach((t, i) => {
-    lines.push(`${i + 1}. ${formatTask(t)}`);
-    lines.push('');
-  });
-
-  return lines.join('\n').trimEnd();
-}
-
-export function formatCycle(c: Cycle): string {
-  const lines = [`${c.name}`];
-  if (c.description) lines.push(`  Description: ${c.description}`);
-  if (c.goal) lines.push(`  Goal: ${c.goal}`);
-  lines.push(`  Start: ${c.startDate} | End: ${c.endDate}`);
-  lines.push(`  Active: ${c.isActive ? "Yes" : "No"}`);
-  lines.push(`  ID: ${c.id}`);
-  return lines.join("\n");
-}
-
-export function formatCycleList(cycles: Cycle[]): string {
-  if (cycles.length === 0) return "No cycles found.";
-  const header = `Found ${cycles.length} cycle(s):\n`;
-  return (
-    header + cycles.map((c, i) => `${i + 1}. ${formatCycle(c)}`).join("\n\n")
-  );
-}
-
-export function formatDocSpace(s: DocSpace): string {
-  const lines = [`${s.title}`];
-  if (s.description) lines.push(`  Description: ${s.description}`);
-  lines.push(`  Slug: ${s.slug}`);
-  lines.push(`  Default: ${s.isDefault ? "Yes" : "No"}`);
-  lines.push(`  ID: ${s.id}`);
-  return lines.join("\n");
-}
-
-export function formatDocSpaceList(spaces: DocSpace[]): string {
-  if (spaces.length === 0) return "No doc spaces found.";
-  const header = `Found ${spaces.length} doc space(s):\n`;
-  return (
-    header +
-    spaces.map((s, i) => `${i + 1}. ${formatDocSpace(s)}`).join("\n\n")
-  );
-}
-
-export function formatDocPage(p: DocPage): string {
-  const lines = [`${p.title}`];
-  lines.push(`  Slug: ${p.slug}`);
-  if (p.currentContent) {
-    const content =
-      p.currentContent.length > 500
-        ? p.currentContent.substring(0, 500) + "..."
-        : p.currentContent;
-    lines.push(`  Content: ${content}`);
-  }
-  lines.push(`  Version: ${p.currentVersionNumber}`);
-  if (p.createdByUser) lines.push(`  Author: ${p.createdByUser.fullName}`);
-  lines.push(`  ID: ${p.id}`);
-  return lines.join("\n");
-}
-
-export function formatDocPageList(pages: DocPage[]): string {
-  if (pages.length === 0) return "No doc pages found.";
-  const header = `Found ${pages.length} doc page(s):\n`;
-  return (
-    header +
-    pages
-      .map(
-        (p, i) =>
-          `${i + 1}. ${p.title} (slug: ${p.slug}, ID: ${p.id})`
-      )
-      .join("\n")
-  );
-}
-
-function formatTimestamp(ts: { seconds: bigint | number } | undefined): string {
-  if (!ts) return "—";
-  const ms = typeof ts.seconds === "bigint" ? Number(ts.seconds) * 1000 : ts.seconds * 1000;
-  return new Date(ms).toISOString().split("T")[0];
-}
-
-export function formatMilestone(m: Milestone): string {
-  const lines = [`${m.name}`];
-  if (m.description) lines.push(`  Description: ${m.description}`);
-  lines.push(`  Status: ${m.status}`);
-  lines.push(`  Start: ${formatTimestamp(m.startDate)} | End: ${formatTimestamp(m.endDate)}`);
-  lines.push(`  Project ID: ${m.projectId}`);
-  lines.push(`  ID: ${m.id} | UUID: ${m.uuid}`);
-  return lines.join("\n");
-}
-
-export function formatMilestoneList(milestones: Milestone[]): string {
-  if (milestones.length === 0) return "No milestones found.";
-  const header = `Found ${milestones.length} milestone(s):\n`;
-  return header + milestones.map((m, i) => `${i + 1}. ${formatMilestone(m)}`).join("\n\n");
-}
-
-export function formatMilestoneTask(mt: MilestoneTask): string {
-  const t = mt.task;
-  if (!t) return `  Task ID: ${mt.taskId} (MilestoneTask ID: ${mt.id})`;
-  const parts = [`${t.identifier ? `${t.identifier} ` : ""}${t.title || `Task #${mt.taskId}`}`];
-  if (t.boardColumn?.name) parts.push(`  Status: ${t.boardColumn.name}`);
-  if (t.taskPriority?.name) parts.push(`  Priority: ${t.taskPriority.name}`);
-  parts.push(`  Task ID: ${mt.taskId} | MilestoneTask ID: ${mt.id}`);
-  return parts.join("\n");
-}
-
-export function formatMilestoneTaskList(milestoneTasks: MilestoneTask[]): string {
-  if (milestoneTasks.length === 0) return "No tasks attached to this milestone.";
-  const header = `Found ${milestoneTasks.length} task(s):\n`;
-  return header + milestoneTasks.map((mt, i) => `${i + 1}. ${formatMilestoneTask(mt)}`).join("\n\n");
-}
-
-export function formatUser(u: User): string {
-  const lines = [`${u.fullName} (${u.email})`];
-  lines.push(`  ID: ${u.id}`);
-  if (u.flattenedRoles?.length) lines.push(`  Roles: ${u.flattenedRoles.join(", ")}`);
-  return lines.join("\n");
-}
-
-export function formatUserList(users: User[]): string {
-  if (users.length === 0) return "No users found.";
-  const header = `Found ${users.length} user(s):\n`;
-  return header + users.map((u, i) => `${i + 1}. ${formatUser(u)}`).join("\n\n");
-}
-
-export function formatLabel(l: Label): string {
-  const lines = [`${l.name}`];
-  lines.push(`  Color: ${l.color}`);
-  if (l.description) lines.push(`  Description: ${l.description}`);
-  lines.push(`  Active: ${l.isActive ? "Yes" : "No"}`);
-  lines.push(`  Project ID: ${l.projectId}`);
-  lines.push(`  ID: ${l.id}`);
-  return lines.join("\n");
-}
-
-export function formatLabelList(labels: Label[]): string {
-  if (labels.length === 0) return "No labels found.";
-  const header = `Found ${labels.length} label(s):\n`;
-  return header + labels.map((l, i) => `${i + 1}. ${formatLabel(l)}`).join("\n\n");
-}
-
-export function formatTaskLabelList(taskLabels: TaskLabel[]): string {
-  if (taskLabels.length === 0) return "No labels attached to this task.";
-  const header = `Found ${taskLabels.length} label attachment(s):\n`;
-  return header + taskLabels.map((tl, i) => {
-    const labelName = tl.label?.name || `Label #${tl.labelId}`;
-    return `${i + 1}. ${labelName} (Label ID: ${tl.labelId} | TaskLabel ID: ${tl.id})`;
-  }).join("\n");
-}
-
-export function formatComment(c: Comment): string {
-  const lines = [];
-  const author = c.user?.fullName || `User #${c.userId}`;
-  const created = c.createdAt
-    ? new Date((typeof c.createdAt.seconds === "bigint" ? Number(c.createdAt.seconds) : c.createdAt.seconds) * 1000).toISOString()
-    : "—";
-  lines.push(`${author} @ ${created}${c.isInternal ? " [internal]" : ""}`);
-  lines.push(`  ${c.content}`);
-  lines.push(`  ID: ${c.id}`);
-  return lines.join("\n");
-}
-
-export function formatCommentList(comments: Comment[]): string {
-  if (comments.length === 0) return "No comments found.";
-  const header = `Found ${comments.length} comment(s):\n`;
-  return header + comments.map((c, i) => `${i + 1}. ${formatComment(c)}`).join("\n\n");
-}
-
-function taskDependencyTypeToString(t: TaskDependencyType): string {
-  switch (t) {
-    case TaskDependencyType.BLOCKS: return "BLOCKS";
-    case TaskDependencyType.BLOCKED_BY: return "BLOCKED_BY";
-    case TaskDependencyType.DUPLICATES: return "DUPLICATES";
-    case TaskDependencyType.RELATES_TO: return "RELATES_TO";
-    default: return "UNSPECIFIED";
-  }
-}
-
-export function formatTaskDependency(d: TaskDependency): string {
-  const typeStr = taskDependencyTypeToString(d.type);
-  const from = d.fromTask?.identifier || `Task #${d.fromTaskId}`;
-  const to = d.toTask?.identifier || `Task #${d.toTaskId}`;
-  return `${from} ${typeStr} ${to}\n  ID: ${d.id}`;
-}
-
-export function formatTaskDependencyList(deps: TaskDependency[]): string {
-  if (deps.length === 0) return "No task dependencies found.";
-  return `Found ${deps.length} dependency(ies):\n` +
-    deps.map((d, i) => `${i + 1}. ${formatTaskDependency(d)}`).join("\n\n");
-}
-
-// ---------------------------------------------------------------------------
-// BlockNote JSON → Markdown
-// ---------------------------------------------------------------------------
-
-// `strike` is the key the BlockNote default schema uses, and it is what both Go
-// writers persist (backend/service/task.go parseInlineMarkdown and
-// orchestrator/internal/util/blocknote.go). `strikethrough` is accepted too so a
-// payload using the long spelling is not silently dropped.
-type BNInlineStyle = {
-  bold?: boolean;
-  italic?: boolean;
-  underline?: boolean;
-  strike?: boolean;
-  strikethrough?: boolean;
-  code?: boolean;
-};
-type BNTextContent = { type: "text"; text: string; styles?: BNInlineStyle };
-type BNLinkContent = { type: "link"; href: string; content: BNTextContent[] };
-type BNInlineContent = BNTextContent | BNLinkContent;
-
-interface BNBlock {
-  type: string;
-  props?: Record<string, unknown>;
-  content?: BNInlineContent[];
-  children?: BNBlock[];
-}
-
-function renderInline(content: BNInlineContent[]): string {
-  return content.map((node) => {
-    if (node.type === "link") {
-      const inner = renderInline(node.content ?? []);
-      return `[${inner}](${node.href})`;
-    }
-    // text node
-    const t = node as BNTextContent;
-    let s = t.text ?? "";
-    if (t.styles?.code) s = `\`${s}\``;
-    if (t.styles?.bold) s = `**${s}**`;
-    if (t.styles?.italic) s = `*${s}*`;
-    // Struck-through text usually means "decided against this". Dropping the
-    // markers would present an abandoned plan item as a live one.
-    if (t.styles?.strike || t.styles?.strikethrough) s = `~~${s}~~`;
-    if (t.styles?.underline) s = `<u>${s}</u>`;
-    return s;
-  }).join("");
-}
-
-function renderBlock(block: BNBlock, indent: string): string[] {
-  const lines: string[] = [];
-  const inline = renderInline(block.content ?? []);
-
-  switch (block.type) {
-    case "heading": {
-      const level = (block.props?.level as number) || 1;
-      const prefix = "#".repeat(Math.min(Math.max(level, 1), 3));
-      lines.push(`${indent}${prefix} ${inline}`);
-      break;
-    }
-    case "bulletListItem":
-      lines.push(`${indent}- ${inline}`);
-      break;
-    case "numberedListItem":
-      lines.push(`${indent}1. ${inline}`);
-      break;
-    case "checkListItem": {
-      const checked = block.props?.checked ? "x" : " ";
-      lines.push(`${indent}- [${checked}] ${inline}`);
-      break;
-    }
-    case "codeBlock": {
-      const lang = (block.props?.language as string) || "";
-      lines.push(`${indent}\`\`\`${lang}`);
-      // A code block's text is one node containing newlines. Indent every line,
-      // not just the first, or the rest escapes the list item it is nested in.
-      for (const body of inline.split("\n")) lines.push(`${indent}${body}`);
-      lines.push(`${indent}\`\`\``);
-      break;
-    }
-    case "quote":
-      lines.push(`${indent}> ${inline}`);
-      break;
-    case "paragraph":
-    default:
-      lines.push(`${indent}${inline}`);
-      break;
-  }
-
-  if (block.children?.length) {
-    for (const child of block.children) {
-      lines.push(...renderBlock(child, indent + "  "));
-    }
-  }
-
-  return lines;
-}
-
-export function blockNoteToMarkdown(content: string): string {
-  try {
-    const parsed = JSON.parse(content);
-    if (!Array.isArray(parsed)) return content;
-
-    const mdLines: string[] = [];
-    for (let i = 0; i < parsed.length; i++) {
-      const block = parsed[i] as BNBlock;
-      if (typeof block !== "object" || block === null || !block.type) return content;
-      const blockLines = renderBlock(block, "");
-      mdLines.push(...blockLines);
-      // Separate top-level blocks with a blank line (except last)
-      if (i < parsed.length - 1) mdLines.push("");
-    }
-    return mdLines.join("\n");
-  } catch {
-    return content;
-  }
-}
-
-export function formatInitiative(ini: Initiative): string {
-  const lines = [`${ini.title}`];
-  if (ini.summary) lines.push(`  Summary: ${ini.summary}`);
-  lines.push(`  Status: ${ini.status}`);
-  lines.push(`  Anchor: ${ini.anchorType}${ini.anchorId ? ` #${ini.anchorId}` : ""}`);
-  if (ini.coreIdea) {
-    const md = blockNoteToMarkdown(ini.coreIdea);
-    const preview = md.length > 120 ? md.substring(0, 120) + "..." : md;
-    lines.push(`  Core Idea: ${preview}`);
-  }
-  const creator = ini.createdByUser?.fullName || `User #${ini.createdByUserId}`;
-  lines.push(`  Created by: ${creator}`);
-  lines.push(`  Project ID: ${ini.projectId}`);
-  lines.push(`  ID: ${ini.id} | UUID: ${ini.uuid}`);
-  return lines.join("\n");
-}
-
-export function formatInitiativeList(initiatives: Initiative[]): string {
-  if (initiatives.length === 0) return "No initiatives found.";
-  const header = `Found ${initiatives.length} initiative(s):\n`;
-  return header + initiatives.map((ini, i) => `${i + 1}. ${formatInitiative(ini)}`).join("\n\n");
-}
-
-export function formatInitiativeMemoryEntry(e: InitiativeMemoryEntry): string {
-  const lines = [];
-  const who = e.isSystem ? "system" : e.isAgent ? "agent" : (e.authorUser?.fullName || `User #${e.authorUserId}`);
-  const created = e.createdAt
-    ? new Date((typeof e.createdAt.seconds === "bigint" ? Number(e.createdAt.seconds) : e.createdAt.seconds) * 1000).toISOString()
-    : "—";
-  lines.push(`[${e.kind.toUpperCase()}] ${who} @ ${created}`);
-  lines.push(`  ${e.body}`);
-  if (e.sourceType && e.sourceType !== "none") {
-    const src = e.sourceId ? `${e.sourceType} #${e.sourceId}` : e.sourceType;
-    lines.push(`  Source: ${src}${e.sourceUrl ? ` (${e.sourceUrl})` : ""}`);
-  }
-  lines.push(`  ID: ${e.id}`);
-  return lines.join("\n");
-}
-
-export function formatInitiativeMemoryList(entries: InitiativeMemoryEntry[]): string {
-  if (entries.length === 0) return "No memory entries found.";
-  const header = `Found ${entries.length} memory entry(ies) (newest first):\n`;
-  return header + entries.map((e, i) => `${i + 1}. ${formatInitiativeMemoryEntry(e)}`).join("\n\n");
-}
-
-export function formatInitiativeGraph(graph: InitiativeGraph, taskMap?: Map<number, Task>): string {
-  const lines: string[] = [];
-
-  if (graph.tasks.length === 0) {
-    lines.push("No tasks in this initiative yet.");
-  } else {
-    lines.push(`Tasks (${graph.tasks.length}):`);
-    graph.tasks.forEach((t, i) => {
-      const status = t.boardColumn?.name || "Unknown";
-      const priority = t.taskPriority?.name || "None";
-      lines.push(`  ${i + 1}. [${t.identifier || `#${t.id}`}] ${t.title}`);
-      lines.push(`     Status: ${status} | Priority: ${priority} | ID: ${t.id}`);
-    });
-  }
-
-  if (graph.edges.length > 0) {
-    lines.push(`\nDependency Edges (${graph.edges.length}):`);
-    graph.edges.forEach((e) => {
-      const localMap = taskMap || new Map(graph.tasks.map(t => [t.id, t]));
-      const fromTask = localMap.get(e.fromTaskId);
-      const toTask = localMap.get(e.toTaskId);
-      const from = fromTask ? (fromTask.identifier || `#${e.fromTaskId}`) : `#${e.fromTaskId}`;
-      const to = toTask ? (toTask.identifier || `#${e.toTaskId}`) : `#${e.toTaskId}`;
-      lines.push(`  ${from} ${e.type.toUpperCase()} ${to}`);
-    });
-  }
-
-  if (graph.slices.length > 0) {
-    lines.push(`\nParallel Execution Batches:`);
-    const localMap = taskMap || new Map(graph.tasks.map(t => [t.id, t]));
-    const sorted = [...graph.slices].sort((a, b) => a.layer - b.layer);
-    sorted.forEach((slice: InitiativeSlice) => {
-      const taskLabels = slice.taskIds.map((id) => {
-        const t = localMap.get(id);
-        return t ? `[${t.identifier || `#${id}`}] ${t.title}` : `#${id}`;
-      });
-      lines.push(`  Parallel batch ${slice.layer}: ${taskLabels.join(", ")}`);
-    });
-  }
-
-  return lines.join("\n");
-}
-
-export const WORKING_AGREEMENT = [
-  "— Working agreement —",
-  "This Initiative is a shared brain that outlives this session. To keep it useful:",
-  "1. This context (core idea · task tree · memory · PRs) is the source of truth — read it before acting.",
-  "2. Log each decision / blocker / learning as it happens with opsee_add_initiative_memory (cite the task or PR).",
-  "3. When you finish a unit of work, call opsee_checkpoint to record what changed and what's next.",
-  "4. Link PRs to their tasks so they roll up here.",
-].join("\n");
-
-export function formatInitiativeContext(
-  initiative: Initiative,
-  graph: InitiativeGraph | undefined,
-  memoryEntries: InitiativeMemoryEntry[],
-  pullRequests: TaskPullRequest[],
-  comments: Comment[],
-): string {
-  const sections: string[] = [];
-
-  sections.push("=== INITIATIVE ===");
-  sections.push(formatInitiative(initiative));
-
-  if (initiative.coreIdea) {
-    sections.push("\n=== CORE IDEA ===");
-    const md = blockNoteToMarkdown(initiative.coreIdea);
-    const body = md.length > 2000
-      ? md.substring(0, 2000) + "\n... [truncated]"
-      : md;
-    sections.push(body);
-  }
-
-  if (graph) {
-    sections.push("\n=== EXECUTION GRAPH ===");
-    sections.push(formatInitiativeGraph(graph));
-  }
-
-  if (memoryEntries.length > 0) {
-    sections.push("\n=== MEMORY LOG (newest first) ===");
-    memoryEntries.forEach((e, i) => {
-      sections.push(`${i + 1}. ${formatInitiativeMemoryEntry(e)}`);
-    });
-  } else {
-    sections.push("\n=== MEMORY LOG ===");
-    sections.push("No memory entries yet.");
-  }
-
-  if (pullRequests.length > 0) {
-    sections.push("\n=== PULL REQUESTS ===");
-    pullRequests.forEach((pr, i) => {
-      const repo = pr.projectRepository?.repositoryFullName || `repo #${pr.projectRepositoryId}`;
-      sections.push(`  ${i + 1}. [${pr.state.toUpperCase()}] #${pr.prNumber} ${pr.title} (${repo})`);
-      sections.push(`     ${pr.url}`);
-    });
-  }
-
-  if (comments.length > 0) {
-    sections.push("\n=== DISCUSSION ===");
-    comments.forEach((c, i) => {
-      sections.push(`${i + 1}. ${formatComment(c)}`);
-    });
-  }
-
-  sections.push("\n" + WORKING_AGREEMENT);
-  return sections.join("\n");
-}
-
-export function formatReconcileChangeset(changeset: ReconcileChangeset): string {
-  const lines: string[] = [];
-
-  if (changeset.added.length > 0) {
-    lines.push(`Added (${changeset.added.length}):`);
-    changeset.added.forEach((t) => {
-      const id = t.identifier || (t.taskId ? `#${t.taskId}` : "(new)");
-      lines.push(`  + [${id}] ${t.title}`);
-    });
-  }
-
-  if (changeset.removed.length > 0) {
-    lines.push(`Removed — pristine, no work detected (${changeset.removed.length}):`);
-    changeset.removed.forEach((t) => {
-      const id = t.identifier || `#${t.taskId}`;
-      lines.push(`  − [${id}] ${t.title}`);
-    });
-  }
-
-  if (changeset.flagged.length > 0) {
-    lines.push(`Flagged — NOT removed, carries execution state (${changeset.flagged.length}):`);
-    lines.push("  These tasks have real work in progress and were left untouched.");
-    changeset.flagged.forEach((t) => {
-      const id = t.identifier || `#${t.taskId}`;
-      lines.push(`  ! [${id}] ${t.title} — flagged: ${t.reason}`);
-    });
-  }
-
-  if (changeset.edgesAdded.length > 0) {
-    lines.push(`Edges + (${changeset.edgesAdded.length}):`);
-    changeset.edgesAdded.forEach((e) => {
-      lines.push(`  + #${e.fromTaskId} ${e.type.toUpperCase()} #${e.toTaskId}`);
-    });
-  }
-
-  if (changeset.edgesRemoved.length > 0) {
-    lines.push(`Edges − (${changeset.edgesRemoved.length}):`);
-    changeset.edgesRemoved.forEach((e) => {
-      lines.push(`  − #${e.fromTaskId} ${e.type.toUpperCase()} #${e.toTaskId}`);
-    });
-  }
-
-  if (lines.length === 0) {
-    lines.push("No changes — the proposed plan matches the existing task tree.");
-  }
-
-  if (changeset.graph) {
-    lines.push("\n" + formatInitiativeGraph(changeset.graph));
-  }
-
-  return lines.join("\n");
-}
-
-export function formatError(error: unknown): string {
-  // Prefer the structured gRPC/Connect code over substring-matching the
-  // message: a backend error whose text embeds a task title containing "401"
-  // or "ECONNREFUSED" must not be misclassified as auth/network.
-  if (error instanceof ConnectError) {
-    if (error.code === Code.Unauthenticated) {
-      return "Not authenticated. Run `npx opsee-mcp login` to connect your Opsee account.";
-    }
-    if (error.code === Code.Unavailable) {
-      return `Could not reach Opsee API. Check your connection and OPSEE_API_URL. (${error.rawMessage})`;
-    }
-    return `[${Code[error.code]}] ${error.rawMessage}`;
-  }
-  if (error instanceof Error) {
-    // Raw transport errors before a Connect response carry a machine-readable
-    // code property (Node sets err.code); match on that, not the message text.
-    const code = (error as { code?: unknown }).code;
-    if (code === "ECONNREFUSED" || code === "ENOTFOUND") {
-      return `Could not reach Opsee API. Check your connection and OPSEE_API_URL. (${error.message})`;
-    }
-    return error.message;
-  }
-  return String(error);
-}
+// The formatters live in ./format/ one module per entity. Node16 resolution
+// will not fold a directory into "../utils/format.js", so this file keeps that
+// specifier working for the ~15 existing import sites.
+export * from "./format/index.js";