codetrellis 0.0.0-stage → 0.3.0

package/src/backend/mcp/tools/governance-tools.js

@@ -0,0 +1,175 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var governance_tools_exports = {};
+__export(governance_tools_exports, {
+  register: () => register
+});
+module.exports = __toCommonJS(governance_tools_exports);
+var import_zod = require("zod");
+var import_helpers = require("../helpers");
+var import_freeze_service = require("../../services/freeze-service");
+var import_record_chain = require("../../services/record-chain");
+var import_evidence = require("../../services/evidence");
+const FLAGGED_NOTE = " Recorded in your name and flagged for a person to review.";
+function register(server, deps) {
+  server.registerTool(
+    "verify_record",
+    {
+      description: "Is the record intact? Every agent event CodeTrellis keeps (tool calls, and the decisions people make: criteria, breakpoints, signals, spec proposals, rules) is linked into a hash chain as it is written. This walks it and says whether anything kept was changed, removed or added around it since, naming each by number, kind and agent. Read only.",
+      inputSchema: {}
+    },
+    async () => {
+      const r = (0, import_record_chain.verifyRecord)();
+      return {
+        _meta: { summary: r.ok ? `Record intact: ${r.entries} entries` : `Record changed: ${r.problems.length} problem${r.problems.length === 1 ? "" : "s"}` },
+        content: [{ type: "text", text: JSON.stringify({
+          ok: r.ok,
+          words: r.words,
+          entries: r.entries,
+          since: r.since,
+          trimmed_through: r.trimmedThrough,
+          head: r.head,
+          problems: r.problems.map((p) => ({ seq: p.seq, event_id: p.eventId, kind: p.kind, at: p.at, type: p.type, agent_type: p.agentType }))
+        }, null, 2) }]
+      };
+    }
+  );
+  server.registerTool(
+    "export_evidence",
+    {
+      description: "The evidence for a plan, or a window of time in an opened project, as one signed package: the record's entries in the window with how to recompute each link, the replay frames, the stack and the signals at the start and the end, the breakpoints and decisions in words, and (for a plan) the sign-off pack; sealed with this computer's key and the record's head. Give plan_uid, or project_path with from and to (milliseconds). Read only.",
+      inputSchema: {
+        plan_uid: import_zod.z.string().optional().describe("A plan: its project, from when it was made until it finished (or now)."),
+        project_path: import_zod.z.string().optional().describe("An opened project, for a window of time. Defaults to the active project."),
+        from: import_zod.z.number().int().nonnegative().optional().describe("The window's start, in milliseconds since 1970."),
+        to: import_zod.z.number().int().nonnegative().optional().describe("The window's end, in milliseconds since 1970.")
+      }
+    },
+    async ({ plan_uid, project_path, from, to }) => {
+      try {
+        const e = (0, import_evidence.sealEvidence)((0, import_evidence.buildEvidence)(plan_uid ? { planUid: plan_uid } : { projectPath: project_path ?? deps.getActiveProjectPath() ?? void 0, from, to }));
+        return {
+          _meta: { summary: `Evidence: ${e.window.words}` },
+          content: [{ type: "text", text: JSON.stringify(e) }]
+        };
+      } catch (err) {
+        if (err instanceof import_evidence.EvidenceError) return { isError: true, content: [{ type: "text", text: err.message }] };
+        throw err;
+      }
+    }
+  );
+  server.registerTool(
+    "get_freeze_status",
+    {
+      description: 'Check whether a project is currently under a freeze period. Returns the freeze state, reason, timing, and which plans are exempt. Handles auto-expiry: if the "until" timestamp has passed, the freeze is treated as inactive.',
+      inputSchema: {
+        project_path: import_zod.z.string().describe("Absolute path to the project root.")
+      }
+    },
+    async ({ project_path }) => {
+      const status = (0, import_freeze_service.getFreezeStatus)(project_path);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(status, null, 2)
+        }]
+      };
+    }
+  );
+  server.registerTool(
+    "set_freeze",
+    {
+      description: "Activate or deactivate a freeze period on a project. During a freeze, agents should not start work on non-exempt plans. Use this during release weeks, incident response, or any period where non-critical changes should be blocked. The freeze is stored in .codetrellis/config.json and committed to the manifest.",
+      inputSchema: {
+        project_path: import_zod.z.string().describe("Absolute path to the project root."),
+        active: import_zod.z.boolean().describe("True to activate the freeze, false to lift it."),
+        reason: import_zod.z.string().optional().describe('Human-readable reason (e.g., "Release v2.3 freeze").'),
+        until: import_zod.z.string().nullable().optional().describe("ISO timestamp when the freeze auto-expires. Null = indefinite."),
+        allowed_plan_uids: import_zod.z.array(import_zod.z.string()).optional().describe("Plan UIDs exempt from the freeze.")
+      }
+    },
+    async ({ project_path, active, reason, until, allowed_plan_uids }, extra) => {
+      const { author, authorType } = (0, import_helpers.authorFromExtra)(deps, extra);
+      const status = (0, import_freeze_service.setFreeze)(project_path, {
+        active,
+        reason,
+        until,
+        allowedPlanUids: allowed_plan_uids
+      }, { actor: author, actorType: authorType, channel: "mcp" });
+      deps.broadcast("freeze-changed", { projectRoot: project_path, status });
+      const msg = (active ? `Freeze activated${reason ? `: ${reason}` : ""}${until ? ` (expires ${until})` : " (indefinite)"}. ${(allowed_plan_uids ?? []).length} plan(s) exempt.` : "Freeze lifted.") + FLAGGED_NOTE;
+      return {
+        content: [{ type: "text", text: msg }]
+      };
+    }
+  );
+  server.registerTool(
+    "check_freeze",
+    {
+      description: "Check whether a specific plan is allowed to be worked on during an active freeze. Returns true if: no freeze is active, the freeze has expired, or the plan is in the exemption list. Agents should call this before claiming items to respect governance.",
+      inputSchema: {
+        project_path: import_zod.z.string().describe("Absolute path to the project root."),
+        plan_uid: import_zod.z.string().describe("UID of the plan to check.")
+      }
+    },
+    async ({ project_path, plan_uid }) => {
+      const allowed = (0, import_freeze_service.isPlanAllowedDuringFreeze)(project_path, plan_uid);
+      const status = (0, import_freeze_service.getFreezeStatus)(project_path);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            planUid: plan_uid,
+            allowed,
+            freezeActive: status.active,
+            reason: status.reason,
+            until: status.until
+          }, null, 2)
+        }]
+      };
+    }
+  );
+  server.registerTool(
+    "exempt_plan_from_freeze",
+    {
+      description: "Add a plan to the freeze exemption list without changing the freeze state. Exempt plans can be worked on during a freeze (e.g., hotfix plans during release freeze).",
+      inputSchema: {
+        project_path: import_zod.z.string().describe("Absolute path to the project root."),
+        plan_uid: import_zod.z.string().describe("UID of the plan to exempt.")
+      }
+    },
+    async ({ project_path, plan_uid }, extra) => {
+      if (!deps.planService.getPlan(plan_uid)) {
+        return { content: [{ type: "text", text: `Plan not found: ${plan_uid}` }], isError: true };
+      }
+      const { author, authorType } = (0, import_helpers.authorFromExtra)(deps, extra);
+      const status = (0, import_freeze_service.exemptPlanFromFreeze)(project_path, plan_uid, { actor: author, actorType: authorType, channel: "mcp" });
+      deps.broadcast("freeze-changed", { projectRoot: project_path, status });
+      return {
+        content: [{
+          type: "text",
+          text: `Plan ${plan_uid} is now exempt from the freeze. ${status.allowedPlanUids.length} plan(s) total exempt.${FLAGGED_NOTE}`
+        }]
+      };
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  register
+});

