@starlove/orbit 1.1.0 → 1.1.1

package/dist/full/version.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlove/orbit",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "edition": "full",
-  "builtAt": "2026-05-26T04:59:52.730Z"
+  "builtAt": "2026-05-26T05:55:12.573Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlove/orbit",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Starscape Orbit ??? zero-dependency, pretty, human-ai-first kanban system.",
   "license": "AGPL-3.0",
   "type": "module",

package/src/core/agent.js

@@ -7,6 +7,7 @@ import {
   relationRows,
   stateByName,
   stateByRole,
+  stateById,
   ticketById,
   ticketByNumber,
   ticketByTitle,
@@ -209,8 +210,11 @@ export function completeTicket(body, ctx) {
   return getContextPack(ticket.id, ctx, 1);
 }
 
-export function getContextPack(ticketId, ctx, depth = 1) {
+export function getContextPack(ticketId, ctx, depth = 1, options = {}) {
   const { db, board, actor } = ctx;
+  const maxCharsPerField = positiveInt(options.max_chars_per_field ?? options.maxCharsPerField, 0);
+  const includeParentFull = Boolean(options.include_parent_full ?? options.includeParentFull);
+  const includeRelatedFull = Boolean(options.include_related_full ?? options.includeRelatedFull);
   const ticket = ticketById(db, ticketId);
   if (!ticket || ticket.board_id !== board.id) throw httpError(404, "ticket_not_found");
   const innerBoard = boardById(db, ticket.board_id);
@@ -233,19 +237,122 @@ export function getContextPack(ticketId, ctx, depth = 1) {
   ]);
 
   return {
-    ticket: {
+    ticket: capTicketFields({
       ...ticket,
       labels
-    },
+    }, maxCharsPerField),
     board: innerBoard,
     board_manual: boardManual(innerBoard.id, ctx),
-    parent_ticket: parentTicket ? compactTicket(parentTicket) : null,
+    parent_ticket: parentTicket ? (includeParentFull ? capTicketFields({ ...parentTicket, labels: labelsForTicket(db, parentTicket.id) }, maxCharsPerField) : compactTicket(parentTicket)) : null,
     child_tickets: childTickets.map((child) => ({
-      ...child,
+      ...capTicketFields(child, maxCharsPerField),
       child_count: childTicketsFor(db, child.id).length
     })),
-    relations,
+    relations: relations.map((relation) => ({
+      ...relation,
+      other_ticket: includeRelatedFull
+        ? capTicketFields({ ...relation.other_ticket, labels: labelsForTicket(db, relation.other_ticket.id) }, maxCharsPerField)
+        : compactTicket(relation.other_ticket)
+    })),
     blockers,
-    related_tickets: relatedTickets
+    related_tickets: relatedTickets.map((related) =>
+      includeRelatedFull ? capTicketFields({ ...related, labels: labelsForTicket(db, related.id) }, maxCharsPerField) : compactTicket(related)
+    )
+  };
+}
+
+export function getAgentDispatchPacket(ticketId, ctx, options = {}) {
+  const { db, board, actor } = ctx;
+  const maxCharsPerField = positiveInt(options.max_chars_per_field ?? options.maxCharsPerField, 4000);
+  const commentLimit = Math.min(nonNegativeInt(options.comment_limit ?? options.commentLimit, 5), 20);
+  const ticket = ticketById(db, ticketId);
+  if (!ticket || ticket.board_id !== board.id) throw httpError(404, "ticket_not_found");
+  const innerBoard = boardById(db, ticket.board_id);
+  requireBoardAccess(actor, innerBoard);
+
+  const labels = labelsForTicket(db, ticket.id).map((label) => label.name);
+  const parentTicket = ticket.parent_ticket_id ? ticketById(db, ticket.parent_ticket_id) : null;
+  const blockers = unresolvedBlockers(db, ticket.id).map(compactTicket);
+  const comments = db
+    .prepare("SELECT id, author, kind, body, created_at FROM comments WHERE ticket_id = ? ORDER BY created_at DESC LIMIT ?")
+    .all(ticket.id, commentLimit)
+    .reverse()
+    .map((comment) => ({ ...comment, body: capString(comment.body, maxCharsPerField) }));
+
+  return {
+    board: {
+      id: innerBoard.id,
+      slug: innerBoard.slug,
+      name: innerBoard.name,
+      repo_path: innerBoard.repo_path || innerBoard.system_path || "",
+      system_path: innerBoard.system_path || innerBoard.repo_path || "",
+      default_branch: innerBoard.default_branch || "main",
+      agent_instructions: capString(innerBoard.agent_instructions || "", maxCharsPerField)
+    },
+    ticket: {
+      id: ticket.id,
+      ticket_id: ticket.id,
+      number: ticket.number,
+      title: ticket.title,
+      type: ticket.type,
+      priority: ticket.priority,
+      state_id: ticket.state_id,
+      state_name: ticket.state_name,
+      state_role: ticket.state_role,
+      description: capString(ticket.description || "", maxCharsPerField),
+      acceptance: capString(extractAcceptance(ticket.description || ""), maxCharsPerField),
+      ai_plan: capString(ticket.ai_plan || "", maxCharsPerField),
+      labels
+    },
+    blockers: {
+      can_start: blockers.length === 0,
+      blockers
+    },
+    parent_ticket: parentTicket ? compactTicket(parentTicket) : null,
+    relevant_state_ids: relevantStateIds(db, innerBoard.id, ticket.state_id),
+    recent_comments: comments
+  };
+}
+
+function positiveInt(value, fallback) {
+  const n = Number(value);
+  return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+
+function nonNegativeInt(value, fallback) {
+  const n = Number(value);
+  return Number.isInteger(n) && n >= 0 ? n : fallback;
+}
+
+function capString(value, maxChars) {
+  const text = String(value || "");
+  return maxChars && text.length > maxChars ? text.slice(0, maxChars) : text;
+}
+
+function capTicketFields(ticket, maxChars) {
+  if (!maxChars) return ticket;
+  const copy = { ...ticket };
+  for (const field of ["description", "ai_plan", "implementation_summary", "implementation_updates"]) {
+    if (Object.hasOwn(copy, field)) copy[field] = capString(copy[field], maxChars);
+  }
+  return copy;
+}
+
+function extractAcceptance(description) {
+  const match = String(description || "").match(/(?:^|\n)\s*(?:acceptance criteria|acceptance)\s*:?\s*\n([\s\S]*)/i);
+  return match ? match[1].trim() : "";
+}
+
+function relevantStateIds(db, boardId, currentStateId) {
+  const byRole = (role) => stateByRole(db, boardId, role)?.id || null;
+  const byName = (name) => stateByName(db, boardId, name)?.id || null;
+  return {
+    current: currentStateId,
+    current_role: stateById(db, currentStateId)?.role || null,
+    ai_ready: byRole("ai_ready") || byName("AI Ready"),
+    in_progress: byRole("in_progress") || byName("In Progress"),
+    review: byRole("review") || byName("Review"),
+    done: byRole("done") || byName("Done"),
+    todo: byRole("todo") || byName("Todo")
   };
 }

package/src/core/board.js

@@ -134,7 +134,7 @@ export {
 export { archiveTicket, createComment, createTicket, deleteTicket, restoreTicket, updateTicket } from "./tickets.js";
 export { archivedTicketsForBoard } from "./queries.js";
 export { getTicketBlockers, getTicketRelations } from "./relations.js";
-export { checkpointTicket, claimNext, completeTicket, getContextPack, readComments, readTicket } from "./agent.js";
+export { checkpointTicket, claimNext, completeTicket, getAgentDispatchPacket, getContextPack, readComments, readTicket } from "./agent.js";
 export { searchTickets } from "./search.js";
 export { exportBoard } from "./snapshots.js";
 

package/src/core/router.js

@@ -65,6 +65,7 @@ import {
   checkpointTicket,
   claimNext,
   completeTicket,
+  getAgentDispatchPacket,
   getContextPack,
   readComments,
   readTicket
@@ -104,6 +105,15 @@ function boardHintsFromQuery(url) {
   };
 }
 
+function agentContextOptions(url) {
+  return {
+    max_chars_per_field: url.searchParams.get("max_chars_per_field"),
+    comment_limit: url.searchParams.get("comment_limit"),
+    include_parent_full: url.searchParams.get("include_parent_full") === "true",
+    include_related_full: url.searchParams.get("include_related_full") === "true"
+  };
+}
+
 export async function handleApi(req, res, url) {
   setCors(res);
 
@@ -269,7 +279,11 @@ export async function handleApi(req, res, url) {
     }
     if (sub === "context" && req.method === "GET") {
       const depth = Number(url.searchParams.get("depth") || 1);
-      sendJson(res, 200, getContextPack(ticketId, ctx, depth));
+      sendJson(res, 200, getContextPack(ticketId, ctx, depth, agentContextOptions(url)));
+      return;
+    }
+    if ((sub === "dispatch-packet" || sub === "agent-dispatch-packet") && req.method === "GET") {
+      sendJson(res, 200, getAgentDispatchPacket(ticketId, ctx, agentContextOptions(url)));
       return;
     }
     if (sub === "history" && req.method === "GET") {
@@ -399,7 +413,11 @@ export async function handleApi(req, res, url) {
     if (!row) throw httpError(400, "board_id_required");
     const args = {
       q: url.searchParams.get("q") || "",
-      limit: url.searchParams.get("limit")
+      limit: url.searchParams.get("limit"),
+      mode: url.searchParams.get("mode"),
+      include_full: url.searchParams.get("include_full") === "true" ? true : undefined,
+      fields: url.searchParams.get("fields"),
+      max_chars_per_field: url.searchParams.get("max_chars_per_field")
     };
     sendJson(res, 200, searchTickets(args, ctxFromBoardRow(row, actor)));
     return;

package/src/core/search.js

@@ -12,9 +12,12 @@ export function searchTickets(args, ctx) {
   const { db, board, actor } = ctx;
   const q = String(args.q || "").trim();
   const limit = Math.min(Number(args.limit || 20), 50);
+  const mode = normalizeMode(args);
+  const maxCharsPerField = positiveInt(args.max_chars_per_field ?? args.maxCharsPerField, 0);
+  const fields = parseFields(args.fields);
 
-  if (!q) return { query: q, results: [] };
-  if (!canAccessBoard(actor, board)) return { query: q, results: [] };
+  if (!q) return { query: q, mode, results: [] };
+  if (!canAccessBoard(actor, board)) return { query: q, mode, results: [] };
 
   const ticketNumber = ticketNumberQuery(q);
   const fts = toFtsQuery(q);
@@ -93,12 +96,82 @@ export function searchTickets(args, ctx) {
     if (deduped.length >= limit) break;
   }
 
-  const results = deduped.map((ticket) => ({
-    ...ticket,
-    labels: labelsForTicket(db, ticket.id)
-  }));
+  const results = deduped.map((ticket) =>
+    shapeSearchResult(ticket, labelsForTicket(db, ticket.id), { mode, fields, maxCharsPerField })
+  );
 
-  return { query: q, results };
+  return { query: q, mode, results };
+}
+
+function normalizeMode(args) {
+  if (args.include_full === true || args.includeFull === true) return "full";
+  const mode = String(args.mode || "summary").trim().toLowerCase();
+  return ["ids", "summary", "full"].includes(mode) ? mode : "summary";
+}
+
+function positiveInt(value, fallback) {
+  const n = Number(value);
+  return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+
+function parseFields(fields) {
+  if (Array.isArray(fields)) return new Set(fields.map(String));
+  if (typeof fields === "string" && fields.trim()) {
+    return new Set(fields.split(",").map((field) => field.trim()).filter(Boolean));
+  }
+  return null;
+}
+
+function cap(value, maxChars) {
+  if (!maxChars || typeof value !== "string") return value;
+  return value.length > maxChars ? value.slice(0, maxChars) : value;
+}
+
+function snippetFor(ticket, maxChars) {
+  const text = ticket.description || ticket.ai_plan || ticket.implementation_summary || "";
+  return cap(text, maxChars || 240);
+}
+
+function labelNames(labels) {
+  return labels.map((label) => label.name);
+}
+
+function pickFields(row, fields) {
+  if (!fields) return row;
+  const picked = {};
+  for (const field of fields) {
+    if (Object.hasOwn(row, field)) picked[field] = row[field];
+  }
+  return picked;
+}
+
+function shapeSearchResult(ticket, labels, { mode, fields, maxCharsPerField }) {
+  if (mode === "ids") {
+    return pickFields({ ticket_id: ticket.id, id: ticket.id, number: ticket.number, rank: ticket.rank }, fields);
+  }
+  if (mode === "full") {
+    const full = { ...ticket, labels };
+    if (maxCharsPerField) {
+      for (const key of ["description", "ai_plan", "implementation_summary", "implementation_updates"]) {
+        full[key] = cap(full[key], maxCharsPerField);
+      }
+    }
+    return pickFields(full, fields);
+  }
+  return pickFields({
+    ticket_id: ticket.id,
+    id: ticket.id,
+    number: ticket.number,
+    title: ticket.title,
+    state_name: ticket.state_name,
+    state_role: ticket.state_role,
+    type: ticket.type,
+    priority: ticket.priority,
+    parent_ticket_id: ticket.parent_ticket_id,
+    rank: ticket.rank,
+    snippet: snippetFor(ticket, maxCharsPerField),
+    labels: labelNames(labels)
+  }, fields);
 }
 
 function ticketNumberQuery(q) {

package/src/mcp/orbit-client.js

@@ -57,6 +57,24 @@ export function createHttpOrbitClient(env = process.env, fetchImpl = globalThis.
   }
 
   const ticketQuery = (args = {}) => ({ board_id: args.board_id, board: args.board_slug || args.board || defaultBoard });
+  const searchQuery = (args = {}) => ({
+    q: args.q,
+    limit: args.limit,
+    board_id: args.board_id,
+    board: args.board_slug || args.board || defaultBoard,
+    mode: args.mode,
+    include_full: args.include_full || args.includeFull ? "true" : undefined,
+    fields: Array.isArray(args.fields) ? args.fields.join(",") : args.fields,
+    max_chars_per_field: args.max_chars_per_field ?? args.maxCharsPerField
+  });
+  const contextQuery = (args = {}) => ({
+    ...ticketQuery(args),
+    depth: args.depth,
+    max_chars_per_field: args.max_chars_per_field ?? args.maxCharsPerField,
+    comment_limit: args.comment_limit ?? args.commentLimit,
+    include_parent_full: args.include_parent_full || args.includeParentFull ? "true" : undefined,
+    include_related_full: args.include_related_full || args.includeRelatedFull ? "true" : undefined
+  });
 
   return {
     mode: "remote",
@@ -68,7 +86,8 @@ export function createHttpOrbitClient(env = process.env, fetchImpl = globalThis.
     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 getTicketContext(args = {}) { return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}/context`, { query: { ...contextQuery(args), depth: args.depth || 1 } }); },
+    async getAgentDispatchPacket(args = {}) { return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}/dispatch-packet`, { query: contextQuery(args) }); },
     async readTicket(args = {}) {
       if (args.ticket_id) {
         return request("GET", `/api/tickets/${encodeURIComponent(args.ticket_id)}`, { query: ticketQuery(args) });
@@ -92,7 +111,7 @@ export function createHttpOrbitClient(env = process.env, fetchImpl = globalThis.
     },
     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 search(args = {}) { return request("GET", "/api/search", { query: searchQuery(args) }); },
     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] }); },
@@ -196,12 +215,13 @@ export async function createLocalOrbitClient(env = process.env) {
     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); },
+    getTicketContext: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.getContextPack(args.ticket_id, ctx, Number(args.depth || 1), args); },
+    getAgentDispatchPacket: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.getAgentDispatchPacket(args.ticket_id, ctx, args); },
+    readTicket: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.readTicket(args, ctx); },
+    readComments: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.readComments(args, ctx); },
+    getTicketRelations: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.getTicketRelations(args.ticket_id, ctx); },
+    getTicketBlockers: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.getTicketBlockers(args.ticket_id, ctx); },
+    search: (args = {}) => { const ctx = ctxFor(rowOrSession(args), actor()); return board.searchTickets(args, 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)); },

