@starlove/orbit 1.0.6 → 1.1.0

package/src/mcp/orbit-client.js

@@ -0,0 +1,223 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+function rpcError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+export function orbitMode(env = process.env) {
+  const mode = String(env.ORBIT_MODE || "local").trim().toLowerCase();
+  if (mode === "remote" || mode === "http") return "remote";
+  if (mode === "local" || mode === "") return "local";
+  throw rpcError(-32602, `Unsupported ORBIT_MODE: ${env.ORBIT_MODE}`);
+}
+
+export async function createOrbitClient(env = process.env) {
+  return orbitMode(env) === "remote" ? createHttpOrbitClient(env) : createLocalOrbitClient(env);
+}
+
+export function createHttpOrbitClient(env = process.env, fetchImpl = globalThis.fetch) {
+  const apiUrl = String(env.ORBIT_API_URL || "").trim().replace(/\/+$/, "");
+  const defaultBoard = String(env.ORBIT_DEFAULT_BOARD || "").trim();
+  if (!apiUrl) throw rpcError(-32602, "ORBIT_MODE=remote requires ORBIT_API_URL.");
+  if (typeof fetchImpl !== "function") throw rpcError(-32603, "ORBIT_MODE=remote requires global fetch support.");
+
+  async function request(method, path, { query = {}, body, ok = [200] } = {}) {
+    const url = new URL(`${apiUrl}${path}`);
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, String(value));
+    }
+    const response = await fetchImpl(url, {
+      method,
+      headers: body === undefined ? undefined : { "Content-Type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body)
+    });
+    let payload = null;
+    const text = await response.text();
+    if (text) {
+      try { payload = JSON.parse(text); } catch { payload = { message: text }; }
+    }
+    if (!ok.includes(response.status)) {
+      const message = payload?.message || payload?.error || `Orbit API ${method} ${url.pathname} failed with HTTP ${response.status}`;
+      throw rpcError(-32000, message);
+    }
+    return payload ?? {};
+  }
+
+  function boardArg(args = {}) {
+    return args.board_id || args.board_slug || args.board || defaultBoard;
+  }
+
+  function requireBoard(args = {}) {
+    const board = boardArg(args);
+    if (!board) throw rpcError(-32602, "Remote Orbit MCP requires board_id/board_slug/board or ORBIT_DEFAULT_BOARD.");
+    return board;
+  }
+
+  const ticketQuery = (args = {}) => ({ board_id: args.board_id, board: args.board_slug || args.board || defaultBoard });
+
+  return {
+    mode: "remote",
+    sessionLabel: apiUrl,
+    close() {},
+    async boardContext(args = {}) {
+      return request("GET", `/api/boards/${encodeURIComponent(requireBoard(args))}/context`, { query: { include_struck: args.include_struck ? "true" : undefined } });
+    },
+    async boardList() { return request("GET", "/api/boards"); },
+    async boardSetActive(args = {}) { if (!args.slug) throw rpcError(-32602, "slug is required."); env.ORBIT_DEFAULT_BOARD = String(args.slug); return { ok: true, slug: String(args.slug), mode: "remote" }; },
+    async claimNext(args = {}) { return request("POST", "/api/agent/claim-next", { body: { ...args, board: requireBoard(args) } }); },
+    async getTicketContext(args = {}) { return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}/context`, { query: { ...ticketQuery(args), depth: args.depth || 1 } }); },
+    async readTicket(args = {}) {
+      if (args.ticket_id) {
+        return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}`, { query: ticketQuery(args) });
+      }
+      if (args.number !== undefined || args.title) {
+        return request("GET", "/api/tickets/lookup", { query: { ...ticketQuery(args), number: args.number, title: args.title } });
+      }
+      throw rpcError(-32602, "ticket_id_or_number_or_title_required");
+    },
+    async readComments(args = {}) {
+      if (args.ticket_id) {
+        return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}/comments`, { query: ticketQuery(args) });
+      }
+      const found = await this.readTicket(args);
+      const ticket = found.ticket || found.results?.find((row) =>
+        (args.number !== undefined && Number(row.number) === Number(args.number)) ||
+        (args.title && String(row.title || "").toLowerCase() === String(args.title).toLowerCase())
+      );
+      if (!ticket?.id) throw rpcError(-32004, "ticket_not_found");
+      return request("GET", `/api/tickets/${encodeURIComponent(ticket.id)}/comments`, { query: ticketQuery(args) });
+    },
+    async getTicketRelations(args = {}) { return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}/relations`, { query: ticketQuery(args) }); },
+    async getTicketBlockers(args = {}) { return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}/blockers`, { query: ticketQuery(args) }); },
+    async search(args = {}) { return request("GET", "/api/search", { query: { q: args.q, limit: args.limit, board_id: args.board_id, board: args.board_slug || args.board || defaultBoard } }); },
+    async createTicket(args = {}) { return request("POST", "/api/tickets", { body: { ...args, board: requireBoard(args) }, ok: [201] }); },
+    async updateTicket({ ticket_id, ...patch }) { return request("PATCH", `/api/tickets/${encodeURIComponent(ticket_id)}`, { query: ticketQuery(patch), body: patch }); },
+    async addComment({ ticket_id, ...body }) { return request("POST", `/api/tickets/${encodeURIComponent(ticket_id)}/comments`, { body, ok: [201] }); },
+    async addBoardEntry(args = {}) { return request("POST", `/api/boards/${encodeURIComponent(requireBoard(args))}/entries`, { body: args, ok: [201] }); },
+    async checkpoint(args = {}) { return request("POST", "/api/agent/checkpoint", { body: args }); },
+    async complete(args = {}) { return request("POST", "/api/agent/complete", { body: args }); },
+    async archiveTicket(args = {}) { return request("POST", `/api/tickets/${encodeURIComponent(args.ticket_id)}/archive`, { query: ticketQuery(args) }); },
+    async restoreTicket(args = {}) { return request("POST", `/api/tickets/${encodeURIComponent(args.ticket_id)}/restore`, { query: ticketQuery(args) }); },
+    async deleteTicket(args = {}) { return request("DELETE", `/api/tickets/${encodeURIComponent(args.ticket_id)}`, { query: ticketQuery(args) }); },
+    async listArchive(args = {}) { return request("GET", `/api/boards/${encodeURIComponent(requireBoard(args))}/archive`); },
+    async exportBoard(args = {}) {
+      return request("GET", `/api/boards/${encodeURIComponent(requireBoard(args))}/export`, {
+        query: { include_attachments: args.include_attachments || args.include_images ? "true" : undefined }
+      });
+    },
+    async updateSettings(args = {}) { const { board_id, board_slug, board, ...patch } = args; return request("PATCH", `/api/boards/${encodeURIComponent(requireBoard(args))}`, { body: patch }); }
+  };
+}
+
+export async function createLocalOrbitClient(env = process.env) {
+  const board = await import("../core/board.js");
+  const dbMod = await import("../core/db.js");
+  const registry = await import("../core/registry.js");
+  const backups = await import("../core/backups.js");
+  const seed = await import("../core/seed.js");
+  const util = await import("../core/util.js");
+
+  const provision = await import("../core/provision-repo-board.js");
+  let sessionBoardRow = null;
+  const setSessionBoard = (row) => { sessionBoardRow = row; if (row) registry.touchBoardActive(row.id); };
+  const getSessionBoard = () => sessionBoardRow;
+  const walkUp = (startDir, predicate) => { let dir = startDir; while (true) { if (predicate(dir)) return dir; const parent = dirname(dir); if (parent === dir) return null; dir = parent; } };
+
+  const start = util.normalizePath(env.PROJECT_ROOT ? resolve(env.PROJECT_ROOT) : process.cwd());
+  const displayStart = resolve(env.PROJECT_ROOT ? env.PROJECT_ROOT : process.cwd());
+
+  // Find repo root (walk up for .git, fall back to start).
+  const gitRoot = walkUp(start, (dir) => existsSync(join(dir, ".git")));
+  const repoRoot = util.normalizePath(gitRoot || start);
+
+  // 1. Registry-first lookup: walk upward from start so we find boards regardless
+  //    of whether they were registered at the git root, at PROJECT_ROOT, or at any
+  //    ancestor (handles boards originally created from a subdirectory).
+  let foundByRegistry = false;
+  {
+    let dir = start;
+    while (true) {
+      const row = registry.getBoardByRepoPath(dir);
+      if (row && existsSync(row.db_path)) { setSessionBoard(row); foundByRegistry = true; break; }
+      const parent = util.normalizePath(dirname(dir));
+      if (parent === dir) break; // filesystem root
+      dir = parent;
+    }
+  }
+  if (!foundByRegistry) {
+    // 2. Legacy fallback: walk up for an existing in-repo .orbit/board.db.
+    const boardRoot = walkUp(start, (dir) => existsSync(join(dir, ".orbit", "board.db")));
+    if (boardRoot) {
+      const root = util.normalizePath(boardRoot);
+      const existing = registry.getBoardByRepoPath(root);
+      if (existing) {
+        setSessionBoard(existing);
+      } else {
+        const dbPath = join(boardRoot, ".orbit", "board.db");
+        const db = dbMod.openConnection(dbPath);
+        dbMod.createBoardSchema(db);
+        const seeded = seed.seedIfEmpty(db, root);
+        if (seeded) {
+          const t = util.now();
+          registry.insertBoard({ id: seeded.id, slug: seeded.slug, name: seeded.name, repo_path: root, db_path: dbPath, repo_url: seeded.repo_url || "", default_branch: seeded.default_branch || "main", last_active_at: t, created_at: t, updated_at: t });
+        }
+        const fresh = registry.getBoardByRepoPath(root);
+        if (fresh) { registry.syncRegistryFromBoardDb(fresh, db); setSessionBoard(fresh); }
+      }
+    } else {
+      // 3. No board found — auto-create one (goes to central DATA_DIR/boards/).
+      provision.provisionRepoBoard(repoRoot, { enableAi: true });
+      const fresh = registry.getBoardByRepoPath(repoRoot);
+      if (fresh) setSessionBoard(fresh);
+    }
+  }
+
+  const ctxFor = (row, actor) => {
+    if (!row) throw rpcError(-32602, "No board in session; pass board_id or board_slug, or call board_set_active first.");
+    return { actor, board: row, db: registry.openBoardDb(row) };
+  };
+  const sessionCtx = (actor) => ctxFor(getSessionBoard(), actor);
+  const backup = (ctx, result) => { backups.scheduleAutomaticBoardBackup(ctx.board, ctx.db); return result; };
+  const explicit = (args = {}) => args.board_id ? registry.getBoardByRegistryId(args.board_id) : (args.board_slug || args.board ? registry.getBoardBySlug(args.board_slug || args.board) : null);
+  const rowOrSession = (args = {}) => explicit(args) || getSessionBoard();
+  const actor = () => board.localAgentActor();
+
+  return {
+    mode: "local",
+    sessionLabel: () => {
+      const b = getSessionBoard();
+      return b ? `${displayStart}  target: ${b.repo_path}  db: ${b.db_path}` : "(none)";
+    },
+    close: () => dbMod.closeAllConnections(),
+    boardContext: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.getBoardContext(ctx.board.id, ctx, { includeStruck: Boolean(args.include_struck) }); },
+    boardList: () => ({ boards: registry.listBoards().map((row) => ({ id: row.id, slug: row.slug, name: row.name, repo_path: row.repo_path })) }),
+    boardSetActive: (args = {}) => { const slug = String(args.slug || "").trim(); if (!slug) throw rpcError(-32602, "slug is required."); const row = registry.getBoardBySlug(slug); if (!row) throw rpcError(-32004, `Board slug not found: ${slug}`); setSessionBoard(row); return { ok: true, board_id: row.id, slug: row.slug, name: row.name, db_path: row.db_path }; },
+    claimNext: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return backup(ctx, board.claimNext(args, ctx)); },
+    getTicketContext: (args = {}) => board.getContextPack(args.ticket_id, sessionCtx(actor()), Number(args.depth || 1)),
+    readTicket: (args = {}) => board.readTicket(args, sessionCtx(actor())),
+    readComments: (args = {}) => board.readComments(args, sessionCtx(actor())),
+    getTicketRelations: (args = {}) => board.getTicketRelations(args.ticket_id, sessionCtx(actor())),
+    getTicketBlockers: (args = {}) => board.getTicketBlockers(args.ticket_id, sessionCtx(actor())),
+    search: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.searchTickets({ q: args.q, limit: args.limit }, ctx); },
+    createTicket: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); const { board_slug, board: _b, ...body } = args; body.board_id = ctx.board.id; return backup(ctx, board.createTicket(body, ctx)); },
+    updateTicket: ({ ticket_id, ...patch }) => { const ctx = sessionCtx(actor()); return backup(ctx, board.updateTicket(ticket_id, patch, ctx)); },
+    addComment: ({ ticket_id, ...body }) => { const ctx = sessionCtx(actor()); return backup(ctx, board.createComment(ticket_id, body, ctx)); },
+    addBoardEntry: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return backup(ctx, board.createBoardEntry(ctx.board.id, args, ctx)); },
+    checkpoint: (args = {}) => { const ctx = sessionCtx(actor()); return backup(ctx, board.checkpointTicket(args, ctx)); },
+    complete: (args = {}) => { const ctx = sessionCtx(actor()); return backup(ctx, board.completeTicket(args, ctx)); },
+    archiveTicket: (args = {}) => { const ctx = sessionCtx(actor()); return backup(ctx, board.archiveTicket(args.ticket_id, ctx)); },
+    restoreTicket: (args = {}) => { const ctx = sessionCtx(actor()); return backup(ctx, board.restoreTicket(args.ticket_id, ctx)); },
+    deleteTicket: (args = {}) => { const ctx = sessionCtx(actor()); return backup(ctx, board.deleteTicket(args.ticket_id, ctx)); },
+    listArchive: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return { tickets: board.archivedTicketsForBoard(ctx.db, ctx.board.id) }; },
+    exportBoard: (args = {}) => {
+      const ctx = ctxFor(rowOrSession(args), actor());
+      return board.exportBoard(ctx.board.id, ctx, {
+        includeAttachments: Boolean(args.include_attachments || args.include_images)
+      });
+    },
+    updateSettings: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); const { board_id, board_slug, ...patch } = args; return backup(ctx, board.updateBoard(ctx.board.id, patch, ctx)); }
+  };
+}

package/src/mcp-server.js

@@ -4,6 +4,7 @@
 // the call it's about to make, so adding new tools never has to think about
 // "active board" state.
 
+import { createOrbitClient } from "./mcp/orbit-client.js";
 import { existsSync, mkdirSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import {
@@ -14,6 +15,7 @@ import {
   completeTicket,
   createBoardEntry,
   createComment,
+  createTicket,
   deleteTicket,
   exportBoard,
   getBoardContext,
@@ -28,7 +30,7 @@ import {
   updateBoard,
   updateTicket
 } from "./core/board.js";
-import { createBoardSchema, openConnection } from "./core/db.js";
+import { closeAllConnections, createBoardSchema, openConnection } from "./core/db.js";
 import {
   getBoardByRegistryId,
   getBoardBySlug,
@@ -40,6 +42,7 @@ import {
   touchBoardActive
 } from "./core/registry.js";
 import { scheduleAutomaticBoardBackup } from "./core/backups.js";
+import { provisionRepoBoard } from "./core/provision-repo-board.js";
 import { seedIfEmpty } from "./core/seed.js";
 import { now, normalizePath } from "./core/util.js";
 
@@ -48,6 +51,7 @@ const SERVER_INFO = {
   version: "0.1.0"
 };
 
+const orbitClient = await createOrbitClient();
 // Per-process session board. Set on init by walking up from cwd, mutable via
 // `board_set_active`. NEVER read by anything outside this file — every
 // downstream call receives an explicit ctx.
@@ -88,7 +92,16 @@ function walkUp(startDir, predicate) {
 function initMcpSessionBoard() {
   const start = normalizePath(process.env.PROJECT_ROOT ? resolve(process.env.PROJECT_ROOT) : process.cwd());
 
-  // 1. Walk up for an existing board db.
+  // 1. Prefer the registry row for PROJECT_ROOT (or one of its ancestors). New
+  // Orbit boards live in central DATA_DIR storage, so there may be no in-repo
+  // .orbit/board.db to discover.
+  const registeredRoot = walkUp(start, (dir) => Boolean(getBoardByRepoPath(normalizePath(dir))));
+  if (registeredRoot) {
+    setSessionBoard(getBoardByRepoPath(normalizePath(registeredRoot)));
+    return;
+  }
+
+  // 2. Walk up for an existing legacy board db.
   const boardRoot = walkUp(start, (dir) => existsSync(join(dir, ".orbit", "board.db")));
   if (boardRoot) {
     const root = normalizePath(boardRoot);
@@ -108,9 +121,10 @@ function initMcpSessionBoard() {
     return;
   }
 
-  // 2. Walk up for a git root; fall back to cwd for non-git projects.
+  // 3. Walk up for a git root; fall back to cwd for non-git projects.
   const gitRoot = walkUp(start, (dir) => existsSync(join(dir, ".git")));
-  createBoardAtRoot(normalizePath(gitRoot || start));
+  const result = provisionRepoBoard(normalizePath(gitRoot || start));
+  if (result.registryRow) setSessionBoard(result.registryRow);
 }
 
 function createBoardAtRoot(root) {
@@ -128,6 +142,7 @@ function createBoardAtRoot(root) {
 }
 
 initMcpSessionBoard();
+closeAllConnections();
 
 /** Build a ctx for the session board (or a board the tool argument selected). */
 function ctxFor(boardRow, actor) {
@@ -180,12 +195,7 @@ const TOOL_DEFS = [
       },
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      const row = resolveBoardOrSession(args);
-      const ctx = ctxFor(row, actor);
-      return getBoardContext(ctx.board.id, ctx, { includeStruck: Boolean(args.include_struck) });
-    }
+    handler: (args) => orbitClient.boardContext(args)
   },
   {
     name: "board_list",
@@ -196,16 +206,7 @@ const TOOL_DEFS = [
       properties: {},
       additionalProperties: false
     },
-    handler: () => {
-      return {
-        boards: listBoards().map((row) => ({
-          id: row.id,
-          slug: row.slug,
-          name: row.name,
-          repo_path: row.repo_path
-        }))
-      };
-    }
+    handler: () => orbitClient.boardList()
   },
   {
     name: "board_set_active",
@@ -219,14 +220,7 @@ const TOOL_DEFS = [
       required: ["slug"],
       additionalProperties: false
     },
-    handler: (args) => {
-      const slug = String(args.slug || "").trim();
-      if (!slug) throw rpcError(-32602, "slug is required.");
-      const row = getBoardBySlug(slug);
-      if (!row) throw rpcError(-32004, `Board slug not found: ${slug}`);
-      setSessionBoard(row);
-      return { ok: true, board_id: row.id, slug: row.slug, name: row.name, db_path: row.db_path };
-    }
+    handler: (args) => orbitClient.boardSetActive(args)
   },
   {
     name: "board_claim_next",
@@ -243,17 +237,12 @@ const TOOL_DEFS = [
       },
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      const row = resolveBoardOrSession(args);
-      const ctx = ctxFor(row, actor);
-      return withAutomaticBackup(ctx, claimNext(args, ctx));
-    }
+    handler: (args) => orbitClient.claimNext(args)
   },
   {
     name: "board_get_ticket_context",
     description:
-      "Read the full context pack for a ticket, including board agent_instructions (project-level agent context), relations, blockers, comments, and child cards. Heavy — prefer board_read_ticket when you only need title/description/comments.",
+      "Read the default agent context pack for a ticket, including board agent_instructions (project-level agent context), relations, blockers, implementation fields, and child cards. Ticket comments are intentionally omitted; use board_read_comments for explicit comment retrieval.",
     inputSchema: {
       type: "object",
       properties: {
@@ -263,16 +252,12 @@ const TOOL_DEFS = [
       required: ["ticket_id"],
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      const ctx = sessionCtx(actor);
-      return getContextPack(args.ticket_id, ctx, Number(args.depth || 1));
-    }
+    handler: (args) => orbitClient.getTicketContext(args)
   },
   {
     name: "board_read_ticket",
     description:
-      "Look up a ticket by ticket_id, number, or exact title (case-insensitive) on the session's active board, and return its title, description, labels, state, and full comment thread plus the board manual (agent_instructions + journal + deployment paths).",
+      "Look up a ticket by ticket_id, number, or exact title (case-insensitive) on the session's active board, and return its title, description, labels, state, and the board manual (agent_instructions + journal + deployment paths). Ticket comments are intentionally omitted; use board_read_comments for explicit comment retrieval.",
     inputSchema: {
       type: "object",
       properties: {
@@ -282,11 +267,7 @@ const TOOL_DEFS = [
       },
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      const ctx = sessionCtx(actor);
-      return readTicket(args, ctx);
-    }
+    handler: (args) => orbitClient.readTicket(args)
   },
   {
     name: "board_read_comments",
@@ -301,11 +282,7 @@ const TOOL_DEFS = [
       },
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      const ctx = sessionCtx(actor);
-      return readComments(args, ctx);
-    }
+    handler: (args) => orbitClient.readComments(args)
   },
   {
     name: "board_get_ticket_relations",
@@ -318,10 +295,7 @@ const TOOL_DEFS = [
       required: ["ticket_id"],
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      return getTicketRelations(args.ticket_id, sessionCtx(actor));
-    }
+    handler: (args) => orbitClient.getTicketRelations(args)
   },
   {
     name: "board_get_ticket_blockers",
@@ -334,10 +308,7 @@ const TOOL_DEFS = [
       required: ["ticket_id"],
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      return getTicketBlockers(args.ticket_id, sessionCtx(actor));
-    }
+    handler: (args) => orbitClient.getTicketBlockers(args)
   },
   {
     name: "board_search",
@@ -355,12 +326,33 @@ const TOOL_DEFS = [
       required: ["q"],
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      const row = resolveBoardOrSession(args);
-      const ctx = ctxFor(row, actor);
-      return searchTickets({ q: args.q, limit: args.limit }, ctx);
-    }
+    handler: (args) => orbitClient.search(args)
+  },
+  {
+    name: "board_create_ticket",
+    description:
+      "Create a new Orbit ticket/card on the active board. Use this instead of editing .orbit/board.db directly. Same operation as POST /api/tickets.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        board_id: { type: "string" },
+        board_slug: { type: "string" },
+        board: { type: "string" },
+        title: { type: "string" },
+        description: { type: "string" },
+        type: { type: "string", enum: ["epic", "feature", "task", "bug"] },
+        parent_ticket_id: { type: ["string", "null"] },
+        ai_plan: { type: "string" },
+        implementation_summary: { type: "string" },
+        implementation_updates: { type: "string" },
+        state_id: { type: "string" },
+        priority: { type: "integer" },
+        labels: { type: "array", items: { type: "string" } }
+      },
+      required: ["title"],
+      additionalProperties: false
+    },
+    handler: (args) => orbitClient.createTicket(args)
   },
   {
     name: "board_update_ticket",
@@ -384,11 +376,7 @@ const TOOL_DEFS = [
       required: ["ticket_id"],
       additionalProperties: false
     },
-    handler: ({ ticket_id, ...patch }) => {
-      const actor = localAgentActor();
-      const ctx = sessionCtx(actor);
-      return withAutomaticBackup(ctx, updateTicket(ticket_id, patch, ctx));
-    }
+    handler: ({ ticket_id, ...patch }) => orbitClient.updateTicket({ ticket_id, ...patch })
   },
   {
     name: "board_add_comment",
@@ -403,11 +391,7 @@ const TOOL_DEFS = [
       required: ["ticket_id", "body"],
       additionalProperties: false
     },
-    handler: ({ ticket_id, ...body }) => {
-      const actor = localAgentActor();
-      const ctx = sessionCtx(actor);
-      return withAutomaticBackup(ctx, createComment(ticket_id, body, ctx));
-    }
+    handler: ({ ticket_id, ...body }) => orbitClient.addComment({ ticket_id, ...body })
   },
   {
     name: "board_add_board_entry",
@@ -425,12 +409,7 @@ const TOOL_DEFS = [
       required: ["type", "title"],
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      const row = resolveBoardOrSession(args);
-      const ctx = ctxFor(row, actor);
-      return withAutomaticBackup(ctx, createBoardEntry(ctx.board.id, args, ctx));
-    }
+    handler: (args) => orbitClient.addBoardEntry(args)
   },
   {
     name: "board_checkpoint",
@@ -445,11 +424,7 @@ const TOOL_DEFS = [
       required: ["ticket_id", "message"],
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      const ctx = sessionCtx(actor);
-      return withAutomaticBackup(ctx, checkpointTicket(args, ctx));
-    }
+    handler: (args) => orbitClient.checkpoint(args)
   },
   {
     name: "board_complete",
@@ -467,11 +442,7 @@ const TOOL_DEFS = [
       required: ["ticket_id", "summary"],
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      const ctx = sessionCtx(actor);
-      return withAutomaticBackup(ctx, completeTicket(args, ctx));
-    }
+    handler: (args) => orbitClient.complete(args)
   },
   {
     name: "board_archive_ticket",
@@ -483,11 +454,7 @@ const TOOL_DEFS = [
       required: ["ticket_id"],
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      const ctx = sessionCtx(actor);
-      return withAutomaticBackup(ctx, archiveTicket(args.ticket_id, ctx));
-    }
+    handler: (args) => orbitClient.archiveTicket(args)
   },
   {
     name: "board_restore_ticket",
@@ -498,11 +465,7 @@ const TOOL_DEFS = [
       required: ["ticket_id"],
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      const ctx = sessionCtx(actor);
-      return withAutomaticBackup(ctx, restoreTicket(args.ticket_id, ctx));
-    }
+    handler: (args) => orbitClient.restoreTicket(args)
   },
   {
     name: "board_delete_ticket",
@@ -514,11 +477,7 @@ const TOOL_DEFS = [
       required: ["ticket_id"],
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      const ctx = sessionCtx(actor);
-      return withAutomaticBackup(ctx, deleteTicket(args.ticket_id, ctx));
-    }
+    handler: (args) => orbitClient.deleteTicket(args)
   },
   {
     name: "board_list_archive",
@@ -531,12 +490,7 @@ const TOOL_DEFS = [
       },
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      const row = resolveBoardOrSession(args);
-      const ctx = ctxFor(row, actor);
-      return { tickets: archivedTicketsForBoard(ctx.db, ctx.board.id) };
-    }
+    handler: (args) => orbitClient.listArchive(args)
   },
   {
     name: "board_export_board",
@@ -545,21 +499,18 @@ const TOOL_DEFS = [
       type: "object",
       properties: {
         board_id: { type: "string" },
-        board_slug: { type: "string" }
+        board_slug: { type: "string" },
+        include_attachments: { type: "boolean", description: "Embed attached image bytes in the JSON snapshot." },
+        include_images: { type: "boolean", description: "Alias for include_attachments." }
       },
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      const row = resolveBoardOrSession(args);
-      const ctx = ctxFor(row, actor);
-      return exportBoard(ctx.board.id, ctx);
-    }
+    handler: (args) => orbitClient.exportBoard(args)
   },
   {
     name: "board_update_settings",
     description:
-      "PATCH-equivalent for board settings: name, repo_url, system_path, default_branch, agent_instructions (project-level agent context), and project_notes (Notes For You). Same fields as PATCH /api/boards/:id.",
+      "PATCH-equivalent for board settings: name (display rename only; slug/canonical URLs stay unchanged), repo_url, system_path, default_branch, agent_instructions (project-level agent context), and project_notes (Notes For You).",
     inputSchema: {
       type: "object",
       properties: {
@@ -574,13 +525,7 @@ const TOOL_DEFS = [
       },
       additionalProperties: false
     },
-    handler: (args) => {
-      const actor = localAgentActor();
-      const row = resolveBoardOrSession(args);
-      const ctx = ctxFor(row, actor);
-      const { board_id, board_slug, ...patch } = args;
-      return withAutomaticBackup(ctx, updateBoard(ctx.board.id, patch, ctx));
-    }
+    handler: (args) => orbitClient.updateSettings(args)
   }
 ];
 
@@ -588,13 +533,21 @@ const tools = new Map(TOOL_DEFS.map((tool) => [tool.name, tool]));
 
 let inputBuffer = Buffer.alloc(0);
 let expectedBodyLength = -1;
+let shuttingDown = false;
+
+function shutdown(code = 0) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  orbitClient.close?.();
+  process.exit(code);
+}
 
 process.stdin.on("data", (chunk) => {
   inputBuffer = Buffer.concat([inputBuffer, chunk]);
   drainInput();
 });
 
-process.stdin.on("end", () => process.exit(0));
+process.stdin.on("end", () => shutdown(0));
 process.stdin.resume();
 
 function drainInput() {
@@ -673,6 +626,8 @@ async function handleMessage(body, transport = "content-length") {
     }, transport);
   } catch (error) {
     writeMessage(errorResponse(message.id, error.code || -32000, error.message || "Internal error."), transport);
+  } finally {
+    orbitClient.close?.();
   }
 }
 
@@ -768,6 +723,11 @@ process.on("unhandledRejection", (error) => {
   writeMessage(errorResponse(null, -32000, error?.message || "Unhandled rejection."));
 });
 
+process.once("SIGINT", () => shutdown(0));
+process.once("SIGTERM", () => shutdown(0));
+process.once("exit", () => orbitClient.close?.());
+
 if (process.env.MAB_MCP_STDERR_LOG === "1") {
-  console.error(`Starscape Orbit MCP ready. Session board: ${getSessionBoard()?.db_path || "(none)"}`);
+  const target = typeof orbitClient.sessionLabel === "function" ? orbitClient.sessionLabel() : orbitClient.sessionLabel;
+  console.error(`Starscape Orbit MCP ready. Mode: ${orbitClient.mode}. Target: ${target}`);
 }