@orboto/mcp 0.192.0 → 0.194.0

package/dist/tools/checklist-writes.test.js

@@ -3,7 +3,7 @@
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { OrbotoClient } from '../orboto-client.js';
-import { makeCheckHandler, makeUncheckHandler, makeAddCheckHandler, makeNewChecklistHandler, makeRemoveCheckHandler, } from './checklist-writes.js';
+import { makeCheckHandler, makeUncheckHandler, makeAddCheckHandler, makeNewChecklistHandler, makeRemoveCheckHandler, makeUpdateCheckHandler, } from './checklist-writes.js';
 beforeEach(() => { vi.restoreAllMocks(); });
 afterEach(() => { vi.restoreAllMocks(); });
 function stub(responses) {
@@ -182,3 +182,71 @@ describe('orboto_new_checklist', () => {
         await expect(makeNewChecklistHandler(client)({ ticketKey: 'ACME-1', title: 'x' })).rejects.toThrow(/ticket:edit/);
     });
 });
+const MEMBERS = [
+    { userId: '4b3e2c1d-6f7a-4b8c-9d0e-1f2a3b4c5d6e', user: { email: 'kim@example.test', fullName: 'Kim Novak' } },
+    { userId: 'u-ada', user: { email: 'ada@example.test', fullName: 'Ada Byron' } },
+];
+describe('orboto_add_check with assignee + dueDate (ORB-235)', () => {
+    it('resolves the assignee by email against the project members and passes the due date through', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: [SAMPLE_LIST] },
+            { json: MEMBERS },
+            { json: { id: 'i3', content: 'Tag the release', assignedTo: '4b3e2c1d-6f7a-4b8c-9d0e-1f2a3b4c5d6e', dueDate: '2026-10-01' } },
+        ]);
+        const res = await makeAddCheckHandler(client)({ ticketKey: 'ACME-1', content: 'Tag the release', assignee: 'kim@example.test', dueDate: '2026-10-01' });
+        expect(calls[4].body).toEqual({ content: 'Tag the release', assignedTo: '4b3e2c1d-6f7a-4b8c-9d0e-1f2a3b4c5d6e', dueDate: '2026-10-01' });
+        expect(res.structuredContent).toMatchObject({ assignedTo: '4b3e2c1d-6f7a-4b8c-9d0e-1f2a3b4c5d6e', dueDate: '2026-10-01' });
+        expect(res.content[0].text).toContain('due 2026-10-01');
+    });
+    it('names the members when the assignee is not one, and refuses a malformed date before any write', async () => {
+        stub([{ json: PROJ }, { json: TICKET }, { json: [SAMPLE_LIST] }, { json: MEMBERS }]);
+        await expect(makeAddCheckHandler(client)({ ticketKey: 'ACME-1', content: 'x', assignee: 'nobody@example.test' })).rejects.toThrow(/not a member.*Kim Novak <kim@example.test>/);
+        const calls = stub([{ json: PROJ }, { json: TICKET }, { json: [SAMPLE_LIST] }]);
+        await expect(makeAddCheckHandler(client)({ ticketKey: 'ACME-1', content: 'x', dueDate: 'next friday' })).rejects.toThrow(/dueDate must be YYYY-MM-DD/);
+        expect(calls.some((c) => c.method === 'POST')).toBe(false);
+    });
+});
+describe('orboto_update_check (ORB-235)', () => {
+    it('resolves the item by index, the assignee by full name, and PATCHes only what was given', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: [SAMPLE_LIST] },
+            { json: MEMBERS },
+            { json: { item: { id: 'i2', content: 'Docs', assignedTo: 'u-ada', assigneeName: 'Ada Byron', dueDate: '2026-10-02' } } },
+        ]);
+        const res = await makeUpdateCheckHandler(client)({ ticketKey: 'ACME-1', item: 2, assignee: 'Ada Byron', dueDate: '2026-10-02' });
+        expect(calls[4].method).toBe('PATCH');
+        expect(calls[4].url).toContain('/checklist-items/i2');
+        expect(calls[4].body).toEqual({ assignedTo: 'u-ada', dueDate: '2026-10-02' });
+        expect(res.structuredContent).toMatchObject({ itemId: 'i2', assigneeName: 'Ada Byron', dueDate: '2026-10-02' });
+        expect(res.content[0].text).toContain('@Ada Byron');
+    });
+    it('null unassigns and clears the date; a user id that is a member passes through unresolved', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: [SAMPLE_LIST] },
+            { json: { item: { id: 'i1', content: 'Tests', assignedTo: null, assigneeName: null, dueDate: null } } },
+        ]);
+        const res = await makeUpdateCheckHandler(client)({ ticketKey: 'ACME-1', item: 1, assignee: null, dueDate: null, content: 'Tests' });
+        expect(calls[3].body).toEqual({ content: 'Tests', assignedTo: null, dueDate: null });
+        expect(res.content[0].text).toContain('unassigned');
+        const byId = stub([
+            { json: PROJ },
+            { json: TICKET },
+            { json: [SAMPLE_LIST] },
+            { json: MEMBERS },
+            { json: { item: { id: 'i1', content: 'Tests', assignedTo: '4b3e2c1d-6f7a-4b8c-9d0e-1f2a3b4c5d6e', assigneeName: 'Kim Novak', dueDate: null } } },
+        ]);
+        await makeUpdateCheckHandler(client)({ ticketKey: 'ACME-1', item: 1, assignee: '4b3e2c1d-6f7a-4b8c-9d0e-1f2a3b4c5d6e' });
+        expect(byId[4].body).toEqual({ assignedTo: '4b3e2c1d-6f7a-4b8c-9d0e-1f2a3b4c5d6e' });
+    });
+    it('refuses an empty update without touching the API', async () => {
+        const calls = stub([{ json: PROJ }, { json: TICKET }, { json: [SAMPLE_LIST] }]);
+        await expect(makeUpdateCheckHandler(client)({ ticketKey: 'ACME-1', item: 1 })).rejects.toThrow(/Nothing to update/);
+        expect(calls.some((c) => c.method === 'PATCH')).toBe(false);
+    });
+});

