@orboto/mcp 0.192.0 → 0.194.0

package/dist/tools/update-project.js

@@ -2,32 +2,12 @@
  * ORB-885 - `orboto_update_project`.
  * ORB-830 - `orboto_create_project` + `orboto_archive_project`.
  *
- * Project-CRUD write surface for the MCP. The read half
- * (`orboto_list_projects`, `orboto_get_project`) shipped in ORB-244
- * Phase B; ORB-885 added `update_project`, ORB-830 closes the gap
- * with create + archive so an agent never has to drop to a raw
- * `POST /projects` to spin up a new project.
- *
- * Status mutation is allowed in `update_project` (unlike
- * `orboto_update_milestone`, which delegates closing to a dedicated
- * tool) because project status is a four-state lifecycle (`draft` →
- * `active` → `archived` / `closed`) with no extra semantics - a
- * single patch field covers it cleanly. `archive_project` is a
- * thin convenience over `update_project({ status: 'archived' })`
- * because "archive this project" is a workflow agents reach for
- * often enough that an explicit verb beats teaching the model the
- * patch shape.
+ * @see ORB-244
  */
 import { z } from 'zod';
 import { resolveProjectByKey } from './shared.js';
-// Mirrors the Zod schema on `PATCH /projects/:id` (see
-// apps/api/src/routes/projects.ts). Kept in sync manually - there's no
-// generator from the API's runtime schema into the MCP package yet.
 const PROJECT_KEY_RE = /^[A-Z0-9]+$/;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-// ORB-993/ORB-994 - the 18 detector-supported workspace/project locales.