package/src/backend/mcp/tools/graph-tools.js

@@ -0,0 +1,181 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var graph_tools_exports = {};
+__export(graph_tools_exports, {
+  register: () => register
+});
+module.exports = __toCommonJS(graph_tools_exports);
+var import_zod = require("zod");
+function register(server, deps) {
+  server.registerTool(
+    "graph_focus",
+    {
+      description: "Focus the dependency graph on a specific file or directory. Pans and zooms the graph canvas to center the target node. Use this to visually show the user a specific part of the architecture.",
+      inputSchema: {
+        path: import_zod.z.string().describe('Relative path of the file or directory to focus on (e.g. "src/backend/services/plan-item-service.ts").'),
+        highlight: import_zod.z.boolean().optional().describe("Briefly highlight the node with a glow effect. Default true.")
+      }
+    },
+    async ({ path: targetPath, highlight }) => {
+      deps.broadcast("ui-graph-focus", { path: targetPath, highlight: highlight !== false });
+      return { content: [{ type: "text", text: `Focused graph on ${targetPath}` }] };
+    }
+  );
+  server.registerTool(
+    "graph_set_mode",
+    {
+      description: 'Set the graph trellis mode \u2014 changes the overlay displayed on the dependency graph. "live" = current state, "baseline" = snapshot comparison, "planned" = show plan targets, "diff" = show changes.',
+      inputSchema: {
+        mode: import_zod.z.enum(["live", "baseline", "planned", "diff"]).describe("Trellis overlay mode.")
+      }
+    },
+    async ({ mode }) => {
+      deps.broadcast("ui-graph-mode", { mode: mode === "baseline" ? "current" : mode });
+      return { content: [{ type: "text", text: `Set graph mode to ${mode}` }] };
+    }
+  );
+  server.registerTool(
+    "graph_set_scope",
+    {
+      description: "Set the graph scope filter to show only files under a specific directory or package path. Pass an empty string to clear the scope and show the full graph.",
+      inputSchema: {
+        scope_path: import_zod.z.string().describe('Directory path to scope to (e.g. "src/backend/services"). Empty string to clear.')
+      }
+    },
+    async ({ scope_path }) => {
+      deps.broadcast("ui-graph-scope", { scopePath: scope_path });
+      return { content: [{ type: "text", text: scope_path ? `Scoped graph to ${scope_path}` : "Cleared graph scope" }] };
+    }
+  );
+  server.registerTool(
+    "graph_select",
+    {
+      description: 'Select one or more nodes on the dependency graph by their file/directory path. Mirrors shift-click multi-select. Selected nodes can then be used with "Plan these" or "Add to task" actions. Pass an empty array to clear the selection.',
+      inputSchema: {
+        paths: import_zod.z.array(import_zod.z.string()).describe(
+          'Array of relative file or directory paths to select (e.g. ["src/backend/server.ts", "src/frontend/App.tsx"]). Empty array to clear.'
+        )
+      }
+    },
+    async ({ paths }) => {
+      deps.broadcast("ui-graph-select", { paths });
+      const msg = paths.length === 0 ? "Cleared graph selection" : `Selected ${paths.length} node(s) on graph`;
+      return { content: [{ type: "text", text: msg }] };
+    }
+  );
+  server.registerTool(
+    "graph_set_layout",
+    {
+      description: 'Switch the graph layout algorithm. "map" = force-directed (d3-force) layout for organic exploration. "tree" = hierarchical (dagre) layout for structured top-down view.',
+      inputSchema: {
+        layout: import_zod.z.enum(["map", "tree"]).describe('Layout algorithm: "map" (force-directed) or "tree" (hierarchical dagre).')
+      }
+    },
+    async ({ layout }) => {
+      deps.broadcast("ui-graph-layout", { layout });
+      return { content: [{ type: "text", text: `Set graph layout to ${layout}` }] };
+    }
+  );
+  server.registerTool(
+    "graph_set_depth",
+    {
+      description: 'Set the graph view depth \u2014 controls what level of detail is shown. "package" = show only packages/directories (highest level). "file" = show individual files within packages. "symbol" = show classes, functions, and methods within files (most detailed).',
+      inputSchema: {
+        depth: import_zod.z.enum(["package", "file", "symbol"]).describe("View depth level.")
+      }
+    },
+    async ({ depth }) => {
+      deps.broadcast("ui-graph-depth", { depth });
+      return { content: [{ type: "text", text: `Set graph view depth to ${depth}` }] };
+    }
+  );
+  server.registerTool(
+    "graph_toggle_projection",
+    {
+      description: "Toggle the plan projection overlay on the dependency graph. When enabled, the graph highlights files and symbols that are targeted by the active plan (Planned/Diff trellis modes). When disabled, shows the raw dependency graph.",
+      inputSchema: {
+        enabled: import_zod.z.boolean().optional().describe("Explicitly set projection on or off. If omitted, toggles the current state.")
+      }
+    },
+    async ({ enabled }) => {
+      deps.broadcast("ui-graph-toggle-projection", { enabled });
+      const label = enabled === true ? "enabled" : enabled === false ? "disabled" : "toggled";
+      return { content: [{ type: "text", text: `Projection ${label}` }] };
+    }
+  );
+  server.registerTool(
+    "graph_export",
+    {
+      description: "Export the current graph view as a PNG image. Returns the graph canvas as a base64-encoded image. Useful for saving a visual snapshot of the architecture or sharing with team members.",
+      inputSchema: {}
+    },
+    async () => {
+      const nonce = `ge-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      const p = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          deps.pendingResponses.delete(nonce);
+          reject(new Error("Graph export timed out \u2014 is the CodeTrellis UI open with the graph visible?"));
+        }, 1e4);
+        deps.pendingResponses.set(nonce, { resolve, reject, timer });
+      });
+      deps.broadcast("ui-screenshot-request", { nonce, panel: "graph" });
+      try {
+        const base64 = await p;
+        return {
+          content: [{
+            type: "image",
+            data: base64,
+            mimeType: "image/png"
+          }]
+        };
+      } catch (err) {
+        return { content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }], isError: true };
+      }
+    }
+  );
+  server.registerTool(
+    "graph_snapshot",
+    {
+      description: "Return a structured JSON snapshot of the current graph data \u2014 all nodes and edges with their types, paths, and relationships. Use this to programmatically analyse the architecture without needing the visual canvas. Much lighter than a screenshot and gives exact data for reasoning about dependencies.",
+      inputSchema: {
+        include_metadata: import_zod.z.boolean().optional().describe("Include full metadata for each node (default false \u2014 keeps response compact).")
+      }
+    },
+    async ({ include_metadata }) => {
+      const nonce = `gs-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+      const p = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          deps.pendingResponses.delete(nonce);
+          reject(new Error("Graph snapshot timed out \u2014 is the CodeTrellis UI open?"));
+        }, 1e4);
+        deps.pendingResponses.set(nonce, { resolve, reject, timer });
+      });
+      deps.broadcast("ui-graph-snapshot-request", { nonce, includeMetadata: include_metadata === true });
+      try {
+        const json = await p;
+        return { content: [{ type: "text", text: json }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }], isError: true };
+      }
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  register
+});

