@rallycry/conveyor-mcp 4.3.10 → 4.3.11

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   ConveyorConnection
-} from "./chunk-KOYKRWVY.js";
+} from "./chunk-BKAHHT4Y.js";
 
 // src/cli.ts
 import { createRequire } from "module";
@@ -261,7 +261,728 @@ function registerProjectConfigTools(server2, conn2) {
 }
 
 // src/tools/tasks.ts
+import { z as z5 } from "zod";
+
+// ../shared/dist/tool-contracts/index.js
+var f = {
+  string(opts) {
+    return { kind: "string", ...opts };
+  },
+  number(opts) {
+    return { kind: "number", ...opts };
+  },
+  boolean(opts) {
+    return { kind: "boolean", ...opts };
+  },
+  enum(values, opts) {
+    return { kind: "enum", values, ...opts };
+  },
+  array(item, opts) {
+    return { kind: "array", item, ...opts };
+  },
+  object(fields, opts) {
+    return { kind: "object", fields, ...opts };
+  },
+  optional(inner) {
+    return { kind: "optional", inner };
+  }
+};
+function compileString(z9, spec) {
+  let schema = z9.string();
+  if (spec.min !== void 0) schema = schema.min(spec.min);
+  if (spec.max !== void 0) schema = schema.max(spec.max);
+  return schema;
+}
+function compileNumber(z9, spec) {
+  let schema = z9.number();
+  if (spec.int) schema = schema.int();
+  if (spec.positive) schema = schema.positive();
+  if (spec.nonnegative) schema = schema.nonnegative();
+  if (spec.min !== void 0) schema = schema.min(spec.min);
+  if (spec.max !== void 0) schema = schema.max(spec.max);
+  return schema;
+}
+function compileArray(z9, spec) {
+  let schema = z9.array(compileField(z9, spec.item));
+  if (spec.min !== void 0) schema = schema.min(spec.min);
+  return schema;
+}
+function compileBase(z9, spec) {
+  switch (spec.kind) {
+    case "string":
+      return compileString(z9, spec);
+    case "number":
+      return compileNumber(z9, spec);
+    case "boolean":
+      return z9.boolean();
+    case "enum":
+      return z9.enum([...spec.values]);
+    case "array":
+      return compileArray(z9, spec);
+    case "object":
+      return z9.object(compileShape(z9, spec.fields));
+  }
+}
+function compileField(z9, spec) {
+  if (spec.kind === "optional") {
+    return compileField(z9, spec.inner).optional();
+  }
+  const schema = compileBase(z9, spec);
+  return spec.desc === void 0 ? schema : schema.describe(spec.desc);
+}
+function compileShape(z9, fields) {
+  const shape = {};
+  for (const [key, spec] of Object.entries(fields)) {
+    shape[key] = compileField(z9, spec);
+  }
+  return shape;
+}
+function defineToolContract(contract) {
+  return contract;
+}
+var mcpProjectId = f.optional(f.string({ desc: "Target Conveyor project ID" }));
+var getTaskContract = defineToolContract({
+  name: "get_task",
+  agent: {
+    description: "Look up any task by slug or ID. Returns JSON with id, slug, title, description, plan, status, branch, githubPRNumber, githubPRUrl, storyPoints. For children use list_subtasks.",
+    fields: {
+      slug_or_id: f.string({ desc: "The task slug (e.g. 'my-task') or CUID" })
+    }
+  },
+  mcp: {
+    description: "Get full task details including plan, chat history, PR info, subtasks, and build status. Pass projectId to target a specific project; otherwise the configured default project is used.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: f.string({
+        desc: "The task ID or slug (the value in a card URL, /cards/<slug>)"
+      })
+    }
+  }
+});
+var postToChatContract = defineToolContract({
+  name: "post_to_chat",
+  agent: {
+    description: "Post a message to the task chat for the team to see. Your turn output is NOT shown in chat, so this is the only way the team sees your status, summaries, and questions. Omit task_id to post to the current task's chat; pass a child's ID to message its chat.",
+    fields: {
+      message: f.optional(f.string({ desc: "The message to post to the team" })),
+      content: f.optional(
+        f.string({
+          desc: "Alias of `message` (the external conveyor-mcp surface names this field `content`). Provide exactly one of the two."
+        })
+      ),
+      task_id: f.optional(
+        f.string({
+          desc: "Child task ID to post to. Omit to post to the current task's chat."
+        })
+      ),
+      milestone: f.optional(
+        f.enum(["plan_ready", "implementation_complete", "blocked"], {
+          desc: "Declare a narrative milestone instead of a routine update. Use SPARINGLY \u2014 only when the plan is ready, implementation is complete, or you are blocked. Milestones appear on the card's activity timeline and in Slack."
+        })
+      )
+    }
+  },
+  mcp: {
+    description: "Post a message to a task's chat. Pass projectId to target a specific project; otherwise the configured default project is used.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: f.string({ desc: "The task ID" }),
+      content: f.optional(f.string({ desc: "Message content" })),
+      message: f.optional(
+        f.string({
+          desc: "Alias of `content` (the in-pod agent surface names this field `message`). Provide exactly one of the two."
+        })
+      )
+    }
+  }
+});
+var readTaskChatContract = defineToolContract({
+  name: "read_task_chat",
+  agent: {
+    description: "Read recent human/user chat messages for a task. Omit task_id for the current task; pass a child ID for a child's chat. For agent logs use get_execution_logs.",
+    fields: {
+      limit: f.optional(f.number({ desc: "Number of recent messages to fetch (default 20)" })),
+      task_id: f.optional(
+        f.string({
+          desc: "Child task ID to read chat from. Omit to read the current task's chat."
+        })
+      )
+    }
+  },
+  mcp: {
+    description: "Read messages from a task's chat. Pass projectId to target a specific project; otherwise the configured default project is used. For agent execution logs use get_task_logs.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: f.string({ desc: "The task ID" }),
+      limit: f.optional(f.number({ desc: "Max messages to return (default 50)" }))
+    }
+  }
+});
+var listTagsContract = defineToolContract({
+  name: "list_tags",
+  agent: {
+    description: "List this project's tags (id, name, color). Use the ids with update_tag.",
+    fields: {}
+  },
+  mcp: {
+    description: "List all project tags with their names, IDs, and colors. Pass projectId to target a specific project; otherwise the configured default project is used.",
+    fields: {
+      projectId: mcpProjectId
+    }
+  }
+});
+var childTaskIdForMerge = f.string({
+  desc: "The child task ID whose PR should be approved and merged"
+});
+var approveAndMergePrContract = defineToolContract({
+  name: "approve_and_merge_pr",
+  agent: {
+    description: "Approve and merge a child task's PR. Preconditions: child in ReviewPR. Returns { merged }: true = merged (status\u2192ReviewDev); false = automerge queued, wait for ReviewDev.",
+    fields: {
+      childTaskId: childTaskIdForMerge
+    }
+  },
+  mcp: {
+    description: "Approve and merge a child task's pull request. Pass projectId to target a specific project; otherwise the configured default project is used. Only succeeds if all CI/CD checks are passing. The child task must be in ReviewPR status with a PR.",
+    fields: {
+      projectId: mcpProjectId,
+      childTaskId: childTaskIdForMerge
+    }
+  }
+});
+var tasksContracts = [
+  getTaskContract,
+  postToChatContract,
+  readTaskChatContract,
+  listTagsContract,
+  approveAndMergePrContract
+];
+var mcpChecklistTaskId = f.string({ desc: "The task ID or slug" });
+var testStatuses = f.optional(
+  f.array(f.enum(["open", "approved", "rejected"]), {
+    desc: "Filter tests by status: open | approved | rejected"
+  })
+);
+var setManualTestItems = f.array(
+  f.object({ title: f.string({ min: 1, desc: "A concise, actionable test step" }) }),
+  { min: 1, desc: "List of manual test steps to add" }
+);
+var titleToEdit = f.string({ min: 1, desc: "The current title of the manual test to edit" });
+var newTitle = f.string({ min: 1, desc: "The new title for the manual test" });
+var titleToRemove = f.string({ min: 1, desc: "The title of the manual test to remove" });
+var titleToApprove = f.string({ min: 1, desc: "The title of the manual test to approve" });
+var titleToReject = f.string({ min: 1, desc: "The title of the manual test to reject" });
+var rejectReason = f.string({
+  min: 1,
+  max: 2e3,
+  desc: "Why the test failed \u2014 what went wrong, shown to the team"
+});
+var listManualTestsContract = defineToolContract({
+  name: "list_manual_tests",
+  agent: {
+    description: "List the manual test checklist items for the current task. Use to see what manual verification steps have already been recorded.",
+    fields: {}
+  },
+  mcp: {
+    description: "List the manual test checklist items for a task. Pass projectId to target a specific project; otherwise the configured default project is used. Use to see what manual verification steps have already been recorded.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: f.string({ desc: "The task ID or slug (the value in a card URL, /cards/<slug>)" })
+    }
+  }
+});
+var queryManualTestsContract = defineToolContract({
+  name: "query_manual_tests",
+  agent: {
+    description: "Query manual tests across many tasks in this project, grouped by task. Filter by card status (ReviewDev, ReviewLive, Complete, ...) and/or test status (open | approved | rejected). Use to answer 'show all OPEN manual tests in ReviewDev' or 'show all REJECTED manual tests with the failing reason'. With no filters it defaults to the needs-attention view: open+rejected tests on ReviewDev/ReviewLive cards.",
+    fields: {
+      cardStatuses: f.optional(
+        f.array(f.string(), {
+          desc: 'Filter tasks by card status, e.g. ["ReviewDev", "ReviewLive"]'
+        })
+      ),
+      testStatuses
+    }
+  },
+  mcp: {
+    description: "Query manual tests across many tasks in a project, grouped by task. Filter by card status (e.g. ReviewDev, ReviewLive, Complete) and/or test status (open | approved | rejected). Use to answer questions like 'show all OPEN manual tests in ReviewDev' or 'show all REJECTED manual tests in ReviewDev/ReviewLive with the failing reason'. With no filters it defaults to the needs-attention view: open+rejected tests on ReviewDev/ReviewLive cards. Pass projectId to target a specific project; otherwise the configured default project is used.",
+    fields: {
+      projectId: mcpProjectId,
+      cardStatuses: f.optional(
+        f.array(f.string(), {
+          desc: 'Filter tasks by card/column status, e.g. ["ReviewDev", "ReviewLive"]'
+        })
+      ),
+      testStatuses
+    }
+  }
+});
+var setManualTestsContract = defineToolContract({
+  name: "set_manual_tests",
+  agent: {
+    description: "Add manual test steps to the task checklist. Existing items with the same title are automatically skipped (deduplication). Use to record specific manual verification steps that reviewers should follow when testing this PR.",
+    fields: {
+      items: setManualTestItems
+    }
+  },
+  mcp: {
+    description: "Add manual test steps to a task's checklist. Pass projectId to target a specific project; otherwise the configured default project is used. Existing items with the same title are automatically skipped (deduplication). Use to record specific manual verification steps that reviewers should follow when testing the task's PR.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: mcpChecklistTaskId,
+      items: setManualTestItems
+    }
+  }
+});
+var editManualTestContract = defineToolContract({
+  name: "edit_manual_test",
+  agent: {
+    description: "Rename an existing manual test step. Identify the test by its current title (case-insensitive); pass the new title to replace it. Use to correct or refine a recorded manual verification step.",
+    fields: {
+      title: titleToEdit,
+      newTitle
+    }
+  },
+  mcp: {
+    description: "Rename an existing manual test step on a task. Pass projectId to target a specific project; otherwise the configured default project is used. Identify the test by its current title (case-insensitive) and pass the new title to replace it.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: mcpChecklistTaskId,
+      title: titleToEdit,
+      newTitle
+    }
+  }
+});
+var removeManualTestContract = defineToolContract({
+  name: "remove_manual_test",
+  agent: {
+    description: "Remove an existing manual test step from the task checklist. Identify the test by its title (case-insensitive). Use to delete a stale or incorrect manual verification step.",
+    fields: {
+      title: titleToRemove
+    }
+  },
+  mcp: {
+    description: "Remove an existing manual test step from a task's checklist. Pass projectId to target a specific project; otherwise the configured default project is used. Identify the test by its title (case-insensitive).",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: mcpChecklistTaskId,
+      title: titleToRemove
+    }
+  }
+});
+var approveManualTestContract = defineToolContract({
+  name: "approve_manual_test",
+  agent: {
+    description: "Sign off on (approve) a manual test step on behalf of your authenticated user. Identify the test by its title (case-insensitive). Use after you have verified the step passes.",
+    fields: {
+      title: titleToApprove
+    }
+  },
+  mcp: {
+    description: "Sign off on (approve) a manual test step on a task on behalf of your authenticated user. Pass projectId to target a specific project; otherwise the configured default project is used. Identify the test by its title (case-insensitive). Use after you have verified the step passes.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: mcpChecklistTaskId,
+      title: titleToApprove
+    }
+  }
+});
+var rejectManualTestContract = defineToolContract({
+  name: "reject_manual_test",
+  agent: {
+    description: "Flag an issue with (reject) a manual test step on behalf of your authenticated user, recording the reason. Identify the test by its title (case-insensitive). Use when the step fails verification.",
+    fields: {
+      title: titleToReject,
+      reason: rejectReason
+    }
+  },
+  mcp: {
+    description: "Flag an issue with (reject) a manual test step on a task on behalf of your authenticated user, recording the reason. Pass projectId to target a specific project; otherwise the configured default project is used. Identify the test by its title (case-insensitive). Use when the step fails verification.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: mcpChecklistTaskId,
+      title: titleToReject,
+      reason: rejectReason
+    }
+  }
+});
+var checklistContracts = [
+  listManualTestsContract,
+  queryManualTestsContract,
+  setManualTestsContract,
+  editManualTestContract,
+  removeManualTestContract,
+  approveManualTestContract,
+  rejectManualTestContract
+];
+var getDependenciesContract = defineToolContract({
+  name: "get_dependencies",
+  agent: {
+    description: "Get this task's dependencies and their met/unmet status (met = merged to dev). Use to confirm blockers merged, or see why a task cannot start. For task state use get_task.",
+    fields: {}
+  },
+  mcp: {
+    description: "Get a task's dependencies and their met/unmet status (met = merged to dev). Pass projectId to target a specific project; otherwise the configured default project is used. Use to confirm blockers merged, or see why a task cannot start. For task state use get_task.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: f.string({ desc: "The task ID" })
+    }
+  }
+});
+var addDependencyContract = defineToolContract({
+  name: "add_dependency",
+  agent: {
+    description: "Add a blocking dependency \u2014 this task cannot start until the named task is merged to dev. For post-task follow-ups use create_follow_up_task instead.",
+    fields: {
+      depends_on_slug_or_id: f.string({ desc: "Slug or ID of the task this task depends on" })
+    }
+  },
+  mcp: {
+    description: "Add a blocking dependency \u2014 this task cannot start until the named task is merged to dev. Pass projectId to target a specific project; otherwise the configured default project is used.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: f.string({ desc: "The task ID that will be blocked" }),
+      dependsOnSlugOrId: f.string({ desc: "Slug or ID of the task this one depends on" })
+    }
+  }
+});
+var removeDependencyContract = defineToolContract({
+  name: "remove_dependency",
+  agent: {
+    description: "Remove a previously added dependency from this task. When to use: the dependency was added in error or is no longer relevant. Returns: confirmation string.",
+    fields: {
+      depends_on_slug_or_id: f.string({ desc: "Slug or ID of the task to remove as dependency" })
+    }
+  },
+  mcp: {
+    description: "Remove a previously added dependency from a task. Pass projectId to target a specific project; otherwise the configured default project is used. The task is no longer blocked by the named task. Returns: confirmation string.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: f.string({ desc: "The task ID to unblock" }),
+      dependsOnSlugOrId: f.string({ desc: "Slug or ID of the dependency to remove" })
+    }
+  }
+});
+var dependenciesContracts = [
+  getDependenciesContract,
+  addDependencyContract,
+  removeDependencyContract
+];
+var SP_DESCRIPTION = "Story point value (1=Common, 2=Magic, 3=Rare, 5=Unique)";
+var AGENT_FOLLOW_PARENT_STATUS = "Child mirrors the parent task's status automatically \u2014 for subtasks that ship on the parent's branch/PR with no build or PR of their own. Manual status writes on a follower stick only until the parent's next transition.";
+var MCP_FOLLOW_PARENT_STATUS = "When true, this subtask mirrors the parent task's status automatically \u2014 for children that ship on the parent's branch/PR and have no build or PR of their own. Manual status writes on a follower stick only until the parent's next transition.";
+var AGENT_DEPENDS_ON = "Sibling subtask ids or slugs this subtask blocks on (it won't start until they merge to dev). Set explicit dependency metadata here instead of describing order in the plan text \u2014 the pack runner schedules children off these edges. Omit / leave empty for independent children so they run in parallel.";
+var MCP_STATUS_ENUM = [
+  "Planning",
+  "Open",
+  "InProgress",
+  "ReviewPR",
+  "ReviewDev",
+  "ReviewLive",
+  "Complete",
+  "Cancelled"
+];
+var createSubtaskContract = defineToolContract({
+  name: "create_subtask",
+  agent: {
+    description: "Create a subtask under the current parent task. Use when breaking a complex parent into smaller pieces during planning. For post-task follow-ups use create_follow_up_task.",
+    fields: {
+      title: f.string({ desc: "Subtask title" }),
+      description: f.optional(f.string({ desc: "Brief description" })),
+      plan: f.optional(f.string({ desc: "Implementation plan in markdown" })),
+      ordinal: f.optional(f.number({ desc: "Step/order number (0-based)" })),
+      storyPointValue: f.optional(f.number({ desc: SP_DESCRIPTION })),
+      followParentStatus: f.optional(f.boolean({ desc: AGENT_FOLLOW_PARENT_STATUS })),
+      dependsOn: f.optional(f.array(f.string(), { desc: AGENT_DEPENDS_ON }))
+    }
+  },
+  mcp: {
+    description: "Create a subtask under a parent task. Pass projectId to target a specific project; otherwise the configured default project is used. Subtasks break a larger task into independently buildable pieces. For children that instead ship on the parent's own branch/PR (e.g. per-theme tracking cards for one bundled PR), set followParentStatus so their status rides the parent's automatically.",
+    fields: {
+      projectId: mcpProjectId,
+      parentTaskId: f.string({ desc: "The parent task ID" }),
+      title: f.string({ desc: "Subtask title" }),
+      description: f.optional(f.string({ desc: "Subtask description" })),
+      plan: f.optional(f.string({ desc: "Subtask implementation plan (markdown)" })),
+      ordinal: f.optional(f.number({ desc: "Ordering position among siblings" })),
+      storyPointValue: f.optional(f.number({ desc: SP_DESCRIPTION })),
+      followParentStatus: f.optional(f.boolean({ desc: MCP_FOLLOW_PARENT_STATUS })),
+      dependsOn: f.optional(
+        f.array(f.string(), {
+          desc: "Sibling subtask ids or slugs this subtask blocks on (it won't start until they merge to dev). Set explicit dependency metadata here instead of describing order in the plan text. Omit / leave empty for independent children so they run in parallel."
+        })
+      )
+    }
+  }
+});
+var updateSubtaskContract = defineToolContract({
+  name: "update_subtask",
+  agent: {
+    description: "Update an existing subtask's fields (title, description, plan, ordinal, storyPointValue, dependsOn) \u2014 and the sanctioned path to make a child buildable: promote it to status Open, assign its agent (agentIdOrName), and set story points. Setting story points does NOT auto-promote; set status explicitly. For the current task use update_task_plan.",
+    fields: {
+      subtaskId: f.string({ desc: "The subtask ID to update" }),
+      title: f.optional(f.string()),
+      description: f.optional(f.string()),
+      plan: f.optional(f.string()),
+      status: f.optional(
+        f.enum(["Planning", "Open"], {
+          desc: 'Move the child between "Planning" and "Open". "Open" marks it ready to execute \u2014 required before start_child_cloud_build. Execution statuses transition automatically.'
+        })
+      ),
+      agentIdOrName: f.optional(
+        f.string({
+          desc: "Assign a project agent to the child (agent id or exact name from the Project Agents list). Required before start_child_cloud_build."
+        })
+      ),
+      ordinal: f.optional(f.number()),
+      storyPointValue: f.optional(f.number({ desc: SP_DESCRIPTION })),
+      followParentStatus: f.optional(f.boolean({ desc: AGENT_FOLLOW_PARENT_STATUS })),
+      dependsOn: f.optional(
+        f.array(f.string(), {
+          desc: `${AGENT_DEPENDS_ON} Replaces the full dependency set \u2014 pass [] to clear all, omit to leave unchanged.`
+        })
+      )
+    }
+  },
+  mcp: {
+    description: "Update a subtask's fields: title, description, plan, status, ordering, story points, or dependencies. Pass projectId to target a specific project; otherwise the configured default project is used. Moving a subtask beyond Planning auto-fills missing story points and agent assignment \u2014 don't spend turns on them.",
+    fields: {
+      projectId: mcpProjectId,
+      subtaskId: f.string({ desc: "The subtask ID" }),
+      title: f.optional(f.string({ desc: "New title" })),
+      description: f.optional(f.string({ desc: "New description" })),
+      plan: f.optional(f.string({ desc: "New plan (markdown)" })),
+      status: f.optional(f.enum(MCP_STATUS_ENUM, { desc: "New status" })),
+      ordinal: f.optional(f.number({ desc: "New ordering position among siblings" })),
+      storyPointValue: f.optional(f.number({ desc: SP_DESCRIPTION })),
+      followParentStatus: f.optional(f.boolean({ desc: MCP_FOLLOW_PARENT_STATUS })),
+      dependsOn: f.optional(
+        f.array(f.string(), {
+          desc: "Replace the sibling subtask ids/slugs this subtask blocks on (pass [] to clear). Omit to leave dependencies unchanged."
+        })
+      )
+    }
+  }
+});
+var deleteSubtaskContract = defineToolContract({
+  name: "delete_subtask",
+  agent: {
+    description: "Delete a subtask by id. When to use: a subtask was created in error or is no longer needed. Returns: confirmation string.",
+    fields: {
+      subtaskId: f.string({ desc: "The subtask ID to delete" })
+    }
+  },
+  mcp: {
+    description: "Delete a subtask by ID. Pass projectId to target a specific project; otherwise the configured default project is used. This is permanent \u2014 use update_subtask to set status to Cancelled if you only want to close it.",
+    fields: {
+      projectId: mcpProjectId,
+      subtaskId: f.string({ desc: "The subtask ID to delete" })
+    }
+  }
+});
+var listSubtasksContract = defineToolContract({
+  name: "list_subtasks",
+  agent: {
+    description: "List all subtasks under the current parent task. Default compact view returns per child: status, agent, story points, PR number/state, dependencies, and holdsBuildSlot \u2014 plus packSlots (in-flight environments vs the PACK_CHILD_LIMIT cap, and which children hold the slots). Use to coordinate child work; pass verbose:true only when you need full description/plan text (large). For non-child tasks use get_task.",
+    fields: {
+      verbose: f.optional(
+        f.boolean({
+          desc: "Return full task rows including description and plan text (large \u2014 can exceed tool result limits on big packs). Default: compact orchestration view."
+        })
+      )
+    }
+  },
+  mcp: {
+    description: "List all subtasks of a parent task with their status and ordering. Pass projectId to target a specific project; otherwise the configured default project is used.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: f.string({ desc: "The parent task ID" })
+    }
+  }
+});
+var subtasksContracts = [
+  createSubtaskContract,
+  updateSubtaskContract,
+  deleteSubtaskContract,
+  listSubtasksContract
+];
+var mcpTaskIdOrSlug = f.string({ desc: "The task ID or slug" });
+var listTaskFilesContract = defineToolContract({
+  name: "list_task_files",
+  agent: {
+    description: "List all files attached to this task with metadata. Use before fetching a specific file to see what is available and how large each is. For file contents use get_attachment.",
+    fields: {}
+  },
+  mcp: {
+    description: "List all files attached to a task with metadata (no contents \u2014 fast and small). Pass projectId to target a specific project; otherwise the configured default project is used. Use before fetching a specific file to see what is available and how large each is. For file contents use get_attachment.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: mcpTaskIdOrSlug
+    }
+  }
+});
+var getAttachmentContract = defineToolContract({
+  name: "get_attachment",
+  agent: {
+    description: "Fetch one task file's content plus metadata by file ID. Call list_task_files first to discover IDs and check sizes \u2014 large binaries may be truncated by the service's size limit.",
+    fields: {
+      fileId: f.string({ desc: "The file ID to retrieve" })
+    }
+  },
+  mcp: {
+    description: "Fetch one task file's content plus metadata by file ID (accepts task id or slug). Pass projectId to target a specific project; otherwise the configured default project is used. Images are returned as viewable image blocks. Large text files (logs, JSON) are returned in pages \u2014 use `offset`/`maxBytes` to read more, or fetch `downloadUrl` for the whole file. Call list_task_files first to discover IDs and sizes.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: mcpTaskIdOrSlug,
+      fileId: f.string({ desc: "The file ID to fetch" }),
+      offset: f.optional(
+        f.number({
+          int: true,
+          nonnegative: true,
+          desc: "Byte offset into text content (paging). Default 0."
+        })
+      ),
+      maxBytes: f.optional(
+        f.number({
+          int: true,
+          positive: true,
+          desc: "Max bytes of text content to return from offset."
+        })
+      )
+    }
+  }
+});
+var uploadAttachmentContract = defineToolContract({
+  name: "upload_attachment",
+  agent: {
+    description: "Upload an image file (e.g. a Playwright screenshot) as a task attachment AND post it to the task chat in one step \u2014 no follow-up post_to_chat call needed. Supports png/jpg/gif/webp.",
+    fields: {
+      path: f.string({
+        desc: "Path to the image file \u2014 absolute, or relative to the workspace root"
+      }),
+      title: f.optional(
+        f.string({ desc: "Short caption posted with the image (defaults to the file name)" })
+      )
+    }
+  },
+  mcp: {
+    description: "Upload a local file as a task attachment (any file type, up to 25MB). Pass projectId to target a specific project; otherwise the configured default project is used. The file appears under the task's Files. Pass `comment` to also post it to the task chat in the same step.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: mcpTaskIdOrSlug,
+      path: f.string({ desc: "Absolute path to the local file to upload" }),
+      comment: f.optional(
+        f.string({ desc: "When set, also posts the attachment to the task chat with this text" })
+      ),
+      mimeType: f.optional(
+        f.string({ desc: "Override the mime type inferred from the file extension" })
+      )
+    }
+  }
+});
+var attachmentsContracts = [
+  listTaskFilesContract,
+  getAttachmentContract,
+  uploadAttachmentContract
+];
+var createSuggestionContract = defineToolContract({
+  name: "create_suggestion",
+  agent: {
+    description: "File a project suggestion (idea/improvement for maintainers to review). Duplicates are AI-deduped into an existing suggestion with an upvote. Returns the suggestion id.",
+    fields: {
+      title: f.string({ min: 1, desc: "Short title" }),
+      description: f.optional(f.string({ desc: "1-3 sentences: what should change and why" })),
+      tag_names: f.optional(f.array(f.string(), { desc: "Tag names to categorize" }))
+    }
+  },
+  mcp: {
+    description: "Suggest a feature, improvement, rule, or idea for the project. Pass projectId to target a specific project; otherwise the configured default project is used. Duplicates are deduped and your upvote is recorded.",
+    fields: {
+      projectId: mcpProjectId,
+      title: f.string({ desc: "Suggestion title" }),
+      description: f.optional(f.string({ desc: "Suggestion details (markdown)" })),
+      tagNames: f.optional(
+        f.array(f.string(), {
+          desc: 'Tag names to categorize the suggestion (e.g., ["agent-runner"])'
+        })
+      )
+    }
+  }
+});
+var suggestionsContracts = [createSuggestionContract];
+var createPullRequestContract = defineToolContract({
+  name: "create_pull_request",
+  agent: {
+    description: "Create a GitHub PR for this task. Auto-stages, commits (commitMessage or title default), pushes to origin, then opens the PR. Always use this instead of gh CLI or raw git.",
+    fields: {
+      title: f.string({ desc: "The PR title" }),
+      body: f.string({ desc: "The PR description/body in markdown" }),
+      branch: f.optional(
+        f.string({
+          desc: "The head branch name for the PR. If the task doesn't have a branch set, this will be used. Defaults to the task's existing branch."
+        })
+      ),
+      baseBranch: f.optional(
+        f.string({
+          desc: "The base branch to target for the PR (e.g. 'main', 'develop'). Defaults to the project's configured dev branch."
+        })
+      ),
+      commitMessage: f.optional(
+        f.string({
+          desc: "Commit message for staging uncommitted changes. If not provided, a default message based on the PR title will be used."
+        })
+      ),
+      skipVerify: f.optional(
+        f.boolean({
+          desc: "Controls the local pre-push quality gate (lint/typecheck/test). Defaults to true (--no-verify): the push skips the local gate because you should run gates yourself before opening the PR and CI re-runs them on the resulting PR. Running the full gate synchronously during the push would block the agent's event loop long enough to drop the Conveyor socket connection. Pass false to force the local pre-push hook to run."
+        })
+      )
+    }
+  },
+  mcp: {
+    description: "Open a GitHub pull request for a task's existing branch (the branch must already be pushed to origin). Pass projectId to target a specific project; otherwise the configured default project is used. Moves the task to ReviewPR. Returns the PR number and URL.",
+    fields: {
+      projectId: mcpProjectId,
+      taskId: f.string({ desc: "The task ID whose branch should be opened as a PR" }),
+      title: f.string({ desc: "Pull request title" }),
+      body: f.string({ desc: "Pull request body (markdown)" }),
+      head: f.optional(
+        f.string({ desc: "Source branch for the PR (defaults to the task's branch)" })
+      ),
+      base: f.optional(
+        f.string({ desc: "Target branch for the PR (defaults to the repo default)" })
+      )
+    }
+  }
+});
+var pullRequestContracts = [createPullRequestContract];
+var TOOL_CONTRACTS = Object.fromEntries(
+  [
+    ...tasksContracts,
+    ...checklistContracts,
+    ...dependenciesContracts,
+    ...subtasksContracts,
+    ...attachmentsContracts,
+    ...suggestionsContracts,
+    ...pullRequestContracts
+  ].map((contract) => [contract.name, contract])
+);
+
+// src/tools/contract-tool.ts
 import { z as z4 } from "zod";