package/dist/tools/claim.js

@@ -1,45 +1,11 @@
 /**
  * ORB-799 - composite ticket-lifecycle tools.
  *
- * Two tools that bundle the most-used wrapper composites:
- *
- *   - orboto_claim   ≈ assign_self + move(in_progress) + timer_start
- *   - orboto_unclaim ≈ unassign_self + move(todo)
- *
- * The composite-atomic behaviour is the real value here - these are
- * the most-typed wrapper commands by agents during ticket pickup. The
- * 1:1 mirror of `orboto.mjs claim` semantics matters:
- *
- *   - `--sole` (`sole=true`) - destructive take-over: remove every
- *     other assignee before adding self. Use sparingly; the API has
- *     no atomic swap so this is a delete-loop + add.
- *   - `--force` (`force=true`) - allow re-claiming a `done` ticket
- *     (the wrapper refuses without it to prevent accidental reopen).
- *   - `--no-timer` (`noTimer=true`) - skip the timer_start side
- *     effect. Useful when the agent only wants ownership-by-assignee
- *     without committing time.
- *
- * Both tools are **idempotent** on the happy paths:
- *   - claim of a ticket where the caller is already an assignee and
- *     statusCategory is already `in_progress` → no PATCH, no extra
- *     assignee POST (the wrapper still POSTs once and 409s; we skip).
- *   - unclaim of a ticket where the caller isn't an assignee → 404 on
- *     DELETE is swallowed, status move still happens.
- *
- * Timer side-effects mirror ORB-179 (`claim`) + ORB-181 (`close`):
- *   - If a different ticket has an active timer, stop it first
- *     (commits the elapsed time-entry under the previous ticket's
- *     description), then start a fresh timer on this one.
- *   - Timer failures never roll back the assign/status work - we
- *     surface them as a `timerWarning` field on the structured
- *     response, same shape as the wrapper.
+ * @see ORB-179, ORB-181
  */
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
 import { mcpInstanceToken, resolveTicketByKey } from './shared.js';