package/src/backend/mcp/tools/intake-tools.js

@@ -0,0 +1,244 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var intake_tools_exports = {};
+__export(intake_tools_exports, {
+  register: () => register
+});
+module.exports = __toCommonJS(intake_tools_exports);
+var import_zod = require("zod");
+var import_helpers = require("../helpers");
+var import_external_intake_service = require("../../services/external-intake-service");
+var import_external_refs_service = require("../../services/external-refs-service");
+var import_trusted_roots = require("../../services/trusted-roots");
+const externalSchema = import_zod.z.object({
+  url: import_zod.z.string().describe("Link to the ticket / issue / page."),
+  key: import_zod.z.string().nullable().optional().describe("Ticket key, e.g. PROJ-412. Derived from the URL when omitted."),
+  title: import_zod.z.string().optional()
+});
+const leafSchema = import_zod.z.object({
+  external: externalSchema.nullable().optional(),
+  title: import_zod.z.string(),
+  body: import_zod.z.string().optional(),
+  acceptance: import_zod.z.array(import_zod.z.string()).optional(),
+  kind: import_zod.z.enum(["object", "action"]).optional()
+});
+const deepSchema = leafSchema.extend({ children: import_zod.z.array(leafSchema).optional() });
+const midSchema = leafSchema.extend({ children: import_zod.z.array(deepSchema).optional() });
+const rootSchema = leafSchema.extend({ children: import_zod.z.array(midSchema).optional() });
+const noPlan = (uid) => ({ content: [{ type: "text", text: `Plan not found: ${uid}` }], isError: true });
+function register(server, deps) {
+  server.registerTool(
+    "create_plan_from_external",
+    {
+      description: `Turn a ticket hierarchy you have already fetched (Jira epic + stories, a Linear project, a set of GitHub issues) into a CodeTrellis plan with nested items, each carrying its ticket key. YOU fetch with your own tracker credentials; CodeTrellis never calls out. Acceptance criteria land as a checklist in each item body. Plan depth is capped at ${import_external_intake_service.MAX_INTAKE_DEPTH} (epic \u2192 story \u2192 task); a fourth level is accepted and levelled into the third rather than dropped. If a plan already carries this epic, the import is REFUSED and the existing plan is named \u2014 updating an imported plan in place is not supported yet, and silently creating a second copy of an epic is worse than saying so.`,
+      inputSchema: {
+        title: import_zod.z.string().describe("Plan title \u2014 usually the epic summary."),
+        description: import_zod.z.string().optional(),
+        external: externalSchema.optional().describe("The epic / parent ticket this plan represents."),
+        items: import_zod.z.array(rootSchema).describe("The ticket tree, already fetched."),
+        project_path: import_zod.z.string().optional().describe(
+          "Absolute path to the project this plan belongs to. Defaults to the project currently open."
+        )
+      }
+    },
+    async (args, extra) => {
+      const author = (0, import_helpers.authorFromExtra)(deps, extra);
+      const epicKey = args.external?.key ?? (args.external?.url ? (0, import_external_intake_service.keyFromUrl)(args.external.url) : null);
+      if (epicKey) {
+        const existing = (0, import_external_intake_service.findPlanByExternalKey)(epicKey);
+        if (existing) {
+          return {
+            content: [{
+              type: "text",
+              text: `Plan ${existing} already carries ${epicKey}. Refusing to import a second copy. Open that plan, or delete it first if you want a clean re-import.`
+            }],
+            isError: true
+          };
+        }
+      }
+      const projectPath = args.project_path ?? (0, import_trusted_roots.getActiveProjectRoot)();
+      if (!projectPath) {
+        return { content: [{ type: "text", text: "No project is open: pass project_path, or open the project first." }], isError: true };
+      }
+      const plan = deps.planService.createPlan(
+        { title: args.title, description: args.description ?? "", tasks: [] },
+        author.author,
+        author.authorType,
+        projectPath
+      );
+      if (args.external) {
+        (0, import_external_intake_service.setPlanExternalRef)({
+          planUid: plan.uid,
+          url: args.external.url,
+          key: args.external.key ?? void 0,
+          title: args.external.title,
+          author: author.author,
+          authorType: author.authorType
+        });
+      }
+      const flat = (0, import_external_intake_service.flattenIntake)(args.items);
+      const uidByIndex = [];
+      let created = 0;
+      let linked = 0;
+      for (let i = 0; i < flat.length; i++) {
+        const { node, depth, parentIndex } = flat[i];
+        const parentUid = parentIndex === null ? null : uidByIndex[parentIndex];
+        const item = deps.planItemService.createItem({
+          planUid: plan.uid,
+          kind: (0, import_external_intake_service.intakeKind)(node, depth),
+          title: node.title,
+          body: (0, import_external_intake_service.intakeBody)(node),
+          parentUid: parentUid ?? void 0,
+          author: author.author,
+          authorType: author.authorType
+        });
+        uidByIndex.push(item?.uid ?? null);
+        if (!item) continue;
+        created++;
+        if (node.external?.url) {
+          (0, import_external_refs_service.createExternalRef)({
+            itemUid: item.uid,
+            url: node.external.url,
+            title: node.external.title,
+            externalKey: node.external.key ?? (0, import_external_intake_service.keyFromUrl)(node.external.url),
+            author: author.author,
+            authorType: author.authorType
+          });
+          linked++;
+        }
+      }
+      const n = deps.broadcast("plan-created", { plan });
+      deps.saveNow(() => deps.exportDatabase());
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(
+            {
+              ok: true,
+              plan_uid: plan.uid,
+              items_created: created,
+              items_with_tickets: linked,
+              depth_cap: import_external_intake_service.MAX_INTAKE_DEPTH,
+              broadcastTo: n,
+              next: "Work the plan as usual. Call get_external_sync_state when you want to write statuses back."
+            },
+            null,
+            2
+          )
+        }]
+      };
+    }
+  );
+  server.registerTool(
+    "set_plan_external_ref",
+    {
+      description: "Attach (or update) the ticket a plan represents \u2014 an epic, a project, a milestone. Idempotent on the ticket key, so calling it twice updates rather than duplicating. Item-level tickets use add_external_ref instead.",
+      inputSchema: {
+        plan_uid: import_zod.z.string(),
+        url: import_zod.z.string(),
+        key: import_zod.z.string().optional(),
+        title: import_zod.z.string().optional()
+      }
+    },
+    async ({ plan_uid, url, key, title }, extra) => {
+      if (!deps.planService.getPlan(plan_uid)) return noPlan(plan_uid);
+      const author = (0, import_helpers.authorFromExtra)(deps, extra);
+      const ref = (0, import_external_intake_service.setPlanExternalRef)({
+        planUid: plan_uid,
+        url,
+        key,
+        title,
+        author: author.author,
+        authorType: author.authorType
+      });
+      return { content: [{ type: "text", text: JSON.stringify(ref, null, 2) }] };
+    }
+  );
+  server.registerTool(
+    "get_external_sync_state",
+    {
+      description: "What has changed in this plan since the last write-back: every item carrying a ticket key whose status moved, with the key, the current status and a SUGGESTED transition name. Read this, write the transitions with your own tracker MCP, then call mark_external_synced. Reading does not advance the watermark \u2014 an agent that read the list and then failed to write would otherwise lose those transitions silently. The suggested transition is advisory: every tracker has its own workflow, and you can see the real transition names; we cannot.",
+      inputSchema: {
+        plan_uid: import_zod.z.string()
+      }
+    },
+    async ({ plan_uid }) => {
+      if (!deps.planService.getPlan(plan_uid)) return noPlan(plan_uid);
+      const state = (0, import_external_intake_service.getSyncState)(plan_uid);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(
+            {
+              plan_uid: state.planUid,
+              last_synced_at: state.lastSyncedAt,
+              never_synced: state.lastSyncedAt === null,
+              plan_tickets: state.planRefs.map((r) => ({ key: r.externalKey, url: r.url, title: r.title })),
+              changed: state.changed.map((c) => ({
+                item_uid: c.itemUid,
+                title: c.title,
+                status: c.status,
+                external_key: c.externalKey,
+                url: c.url,
+                suggested_transition: c.suggestedTransition
+              }))
+            },
+            null,
+            2
+          )
+        }]
+      };
+    }
+  );
+  server.registerTool(
+    "mark_external_synced",
+    {
+      description: "Record that you have written this plan's status changes back to the tracker. Advances the watermark, so the next get_external_sync_state returns only what changed after this point. Call it only once the writes actually succeeded.",
+      inputSchema: {
+        plan_uid: import_zod.z.string(),
+        note: import_zod.z.string().optional().describe("What you wrote back, for the audit trail.")
+      }
+    },
+    async ({ plan_uid, note }, extra) => {
+      if (!deps.planService.getPlan(plan_uid)) return noPlan(plan_uid);
+      const author = (0, import_helpers.authorFromExtra)(deps, extra);
+      const result = (0, import_external_intake_service.markSynced)(plan_uid, author.author, note);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ ok: true, plan_uid, ...result }, null, 2)
+        }]
+      };
+    }
+  );
+  server.registerTool(
+    "list_plan_external_refs",
+    {
+      description: "The tickets attached to a plan itself (as opposed to its items).",
+      inputSchema: { plan_uid: import_zod.z.string() }
+    },
+    async ({ plan_uid }) => {
+      if (!deps.planService.getPlan(plan_uid)) return noPlan(plan_uid);
+      return { content: [{ type: "text", text: JSON.stringify((0, import_external_intake_service.getPlanExternalRefs)(plan_uid), null, 2) }] };
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  register
+});