+function mcpShape(surface) {
+  return compileShape(z4, surface.fields);
+}
+function registerContractTool(server2, contract, handler) {
+  server2.tool(
+    contract.name,
+    contract.mcp.description,
+    mcpShape(contract.mcp),
+    handler
+  );
+}
+
+// src/tools/tasks.ts
 var CLI_EVENT_FORMATTERS = {
   thinking: (data) => String(data.message ?? ""),
   tool_use: (data) => `${data.tool}: ${String(data.input ?? "").slice(0, 1e3)}`,
@@ -331,10 +1052,10 @@ var STATUS_ENUM = [
 ];
 var CARD_TYPE_ENUM = ["task", "incident", "suggestion"];
 var RISK_ENUM = ["critical", "high", "medium", "low"];
-var BOARD_FILTER = z4.string().nullable().optional().describe(
+var BOARD_FILTER = z5.string().nullable().optional().describe(
   "Filter to a sub-project board. Omit to use the connection's default board (CONVEYOR_SUBPROJECT_ID) when set, else the whole project; pass null to force the whole project. Use list_accessible_subprojects to find board IDs."
 );
-var BOARD_ASSIGN = z4.string().nullable().optional().describe(
+var BOARD_ASSIGN = z5.string().nullable().optional().describe(
   "Assign the card to a sub-project board. Omit to use the connection's default board (CONVEYOR_SUBPROJECT_ID) when set, else the parent project; pass null to force the parent project. Use list_accessible_subprojects to find board IDs."
 );
 function registerListTasks(server2, conn2) {
@@ -342,15 +1063,15 @@ function registerListTasks(server2, conn2) {
     "list_tasks",
     "List project cards, optionally filtered by card type, status, or assignment (a specific assignee, or unassigned tasks). Defaults to type=task \u2014 pass typeFilters to list incidents/suggestions. Results are relevance-ordered: highest priority first then newest; suggestions-only queries rank by upvote score. Pass projectId to target a specific project; otherwise the configured default project is used. Returns summaries \u2014 plan omitted, description truncated; use get_task for full details.",
     {
-      projectId: z4.string().optional().describe("Target Conveyor project ID"),
-      status: z4.enum(STATUS_ENUM).optional().describe("Filter by task status"),
-      typeFilters: z4.array(z4.enum(CARD_TYPE_ENUM)).optional().describe(
+      projectId: z5.string().optional().describe("Target Conveyor project ID"),
+      status: z5.enum(STATUS_ENUM).optional().describe("Filter by task status"),
+      typeFilters: z5.array(z5.enum(CARD_TYPE_ENUM)).optional().describe(
         'Card types to include, e.g. ["incident"] or ["task", "incident"]. Omit for tasks only.'
       ),
-      assigneeId: z4.string().optional().describe("Filter by assigned user ID"),
-      unassigned: z4.boolean().optional().describe("Only return tasks with no assignee (mutually exclusive with assigneeId)"),
+      assigneeId: z5.string().optional().describe("Filter by assigned user ID"),
+      unassigned: z5.boolean().optional().describe("Only return tasks with no assignee (mutually exclusive with assigneeId)"),
       subProjectId: BOARD_FILTER,
-      limit: z4.number().optional().describe("Max tasks to return (default 50)")
+      limit: z5.number().optional().describe("Max tasks to return (default 50)")
     },
     async (params) => {
       const tasks = await conn2.listTasks(params);
@@ -361,26 +1082,18 @@ function registerListTasks(server2, conn2) {
   );
 }
 function registerGetTask(server2, conn2) {
-  server2.tool(
-    "get_task",
-    "Get full task details including plan, chat history, PR info, subtasks, and build status. Pass projectId to target a specific project; otherwise the configured default project is used.",
-    {
-      projectId: z4.string().optional().describe("Target Conveyor project ID"),
-      taskId: z4.string().describe("The task ID or slug (the value in a card URL, /cards/<slug>)")
-    },
-    async (params) => {
-      const task = await conn2.getTask(params.taskId, params.projectId);
-      return { content: [{ type: "text", text: JSON.stringify(task, null, 2) }] };
-    }
-  );
+  registerContractTool(server2, getTaskContract, async (params) => {
+    const task = await conn2.getTask(params.taskId, params.projectId);
+    return { content: [{ type: "text", text: JSON.stringify(task, null, 2) }] };
+  });
 }
 function registerGetCardBySlug(server2, conn2) {
   server2.tool(
     "get_card_by_slug",
     "Get full card details by the slug from a card URL (/cards/<slug>) instead of a task ID. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      projectId: z4.string().optional().describe("Target Conveyor project ID"),
-      slug: z4.string().describe("The card slug from a Conveyor card URL, e.g. 'ship-it'")
+      projectId: z5.string().optional().describe("Target Conveyor project ID"),
+      slug: z5.string().describe("The card slug from a Conveyor card URL, e.g. 'ship-it'")
     },
     async (params) => {
       const task = await conn2.getCardBySlug(params.slug, params.projectId);
@@ -393,11 +1106,11 @@ function registerCreateTask(server2, conn2) {
     "create_task",
     "Create a new task with title, description, and optional plan. Pass projectId to target a specific project; otherwise the configured default project is used. Icon, story points, and agent assignment are auto-filled when a task is created in (or later moved to) a status beyond Planning \u2014 don't spend turns on them.",
     {
-      projectId: z4.string().optional().describe("Target Conveyor project ID"),
-      title: z4.string().describe("Task title"),
-      description: z4.string().optional().describe("Task description"),
-      plan: z4.string().optional().describe("Task implementation plan (markdown)"),
-      status: z4.enum(["Planning", "Open"]).optional().describe("Initial status (default: Planning)"),
+      projectId: z5.string().optional().describe("Target Conveyor project ID"),
+      title: z5.string().describe("Task title"),
+      description: z5.string().optional().describe("Task description"),
+      plan: z5.string().optional().describe("Task implementation plan (markdown)"),
+      status: z5.enum(["Planning", "Open"]).optional().describe("Initial status (default: Planning)"),
       subProjectId: BOARD_ASSIGN
     },
     async (params) => {
@@ -418,17 +1131,17 @@ function registerUpdateTask(server2, conn2) {
     "update_task",
     "Update task fields: title, description, plan, status, risk, or assignment. Set status to claim a card (InProgress), triage it (Open), or cancel it (Cancelled); for review approvals prefer approve_task / request_changes, which guard against stale-state races. Pass projectId to target a specific project; otherwise the configured default project is used. Moving a task beyond Planning auto-fills any missing icon, story points, and agent assignment \u2014 don't spend turns on them.",
     {
-      projectId: z4.string().optional().describe("Target Conveyor project ID"),
-      taskId: z4.string().describe("The task ID"),
-      title: z4.string().optional().describe("New title"),
-      description: z4.string().optional().describe("New description"),
-      plan: z4.string().optional().describe("New plan (markdown)"),
-      status: z4.enum(STATUS_ENUM).optional().describe("New status"),
-      risk: z4.enum(RISK_ENUM).nullable().optional().describe(
+      projectId: z5.string().optional().describe("Target Conveyor project ID"),
+      taskId: z5.string().describe("The task ID"),
+      title: z5.string().optional().describe("New title"),
+      description: z5.string().optional().describe("New description"),
+      plan: z5.string().optional().describe("New plan (markdown)"),
+      status: z5.enum(STATUS_ENUM).optional().describe("New status"),
+      risk: z5.enum(RISK_ENUM).nullable().optional().describe(
         "Risk level \u2014 how much important surface the task touches (critical/high/medium/low). Pass null to clear."
       ),
-      assignedUserId: z4.string().nullable().optional().describe("User ID to assign, or null"),
-      subProjectId: z4.string().nullable().optional().describe(
+      assignedUserId: z5.string().nullable().optional().describe("User ID to assign, or null"),
+      subProjectId: z5.string().nullable().optional().describe(
         "Assign the task to a sub-project board; null moves it back to the parent board. Omit to leave unchanged."
       )
     },
@@ -445,9 +1158,9 @@ function registerMoveCard(server2, conn2) {
     "move_card",
     "Move an eligible Planning or Open task, incident, or suggestion card to another project. Cards with identification or automation in progress, active compute, pull requests, deployments, releases, reviews, or delivered reporter email cannot move. Project-specific metadata is cleared instead of mapped by name. Pass projectId for the source project; otherwise the configured default project is used.",
     {
-      projectId: z4.string().optional().describe("Source Conveyor project ID"),
-      taskId: z4.string().describe("Card ID or slug"),
-      destinationProjectId: z4.string().describe("Destination Conveyor project ID")
+      projectId: z5.string().optional().describe("Source Conveyor project ID"),
+      taskId: z5.string().describe("Card ID or slug"),
+      destinationProjectId: z5.string().describe("Destination Conveyor project ID")
     },
     async (params) => {
       const result = await conn2.moveCard(params);
@@ -464,44 +1177,37 @@ function registerMoveCard(server2, conn2) {
   );
 }
 function registerChatTools(server2, conn2) {
-  server2.tool(
-    "read_task_chat",
-    "Read messages from a task's chat. Pass projectId to target a specific project; otherwise the configured default project is used. For agent execution logs use get_task_logs.",
-    {
-      projectId: z4.string().optional().describe("Target Conveyor project ID"),
-      taskId: z4.string().describe("The task ID"),
-      limit: z4.number().optional().describe("Max messages to return (default 50)")
-    },
-    async (params) => {
-      const messages = await conn2.getTaskChat(params.taskId, params.limit, params.projectId);
-      return { content: [{ type: "text", text: JSON.stringify(messages, null, 2) }] };
-    }
-  );
-  server2.tool(
-    "post_to_chat",
-    "Post a message to a task's chat. Pass projectId to target a specific project; otherwise the configured default project is used.",
-    {
-      projectId: z4.string().optional().describe("Target Conveyor project ID"),
-      taskId: z4.string().describe("The task ID"),
-      content: z4.string().describe("Message content")
-    },
-    async (params) => {
-      await conn2.postToTaskChat(params.taskId, params.content, params.projectId);
-      return { content: [{ type: "text", text: "Message posted" }] };
+  registerContractTool(server2, readTaskChatContract, async (params) => {
+    const messages = await conn2.getTaskChat(params.taskId, params.limit, params.projectId);
+    return { content: [{ type: "text", text: JSON.stringify(messages, null, 2) }] };
+  });
+  registerContractTool(server2, postToChatContract, async (params) => {
+    const text = params.content ?? params.message;
+    if (text === void 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: "Nothing to post \u2014 provide `content` (or its alias `message`)."
+          }
+        ]
+      };
     }
-  );
+    await conn2.postToTaskChat(params.taskId, text, params.projectId);
+    return { content: [{ type: "text", text: "Message posted" }] };
+  });
 }
 function registerGetTaskCli(server2, conn2) {
   server2.tool(
     "get_task_logs",
     "Read CLI execution logs from a task. Pass projectId to target a specific project; otherwise the configured default project is used. Returns agent reasoning, tool calls, setup output, and other execution events. For human chat use read_task_chat.",
     {
-      projectId: z4.string().optional().describe("Target Conveyor project ID"),
-      taskId: z4.string().describe("The task ID or slug"),
-      source: z4.enum(["agent", "application"]).optional().describe(
+      projectId: z5.string().optional().describe("Target Conveyor project ID"),
+      taskId: z5.string().describe("The task ID or slug"),
+      source: z5.enum(["agent", "application"]).optional().describe(
         "Filter by log source: 'agent' for reasoning/tool calls, 'application' for setup/dev-server output"
       ),
-      limit: z4.number().optional().describe("Max entries to return (default 50, max 500)")
+      limit: z5.number().optional().describe("Max entries to return (default 50, max 500)")
     },
     async ({ taskId, source, limit, projectId: projectId2 }) => {
       const effectiveLimit = Math.min(limit ?? 50, 500);
@@ -520,8 +1226,8 @@ function registerGetTaskSessions(server2, conn2) {
     "get_task_sessions",
     "Read compute-session state for a task: legacy CodespaceSession rows plus v3 workspaces, including purpose=review review workspaces. Shows pod identity, liveness, lifecycle, and code-review claim state. Use to diagnose stalled/dead agents or code-review runs. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      projectId: z4.string().optional().describe("Target Conveyor project ID"),
-      taskId: z4.string().describe("The task ID or slug")
+      projectId: z5.string().optional().describe("Target Conveyor project ID"),
+      taskId: z5.string().describe("The task ID or slug")
     },
     async ({ taskId, projectId: projectId2 }) => {
       const tasks = await conn2.getTaskSessions(taskId, projectId2);
@@ -539,17 +1245,17 @@ function registerSearchTasks(server2, conn2) {
     "search_tasks",
     "Search cards by tag name, text query, status, type, and/or assignment. Defaults to type=task \u2014 pass typeFilters to include incidents/suggestions. Results are relevance-ordered: highest priority first then newest; suggestions-only queries rank by upvote score. Pass projectId to target a specific project; otherwise the configured default project is used. Use tag names like 'agent-runner', not IDs. Returns summaries \u2014 plan omitted, description truncated; use get_task for full details.",
     {
-      projectId: z4.string().optional().describe("Target Conveyor project ID"),
-      tagNames: z4.array(z4.string()).optional().describe('Tag names to filter by (e.g., ["agent-runner", "chat"])'),
-      searchQuery: z4.string().optional().describe("Text search on title and description"),
-      statusFilters: z4.array(z4.enum(STATUS_ENUM)).optional().describe("Filter by one or more statuses"),
-      typeFilters: z4.array(z4.enum(CARD_TYPE_ENUM)).optional().describe(
+      projectId: z5.string().optional().describe("Target Conveyor project ID"),
+      tagNames: z5.array(z5.string()).optional().describe('Tag names to filter by (e.g., ["agent-runner", "chat"])'),
+      searchQuery: z5.string().optional().describe("Text search on title and description"),
+      statusFilters: z5.array(z5.enum(STATUS_ENUM)).optional().describe("Filter by one or more statuses"),
+      typeFilters: z5.array(z5.enum(CARD_TYPE_ENUM)).optional().describe(
         'Card types to include (default ["task"]). Pass e.g. ["incident"] or list several to search across types.'
       ),
-      assigneeId: z4.string().optional().describe("Filter by assigned user ID"),
-      unassigned: z4.boolean().optional().describe("Only return tasks with no assignee (mutually exclusive with assigneeId)"),
+      assigneeId: z5.string().optional().describe("Filter by assigned user ID"),
+      unassigned: z5.boolean().optional().describe("Only return tasks with no assignee (mutually exclusive with assigneeId)"),
       subProjectId: BOARD_FILTER,
-      limit: z4.number().optional().describe("Max results to return (default 20)")
+      limit: z5.number().optional().describe("Max results to return (default 20)")
     },
     async (params) => {
       const tasks = await conn2.searchTasks(params);
@@ -560,26 +1266,19 @@ function registerSearchTasks(server2, conn2) {
   );
 }
 function registerListTags(server2, conn2) {
-  server2.tool(
-    "list_tags",
-    "List all project tags with their names, IDs, and colors. Pass projectId to target a specific project; otherwise the configured default project is used.",
-    {
-      projectId: z4.string().optional().describe("Target Conveyor project ID")
-    },
-    async (params) => {
-      const tags = await conn2.listTags(params.projectId);
-      return { content: [{ type: "text", text: JSON.stringify(tags, null, 2) }] };
-    }
-  );
+  registerContractTool(server2, listTagsContract, async (params) => {
+    const tags = await conn2.listTags(params.projectId);
+    return { content: [{ type: "text", text: JSON.stringify(tags, null, 2) }] };
+  });
 }
 function registerReviewTools(server2, conn2) {
   server2.tool(
     "approve_task",
     "Move a task forward in the review flow (ReviewPR -> ReviewDev, or -> Complete). Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      projectId: z4.string().optional().describe("Target Conveyor project ID"),
-      taskId: z4.string().describe("The task ID"),
-      risk: z4.enum(RISK_ENUM).optional().describe("Optional risk level to record; defaults to a raise-only 'low' on approval.")
+      projectId: z5.string().optional().describe("Target Conveyor project ID"),
+      taskId: z5.string().describe("The task ID"),
+      risk: z5.enum(RISK_ENUM).optional().describe("Optional risk level to record; defaults to a raise-only 'low' on approval.")
     },
     async (params) => {
       const result = await conn2.approveTask(params.taskId, params.projectId, params.risk);
@@ -588,33 +1287,25 @@ function registerReviewTools(server2, conn2) {
       };
     }
   );
-  server2.tool(
-    "approve_and_merge_pr",
-    "Approve and merge a child task's pull request. Pass projectId to target a specific project; otherwise the configured default project is used. Only succeeds if all CI/CD checks are passing. The child task must be in ReviewPR status with a PR.",
-    {
-      projectId: z4.string().optional().describe("Target Conveyor project ID"),
-      childTaskId: z4.string().describe("The child task ID whose PR should be approved and merged")
-    },
-    async (params) => {
-      const result = await conn2.approveAndMergePR(params.childTaskId, params.projectId);
-      return {
-        content: [
-          {
-            type: "text",
-            text: `PR #${result.prNumber} approved and merged for task ${result.childTaskId}`
-          }
-        ]
-      };
-    }
-  );
+  registerContractTool(server2, approveAndMergePrContract, async (params) => {
+    const result = await conn2.approveAndMergePR(params.childTaskId, params.projectId);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `PR #${result.prNumber} approved and merged for task ${result.childTaskId}`
+        }
+      ]
+    };
+  });
   server2.tool(
     "request_changes",
     "Post feedback and send task back to InProgress for more work. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      projectId: z4.string().optional().describe("Target Conveyor project ID"),
-      taskId: z4.string().describe("The task ID"),
-      feedback: z4.string().describe("Feedback message describing requested changes"),
-      risk: z4.enum(RISK_ENUM).optional().describe("Optional risk level to record; defaults to a raise-only 'medium' on changes.")
+      projectId: z5.string().optional().describe("Target Conveyor project ID"),
+      taskId: z5.string().describe("The task ID"),
+      feedback: z5.string().describe("Feedback message describing requested changes"),
+      risk: z5.enum(RISK_ENUM).optional().describe("Optional risk level to record; defaults to a raise-only 'medium' on changes.")
     },
     async (params) => {
       await conn2.requestChanges(params.taskId, params.feedback, params.projectId, params.risk);
@@ -631,9 +1322,9 @@ function registerReviewerTools(server2, conn2) {
     "add_reviewer",
     "Add a project member as a reviewer on a task. Pass projectId to target a specific project; otherwise the configured default project is used. Idempotent \u2014 adding an existing reviewer is a no-op.",
     {
-      projectId: z4.string().optional().describe("Target Conveyor project ID"),
-      taskId: z4.string().describe("The task ID or slug"),
-      userId: z4.string().describe("User ID of the reviewer (use list_project_members to resolve a name or email)")
+      projectId: z5.string().optional().describe("Target Conveyor project ID"),
+      taskId: z5.string().describe("The task ID or slug"),
+      userId: z5.string().describe("User ID of the reviewer (use list_project_members to resolve a name or email)")
     },
     async (params) => {
       const result = await conn2.addReviewer(params);
@@ -651,9 +1342,9 @@ function registerReviewerTools(server2, conn2) {
     "remove_reviewer",
     "Remove a reviewer from a task. Pass projectId to target a specific project; otherwise the configured default project is used. Idempotent \u2014 removing a non-reviewer is a no-op.",
     {
-      projectId: z4.string().optional().describe("Target Conveyor project ID"),
-      taskId: z4.string().describe("The task ID or slug"),
-      userId: z4.string().describe("User ID of the reviewer to remove")
+      projectId: z5.string().optional().describe("Target Conveyor project ID"),
+      taskId: z5.string().describe("The task ID or slug"),
+      userId: z5.string().describe("User ID of the reviewer to remove")
     },
     async (params) => {
       const result = await conn2.removeReviewer(params);
@@ -685,7 +1376,7 @@ function registerTaskTools(server2, conn2) {
 }
 
 // src/tools/builds.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 function textResult2(result) {
   return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 }
@@ -694,8 +1385,8 @@ function registerTaskLifecycleTools(server2, conn2) {
     "stop_task",
     "Compatibility alias for the legacy stop path. stop_task now performs the same durable sleep behavior as sleep_task, preserving task Claudespace state while stopping compute. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      projectId: z5.string().optional().describe("Target Conveyor project ID"),
-      taskId: z5.string().describe("The task ID")
+      projectId: z6.string().optional().describe("Target Conveyor project ID"),
+      taskId: z6.string().describe("The task ID")
     },
     async (params) => textResult2(await conn2.sleepTask(params.taskId, params.projectId))
   );
@@ -703,8 +1394,8 @@ function registerTaskLifecycleTools(server2, conn2) {
     "sleep_task",
     "Sleep a task Claudespace, stopping compute while preserving durable state. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      projectId: z5.string().optional().describe("Target Conveyor project ID"),
-      taskId: z5.string().describe("The task ID")
+      projectId: z6.string().optional().describe("Target Conveyor project ID"),
+      taskId: z6.string().describe("The task ID")
     },
     async (params) => textResult2(await conn2.sleepTask(params.taskId, params.projectId))
   );
@@ -712,8 +1403,8 @@ function registerTaskLifecycleTools(server2, conn2) {
     "resume_task",
     "Resume a sleeping task Claudespace. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      projectId: z5.string().optional().describe("Target Conveyor project ID"),
-      taskId: z5.string().describe("The task ID")
+      projectId: z6.string().optional().describe("Target Conveyor project ID"),
+      taskId: z6.string().describe("The task ID")
     },
     async (params) => textResult2(await conn2.resumeTask(params.taskId, params.projectId))
   );
@@ -721,8 +1412,8 @@ function registerTaskLifecycleTools(server2, conn2) {
     "delete_task_environment",
     "Delete a task environment, including durable Claudespace state. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      projectId: z5.string().optional().describe("Target Conveyor project ID"),
-      taskId: z5.string().describe("The task ID")
+      projectId: z6.string().optional().describe("Target Conveyor project ID"),
+      taskId: z6.string().describe("The task ID")
     },
     async (params) => textResult2(await conn2.deleteTaskEnvironment(params.taskId, params.projectId))
   );
@@ -732,8 +1423,8 @@ function registerBuildTools(server2, conn2) {
     "start_task",
     "Start a cloud build (codespace) for a task. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      projectId: z5.string().optional().describe("Target Conveyor project ID"),
-      taskId: z5.string().describe("The task ID")
+      projectId: z6.string().optional().describe("Target Conveyor project ID"),
+      taskId: z6.string().describe("The task ID")
     },
     async (params) => {
       const result = await conn2.startBuild(params.taskId, params.projectId);
@@ -745,8 +1436,8 @@ function registerBuildTools(server2, conn2) {
     "create_release",
     "Create a release for the project \u2014 the same flow as the Release button in the web UI. Pass projectId to target a specific project; otherwise the configured default project is used. Creates a release task with a release/YYYY.MM.N branch and a PR from the dev branch to the default branch. Omit taskIds to release ALL cards currently in Review (Dev); pass a subset to cherry-pick \u2014 a cloud build agent then cherry-picks those changes and resolves conflicts. Fails if a release is already in progress or no cards are in Review (Dev).",
     {
-      projectId: z5.string().optional().describe("Target Conveyor project ID"),
-      taskIds: z5.array(z5.string()).optional().describe(
+      projectId: z6.string().optional().describe("Target Conveyor project ID"),
+      taskIds: z6.array(z6.string()).optional().describe(
         "Task IDs in Review (Dev) to cherry-pick into the release. Omit to release all of them."
       )
     },
@@ -759,8 +1450,8 @@ function registerBuildTools(server2, conn2) {
     "get_build_status",
     "Check codespace and agent status for a task. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      projectId: z5.string().optional().describe("Target Conveyor project ID"),
-      taskId: z5.string().describe("The task ID")
+      projectId: z6.string().optional().describe("Target Conveyor project ID"),
+      taskId: z6.string().describe("The task ID")
     },
     async (params) => {
       const status = await conn2.getBuildStatus(params.taskId, params.projectId);
@@ -772,7 +1463,6 @@ function registerBuildTools(server2, conn2) {
 // src/tools/attachments.ts
 import { readFile, stat } from "fs/promises";
 import { basename, extname } from "path";
-import { z as z6 } from "zod";
 var MAX_FILE_SIZE_BYTES = 25 * 1024 * 1024;
 var MIME_BY_EXT = {
   ".png": "image/png",
@@ -805,18 +1495,10 @@ function inferMimeType(filePath, override) {
   return MIME_BY_EXT[extname(filePath).toLowerCase()] ?? "application/octet-stream";
 }
 function registerListTaskFiles(server2, conn2) {
-  server2.tool(
-    "list_task_files",
-    "List all files attached to a task with metadata (no contents \u2014 fast and small). Pass projectId to target a specific project; otherwise the configured default project is used. Use before fetching a specific file to see what is available and how large each is. For file contents use get_attachment.",
-    {
-      projectId: z6.string().optional().describe("Target Conveyor project ID"),
-      taskId: z6.string().describe("The task ID or slug")
-    },
-    async (params) => {
-      const files = await conn2.listTaskFiles(params.taskId, params.projectId);
-      return { content: [{ type: "text", text: JSON.stringify(files, null, 2) }] };
-    }
-  );
+  registerContractTool(server2, listTaskFilesContract, async (params) => {
+    const files = await conn2.listTaskFiles(params.taskId, params.projectId);
+    return { content: [{ type: "text", text: JSON.stringify(files, null, 2) }] };
+  });
 }
 function buildTextContent(file, content) {
   const start = file.contentByteOffset ?? 0;
@@ -848,90 +1530,68 @@ function buildAttachmentContent(file) {
   return [{ type: "text", text: JSON.stringify(metadata, null, 2) }];
 }
 function registerGetAttachment(server2, conn2) {
-  server2.tool(
-    "get_attachment",
-    "Fetch one task file's content plus metadata by file ID (accepts task id or slug). Pass projectId to target a specific project; otherwise the configured default project is used. Images are returned as viewable image blocks. Large text files (logs, JSON) are returned in pages \u2014 use `offset`/`maxBytes` to read more, or fetch `downloadUrl` for the whole file. Call list_task_files first to discover IDs and sizes.",
-    {
-      projectId: z6.string().optional().describe("Target Conveyor project ID"),
-      taskId: z6.string().describe("The task ID or slug"),
-      fileId: z6.string().describe("The file ID to fetch"),
-      offset: z6.number().int().nonnegative().optional().describe("Byte offset into text content (paging). Default 0."),
-      maxBytes: z6.number().int().positive().optional().describe("Max bytes of text content to return from offset.")
-    },
-    async (params) => {
-      const file = await conn2.getAttachment(params.taskId, params.fileId, {
-        offset: params.offset,
-        maxBytes: params.maxBytes,
-        projectId: params.projectId
-      });
-      return { content: buildAttachmentContent(file) };
-    }
-  );
+  registerContractTool(server2, getAttachmentContract, async (params) => {
+    const file = await conn2.getAttachment(params.taskId, params.fileId, {
+      offset: params.offset,
+      maxBytes: params.maxBytes,
+      projectId: params.projectId
+    });
+    return { content: buildAttachmentContent(file) };
+  });
 }
 function registerUploadAttachment(server2, conn2) {
-  server2.tool(
-    "upload_attachment",
-    "Upload a local file as a task attachment (any file type, up to 25MB). Pass projectId to target a specific project; otherwise the configured default project is used. The file appears under the task's Files. Pass `comment` to also post it to the task chat in the same step.",
-    {
-      projectId: z6.string().optional().describe("Target Conveyor project ID"),
-      taskId: z6.string().describe("The task ID or slug"),
-      path: z6.string().describe("Absolute path to the local file to upload"),
-      comment: z6.string().optional().describe("When set, also posts the attachment to the task chat with this text"),
-      mimeType: z6.string().optional().describe("Override the mime type inferred from the file extension")
-    },
-    async (params) => {
-      const info = await stat(params.path).catch(() => null);
-      if (!info?.isFile()) {
-        return { content: [{ type: "text", text: `File not found: ${params.path}` }] };
-      }
-      if (info.size > MAX_FILE_SIZE_BYTES) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `File is ${info.size} bytes \u2014 exceeds the ${MAX_FILE_SIZE_BYTES} byte (25MB) upload limit.`
-            }
-          ]
-        };
-      }
-      const fileName = basename(params.path);
-      const mimeType = inferMimeType(params.path, params.mimeType);
-      const { fileId, uploadUrl } = await conn2.requestFileUpload(params.taskId, {
-        fileName,
-        mimeType,
-        fileSize: info.size,
-        projectId: params.projectId
-      });
-      const body = await readFile(params.path);
-      const res = await fetch(uploadUrl, {
-        method: "PUT",
-        headers: { "Content-Type": mimeType },
-        body
-      });
-      if (!res.ok) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Upload to storage failed: HTTP ${res.status} ${await res.text().catch(() => "")}`
-            }
-          ]
-        };
-      }
-      const result = await conn2.confirmFileUpload(
-        params.taskId,
-        fileId,
-        params.comment,
-        params.projectId
-      );
-      const lines = [
-        `Uploaded ${result.fileName} (${info.size} bytes, ${mimeType}). File ID: ${result.fileId}`
-      ];
-      if (result.downloadUrl) lines.push(`downloadUrl: ${result.downloadUrl}`);
-      if (result.messageId) lines.push("Posted to the task chat.");
-      return { content: [{ type: "text", text: lines.join("\n") }] };
+  registerContractTool(server2, uploadAttachmentContract, async (params) => {
+    const info = await stat(params.path).catch(() => null);
+    if (!info?.isFile()) {
+      return { content: [{ type: "text", text: `File not found: ${params.path}` }] };
     }
-  );
+    if (info.size > MAX_FILE_SIZE_BYTES) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `File is ${info.size} bytes \u2014 exceeds the ${MAX_FILE_SIZE_BYTES} byte (25MB) upload limit.`
+          }
+        ]
+      };
+    }
+    const fileName = basename(params.path);
+    const mimeType = inferMimeType(params.path, params.mimeType);
+    const { fileId, uploadUrl } = await conn2.requestFileUpload(params.taskId, {
+      fileName,
+      mimeType,
+      fileSize: info.size,
+      projectId: params.projectId
+    });
+    const body = await readFile(params.path);
+    const res = await fetch(uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Type": mimeType },
+      body
+    });
+    if (!res.ok) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Upload to storage failed: HTTP ${res.status} ${await res.text().catch(() => "")}`
+          }
+        ]
+      };
+    }
+    const result = await conn2.confirmFileUpload(
+      params.taskId,
+      fileId,
+      params.comment,
+      params.projectId
+    );
+    const lines = [
+      `Uploaded ${result.fileName} (${info.size} bytes, ${mimeType}). File ID: ${result.fileId}`
+    ];
+    if (result.downloadUrl) lines.push(`downloadUrl: ${result.downloadUrl}`);
+    if (result.messageId) lines.push("Posted to the task chat.");
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  });
 }
 function registerAttachmentTools(server2, conn2) {
   registerListTaskFiles(server2, conn2);
@@ -940,126 +1600,45 @@ function registerAttachmentTools(server2, conn2) {
 }
 
 // src/tools/pull-request.ts
-import { z as z7 } from "zod";
 function registerPullRequestTools(server2, conn2) {
-  server2.tool(
-    "create_pull_request",
-    "Open a GitHub pull request for a task's existing branch (the branch must already be pushed to origin). Pass projectId to target a specific project; otherwise the configured default project is used. Moves the task to ReviewPR. Returns the PR number and URL.",
-    {
-      projectId: z7.string().optional().describe("Target Conveyor project ID"),
-      taskId: z7.string().describe("The task ID whose branch should be opened as a PR"),
-      title: z7.string().describe("Pull request title"),
-      body: z7.string().describe("Pull request body (markdown)"),
-      head: z7.string().optional().describe("Source branch for the PR (defaults to the task's branch)"),
-      base: z7.string().optional().describe("Target branch for the PR (defaults to the repo default)")
-    },
-    async (params) => {
-      const result = await conn2.createPullRequest(params);
-      return {
-        content: [{ type: "text", text: `PR #${result.prNumber} opened: ${result.prUrl}` }]
-      };
-    }
-  );
+  registerContractTool(server2, createPullRequestContract, async (params) => {
+    const result = await conn2.createPullRequest(params);
+    return {
+      content: [{ type: "text", text: `PR #${result.prNumber} opened: ${result.prUrl}` }]
+    };
+  });
 }
 
 // src/tools/subtasks.ts
-import { z as z8 } from "zod";
-var STATUS_ENUM2 = [
-  "Planning",
-  "Open",
-  "InProgress",
-  "ReviewPR",
-  "ReviewDev",
-  "ReviewLive",
-  "Complete",
-  "Cancelled"
-];
-var SP_DESCRIPTION = "Story point value (1=Common, 2=Magic, 3=Rare, 5=Unique)";
-var FOLLOW_PARENT_STATUS_DESCRIPTION = "When true, this subtask mirrors the parent task's status automatically \u2014 for children that ship on the parent's branch/PR and have no build or PR of their own. Manual status writes on a follower stick only until the parent's next transition.";
 function registerCreateSubtask(server2, conn2) {
-  server2.tool(
-    "create_subtask",
-    "Create a subtask under a parent task. Pass projectId to target a specific project; otherwise the configured default project is used. Subtasks break a larger task into independently buildable pieces. For children that instead ship on the parent's own branch/PR (e.g. per-theme tracking cards for one bundled PR), set followParentStatus so their status rides the parent's automatically.",
-    {
-      projectId: z8.string().optional().describe("Target Conveyor project ID"),
-      parentTaskId: z8.string().describe("The parent task ID"),
-      title: z8.string().describe("Subtask title"),
-      description: z8.string().optional().describe("Subtask description"),
-      plan: z8.string().optional().describe("Subtask implementation plan (markdown)"),
-      ordinal: z8.number().optional().describe("Ordering position among siblings"),
-      storyPointValue: z8.number().optional().describe(SP_DESCRIPTION),
-      followParentStatus: z8.boolean().optional().describe(FOLLOW_PARENT_STATUS_DESCRIPTION),
-      dependsOn: z8.array(z8.string()).optional().describe(
-        "Sibling subtask ids or slugs this subtask blocks on (it won't start until they merge to dev). Set explicit dependency metadata here instead of describing order in the plan text. Omit / leave empty for independent children so they run in parallel."
-      )
-    },
-    async (params) => {
-      const subtask = await conn2.createSubtask(params);
-      return {
-        content: [{ type: "text", text: `Subtask created: ${subtask.id} (slug: ${subtask.slug})` }]
-      };
-    }
-  );
+  registerContractTool(server2, createSubtaskContract, async (params) => {
+    const subtask = await conn2.createSubtask(params);
+    return {
+      content: [{ type: "text", text: `Subtask created: ${subtask.id} (slug: ${subtask.slug})` }]
+    };
+  });
 }
 function registerUpdateSubtask(server2, conn2) {
-  server2.tool(
-    "update_subtask",
-    "Update a subtask's fields: title, description, plan, status, ordering, story points, or dependencies. Pass projectId to target a specific project; otherwise the configured default project is used. Moving a subtask beyond Planning auto-fills missing story points and agent assignment \u2014 don't spend turns on them.",
-    {
-      projectId: z8.string().optional().describe("Target Conveyor project ID"),
-      subtaskId: z8.string().describe("The subtask ID"),
-      title: z8.string().optional().describe("New title"),
-      description: z8.string().optional().describe("New description"),
-      plan: z8.string().optional().describe("New plan (markdown)"),
-      status: z8.enum(STATUS_ENUM2).optional().describe("New status"),
-      ordinal: z8.number().optional().describe("New ordering position among siblings"),
-      storyPointValue: z8.number().optional().describe(SP_DESCRIPTION),
-      followParentStatus: z8.boolean().optional().describe(FOLLOW_PARENT_STATUS_DESCRIPTION),
-      dependsOn: z8.array(z8.string()).optional().describe(
-        "Replace the sibling subtask ids/slugs this subtask blocks on (pass [] to clear). Omit to leave dependencies unchanged."
-      )
-    },
-    async (params) => {
-      const result = await conn2.updateSubtask(params);
-      return {
-        content: [
-          { type: "text", text: `Subtask ${result.id} updated (status: ${result.status})` }
-        ]
-      };
-    }
-  );
+  registerContractTool(server2, updateSubtaskContract, async (params) => {
+    const result = await conn2.updateSubtask(params);
+    return {
+      content: [{ type: "text", text: `Subtask ${result.id} updated (status: ${result.status})` }]
+    };
+  });
 }
 function registerListSubtasks(server2, conn2) {
-  server2.tool(
-    "list_subtasks",
-    "List all subtasks of a parent task with their status and ordering. Pass projectId to target a specific project; otherwise the configured default project is used.",
-    {
-      projectId: z8.string().optional().describe("Target Conveyor project ID"),
-      taskId: z8.string().describe("The parent task ID")
-    },
-    async (params) => {
-      const subtasks = await conn2.listSubtasks(params.taskId, params.projectId);
-      return { content: [{ type: "text", text: JSON.stringify(subtasks, null, 2) }] };
-    }
-  );
+  registerContractTool(server2, listSubtasksContract, async (params) => {
+    const subtasks = await conn2.listSubtasks(params.taskId, params.projectId);
+    return { content: [{ type: "text", text: JSON.stringify(subtasks, null, 2) }] };
+  });
 }
 function registerDeleteSubtask(server2, conn2) {
-  server2.tool(
-    "delete_subtask",
-    "Delete a subtask by ID. Pass projectId to target a specific project; otherwise the configured default project is used. This is permanent \u2014 use update_subtask to set status to Cancelled if you only want to close it.",
-    {
-      projectId: z8.string().optional().describe("Target Conveyor project ID"),
-      subtaskId: z8.string().describe("The subtask ID to delete")
-    },
-    async (params) => {
-      const result = await conn2.deleteSubtask(params.subtaskId, params.projectId);
-      return {
-        content: [
-          { type: "text", text: result.deleted ? "Subtask deleted" : "Subtask not deleted" }
-        ]
-      };
-    }
-  );
+  registerContractTool(server2, deleteSubtaskContract, async (params) => {
+    const result = await conn2.deleteSubtask(params.subtaskId, params.projectId);
+    return {
+      content: [{ type: "text", text: result.deleted ? "Subtask deleted" : "Subtask not deleted" }]
+    };
+  });
 }
 function registerSubtaskTools(server2, conn2) {
   registerCreateSubtask(server2, conn2);
@@ -1069,50 +1648,23 @@ function registerSubtaskTools(server2, conn2) {
 }
 
 // src/tools/dependencies.ts
-import { z as z9 } from "zod";
 function registerGetDependencies(server2, conn2) {
-  server2.tool(
-    "get_dependencies",
-    "Get a task's dependencies and their met/unmet status (met = merged to dev). Pass projectId to target a specific project; otherwise the configured default project is used. Use to confirm blockers merged, or see why a task cannot start. For task state use get_task.",
-    {
-      projectId: z9.string().optional().describe("Target Conveyor project ID"),
-      taskId: z9.string().describe("The task ID")
-    },
-    async (params) => {
-      const deps = await conn2.getDependencies(params.taskId, params.projectId);
-      return { content: [{ type: "text", text: JSON.stringify(deps, null, 2) }] };
-    }
-  );
+  registerContractTool(server2, getDependenciesContract, async (params) => {
+    const deps = await conn2.getDependencies(params.taskId, params.projectId);
+    return { content: [{ type: "text", text: JSON.stringify(deps, null, 2) }] };
+  });
 }
 function registerAddDependency(server2, conn2) {
-  server2.tool(
-    "add_dependency",
-    "Add a blocking dependency \u2014 this task cannot start until the named task is merged to dev. Pass projectId to target a specific project; otherwise the configured default project is used.",
-    {
-      projectId: z9.string().optional().describe("Target Conveyor project ID"),
-      taskId: z9.string().describe("The task ID that will be blocked"),
-      dependsOnSlugOrId: z9.string().describe("Slug or ID of the task this one depends on")
-    },
-    async (params) => {
-      await conn2.addDependency(params);
-      return { content: [{ type: "text", text: "Dependency added" }] };
-    }
-  );
+  registerContractTool(server2, addDependencyContract, async (params) => {
+    await conn2.addDependency(params);
+    return { content: [{ type: "text", text: "Dependency added" }] };
+  });
 }
 function registerRemoveDependency(server2, conn2) {
-  server2.tool(
-    "remove_dependency",
-    "Remove a previously added dependency from a task. Pass projectId to target a specific project; otherwise the configured default project is used. The task is no longer blocked by the named task. Returns: confirmation string.",
-    {
-      projectId: z9.string().optional().describe("Target Conveyor project ID"),
-      taskId: z9.string().describe("The task ID to unblock"),
-      dependsOnSlugOrId: z9.string().describe("Slug or ID of the dependency to remove")
-    },
-    async (params) => {
-      await conn2.removeDependency(params);
-      return { content: [{ type: "text", text: "Dependency removed" }] };
-    }
-  );
+  registerContractTool(server2, removeDependencyContract, async (params) => {
+    await conn2.removeDependency(params);
+    return { content: [{ type: "text", text: "Dependency removed" }] };
+  });
 }
 function registerDependencyTools(server2, conn2) {
   registerGetDependencies(server2, conn2);
@@ -1121,27 +1673,15 @@ function registerDependencyTools(server2, conn2) {
 }
 
 // src/tools/suggestions.ts
-import { z as z10 } from "zod";
 function registerSuggestionTools(server2, conn2) {
-  server2.tool(
-    "create_suggestion",
-    "Suggest a feature, improvement, rule, or idea for the project. Pass projectId to target a specific project; otherwise the configured default project is used. Duplicates are deduped and your upvote is recorded.",
-    {
-      projectId: z10.string().optional().describe("Target Conveyor project ID"),
-      title: z10.string().describe("Suggestion title"),
-      description: z10.string().optional().describe("Suggestion details (markdown)"),
-      tagNames: z10.array(z10.string()).optional().describe('Tag names to categorize the suggestion (e.g., ["agent-runner"])')
-    },
-    async (params) => {
-      const result = await conn2.createSuggestion(params);
-      const text = result.merged ? `Suggestion merged into existing suggestion ${result.mergedIntoId} (upvote recorded)` : `Suggestion created: ${result.id}`;
-      return { content: [{ type: "text", text }] };
-    }
-  );
+  registerContractTool(server2, createSuggestionContract, async (params) => {
+    const result = await conn2.createSuggestion(params);
+    const text = result.merged ? `Suggestion merged into existing suggestion ${result.mergedIntoId} (upvote recorded)` : `Suggestion created: ${result.id}`;
+    return { content: [{ type: "text", text }] };
+  });
 }
 
 // src/tools/checklists.ts
-import { z as z11 } from "zod";
 function renderManualTestGroups(groups) {
   const lines = [];
   for (const g of groups) {
@@ -1150,8 +1690,8 @@ function renderManualTestGroups(groups) {
       const mark = t.status === "approved" ? "\u2713" : t.status === "rejected" ? "\u2717" : "\u25CB";
       lines.push(`  ${mark} ${t.title} \u2014 ${t.status}`);
       if (t.status === "rejected") {
-        for (const f of t.failures ?? []) {
-          lines.push(`      \u26A0 ${f.userName ?? "Someone"}: ${f.reason ?? "(no message)"}`);
+        for (const f2 of t.failures ?? []) {
+          lines.push(`      \u26A0 ${f2.userName ?? "Someone"}: ${f2.reason ?? "(no message)"}`);
         }
       }
     }
@@ -1160,139 +1700,75 @@ function renderManualTestGroups(groups) {
   return lines.join("\n").trimEnd();
 }
 function registerListManualTests(server2, conn2) {
-  server2.tool(
-    "list_manual_tests",
-    "List the manual test checklist items for a task. Pass projectId to target a specific project; otherwise the configured default project is used. Use to see what manual verification steps have already been recorded.",
-    {
-      projectId: z11.string().optional().describe("Target Conveyor project ID"),
-      taskId: z11.string().describe("The task ID or slug (the value in a card URL, /cards/<slug>)")
-    },
-    async (params) => {
-      const items = await conn2.listManualTests(params.taskId, params.projectId);
-      if (items.length === 0) {
-        return { content: [{ type: "text", text: "No manual tests recorded for this task." }] };
-      }
-      const lines = items.flatMap((item, i) => {
-        const checked = item.checked ? "[x]" : "[ ]";
-        const row = [`${i + 1}. ${checked} ${item.title}`];
-        for (const f of item.failures ?? []) {
-          const who = f.userName ?? "Someone";
-          const reason = f.reason ?? "(no message)";
-          row.push(`   \u26A0 Failed (${who}): ${reason}`);
-        }
-        return row;
-      });
-      return { content: [{ type: "text", text: lines.join("\n") }] };
+  registerContractTool(server2, listManualTestsContract, async (params) => {
+    const items = await conn2.listManualTests(params.taskId, params.projectId);
+    if (items.length === 0) {
+      return { content: [{ type: "text", text: "No manual tests recorded for this task." }] };
     }
-  );
+    const lines = items.flatMap((item, i) => {
+      const checked = item.checked ? "[x]" : "[ ]";
+      const row = [`${i + 1}. ${checked} ${item.title}`];
+      for (const f2 of item.failures ?? []) {
+        const who = f2.userName ?? "Someone";
+        const reason = f2.reason ?? "(no message)";
+        row.push(`   \u26A0 Failed (${who}): ${reason}`);
+      }
+      return row;
+    });
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  });
 }
 function registerSetManualTests(server2, conn2) {
-  server2.tool(
-    "set_manual_tests",
-    "Add manual test steps to a task's checklist. Pass projectId to target a specific project; otherwise the configured default project is used. Existing items with the same title are automatically skipped (deduplication). Use to record specific manual verification steps that reviewers should follow when testing the task's PR.",
-    {
-      projectId: z11.string().optional().describe("Target Conveyor project ID"),
-      taskId: z11.string().describe("The task ID or slug"),
-      items: z11.array(z11.object({ title: z11.string().min(1).describe("A concise, actionable test step") })).min(1).describe("List of manual test steps to add")
-    },
-    async (params) => {
-      const result = await conn2.setManualTests(params.taskId, params.items, params.projectId);
-      const parts = [`Created ${result.created} manual test item(s).`];
-      if (result.skipped > 0) parts.push(`Skipped ${result.skipped} duplicate(s).`);
-      return { content: [{ type: "text", text: parts.join(" ") }] };
-    }
-  );
+  registerContractTool(server2, setManualTestsContract, async (params) => {
+    const result = await conn2.setManualTests(params.taskId, params.items, params.projectId);
+    const parts = [`Created ${result.created} manual test item(s).`];
+    if (result.skipped > 0) parts.push(`Skipped ${result.skipped} duplicate(s).`);
+    return { content: [{ type: "text", text: parts.join(" ") }] };
+  });
 }
 function registerEditManualTest(server2, conn2) {
-  server2.tool(
-    "edit_manual_test",
-    "Rename an existing manual test step on a task. Pass projectId to target a specific project; otherwise the configured default project is used. Identify the test by its current title (case-insensitive) and pass the new title to replace it.",
-    {
-      projectId: z11.string().optional().describe("Target Conveyor project ID"),
-      taskId: z11.string().describe("The task ID or slug"),
-      title: z11.string().min(1).describe("The current title of the manual test to edit"),
-      newTitle: z11.string().min(1).describe("The new title for the manual test")
-    },
-    async (params) => {
-      await conn2.editManualTest(params.taskId, params.title, params.newTitle, params.projectId);
-      return { content: [{ type: "text", text: `Updated manual test to "${params.newTitle}".` }] };
-    }
-  );
+  registerContractTool(server2, editManualTestContract, async (params) => {
+    await conn2.editManualTest(params.taskId, params.title, params.newTitle, params.projectId);
+    return { content: [{ type: "text", text: `Updated manual test to "${params.newTitle}".` }] };
+  });
 }
 function registerRemoveManualTest(server2, conn2) {
-  server2.tool(
-    "remove_manual_test",
-    "Remove an existing manual test step from a task's checklist. Pass projectId to target a specific project; otherwise the configured default project is used. Identify the test by its title (case-insensitive).",
-    {
-      projectId: z11.string().optional().describe("Target Conveyor project ID"),
-      taskId: z11.string().describe("The task ID or slug"),
-      title: z11.string().min(1).describe("The title of the manual test to remove")
-    },
-    async (params) => {
-      await conn2.removeManualTest(params.taskId, params.title, params.projectId);
-      return { content: [{ type: "text", text: `Removed manual test "${params.title}".` }] };
-    }
-  );
+  registerContractTool(server2, removeManualTestContract, async (params) => {
+    await conn2.removeManualTest(params.taskId, params.title, params.projectId);
+    return { content: [{ type: "text", text: `Removed manual test "${params.title}".` }] };
+  });
 }
 function registerApproveManualTest(server2, conn2) {
-  server2.tool(
-    "approve_manual_test",
-    "Sign off on (approve) a manual test step on a task on behalf of your authenticated user. Pass projectId to target a specific project; otherwise the configured default project is used. Identify the test by its title (case-insensitive). Use after you have verified the step passes.",
-    {
-      projectId: z11.string().optional().describe("Target Conveyor project ID"),
-      taskId: z11.string().describe("The task ID or slug"),
-      title: z11.string().min(1).describe("The title of the manual test to approve")
-    },
-    async (params) => {
-      await conn2.approveManualTest(params.taskId, params.title, params.projectId);
-      return { content: [{ type: "text", text: `Approved manual test "${params.title}".` }] };
-    }
-  );
+  registerContractTool(server2, approveManualTestContract, async (params) => {
+    await conn2.approveManualTest(params.taskId, params.title, params.projectId);
+    return { content: [{ type: "text", text: `Approved manual test "${params.title}".` }] };
+  });
 }
 function registerRejectManualTest(server2, conn2) {
-  server2.tool(
-    "reject_manual_test",
-    "Flag an issue with (reject) a manual test step on a task on behalf of your authenticated user, recording the reason. Pass projectId to target a specific project; otherwise the configured default project is used. Identify the test by its title (case-insensitive). Use when the step fails verification.",
-    {
-      projectId: z11.string().optional().describe("Target Conveyor project ID"),
-      taskId: z11.string().describe("The task ID or slug"),
-      title: z11.string().min(1).describe("The title of the manual test to reject"),
-      reason: z11.string().min(1).max(2e3).describe("Why the test failed \u2014 what went wrong, shown to the team")
-    },
-    async (params) => {
-      await conn2.rejectManualTest(params.taskId, params.title, params.reason, params.projectId);
-      return {
-        content: [
-          {
-            type: "text",
-            text: `Flagged an issue with manual test "${params.title}": ${params.reason}`
-          }
-        ]
-      };
-    }
-  );
+  registerContractTool(server2, rejectManualTestContract, async (params) => {
+    await conn2.rejectManualTest(params.taskId, params.title, params.reason, params.projectId);
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Flagged an issue with manual test "${params.title}": ${params.reason}`
+        }
+      ]
+    };
+  });
 }
 function registerQueryManualTests(server2, conn2) {
-  server2.tool(
-    "query_manual_tests",
-    "Query manual tests across many tasks in a project, grouped by task. Filter by card status (e.g. ReviewDev, ReviewLive, Complete) and/or test status (open | approved | rejected). Use to answer questions like 'show all OPEN manual tests in ReviewDev' or 'show all REJECTED manual tests in ReviewDev/ReviewLive with the failing reason'. With no filters it defaults to the needs-attention view: open+rejected tests on ReviewDev/ReviewLive cards. Pass projectId to target a specific project; otherwise the configured default project is used.",
-    {
-      projectId: z11.string().optional().describe("Target Conveyor project ID"),
-      cardStatuses: z11.array(z11.string()).optional().describe('Filter tasks by card/column status, e.g. ["ReviewDev", "ReviewLive"]'),
-      testStatuses: z11.array(z11.enum(["open", "approved", "rejected"])).optional().describe("Filter tests by status: open | approved | rejected")
-    },
-    async (params) => {
-      const groups = await conn2.queryManualTests({
-        projectId: params.projectId,
-        cardStatuses: params.cardStatuses,
-        testStatuses: params.testStatuses
-      });
-      if (groups.length === 0) {
-        return { content: [{ type: "text", text: "No manual tests match those filters." }] };
-      }
-      return { content: [{ type: "text", text: renderManualTestGroups(groups) }] };
+  registerContractTool(server2, queryManualTestsContract, async (params) => {
+    const groups = await conn2.queryManualTests({
+      projectId: params.projectId,
+      cardStatuses: params.cardStatuses,
+      testStatuses: params.testStatuses
+    });
+    if (groups.length === 0) {
+      return { content: [{ type: "text", text: "No manual tests match those filters." }] };
     }
-  );
+    return { content: [{ type: "text", text: renderManualTestGroups(groups) }] };
+  });
 }
 function registerChecklistTools(server2, conn2) {
   registerListManualTests(server2, conn2);
@@ -1305,7 +1781,7 @@ function registerChecklistTools(server2, conn2) {
 }
 
 // src/tools/workspace.ts
-import { z as z12 } from "zod";
+import { z as z7 } from "zod";
 
 // src/workspace-ssh-tunnel.ts
 import net from "net";
@@ -1425,8 +1901,8 @@ function registerAttachInfoTool(server2, conn2) {
     "workspace_attach_info",
     "Return SSH/SFTP attach metadata for a running task Claudespace, plus hosted preview URLs and configured preview ports. Optionally installs an OpenSSH public key for this attach session.",
     {
-      taskId: z12.string().describe("The task ID"),
-      sshPublicKey: z12.string().optional().describe("Optional OpenSSH public key to install into the workspace")
+      taskId: z7.string().describe("The task ID"),
+      sshPublicKey: z7.string().optional().describe("Optional OpenSSH public key to install into the workspace")
     },
     async ({ taskId, sshPublicKey }) => {
       const info = await conn2.getWorkspaceAttachInfo(taskId, sshPublicKey);
@@ -1439,7 +1915,7 @@ function registerPreviewUrlsTool(server2, conn2) {
     "workspace_preview_urls",
     "Return the hosted preview URLs and preview ports for a running task Claudespace. This mirrors the web UI preview link metadata.",
     {
-      taskId: z12.string().describe("The task ID")
+      taskId: z7.string().describe("The task ID")
     },
     async ({ taskId }) => {
       const info = await conn2.getWorkspaceAttachInfo(taskId);
@@ -1468,10 +1944,10 @@ function registerStartTunnelTool(server2, conn2, startTunnel) {
     "workspace_start_tunnel",
     "Start a local loopback tunnel through the MCP server to a running task Claudespace port. Use port 2222 for SSH/SFTP, or one of previewPorts for app access.",
     {
-      taskId: z12.string().describe("The task ID"),
-      port: z12.number().optional().describe("Remote Claudespace port. Defaults to SSH port 2222."),
-      preferredLocalPort: z12.number().optional().describe("Preferred local loopback port. If omitted, the OS chooses one."),
-      sshPublicKey: z12.string().optional().describe("Optional OpenSSH public key to install before opening the tunnel")
+      taskId: z7.string().describe("The task ID"),
+      port: z7.number().optional().describe("Remote Claudespace port. Defaults to SSH port 2222."),
+      preferredLocalPort: z7.number().optional().describe("Preferred local loopback port. If omitted, the OS chooses one."),
+      sshPublicKey: z7.string().optional().describe("Optional OpenSSH public key to install before opening the tunnel")
     },
     async ({ taskId, port, preferredLocalPort, sshPublicKey }) => {
       const info = await conn2.getWorkspaceAttachInfo(taskId, sshPublicKey);
@@ -1524,7 +2000,7 @@ function registerStopTunnelTool(server2) {
     "workspace_stop_tunnel",
     "Stop a local workspace tunnel previously opened by workspace_start_tunnel.",
     {
-      tunnelId: z12.string().describe("Tunnel id returned by workspace_start_tunnel")
+      tunnelId: z7.string().describe("Tunnel id returned by workspace_start_tunnel")
     },
     async ({ tunnelId }) => {
       const tunnel = activeTunnels.get(tunnelId);
@@ -1543,7 +2019,7 @@ function registerWorkspaceTools(server2, conn2, deps = {}) {
 }
 
 // src/tools/logs.ts
-import { z as z13 } from "zod";
+import { z as z8 } from "zod";
 var SEVERITY_ENUM = [
   "DEBUG",
   "INFO",
@@ -1678,18 +2154,18 @@ function registerGrafanaLogTool(server2, conn2) {
     "query_grafana_logs",
     "Query the project's connected Grafana (Loki) logs \u2014 the application logs shipped to Grafana Cloud/Loki, complementing query_gcp_logs (GCP infrastructure logs). Start with structured filters (env, level=error, sinceMinutes=60, services), then narrow with search; pass raw LogQL via logql only when structured filters can't express the query (it REPLACES them). The response header echoes the composed LogQL \u2014 iterate on it. Returns compact lines: '<time> <SEVERITY> [<service>] <message>'.",
     {
-      projectId: z13.string().optional().describe("Target Conveyor project ID"),
-      env: z13.enum(["prod", "dev"]).optional().describe("Configured Grafana env mapping to scope by (default prod)"),
-      sinceMinutes: z13.number().int().min(1).max(10080).optional().describe(
+      projectId: z8.string().optional().describe("Target Conveyor project ID"),
+      env: z8.enum(["prod", "dev"]).optional().describe("Configured Grafana env mapping to scope by (default prod)"),
+      sinceMinutes: z8.number().int().min(1).max(10080).optional().describe(
         "Relative time window ending now, in minutes (default 60). Ignored if startTime is set."
       ),
-      startTime: z13.string().optional().describe("ISO 8601 lower bound (overrides sinceMinutes)"),
-      endTime: z13.string().optional().describe("ISO 8601 upper bound (default now)"),
-      level: z13.enum(["debug", "info", "warn", "error", "fatal"]).optional().describe("Minimum severity, inclusive \u2014 error returns error and above"),
-      services: z13.array(z13.string()).optional().describe("Restrict to these service_name label values"),
-      search: z13.string().max(256).optional().describe("Substring line filter (exact substring, not regex)"),
-      logql: z13.string().max(2e3).optional().describe("Advanced: raw LogQL query \u2014 REPLACES env/services/level/search composition"),
-      limit: z13.number().int().min(1).max(200).optional().describe("Max entries (default 50)")
+      startTime: z8.string().optional().describe("ISO 8601 lower bound (overrides sinceMinutes)"),
+      endTime: z8.string().optional().describe("ISO 8601 upper bound (default now)"),
+      level: z8.enum(["debug", "info", "warn", "error", "fatal"]).optional().describe("Minimum severity, inclusive \u2014 error returns error and above"),
+      services: z8.array(z8.string()).optional().describe("Restrict to these service_name label values"),
+      search: z8.string().max(256).optional().describe("Substring line filter (exact substring, not regex)"),
+      logql: z8.string().max(2e3).optional().describe("Advanced: raw LogQL query \u2014 REPLACES env/services/level/search composition"),
+      limit: z8.number().int().min(1).max(200).optional().describe("Max entries (default 50)")
     },
     async (params) => {
       const text = await runQueryGrafanaLogs(conn2, params);
@@ -1702,25 +2178,25 @@ function registerLogTools(server2, conn2) {
     "query_gcp_logs",
     "Query Google Cloud Logging for a project's linked GCP environments \u2014 use this to investigate production or dev issues directly ('something broke on prod'). Envs: 'prod' and 'dev' are the project's Cloud Run apps + Cloud SQL databases (scoped by default to the resources linked in project settings); 'claudespace' is the project's GKE agent-pod namespace. Start broad (severity=ERROR, sinceMinutes=60), then narrow with services/search. Returns compact lines: '<time> <SEVERITY> [<source>] <message> | key=value \u2026' (the key=value tail is the entry's structured payload \u2014 error details, service/method, actor and entity ids). When the response ends with a pageToken line, pass that token back as pageToken for the next page. Pass projectId to target a specific project; otherwise the configured default project is used.",
     {
-      projectId: z13.string().optional().describe("Target Conveyor project ID"),
-      env: z13.enum(["prod", "dev", "claudespace"]).optional().describe("GCP environment slot to query (default prod)"),
-      sinceMinutes: z13.number().int().min(1).max(10080).optional().describe(
+      projectId: z8.string().optional().describe("Target Conveyor project ID"),
+      env: z8.enum(["prod", "dev", "claudespace"]).optional().describe("GCP environment slot to query (default prod)"),
+      sinceMinutes: z8.number().int().min(1).max(10080).optional().describe(
         "Relative time window ending now, in minutes (default 60). Ignored if startTime is set."
       ),
-      startTime: z13.string().optional().describe("ISO 8601 lower bound (overrides sinceMinutes)"),
-      endTime: z13.string().optional().describe("ISO 8601 upper bound (default now)"),
-      severity: z13.enum(SEVERITY_ENUM).optional().describe("Minimum severity, inclusive \u2014 ERROR returns ERROR and above"),
-      services: z13.array(z13.string()).optional().describe(
+      startTime: z8.string().optional().describe("ISO 8601 lower bound (overrides sinceMinutes)"),
+      endTime: z8.string().optional().describe("ISO 8601 upper bound (default now)"),
+      severity: z8.enum(SEVERITY_ENUM).optional().describe("Minimum severity, inclusive \u2014 ERROR returns ERROR and above"),
+      services: z8.array(z8.string()).optional().describe(
         "Restrict to these Cloud Run service names (prod/dev only). Defaults to all services linked in project settings."
       ),
-      sqlInstances: z13.array(z13.string()).optional().describe("Restrict to these Cloud SQL instance names (prod/dev only)"),
-      allServices: z13.boolean().optional().describe(
+      sqlInstances: z8.array(z8.string()).optional().describe("Restrict to these Cloud SQL instance names (prod/dev only)"),
+      allServices: z8.boolean().optional().describe(
         "Set true to search ALL logs in the GCP project, ignoring the linked-resource scope"
       ),
-      search: z13.string().max(256).optional().describe("Free-text search across all log fields (exact substring, not regex)"),
-      filter: z13.string().max(1e3).optional().describe("Advanced: raw Cloud Logging filter expression, ANDed with the scope"),
-      limit: z13.number().int().min(1).max(200).optional().describe("Max entries per page (default 50)"),
-      pageToken: z13.string().optional().describe("Opaque token from a previous response to fetch the next page")
+      search: z8.string().max(256).optional().describe("Free-text search across all log fields (exact substring, not regex)"),
+      filter: z8.string().max(1e3).optional().describe("Advanced: raw Cloud Logging filter expression, ANDed with the scope"),
+      limit: z8.number().int().min(1).max(200).optional().describe("Max entries per page (default 50)"),
+      pageToken: z8.string().optional().describe("Opaque token from a previous response to fetch the next page")
     },
     async (params) => {
       const text = await runQueryGcpLogs(conn2, params);