-// Mirrors WORKSPACE_LOCALE_CODES in @orboto/shared-schema (kept in sync
-// manually, same as the rest of this tool's schema).
 const LOCALE_CODES = ['en', 'de', 'fr', 'es', 'it', 'nl', 'pt', 'ru', 'pl', 'tr', 'cs', 'da', 'sv', 'no', 'fi', 'ja', 'zh', 'ko'];
 export const updateProjectToolConfig = {
     title: 'Update a project\'s metadata',
@@ -70,9 +50,6 @@ export function makeUpdateProjectHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_create_project - ORB-830
-// ---------------------------------------------------------------------------
 export const createProjectToolConfig = {
     title: 'Create a new project',
     description: 'Create a new project in the workspace. `name` is required; `key` is optional and the API auto-derives one from the name when omitted (uppercase initials). Returns the new project\'s id + key + status (`active` by default). Caller must have `admin:project:create` or be a super-admin. Note: a new project is auto-provisioned with a general doc space (slug `<key>-general`, system-generated, for the AI primer + notes) - don\'t create a separate doc space for its docs, reuse that one (orboto_list_doc_spaces).',
@@ -116,9 +93,6 @@ export function makeCreateProjectHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_archive_project - ORB-830
-// ---------------------------------------------------------------------------
 export const archiveProjectToolConfig = {
     title: 'Archive a project',
     description: 'Archive a project - moves it out of the active rotation without deleting any data. Convenience wrapper around `orboto_update_project({ status: "archived" })` because "archive this project" is a workflow operators hit often. Archiving is reversible: pass the same project back through `orboto_update_project({ status: "active" })` to restore. Idempotent - re-archiving an already-archived project is a no-op success.',

package/dist/tools/update-project.test.js

@@ -152,7 +152,7 @@ describe('orboto_archive_project', () => {
             { json: { ...PROJ, status: 'archived' } },
         ]);
         const res = await makeArchiveProjectHandler(client)({ projectKey: 'ACME' });
-        expect(calls).toHaveLength(1); // only the resolve, no PATCH
+        expect(calls).toHaveLength(1);
         expect(res.content[0].text).toMatch(/already archived/);
         expect(res.structuredContent).toMatchObject({ alreadyArchived: true });
     });

package/dist/tools/wiki.js

@@ -11,7 +11,6 @@ import { resolveDocId } from './docs.js';
 function text(t, structured) {
     return { content: [{ type: 'text', text: t }], ...(structured ? { structuredContent: structured } : {}) };
 }
-// --- orboto_wiki_ingest_url ------------------------------------------------
 export const wikiIngestUrlToolConfig = {
     title: 'Ingest a URL into an LLM-Wiki space',
     description: 'Fetch a public URL, extract its main article as Markdown, and create a SOURCE doc in the space. When the space has the LLM-Wiki enabled, this also enqueues the auto-ingest worker, which curates the source into wiki pages (immediately under auto-apply, or as a pending plan under review-gate). Wraps POST /spaces/:id/docs/ingest-url.',
@@ -31,7 +30,6 @@ export function makeWikiIngestUrlHandler(client) {
         return text(`Ingested source "${res.title}" (docId: ${res.docId}). If the space is LLM-Wiki-enabled the curation worker is now processing it.`, { docId: res.docId, title: res.title });
     };
 }
-// --- orboto_wiki_ask -------------------------------------------------------
 export const wikiAskToolConfig = {
     title: 'Ask a question over the wiki (RAG with citations)',
     description: 'Retrieval-augmented Q&A over the docs corpus, optionally scoped to one space. Returns an answer with numbered citations linking back to source docs. Requires both a chat AND an embedding provider (check orboto_ai_status). Wraps POST /ai/ask-docs.',
@@ -54,7 +52,6 @@ export function makeWikiAskHandler(client) {
         return text(`${res.answer}\n\n${cites ? `Sources:\n${cites}` : ''}`.trim(), { answer: res.answer, citations: res.citations, mode: res.mode });
     };
 }
-// --- orboto_wiki_lint ------------------------------------------------------
 export const wikiLintToolConfig = {
     title: 'Run the LLM-Wiki lint pass on a space',
     description: 'Scan an LLM-Wiki space for inconsistencies (orphan pages, missing cross-references, stale pages, unprocessed sources, and - when AI is configured - contradictions and undocumented concepts). Returns the open issues, each with a suggested fix. Wraps POST /spaces/:id/llm-wiki/lint.',
@@ -72,7 +69,6 @@ export function makeWikiLintHandler(client) {
         return text(`Lint complete: ${res.issues.length} open issue(s), ${res.resolved} auto-resolved.\n${lines.join('\n')}`, { issues: res.issues, detected: res.detected, resolved: res.resolved });
     };
 }
-// --- orboto_wiki_plan_update / apply_plan ----------------------------------
 export const wikiPlanUpdateToolConfig = {
     title: 'Plan a wiki edit (dry-run, no writes)',
     description: 'Turn a natural-language instruction into a concrete set of page operations (create / patch / append) WITHOUT writing anything. Returns a planId valid for 15 minutes plus the proposed ops. Review the ops, then call orboto_wiki_apply_plan to commit. Wraps POST /spaces/:id/docs/plan-update.',
@@ -108,7 +104,6 @@ export function makeWikiApplyPlanHandler(client) {
         return text(`Applied plan ${input.planId}: ${res.touchedDocs.length} page(s) updated.`, { touchedDocs: res.touchedDocs });
     };
 }
-// --- orboto_wiki_record (convenience: plan + apply) ------------------------
 export const wikiRecordToolConfig = {
     title: 'Record a wiki update in one step (plan + apply)',
     description: 'Convenience wrapper that plans an edit from your instruction and immediately applies it - use mid-task to capture a fact or update a page without the two-step review loop. Internally calls plan-update then apply-plan. For a reviewable change, use orboto_wiki_plan_update instead.',
@@ -129,7 +124,6 @@ export function makeWikiRecordHandler(client) {
         return text(`Recorded: ${applied.touchedDocs.length} page(s) updated.`, { planId: plan.planId, touchedDocs: applied.touchedDocs });
     };
 }
-// --- orboto_wiki_append_section -------------------------------------------
 export const wikiAppendSectionToolConfig = {
     title: 'Append a section to a wiki page (idempotent)',
     description: 'Append a Markdown section to a doc. Idempotent: appending identical content a second time is a no-op, so this is safe to call repeatedly (e.g. across multiple ingests). Wraps POST /docs/:id/append-section.',
@@ -146,7 +140,6 @@ export function makeWikiAppendSectionHandler(client) {
         return text(res.appended ? 'Section appended.' : 'No change - an identical section is already present.', { appended: res.appended });
     };
 }
-// --- orboto_wiki_save_answer -----------------------------------------------
 export const wikiSaveAnswerToolConfig = {
     title: 'Save a Q&A answer as a wiki page',
     description: 'Turn an answer (e.g. from orboto_wiki_ask) into a curated wiki page with smart-links to its citations. Idempotent per (space, question): re-saving the same question updates the page instead of duplicating it. Wraps POST /ai/save-answer-to-wiki.',
@@ -166,7 +159,6 @@ export function makeWikiSaveAnswerHandler(client) {
         return text(res.created ? `Saved as a new wiki page (docId: ${res.docId}).` : `Updated the existing wiki page (docId: ${res.docId}).`, { docId: res.docId, created: res.created });
     };
 }
-// --- orboto_wiki_flag_stale ------------------------------------------------
 export const wikiFlagStaleToolConfig = {
     title: 'Flag (or unflag) a wiki page as possibly outdated',
     description: 'Set or clear the "may be outdated" flag on a page. The flag surfaces passively as a pill in the UI; it does not change the content. Pass stale=false to clear. Wraps POST /docs/:id/flag-stale.',

package/dist/tools/work-next.js

@@ -46,7 +46,6 @@ export const workNextToolConfig = {
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
 export function makeWorkNextHandler(client) {
-    // Per-connection rules-hash cache, same pattern as orboto_work_start.
     let lastKnownRulesHash;
     return async (args, extra) => {
         const token = mcpInstanceToken(args.agentSessionToken, extra);
@@ -64,7 +63,6 @@ export function makeWorkNextHandler(client) {
         });
         validateNextWorkEnvelope(res, args.peek);
         if (!res.reserved) {
-            // ORB-1930 - a peek that found work: name it, reserve nothing.
             if (args.peek && res.candidate) {
                 const c = res.candidate;
                 return {
@@ -85,8 +83,6 @@ export function makeWorkNextHandler(client) {
                     },
                 };
             }
-            // ORB-1774 - a pause is an operator decision, not a backoff situation:
-            // tell the agent to idle, not to poll for a free slot.
             if (res.reason === 'autonomy_paused') {
                 return {
                     content: [{
@@ -164,7 +160,6 @@ export function makeWorkNextHandler(client) {
                 }
             }
         }
-        // ORB-1614 - see the comment on the other fmtDeps above.
         const fmtDeps = (edges) => edges.length === 0 ? '(none)' : edges.map((e) => `- [${e.ticketKey ?? '?'}] ${e.title ?? `External dependency (access restricted)${e.resolved ? ' - resolved' : ' - still open'}`}${e.statusName ? ` - ${e.statusName}` : ''}`).join('\n');
         lines.push('', '## Dependencies');
         lines.push('Blocked by:', fmtDeps(r.dependencies.blockedBy), 'Blocks:', fmtDeps(r.dependencies.blocks));

package/dist/tools/work-sessions-start.test.js

@@ -89,8 +89,6 @@ describe('orboto_work_start', () => {
         expect(post.method).toBe('POST');
         expect(post.url).toContain('/work-sessions/start');
         expect(post.body?.ticketId).toBe('t1');
-        // The instance token must be sent unprompted, same contract as
-        // orboto_work_session_start.
         expect(String(post.body?.agentSessionToken)).toMatch(/^mcp-/);
         const text = res.content[0].text;
         expect(text).toContain('Started a implementation work session on ACME-42');

package/dist/tools/work-sessions.js

@@ -1,19 +1,5 @@
 /**
  * ORB-1609 - work-session tools.
- *
- * A work session is the transactional record behind "I am working on
- * this ticket": it holds the lease, owns the timer, drives presence,
- * and carries the finish-time evidence (commit + verification). It is
- * the primitive `orboto work start / finish / next` (wave 3) is built
- * on, and it is what makes ownership visible ACROSS accounts - a lease
- * held by another team's bot is a 409 with the holder attached, not an
- * invisible collision discovered at push time.
- *
- * The three roles that are not `implementation` deliberately do NOT
- * reassign the ticket or move its status: a review / preflight /
- * integration session attaches to a ticket without pretending to own
- * its delivery. That is what makes one-ticket-one-commit workable for
- * work that produces no commit of its own.
  */
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
@@ -44,12 +30,6 @@ function describe(s) {
     const who = s.userFullName ?? s.userEmail ?? 'unknown';
     return `  - ${key} [${s.role}] ${who} - lease until ${s.leaseUntil}${s.commitSha ? ` (commit ${s.commitSha.slice(0, 8)})` : ''}`;
 }
-// ---------------------------------------------------------------------------
-// orboto_work_start - ORB-1611
-// ---------------------------------------------------------------------------
-// Mirrors apps/mcp/src/tools/session-start.ts's local shapes - kept
-// duplicated rather than imported, same choice that file already made for
-// its own bundle types (no shared MCP-side schema layer for these).
 export const workStartToolConfig = {
     title: 'Start a work session and load the full context bundle',
     description: 'ORB-1611 - the one-call ticket pickup. Acquires the (ticket, role) work lease with the exact same guarantees as orboto_work_session_start (exactly ONE active session per ticket+role workspace-wide, a conflict names the holder, resourceClaims apply atomically with the lease), AND in the SAME response returns the rules-hash ack (same semantics as orboto_session_start), the project primer, the ticket enriched with its description/status/priority, its checklists, its dependencies, that project\'s git connection health, and any other live sessions already on the ticket. This replaces the 8-15 separate calls (orboto_session_start, orboto_get_project_primer, orboto_get_ticket, orboto_get_checklists, orboto_list_ticket_dependencies, ...) a normal ticket pickup used to cost. Prefer this over orboto_work_session_start for picking up a ticket; use the plain tool only when you deliberately do not want the bundle (e.g. a mid-task lease renewal where you already have fresh context). A conflict never leaves a partial session behind - same rollback-on-conflict guarantee as orboto_work_session_start.',
@@ -70,12 +50,9 @@ export const workStartToolConfig = {
         onConflict: z.enum(['reject', 'queue']).optional()
             .describe('Only matters when `resourceClaims` is set. Default `reject`.'),
     }).shape,
-    // takeover=true cancels another holder; hints describe the worst allowed call.
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };
 export function makeWorkStartHandler(client) {
-    // Per-connection rules-hash cache, mirrored from session-start.ts's
-    // makeSessionStartHandler - this closure lives for one MCP connection.
     let lastKnownRulesHash;
     return async (args, extra) => {
         const token = mcpInstanceToken(args.agentSessionToken, extra);
@@ -141,9 +118,6 @@ export function makeWorkStartHandler(client) {
                     }
                 }
             }
-            // ORB-1614 - a cross-project blocker/dependent the caller cannot read
-            // comes back with `title: null` - render a fixed placeholder instead
-            // of the literal "null".
             const fmtDeps = (edges) => edges.length === 0 ? '(none)' : edges.map((e) => `- [${e.ticketKey ?? '?'}] ${e.title ?? `External dependency (access restricted)${e.resolved ? ' - resolved' : ' - still open'}`}${e.statusName ? ` - ${e.statusName}` : ''}`).join('\n');
             lines.push('', '## Dependencies');
             lines.push('Blocked by:', fmtDeps(res.dependencies.blockedBy), 'Blocks:', fmtDeps(res.dependencies.blocks));
@@ -216,9 +190,6 @@ export function makeWorkStartHandler(client) {
         }
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_work_session_start
-// ---------------------------------------------------------------------------
 export const workSessionStartToolConfig = {
     title: 'Start (or renew) a work session on a ticket',
     description: 'Take the work lease on a ticket in a given role and start its timer. This is the coordination primitive: exactly ONE active session per (ticket, role) exists workspace-wide, so a second agent attempting the same role gets a conflict naming the current holder instead of silently colliding. Re-calling with the same agent instance renews your own lease and is a no-op otherwise - safe to call defensively. Roles other than `implementation` (review / preflight / integration) attach to the ticket WITHOUT reassigning it or moving its status, so a reviewing agent no longer has to fake a claim. The lease expires on its own (default 15 min, renewed automatically by your subsequent calls), so a crashed agent never wedges a ticket. Pass `takeover: true` only when you have decided to displace the current holder - their session is closed and their time booked, and the takeover is visible in history.',
@@ -239,7 +210,6 @@ export const workSessionStartToolConfig = {
         onConflict: z.enum(['reject', 'queue']).optional()
             .describe('Only matters when `resourceClaims` is set. Default `reject`: a conflicting write claim fails the WHOLE call with the conflicting holder(s) named - if this call would have created a brand-new session, that session is rolled back rather than left holding the lease without its claims. `queue`: the conflicting claim is accepted as `state: "waiting"` instead of failing; it is promoted automatically once the conflict clears (release, finish, or the next orboto_work_sessions read).'),
     }).shape,
-    // The optional takeover can displace someone else's active session.
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };
 export function makeWorkSessionStartHandler(client) {
@@ -280,8 +250,6 @@ export function makeWorkSessionStartHandler(client) {
             if (err instanceof OrbotoApiError && err.status === 409) {
                 const claimConflicts = parseClaimConflicts(err);
                 if (claimConflicts && claimConflicts.length > 0) {
-                    // ORB-1610 - a resourceClaims conflict, distinct from the lease
-                    // conflict below: the body carries `claimConflicts`, not `holder`.
                     return {
                         content: [{
                                 type: 'text',
@@ -293,10 +261,6 @@ export function makeWorkSessionStartHandler(client) {
                         isError: true,
                     };
                 }
-                // OrbotoApiError carries the raw body string; the 409 payload is the
-                // standard i18n error triple plus `holder`, which is the whole point
-                // of the conflict response - the caller must not need a second call
-                // to learn who has the ticket.
                 let holder;
                 try {
                     holder = JSON.parse(err.body).holder;
@@ -321,9 +285,6 @@ export function makeWorkSessionStartHandler(client) {
         }
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_work_session_finish
-// ---------------------------------------------------------------------------
 export const workSessionFinishToolConfig = {
     title: 'Finish a work session (books time, frees the lease)',
     description: 'End a work session: its timer is stopped and booked, the (ticket, role) lease is released for the next agent, and the evidence you pass (commit sha + which gates you ran) is recorded on the session. Idempotent - finishing an already-finished session succeeds and still absorbs late evidence, so a retrying harness never has to distinguish "already done" from "failed". This does NOT close the ticket; ticket status is a separate, deliberate decision (use orboto_close_ticket once the acceptance criteria are verified). Prefer orboto_work_finish (ORB-1612) for an `implementation` session that is actually done - it does this AND the ticket transition AND the completion note in one call.',
@@ -414,9 +375,6 @@ export function makeWorkFinishHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_work_sessions
-// ---------------------------------------------------------------------------
 export const workSessionsToolConfig = {
     title: 'List live work sessions (who is working on what)',
     description: 'The coordination view: every live work lease you can see, or the sessions on one ticket. Call this BEFORE picking up work in a fleet - a ticket with a live `implementation` lease is already being worked, and starting on it anyway is how two agents produce conflicting commits. Unlike agent presence (which reports who is online), this reports who OWNS what, across accounts.',
@@ -451,9 +409,6 @@ export function makeWorkSessionsHandler(client) {
         return { content: [{ type: 'text', text }], structuredContent: { sessions: rows } };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_work_session_claims_add
-// ---------------------------------------------------------------------------
 export const workSessionClaimsAddToolConfig = {
     title: 'Add resource claims to a live work session',
     description: 'ORB-1610 - declare more resource claims on a session you already hold (from orboto_work_session_start), without touching the ticket lease or timer. Use this when you did not know the files/resources you would touch at start time, or need to widen scope mid-task. Same conflict rule as start: `write` claims conflict with any OVERLAPPING active write claim workspace-wide; `read` claims never conflict. Default `onConflict: "reject"` fails the WHOLE call (nothing is added) and names every conflicting holder; `queue` accepts the conflicting ones as `state: "waiting"`.',
@@ -499,9 +454,6 @@ export function makeWorkSessionClaimsAddHandler(client) {
         }
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_work_session_claims_release
-// ---------------------------------------------------------------------------
 export const workSessionClaimsReleaseToolConfig = {
     title: 'Release resource claims from a live work session',
     description: 'ORB-1610 - drop specific resource claims (or all of them) from a session you hold, WITHOUT finishing the session or touching the ticket lease/timer. Releasing a granted write claim immediately runs a grant pass, so the earliest queued waiter for that resource is promoted as part of this call - useful once you know you are done touching a subtree but are not done with the ticket. Omit `claims` to release everything the session holds.',

package/dist/tools/work-sessions.test.js

@@ -58,8 +58,6 @@ describe('orboto_work_session_start', () => {
         expect(post.method).toBe('POST');
         expect(post.url).toContain('/work-sessions');
         expect(post.body?.ticketId).toBe('t1');
-        // The instance token must be sent unprompted - without it the lease has
-        // no owner to renew against.
         expect(String(post.body?.agentSessionToken)).toMatch(/^mcp-/);
         const text = res.content[0].text;
         expect(text).toContain('Started a implementation work session on ACME-42');
@@ -112,7 +110,6 @@ describe('orboto_work_session_start', () => {
         });
         const post = calls[calls.length - 1];
         expect(post.body).toMatchObject({ role: 'review', leaseSeconds: 3600, takeover: true });
-        // A review session attaches without booking time by default.
         expect(res.content[0].text).toContain('No timer started for this role.');
     });
 });
@@ -350,8 +347,6 @@ describe('ORB-1610 - orboto_work_session_claims_release', () => {
     it('releases everything when claims is omitted, and still sends a body', async () => {
         const calls = stub([{ text: JSON.stringify({ ...SESSION, resourceClaims: [] }) }]);
         const res = await makeWorkSessionClaimsReleaseHandler(client)({ sessionId: 'ws1' });
-        // A DELETE with a genuinely absent body 400s on the API's schema
-        // (ORB-1610 finding) - the handler must always send at least `{}`.
         expect(calls[0].body).toEqual({});
         expect(res.content[0].text).toContain('Released every claim');
     });

package/dist/toolset.js

@@ -2,100 +2,33 @@
  * ORB-1520 - manifest triage for the Code-Mode escape hatch (epic
  * ORB-1517).
  *
- * Eager-loading MCP clients (Codex, Cursor, Claude Desktop) pull EVERY
- * tool schema at connect time - with ~190 named tools that is tens of
- * thousands of tokens before the user says a word. The default manifest
- * is therefore the CURATED set below; the long tail stays fully
- * reachable through `orboto_api_search` + `orboto_api_call`, and the
- * complete named manifest is one opt-in away - and since ORB-1805 a
- * SMALLER one is too, for local models with an 8k/16k window:
- *
- *   stdio: ORBOTO_MCP_TOOLSET=minimal | curated | full
- *   http:  .../mcp?toolset=minimal  (or header x-orboto-toolset: full;
- *          the query param rides on every request, so no session
- *          persistence is involved)
- *
- * KEEP-LIST BASIS - measured, not guessed (ORB-1520): 30-day
- * `mcp_call_log` distribution on the core instance, 2026-08-10, 15.5k
- * calls total. Every tool with a meaningful call volume is in; the two
- * additions beyond the data are `orboto_my_tickets` (the natural "what
- * am I working on" entry for interactive desktop clients - the exact
- * audience this manifest serves; agent-dominated prod traffic
- * under-counts it) and the escape-hatch pair itself. The numbers live
- * in the ORB-1520 ticket comment.
- *
- * Tail tools are NOT deleted: their code, tests, chat mirrors and
- * drift-guard entries are untouched - only their REGISTRATION is
- * skipped in curated mode (the chat-tools parity guard reads server.ts
- * SOURCE, so it keeps covering the whole set in both modes).
+ * @see ORB-1805
  */
 /**
  * ORB-1805 - the small-context tier.
  *
- * Measured 2026-09-01: the CURATED manifest alone costs ~9.4k tokens of
- * tool schemas plus ~1k of instructions, so an 8k local model (LM Studio
- * / Ollama defaults) dies before the first user turn:
- * `n_keep: 13533 >= n_ctx: 8192`. `minimal` is the daily loop and
- * nothing else - orient, find, read, write, claim, close, track time -
- * plus the escape-hatch pair, which keeps the ENTIRE REST API reachable
- * from 12 tools.
- *
- * The pair is `claim` + `close_ticket` because that is the loop the
- * skill's own workflow mandates (SKILL.md "Claim = assign + status +
- * timer; stop the timer the moment you finish"), not
- * `work_next`/`work_finish` (those are not even in the curated set).
- *
- * Deliberately OUT, and why the loop still holds without them:
- * - `orboto_whoami` - measured at 357 tokens, 12 % of the whole budget,
- *   for data `orboto_session_start` already prints ("You are <name>
- *   (<email>)." + the workspace write language). The mandated first call
- *   covers it; a second identity tool does not earn a tier this small.
- * - `orboto_check_similar` - `orboto_create_ticket` enforces the
- *   duplicate block server-side (ORB-1471), so the mandated pre-create
- *   check still happens, just inside the create.
- * - `orboto_my_tickets` / `orboto_list_tickets` - `orboto_session_start`
- *   already returns the caller's in-progress work, and `orboto_search`
- *   covers "anything about X".
- * - `orboto_move_ticket` - claim moves to in_progress and close moves to
- *   done; any other transition goes through `orboto_api_call`.
- * - `orboto_help` / `orboto_response_expand` - both are recovery paths
- *   for large payloads, which is the opposite of this tier's problem.
- *
- * MUST stay a subset of CURATED_TOOLS (asserted in toolset.test.ts): a
- * name that is not registered in curated cannot be registered here
- * either, and the tier ordering minimal < curated < full is what the
- * docs promise.
+ * @see ORB-1471
  */
 export const MINIMAL_TOOLS = new Set([
-    // Orient (session_start also reports who you are + the write language)
     'orboto_session_start',
-    // Find + read
     'orboto_search',
     'orboto_get_ticket',
-    // Write
     'orboto_create_ticket',
     'orboto_update_ticket',
     'orboto_comment',
-    // The claim -> close loop + its timer
     'orboto_claim',
     'orboto_close_ticket',
     'orboto_timer_start',
     'orboto_timer_stop',
-    // Everything else, on demand (ORB-1959 measured orboto_messages at ~3k
-    // chars - a fifth of this tier's whole window - so the inbox stays in
-    // curated, where the default connection lives; minimal is the explicit
-    // small-model opt-in and reaches the inbox through orboto_api_call).
     'orboto_api_search',
     'orboto_api_call',
 ]);
 /** Order matches the measured 30d call counts (see ticket comment). */
 export const CURATED_TOOLS = new Set([
-    // Session + identity + orientation
     'orboto_session_start', // 662 calls/30d, and the binding-rules bootstrap
     'orboto_whoami', // 28
     'orboto_get_project_primer', // 131
     'orboto_list_projects', // 27, referenced by the server instructions
-    // Reads
     'orboto_get_ticket', // 1764
     'orboto_list_tickets', // 161
     'orboto_my_tickets', // interactive-client staple (see header)
@@ -103,7 +36,6 @@ export const CURATED_TOOLS = new Set([
     'orboto_query', // 26 - the OQL surface, prior art of this pattern
     'orboto_check_similar', // 258 - mandated pre-create dup check
     'orboto_get_doc', // 86
-    // Ticket writes (the strict claim->commit->close loop)
     'orboto_create_ticket', // 2069
     'orboto_bulk_create_tickets', // ORB-1694 - 48 measured runs of consecutive creates
     'orboto_bulk_add_ticket_dependencies', // ORB-1694 - longest dependency run: 27 calls
@@ -116,26 +48,15 @@ export const CURATED_TOOLS = new Set([
     'orboto_add_ticket_dependency', // 314 - the mandated blocker primitive
     'orboto_check', // 103 - acceptance-criteria checklists
     'orboto_create_milestone', // 42 - "milestone FIRST" rule for big features
-    // Time tracking (the timer rules)
     'orboto_timer_start', // 34
     'orboto_timer_stop', // 772
     'orboto_log_time', // 130
     'orboto_get_timer', // 43
-    // ORB-1959 - agent coordination on the DEFAULT connection. Without
-    // these four an agent on curated could neither receive nor acknowledge
-    // mail (broadcasts included, they land in the inbox since ORB-1959),
-    // announce itself (heartbeat / presence) nor reach another agent - the
-    // workspace rules demand exactly that, and every fresh `mcp add` forgot
-    // the ?toolset=full workaround. Four small schemas; measured cost in
-    // manifest-size.test.ts.
     'orboto_messages',
     'orboto_agent_notify',
     'orboto_agent_broadcast',
     'orboto_agent_heartbeat',
-    // Transport plumbing + the escape hatch itself
     'orboto_response_expand',
-    // ORB-1741 - the way back from one-line manifest summaries: full
-    // guidance on demand. Must ride every manifest the summaries ride.
     'orboto_report_feedback', // ORB-1910 - an agent that hits a bug reports it without ?toolset=full
     'orboto_help', // ORB-1697 - the way back from a budget cut
     'orboto_api_search', // ORB-1518 - discovery half of the escape hatch

package/dist/toolset.test.js

@@ -7,8 +7,6 @@ import { buildOrbotoMcpServer } from './server.js';
 import { CURATED_TOOLS, MINIMAL_TOOLS, resolveToolset, toolInToolset } from './toolset.js';
 beforeEach(() => {
     vi.restoreAllMocks();
-    // buildOrbotoMcpServer fetches /agent-instructions at connect; offline
-    // in unit tests - the catch keeps the fallback rules, which is fine.
     vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('offline test'));
     delete process.env.ORBOTO_MCP_TOOLSET;
 });
@@ -17,9 +15,6 @@ afterEach(() => {
     delete process.env.ORBOTO_MCP_TOOLSET;
 });
 function registeredTools(server) {
-    // The SDK keeps its registry on `_registeredTools` (verified against
-    // @modelcontextprotocol/sdk 1.29). If a bump renames it, this helper
-    // fails loudly rather than passing on an empty object.
     const tools = server._registeredTools;
     if (!tools || Object.keys(tools).length === 0) {
         throw new Error('SDK _registeredTools not found or empty - did the SDK internals change?');
@@ -37,9 +32,6 @@ describe('resolveToolset', () => {
         expect(resolveToolset('bogus', 'full')).toBe('full');
         expect(resolveToolset('bogus', 'nonsense')).toBe('curated');
     });
-    // ORB-1805 - the small-context tier resolves on both surfaces and,
-    // like the others, a typo still degrades to curated rather than
-    // silently handing an 8k model 175 tools.
     it('minimal resolves from either surface and keeps the safe fallback', () => {
         expect(resolveToolset('minimal', undefined)).toBe('minimal');
         expect(resolveToolset(undefined, 'minimal')).toBe('minimal');
@@ -54,7 +46,6 @@ describe('toolInToolset', () => {
         expect(toolInToolset('orboto_claim', 'curated')).toBe(true);
         expect(toolInToolset('orboto_api_call', 'curated')).toBe(true);
     });
-    // ORB-1959 - coordination is part of the default connection, not an opt-in.
     it('curated carries the four agent-coordination tools; minimal stays the 12-tool loop', () => {
         for (const name of ['orboto_messages', 'orboto_agent_notify', 'orboto_agent_broadcast', 'orboto_agent_heartbeat']) {
             expect(toolInToolset(name, 'curated'), name).toBe(true);
@@ -65,7 +56,6 @@ describe('toolInToolset', () => {
         expect(toolInToolset('orboto_claim', 'minimal')).toBe(true);
         expect(toolInToolset('orboto_api_search', 'minimal')).toBe(true);
         expect(toolInToolset('orboto_api_call', 'minimal')).toBe(true);
-        // In curated, out of minimal.
         expect(toolInToolset('orboto_list_projects', 'minimal')).toBe(false);
         expect(toolInToolset('orboto_help', 'minimal')).toBe(false);
         expect(toolInToolset('orboto_wiki_ask', 'minimal')).toBe(false);
@@ -73,10 +63,6 @@ describe('toolInToolset', () => {
 });
 describe('ORB-1805 - the tiers nest', () => {
     it('MINIMAL_TOOLS is a strict subset of CURATED_TOOLS', () => {
-        // A name that is not registered in curated cannot register in
-        // minimal either - the tier ordering minimal < curated < full is
-        // what the docs promise, and a typo here would silently ship an
-        // empty slot.
         const notInCurated = [...MINIMAL_TOOLS].filter((t) => !CURATED_TOOLS.has(t));
         expect(notInCurated).toEqual([]);
         expect(MINIMAL_TOOLS.size).toBeLessThan(CURATED_TOOLS.size);
@@ -115,9 +101,6 @@ describe('buildOrbotoMcpServer toolset gating', () => {
     it('curated instructions point at the escape hatch; full keeps get_checklists', async () => {
         const curated = await buildOrbotoMcpServer(baseOpts);
         const full = await buildOrbotoMcpServer({ ...baseOpts, toolset: 'full' });
-        // `_instructions` verified against @modelcontextprotocol/sdk 1.29
-        // (server/index.js). Assert non-empty first so an SDK rename fails
-        // this test loudly instead of green-skipping.
         const instructionsOf = (s) => String(s.server._instructions ?? '');
         const curatedText = instructionsOf(curated);
         const fullText = instructionsOf(full);
@@ -137,12 +120,9 @@ describe('buildOrbotoMcpServer toolset gating', () => {
         const minimal = await buildOrbotoMcpServer({ ...baseOpts, toolset: 'minimal' });
         const text = String(minimal.server._instructions ?? '');
         expect(text.length).toBeGreaterThan(100);
-        // The two things a minimal-tier agent cannot work without.
         expect(text).toContain('orboto_session_start');
         expect(text).toContain('orboto_api_search');
         expect(text).toContain('MINIMAL');
-        // ORB-1805 - the workspace rules block is deliberately absent; it
-        // arrives via orboto_session_start, on the caller's budget.
         expect(text).not.toContain('Working rules for this workspace:');
     });
     it('minimal drops the display title; curated keeps it', async () => {

package/dist/version-guard.test.js

@@ -15,7 +15,6 @@ import { createRequire } from 'node:module';
 import { VERSION } from './version.js';
 const SRC = dirname(fileURLToPath(import.meta.url));
 const pkg = createRequire(import.meta.url)('../package.json');
-// version.ts legitimately holds the '0.0.0' runtime fallback literal.
 const ALLOWED = new Set(['version.ts']);
 function walk(dir, acc = []) {
     for (const entry of readdirSync(dir)) {
@@ -35,9 +34,6 @@ describe('ORB-1173 - version literal guard', () => {
     });
     it('no hardcoded semver string literal in src (use VERSION instead)', () => {
         const offenders = [];
-        // A quoted X.Y.Z literal - what a drifting hardcoded version looks
-        // like. Comments (// v0.110.1) and ticket refs (ORB-1166) are not
-        // quoted semver, so they don't trip this.
         const semverLiteral = /['"]\d+\.\d+\.\d+['"]/;
         for (const file of walk(SRC)) {
             const text = readFileSync(file, 'utf8');

package/dist/version.js

@@ -1,17 +1,5 @@
 /**
  * ORB-1166 - single source of truth for the MCP server version.
- *
- * Read from package.json (which release.mjs bumps) so serverInfo.version
- * + the User-Agent header always reflect the real release instead of a
- * hardcoded literal that drifts.
- *
- * WRAPPED IN try/catch on purpose: the Docker runtime image is stripped
- * to `dist/` + `node_modules/` and may not ship package.json at the path
- * `createRequire` resolves. A bare `require('../package.json')` at module
- * load threw there and crash-looped the MCP container (took prod down in
- * v0.110.1). The catch guarantees this module can NEVER crash the server
- * on boot; the Dockerfile now also copies package.json so the real
- * version resolves in-container.
  */
 import { createRequire } from 'node:module';
 function readVersion() {

package/dist/with-metrics-output-schema.test.js

@@ -2,13 +2,7 @@
  * ORB-1738 - declared output schemas ADVERTISE the response budget's
  * `__truncation` marker.
  *
- * Second instance of the ORB-1733 class: the budget injects the marker
- * into structuredContent, the SDK advertises output schemas with
- * additionalProperties:false, and strict clients validate structured
- * content against that - so every over-budget response of a tool with a
- * declared outputSchema was rejected wholesale (orboto_list_projects
- * failed on EVERY call of this 57-project workspace; reported via the
- * agent inbox 2026-08-28).
+ * @see ORB-1733
  */
 import { describe, it, expect } from 'vitest';
 import { listProjectsToolConfig } from './tools/list-projects.js';
@@ -40,19 +34,13 @@ describe('ORB-1738 - __truncation is part of the advertised output schema', () =
         };
         const { result } = applyResponseBudget('orboto_list_projects', bigResult);
         const sc = result.structuredContent;
-        // The budget DID cut and marked it.
         expect(sc.__truncation).toBeDefined();
         const shape = advertisedOutputShape(listProjectsToolConfig.outputSchema);
-        // Before the fix this was false - the marker was undeclared.
         expect(strictClientAccepts(shape, sc)).toBe(true);
-        // And the marker itself matches BOTH the exact runtime shape and the
-        // compact schema actually advertised on the wire (ORB-1805).
         expect(TruncationBlockSchema.safeParse(sc.__truncation).success).toBe(true);
         expect(TruncationBlockAdvertisedSchema.safeParse(sc.__truncation).success).toBe(true);
     });
     it('ORB-1805 - the advertised marker schema is strictly more permissive than the exact one', () => {
-        // Anything the exact shape accepts, the advertised one must accept -
-        // otherwise the diet would start rejecting valid payloads.
         const block = {
             handle: 'h1', budgetChars: 4000, originalChars: 9000, omittedChars: 5000,
             omitted: [{ path: 'items', kind: 'array', omittedItems: 12, keptItems: 3 }],
@@ -60,7 +48,6 @@ describe('ORB-1738 - __truncation is part of the advertised output schema', () =
         };
         expect(TruncationBlockSchema.safeParse(block).success).toBe(true);
         expect(TruncationBlockAdvertisedSchema.safeParse(block).success).toBe(true);
-        // A future field added to the runtime block must not break clients.
         expect(TruncationBlockAdvertisedSchema.safeParse({ ...block, futureField: 1 }).success).toBe(true);
     });
     it('the budget layer adds exactly ONE key - __truncation - and nothing else (class sweep)', () => {