package/src/mcp-server.js

@@ -19,6 +19,7 @@ import {
   deleteTicket,
   exportBoard,
   getBoardContext,
+  getAgentDispatchPacket,
   getContextPack,
   readComments,
   readTicket,
@@ -247,13 +248,38 @@ const TOOL_DEFS = [
       type: "object",
       properties: {
         ticket_id: { type: "string" },
-        depth: { type: "integer", minimum: 1, maximum: 3 }
+        board_id: { type: "string" },
+        board_slug: { type: "string" },
+        board: { type: "string" },
+        depth: { type: "integer", minimum: 1, maximum: 3 },
+        max_chars_per_field: { type: "integer", minimum: 1 },
+        include_parent_full: { type: "boolean" },
+        include_related_full: { type: "boolean" }
       },
       required: ["ticket_id"],
       additionalProperties: false
     },
     handler: (args) => orbitClient.getTicketContext(args)
   },
+  {
+    name: "board_get_agent_dispatch_packet",
+    description:
+      "Return a lean agent dispatch packet for one ticket: board identity/instructions, capped ticket description/acceptance/AI plan, blockers, shallow parent, relevant workflow state IDs, repo path/default branch, recent capped comments, and label names. Parent/related/implementation bodies are intentionally omitted.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ticket_id: { type: "string" },
+        board_id: { type: "string" },
+        board_slug: { type: "string" },
+        board: { type: "string" },
+        max_chars_per_field: { type: "integer", minimum: 1 },
+        comment_limit: { type: "integer", minimum: 0, maximum: 20 }
+      },
+      required: ["ticket_id"],
+      additionalProperties: false
+    },
+    handler: (args) => orbitClient.getAgentDispatchPacket(args)
+  },
   {
     name: "board_read_ticket",
     description:
@@ -263,7 +289,10 @@ const TOOL_DEFS = [
       properties: {
         ticket_id: { type: "string" },
         number: { type: "integer" },
-        title: { type: "string" }
+        title: { type: "string" },
+        board_id: { type: "string" },
+        board_slug: { type: "string" },
+        board: { type: "string" }
       },
       additionalProperties: false
     },
@@ -278,7 +307,10 @@ const TOOL_DEFS = [
       properties: {
         ticket_id: { type: "string" },
         number: { type: "integer" },
-        title: { type: "string" }
+        title: { type: "string" },
+        board_id: { type: "string" },
+        board_slug: { type: "string" },
+        board: { type: "string" }
       },
       additionalProperties: false
     },
@@ -290,7 +322,10 @@ const TOOL_DEFS = [
     inputSchema: {
       type: "object",
       properties: {
-        ticket_id: { type: "string" }
+        ticket_id: { type: "string" },
+        board_id: { type: "string" },
+        board_slug: { type: "string" },
+        board: { type: "string" }
       },
       required: ["ticket_id"],
       additionalProperties: false
@@ -303,7 +338,10 @@ const TOOL_DEFS = [
     inputSchema: {
       type: "object",
       properties: {
-        ticket_id: { type: "string" }
+        ticket_id: { type: "string" },
+        board_id: { type: "string" },
+        board_slug: { type: "string" },
+        board: { type: "string" }
       },
       required: ["ticket_id"],
       additionalProperties: false
@@ -321,7 +359,11 @@ const TOOL_DEFS = [
         board: { type: "string" },
         board_slug: { type: "string" },
         board_id: { type: "string" },
-        limit: { type: "integer", minimum: 1, maximum: 50 }
+        limit: { type: "integer", minimum: 1, maximum: 50 },
+        mode: { type: "string", enum: ["ids", "summary", "full"] },
+        include_full: { type: "boolean" },
+        fields: { type: "array", items: { type: "string" } },
+        max_chars_per_field: { type: "integer", minimum: 1 }
       },
       required: ["q"],
       additionalProperties: false