-// `statusCategory` is the discriminator the API exposes on every
-// ticket-read response; we map it (rather than `status` legacy enum)
-// because that's what the wrapper inspects too.
 const CATEGORY_TO_LEGACY = {
     todo: 'TODO',
     in_progress: 'IN_PROGRESS',
@@ -47,14 +13,9 @@ const CATEGORY_TO_LEGACY = {
     done: 'DONE',
     wont_fix: 'WONT_FIX',
 };
-// ---------------------------------------------------------------------------
-// orboto_claim
-// ---------------------------------------------------------------------------
 export const claimToolConfig = {
     title: 'Claim a ticket (assign self + in_progress + timer)',
     description: 'Composite of `assign self → move to in_progress → start timer` - the canonical "I am picking this up now" move. Idempotent: re-claiming an already-claimed in_progress ticket is a no-op. Set `sole=true` to remove every other assignee first (destructive take-over). Set `force=true` to allow re-claiming a `done` ticket (otherwise refuses, to prevent accidental reopens). Set `noTimer=true` to skip the timer start (e.g. when you only want ownership, not time tracking). If a different ticket has an active timer, it is stopped first (its elapsed time commits a time entry under the previous ticket). '
-        // ORB-1805 - moved out of the input schema, which every client pays
-        // for at connect; orboto_help serves this text in full.
         + '`agentSessionToken` is a stable per-agent-instance token: on a bot/service account it scopes the timer to YOUR instance - concurrent per-instance timers and NO auto-stop, so you own both start and stop. Omit it on human accounts, which keep the single-timer behaviour.',
     inputSchema: z.object({
         ticketKey: z.string().min(3),
@@ -63,9 +24,6 @@ export const claimToolConfig = {
         noTimer: z.boolean().optional().describe('Skip the timer start.'),
         agentSessionToken: z.string().optional().describe('Per-agent-instance token; scopes the timer on bot accounts.'),
     }).shape,
-    // ORB-1669 - destructive because of `sole=true`, which strips every
-    // other assignee. Annotations are per-tool and cannot be conditioned on
-    // an argument, so the hint has to cover the worst call the tool allows.
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };
 export function makeClaimHandler(client) {
@@ -78,9 +36,6 @@ export function makeClaimHandler(client) {
         if (currentCategory === 'done' && !force) {
             throw new Error(`Refusing to claim [${current.ticketKey}]: status is "done". Pass force=true to reopen + claim.`);
         }
-        // --sole: destructive take-over. Remove every other assignee
-        // first. Each DELETE tolerates a 404 (race condition where another
-        // process already unassigned them).
         if (sole) {
             for (const a of currentAssignees) {
                 if (a.id === me.id)
@@ -94,43 +49,25 @@ export function makeClaimHandler(client) {
                 }
             }
         }
-        // Additive self-add. Skip if we're already on the ticket - POSTing
-        // again would 409; idempotency here matters because agents call
-        // claim defensively at the start of every operation.
         if (!alreadyAssigned) {
             try {
                 await client.post(`/projects/${current.projectId}/tickets/${current.id}/assignees/${me.id}`, {});
             }
             catch (err) {
-                // 409 = race-added by another process while we were checking.
-                // Treat as already-assigned success.
                 if (!(err instanceof OrbotoApiError) || err.status !== 409)
                     throw err;
             }
         }
-        // Only PATCH if we're not already in_progress. Saves an audit row
-        // + websocket broadcast on the common re-claim path.
         let finalTicket = current;
         if (currentCategory !== 'in_progress') {
             finalTicket = await client.patch(`/projects/${current.projectId}/tickets/${current.id}`, { status: CATEGORY_TO_LEGACY.in_progress });
         }
-        // Timer side-effects. Mirrors the wrapper's ORB-179 path: stop a
-        // timer running on a different ticket, then start fresh here. A
-        // 409 on the start side is captured as a warning rather than
-        // raised, so the assign/status work still counts as success.
         let timerStarted = false;
         let timerWarning = null;
-        // Bot/service accounts own their timer (per-instance, no auto-stop). Instance
-        // id: explicit arg > per-connection MCP session id (distinct per client even
-        // on a shared HTTP server) > per-process id (stdio). Human accounts fall
-        // through to the legacy auto-stop path.
         const effectiveToken = agentSessionToken ?? (me.isBot ? mcpInstanceToken(undefined, extra) : undefined);
         if (!noTimer) {
             try {
                 if (effectiveToken) {
-                    // ORB-1252 - agent instance owns its timer: per-session, no auto-stop.
-                    // Idempotent on the same ticket; 409 if this session already runs a
-                    // different ticket (surfaced as a warning below).
                     await client.post('/time/timer/start', { ticketId: current.id, agentSessionToken: effectiveToken });
                     timerStarted = true;
                 }
@@ -141,13 +78,10 @@ export function makeClaimHandler(client) {
                         await client.post('/time/timer/stop', {
                             note: `Auto-stopped by claim of ${finalTicket.ticketKey ?? current.id}`,
                         }).catch(() => {
-                            // Swallow - we'll try start below; if start 409s we surface
-                            // the warning then.
                             timerWarning = `Failed to stop timer on ${other}; new timer not started.`;
                         });
                     }
                     else if (active && active.ticketId === current.id) {
-                        // Same ticket - effectively already started.
                         timerStarted = true;
                     }
                     if (!timerStarted && !timerWarning) {
@@ -161,7 +95,6 @@ export function makeClaimHandler(client) {
                     timerWarning = 'A timer is already running on another ticket; could not start one here. Run `orboto_timer_stop` first.';
                 }
                 else {
-                    // Any other timer error → keep the claim, surface the issue.
                     timerWarning = err instanceof Error ? err.message : String(err);
                 }
             }
@@ -192,9 +125,6 @@ export function makeClaimHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_unclaim
-// ---------------------------------------------------------------------------
 export const unclaimToolConfig = {
     title: 'Unclaim a ticket (composite: unassign self + move to todo)',
     description: 'Inverse of `orboto_claim`: remove the calling user as an assignee and move the ticket back to `todo`. Idempotent - if the caller wasn\'t an assignee, the unassign step is a no-op and the status move still happens. Does not stop a running timer (use `orboto_timer_stop` if you want that side-effect; staying separate avoids surprising the next claimant).',

package/dist/tools/claim.test.js

@@ -86,8 +86,6 @@ describe('orboto_claim', () => {
             { json: { ticketId: 't1' } }, // GET /time/timer - already on same ticket
         ]);
         const res = await makeClaimHandler(client)({ ticketKey: 'ACME-1' });
-        // 4 calls total: /users/me, by-key project, by-key ticket, GET /time/timer.
-        // No POST /assignees, no PATCH status, no POST /timer/start.
         expect(calls).toHaveLength(4);
         expect(calls.some((c) => c.method === 'PATCH')).toBe(false);
         expect(calls.some((c) => c.url.includes('/timer/start'))).toBe(false);

package/dist/tools/critical-path.js

@@ -21,8 +21,6 @@ export function makeCriticalPathHandler(client) {
         const project = await resolveProjectByKey(client, input.projectKey);
         const params = new URLSearchParams();
         if (input.milestone) {
-            // ORB-1696 - shared resolver: key (ORB-M3), name or UUID, ambiguous
-            // name -> explicit error. Matches create_ticket/set_milestone/OQL.
             const m = await resolveMilestoneByNameOrId(client, project.id, input.milestone);
             params.set('milestoneId', m.id);
         }
@@ -37,15 +35,12 @@ export function makeCriticalPathHandler(client) {
                 structuredContent: { cycle: res.cycle, criticalPath: [], projectDurationDays: 0, tickets: [] },
             };
         }
-        // ORB-1614 - flag cross-project neighbours pulled into the graph so the
-        // reader knows a key like "OVB-55" is not a typo for this project.
         const externalKeys = new Set(res.tickets.filter((t) => t.external).map((t) => t.ticketKey));
         const slack = res.tickets
             .filter((t) => !t.isCritical && t.totalFloat > 0)
             .sort((a, b) => a.totalFloat - b.totalFloat)
             .map((t) => `  ${t.ticketKey}${t.external ? ' [external]' : ''}: ${t.totalFloat}d slack`)
             .join('\n');
-        // ORB-1459 - surface tickets whose deadline can't be met (negative float).
         const risks = (res.deadlineRisks ?? [])
             .map((r) => {
             const via = r.constrainingTicketKey && r.constrainingTicketKey !== r.ticketKey

package/dist/tools/critical-path.test.js

@@ -75,9 +75,6 @@ describe('orboto_critical_path (ORB-1028)', () => {
         expect(sc.deadlineRisks).toHaveLength(2);
         expect(sc.deadlineRisks[0]).toMatchObject({ ticketKey: 'ACME-1', shortfallDays: 2 });
     });
-    // ORB-1614 - a 1-hop cross-project neighbour is marked external:true by
-    // the API; the tool should flag it in both the text (so "OVB-55" isn't
-    // mistaken for a typo of this project's key) and the structured output.
     it('flags a cross-project neighbour with [external] in text and structured output', async () => {
         const calls = stub([
             { json: PROJ },

package/dist/tools/cross-project-links.ee.js

@@ -2,24 +2,10 @@
 /**
  * ORB-632 / ORB-945 - Cross-Project Linking MCP tools.
  *
- * - orboto_list_cross_project_links - GET /tickets/:id/cross-project-links
- * - orboto_add_cross_project_link - POST /tickets/:id/cross-project-links
- * - orboto_update_cross_project_link - PATCH /tickets/:id/cross-project-links/:linkId
- * - orboto_remove_cross_project_link - DELETE /tickets/:id/cross-project-links/:linkId
- *
- * Business-tier feature (`.ee.*`). The API records the EE soft-warn
- * event on mutating calls; the tool surface here is identical to
- * every other MCP tool and reads the existing license-state via the
- * Authorization-header path.
- *
- * Accepts BOTH a UUID and a ticket-key (`OCP-42`, case-insensitive) on
- * every input - the API resolves either form.
+ * @see OCP-42
  */
 import { z } from 'zod';
 const RELATION_TYPES = ['counterpart', 'depends_on', 'blocks', 'related'];
-// ---------------------------------------------------------------------------
-// orboto_list_cross_project_links
-// ---------------------------------------------------------------------------
 export const listCrossProjectLinksToolConfig = {
     title: 'List cross-project links on a ticket',
     description: 'Return every cross-project link touching the ticket - both outgoing (this → other) and incoming (other → this). Each row carries the other end\'s project key, ticket key, title, and current status, so the model can see the linked work\'s state without a follow-up tool call. ACL-filtered: rows whose other-end project the caller cannot read are dropped silently.',
@@ -50,9 +36,6 @@ export function makeListCrossProjectLinksHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_add_cross_project_link
-// ---------------------------------------------------------------------------
 export const addCrossProjectLinkToolConfig = {
     title: 'Add a cross-project link between two tickets',
     description: 'Create a formal relation between two tickets in different projects. Caller must be a member of BOTH the source and target projects. Relation types: counterpart (parallel work in two repos - bidirectional), depends_on (this ticket waits for the other), blocks (the other waits for this), related (loose association). Pass statusSyncEnabled=true to opt into auto-close: when a counterpart-linked ticket moves to done, the other auto-closes too. Off by default.',
@@ -76,9 +59,6 @@ export function makeAddCrossProjectLinkHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_update_cross_project_link
-// ---------------------------------------------------------------------------
 export const updateCrossProjectLinkToolConfig = {
     title: 'Toggle status-sync on a cross-project link',
     description: 'Flip the statusSyncEnabled flag on an existing cross-project link. When enabled on a counterpart-typed link, the other end auto-closes when this one moves to done (and vice versa). Other relation types ignore the flag at runtime, so toggling it on them is a no-op as far as status-sync goes.',
@@ -101,9 +81,6 @@ export function makeUpdateCrossProjectLinkHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_remove_cross_project_link
-// ---------------------------------------------------------------------------
 export const removeCrossProjectLinkToolConfig = {
     title: 'Remove a cross-project link',
     description: 'DESTRUCTIVE - drops the cross-project link between two tickets. Caller must be a member of both source and target projects (or super-admin). The underlying tickets are unaffected; only the relation row is deleted.',

package/dist/tools/doc-attachments.js

@@ -1,20 +1,5 @@
 /**
  * ORB-914 - doc-attachments MCP tools (epic ORB-911 Phase 3).
- *
- * Mirrors the ticket-attachment surface (apps/mcp/src/tools/attach.ts)
- * for doc pages. Three tools:
- *
- * - orboto_upload_doc_attachment - multipart upload + optional embed
- * - orboto_list_doc_attachments - flat list with download URLs
- * - orboto_delete_doc_attachment - destructive
- *
- * The embed branch on upload PATCHes the doc body to append a Markdown
- * image-or-link line, same pattern as orboto_attach_to_ticket. Useful
- * when an agent wants to drop a screenshot into a page in one call.
- *
- * MIME / extension policy is enforced server-side via `isAttachmentAllowed`
- * - the tool just surfaces the 415 as an OrbotoApiError so the caller
- * can pick a different file.
  */
 import { z } from 'zod';
 import { resolveDocId } from './docs.js';
@@ -50,9 +35,6 @@ function mimetypeFor(filename) {
 function isImage(mimetype) {
     return mimetype.startsWith('image/');
 }
-// ---------------------------------------------------------------------------
-// orboto_upload_doc_attachment
-// ---------------------------------------------------------------------------
 export const uploadDocAttachmentToolConfig = {
     title: 'Upload an attachment to a doc page',
     description: 'Upload a file as an attachment on a wiki doc and return its Markdown image (or link) line + the stable download URL. Bytes come in as base64 (`contentBase64`) so this works without local FS access on the agent side. Set `embed=true` to also PATCH the doc body to append the Markdown line - useful for dropping a screenshot into a page in one call. MIME / extension policy is enforced server-side: blocked types (HTML, SVG, executables) surface a 415.',
@@ -70,8 +52,6 @@ export function makeUploadDocAttachmentHandler(client) {
         docId = await resolveDocId(client, docId);
         let arrayBuffer;
         try {
-            // Buffer → fresh ArrayBuffer copy (see attach.ts for the Blob
-            // type-constraint rationale).
             const buf = Buffer.from(contentBase64, 'base64');
             arrayBuffer = new ArrayBuffer(buf.byteLength);
             new Uint8Array(arrayBuffer).set(buf);
@@ -92,8 +72,6 @@ export function makeUploadDocAttachmentHandler(client) {
             : `[${alt}](${url})`;
         let embedded = false;
         if (embed === true) {
-            // Read the current body first - PATCH /docs/:id replaces, not
-            // appends. Then write the new body in one go.
             const current = await client.get(`/docs/${docId}`);
             const existing = current.content ?? '';
             const next = existing ? `${existing}\n\n${markdown}` : markdown;
@@ -118,9 +96,6 @@ export function makeUploadDocAttachmentHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_list_doc_attachments
-// ---------------------------------------------------------------------------
 export const listDocAttachmentsToolConfig = {
     title: 'List attachments on a doc page',
     description: 'Return the doc\'s attachments newest-first, with stable download URLs the agent can hand to the user. Empty list = no attachments.',
@@ -160,9 +135,6 @@ export function makeListDocAttachmentsHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_delete_doc_attachment
-// ---------------------------------------------------------------------------
 export const deleteDocAttachmentToolConfig = {
     title: 'Delete an attachment from a doc page',
     description: 'DESTRUCTIVE - drops the file row + deletes the underlying S3 object. Does NOT rewrite the doc body, so embedded Markdown lines pointing at the deleted URL will surface as broken images / links. Walk those by hand if needed.',

package/dist/tools/doc-attachments.test.js

@@ -46,9 +46,7 @@ function stubFetch(responses) {
     });
     return calls;
 }
-const TINY_PNG_BASE64 = 
-// 1x1 red png - smallest valid bytes we can pass through
-'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAFhAJ/wlseKgAAAABJRU5ErkJggg==';
+const TINY_PNG_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAFhAJ/wlseKgAAAABJRU5ErkJggg==';
 describe('orboto_upload_doc_attachment', () => {
     it('POSTs multipart to /docs/:id/attachments and returns markdown image line', async () => {
         const calls = stubFetch([{ status: 201, json: ATTACHMENT }]);
@@ -61,7 +59,6 @@ describe('orboto_upload_doc_attachment', () => {
             method: 'POST',
             url: `https://orboto.example.com/docs/${DOC_ID}/attachments`,
         });
-        // FormData reaches fetch as a FormData instance.
         expect(calls[0].body).toBeInstanceOf(FormData);
         const fd = calls[0].body;
         expect(fd.get('file')).toBeTruthy();

package/dist/tools/doc-comments.js

@@ -1,25 +1,8 @@
 /**
  * ORB-917 - doc-comments MCP tools (epic ORB-911 Phase 6).
- *
- * - orboto_list_doc_comments - GET /docs/:id/comments  (cursor-paged, oldest-first)
- * - orboto_post_doc_comment - POST /docs/:id/comments
- * - orboto_resolve_doc_comment - POST /docs/:id/comments/:cid/resolve
- * - orboto_delete_doc_comment - DELETE /docs/:id/comments/:cid
- *
- * Comments support replies (single-level - replying to a reply lands as
- * a sibling of the original reply because the API auto-flattens past
- * one level) and optional anchors (a 3-tuple of {text, before, after}
- * the frontend uses to re-locate a highlight even after the doc body
- * has shifted).
- *
- * resolve acts on the thread root by design so resolving from a reply
- * folds the whole conversation - mirrors the web UI's behaviour.
  */
 import { z } from 'zod';
 import { resolveDocId } from './docs.js';
-// ---------------------------------------------------------------------------
-// orboto_list_doc_comments
-// ---------------------------------------------------------------------------
 export const listDocCommentsToolConfig = {
     title: 'List comments on a doc page',
     description: 'Return comments on a doc page, oldest-first so the reply tree reads top-to-bottom. Each row carries the author name + content + resolved state. Cursor-paged - pass `cursor` from the previous call\'s nextCursor to walk older pages.',
@@ -46,9 +29,6 @@ export function makeListDocCommentsHandler(client) {
                 structuredContent: { comments: [], nextCursor: null },
             };
         }
-        // Build a parent-keyed tree so the Markdown rendering can indent
-        // replies one level under their root. The API already flattens
-        // past one level, so depth is always 0 or 1.
         const byParent = new Map();
         for (const c of page.items) {
             const key = c.parentCommentId ?? null;
@@ -62,23 +42,19 @@ export function makeListDocCommentsHandler(client) {
             const author = c.userName ?? `user ${c.userId.slice(0, 8)}`;
             const resolved = c.resolvedAt ? ' [resolved]' : '';
             lines.push(`${indent}- ${author}  ·  ${c.createdAt}${resolved}  ·  id: ${c.id}`);
-            // Anchor preview helps the model understand what part of the
-            // doc the comment is anchored to. Truncate to keep the output
-            // compact.
             if (c.anchor) {
                 const snippet = c.anchor.text.length > 80 ? c.anchor.text.slice(0, 77) + '...' : c.anchor.text;
                 lines.push(`${indent}  anchored on: "${snippet}"`);
             }
             const body = c.content.split('\n').map((l) => `${indent}  ${l}`).join('\n');
             lines.push(body);
-            // Render direct replies one level deeper.
             const replies = byParent.get(c.id) ?? [];
             for (const r of replies)
                 renderOne(r, depth + 1);
         };
         for (const root of byParent.get(null) ?? []) {
             renderOne(root, 0);
-            lines.push(''); // blank line between root threads
+            lines.push('');
         }
         if (page.nextCursor) {
             lines.push(`(more available - pass cursor: ${page.nextCursor})`);
@@ -104,9 +80,6 @@ export function makeListDocCommentsHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_post_doc_comment
-// ---------------------------------------------------------------------------
 export const postDocCommentToolConfig = {
     title: 'Post a comment on a doc page (or reply to one)',
     description: 'Add a comment to a doc page. Pass `parentCommentId` to reply (the API flattens reply chains past one level so a reply-of-reply lands as a sibling of the original reply). Optional `anchor` (`{text, before, after}`) attaches the comment to a specific highlight in the body - the frontend uses the surrounding context to re-locate the anchor even after the doc has been edited. Mentions in the content body (`@username`) fire notifications automatically.',
@@ -147,9 +120,6 @@ export function makePostDocCommentHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_resolve_doc_comment
-// ---------------------------------------------------------------------------
 export const resolveDocCommentToolConfig = {
     title: 'Mark a doc comment thread as resolved (or reopen it)',
     description: 'Toggle a comment thread\'s resolved state. Pass `resolved=true` to fold the conversation, `resolved=false` to reopen. Always acts on the thread ROOT - resolving from a reply folds the whole conversation, same as the web UI.',
@@ -177,9 +147,6 @@ export function makeResolveDocCommentHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_update_doc_comment - ORB-933
-// ---------------------------------------------------------------------------
 export const updateDocCommentToolConfig = {
     title: 'Edit your own doc comment',
     description: 'Edit a doc comment\'s body. Author OR super-admin can edit; everyone else gets a 403. Doc-comments do not carry a revision history today (unlike ticket comments), so the prior content is overwritten in place. A no-op call (same content as before) returns the unchanged row.',
@@ -204,9 +171,6 @@ export function makeUpdateDocCommentHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_delete_doc_comment
-// ---------------------------------------------------------------------------
 export const deleteDocCommentToolConfig = {
     title: 'Delete a doc comment',
     description: 'DESTRUCTIVE - drops the comment + (via FK cascade) every reply under it. Only the author can delete their own comments; super-admins can delete anyone\'s. Returns success silently; 403 surfaces as an OrbotoApiError.',

package/dist/tools/doc-comments.test.js

@@ -62,7 +62,7 @@ describe('orboto_list_doc_comments', () => {
         const res = await makeListDocCommentsHandler(client)({ docId: DOC_ID });
         const text = res.content[0].text;
         expect(text.indexOf('Alice')).toBeLessThan(text.indexOf('Bob'));
-        expect(text).toMatch(/\s\s- Bob/); // reply is indented one level
+        expect(text).toMatch(/\s\s- Bob/);
         expect(text).toContain('Agreed.');
         const comments = res.structuredContent.comments;
         expect(comments).toHaveLength(2);
@@ -100,7 +100,6 @@ describe('orboto_post_doc_comment', () => {
             url: `https://orboto.example.com/docs/${DOC_ID}/comments`,
             body: { content: 'Looks good to me.' },
         });
-        // No parentCommentId in the body for a root comment.
         expect(calls[0].body.parentCommentId).toBeUndefined();
     });
     it('passes parentCommentId through for a reply', async () => {

package/dist/tools/doc-edits.js

@@ -1,33 +1,12 @@
 /**
  * ORB-1342 (epic ORB-1339) - doc snippet-search + targeted-edit MCP tools.
  *
- * Phase-3 four-way-sync rollout of the two REST primitives shipped in
- * ORB-1340 (GET /docs/search) and ORB-1341 (POST /docs/:id/edits). The
- * whole point of the feature is context efficiency: an agent finds the
- * right passage with one search (snippet + heading anchor, NOT the full
- * doc body) and changes it with one edit that ships only the diff in both
- * directions. Prefer these over orboto_get_doc + orboto_update_doc for
- * small changes to a large doc.
- *
- * Three tools:
- *   - orboto_search_docs       GET  /docs/search
- *   - orboto_edit_doc          POST /docs/:id/edits (string-replace edits)
- *   - orboto_edit_doc_section  POST /docs/:id/edits (heading-addressed ops)
- *
- * The two edit tools hit the same endpoint with a different half of its
- * body, so they share the 409-conflict translation below: a machine-
- * readable conflict (no/ambiguous match, stale revision, heading not
- * found / ambiguous) comes back as a NON-throwing tool result with
- * `isError: true` so the model can self-correct instead of the raw API
- * error bubbling up as an opaque failure.
+ * @see ORB-1340, ORB-1341
  */
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
 import { resolveDocId } from './docs.js';
 import { resolveProjectByKey } from './shared.js';
-// ---------------------------------------------------------------------------
-// 409 translation - shared by both edit tools.
-// ---------------------------------------------------------------------------
 /** Turn a 409 from POST /docs/:id/edits into a clear, non-throwing tool
  *  result the model can act on. Returns null for any non-409 so the caller
  *  rethrows (a genuine transport/permission failure should still surface). */
@@ -98,9 +77,6 @@ function renderEditResult(res) {
         },
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_search_docs  (GET /docs/search - ORB-1340)
-// ---------------------------------------------------------------------------
 export const searchDocsToolConfig = {
     title: 'Search docs for snippets (context-efficient)',
     description: 'Full-text search across wiki docs that returns a highlighted SNIPPET (matched fragments, <mark>…</mark> around each hit) plus the nearest markdown heading path (section anchor) and char/line offset per hit - WITHOUT echoing the full doc body. Use this instead of orboto_get_doc when you only need to locate a passage: find the right doc + section, then change it with orboto_edit_doc / orboto_edit_doc_section, all without transferring the whole document. ACL-filtered in SQL (you only see docs you can read). Ranked by relevance.',
@@ -157,9 +133,6 @@ export function makeSearchDocsHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_edit_doc  (POST /docs/:id/edits - string-replace, ORB-1341)
-// ---------------------------------------------------------------------------
 export const editDocToolConfig = {
     title: 'Targeted string-replace edit of a doc (context-efficient)',
     description: 'Change a doc by byte-precise string replacement (Edit-tool-like) - ship only the diff, not the whole doc. Each oldString must match EXACTLY ONCE in the current content (add surrounding context to make it unique) unless replaceAll=true (then >=1). The whole batch is atomic: any match failure applies nothing and returns a 409 you can act on. Prefer this over orboto_update_doc for small changes to a large doc. Pass baseRevisionId (from a previous edit\'s revisionId or orboto_list_doc_revisions) for optimistic concurrency - a stale token is rejected with the current revision id instead of clobbering a concurrent change. Returns a short context window around each change, not the full doc.',
@@ -192,9 +165,6 @@ export function makeEditDocHandler(client) {
         }
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_edit_doc_section  (POST /docs/:id/edits - section ops, ORB-1341)
-// ---------------------------------------------------------------------------
 export const editDocSectionToolConfig = {
     title: 'Edit a doc section by heading path (context-efficient)',
     description: 'Change a doc by markdown-heading-addressed section operations - ship only the new section content, not the whole doc. A section is addressed by its heading path (e.g. ["Setup","Credentials"] = a "Credentials" heading nested under "Setup"). Heading matching is EXACT + case-sensitive; the leading path elements must be an ordered ancestor chain (not necessarily immediate parents). op=replace swaps the section body, op=append adds to its end, op=insertAfter inserts directly below the heading line (the heading line itself is never removed). A path that matches zero or multiple headings returns a 409 you can act on (narrow the path to disambiguate). Prefer this over orboto_update_doc for section-scoped rewrites. baseRevisionId gives optimistic concurrency. Returns a short context window per op.',

package/dist/tools/doc-edits.test.js

@@ -40,9 +40,6 @@ function stubJSON(responses) {
 const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
 const DOC_UUID = '33333333-3333-3333-3333-333333333333';
 const REV_UUID = '44444444-4444-4444-4444-444444444444';
-// ---------------------------------------------------------------------------
-// orboto_search_docs
-// ---------------------------------------------------------------------------
 describe('orboto_search_docs', () => {
     const HIT = {
         id: DOC_UUID,
@@ -91,9 +88,6 @@ describe('orboto_search_docs', () => {
         expect(res.content[0].text).toContain('No docs matched');
     });
 });
-// ---------------------------------------------------------------------------
-// orboto_edit_doc - string-replace
-// ---------------------------------------------------------------------------
 describe('orboto_edit_doc', () => {
     it('POSTs edits to /docs/:id/edits (UUID passthrough) and renders the window', async () => {
         const calls = stubJSON([{
@@ -158,9 +152,6 @@ describe('orboto_edit_doc', () => {
         await expect(makeEditDocHandler(client)({ docId: DOC_UUID, edits: [{ oldString: 'a', newString: 'b' }] })).rejects.toThrow(/403/);
     });
 });
-// ---------------------------------------------------------------------------
-// orboto_edit_doc_section - heading-addressed
-// ---------------------------------------------------------------------------
 describe('orboto_edit_doc_section', () => {
     it('POSTs sectionOps to /docs/:id/edits', async () => {
         const calls = stubJSON([{