@orboto/mcp 0.178.0

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

@@ -0,0 +1,172 @@
+/**
+ * ORB-885 - unit tests for `orboto_update_project`.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { makeUpdateProjectHandler, makeCreateProjectHandler, makeArchiveProjectHandler, } from './update-project.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({
+            url: url.toString(),
+            method: init?.method ?? 'GET',
+            body: init?.body ? JSON.parse(init.body) : undefined,
+        });
+        const r = responses.shift();
+        if (!r)
+            throw new Error('unexpected extra fetch');
+        return {
+            ok: r.ok ?? true,
+            status: r.status ?? 200,
+            statusText: 'OK',
+            json: async () => ('json' in r ? r.json : {}),
+            text: async () => '',
+        };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const PROJ = { id: 'p1', key: 'ACME', name: 'Acme', description: null, status: 'active' };
+describe('orboto_update_project', () => {
+    it('PATCHes only the supplied fields', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: { ...PROJ, description: 'A new description.' } },
+        ]);
+        const res = await makeUpdateProjectHandler(client)({
+            projectKey: 'ACME', patch: { description: 'A new description.' },
+        });
+        expect(calls[1]).toMatchObject({
+            method: 'PATCH',
+            url: 'https://orboto.example.com/projects/p1',
+            body: { description: 'A new description.' },
+        });
+        expect(res.structuredContent).toMatchObject({
+            key: 'ACME', description: 'A new description.',
+        });
+    });
+    it('passes null for description to clear it', async () => {
+        const calls = stub([
+            { json: { ...PROJ, description: 'old' } },
+            { json: { ...PROJ, description: null } },
+        ]);
+        await makeUpdateProjectHandler(client)({
+            projectKey: 'ACME', patch: { description: null },
+        });
+        expect(calls[1].body).toEqual({ description: null });
+    });
+    it('passes status + name together when both are in the patch', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: { ...PROJ, name: 'Acme Renamed', status: 'archived' } },
+        ]);
+        const res = await makeUpdateProjectHandler(client)({
+            projectKey: 'ACME', patch: { name: 'Acme Renamed', status: 'archived' },
+        });
+        expect(calls[1].body).toEqual({ name: 'Acme Renamed', status: 'archived' });
+        expect(res.structuredContent).toMatchObject({ name: 'Acme Renamed', status: 'archived' });
+    });
+    it('surfaces a 403 on PATCH as OrbotoApiError', async () => {
+        stub([
+            { json: PROJ },
+            { ok: false, status: 403, json: { error: 'forbidden' } },
+        ]);
+        await expect(makeUpdateProjectHandler(client)({
+            projectKey: 'ACME', patch: { description: 'whatever' },
+        })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+    it('throws a clear error when the project key is unknown', async () => {
+        stub([
+            { ok: false, status: 404, json: { error: 'not found' } },
+        ]);
+        await expect(makeUpdateProjectHandler(client)({
+            projectKey: 'GHOST', patch: { description: 'x' },
+        })).rejects.toThrow(/Project "GHOST" not found/);
+    });
+});
+describe('orboto_create_project', () => {
+    it('POSTs name + key when both supplied', async () => {
+        const calls = stub([
+            { json: { id: 'new1', key: 'ACME', name: 'Acme', description: null, status: 'active' } },
+        ]);
+        const res = await makeCreateProjectHandler(client)({ name: 'Acme', key: 'ACME' });
+        expect(calls[0]).toMatchObject({
+            method: 'POST',
+            url: 'https://orboto.example.com/projects',
+            body: { name: 'Acme', key: 'ACME' },
+        });
+        expect(res.structuredContent).toMatchObject({ key: 'ACME', name: 'Acme', status: 'active' });
+    });
+    it('omits optional fields when not supplied so the API auto-derives the key', async () => {
+        const calls = stub([
+            { json: { id: 'new2', key: 'NN', name: 'No Name', description: null, status: 'active' } },
+        ]);
+        await makeCreateProjectHandler(client)({ name: 'No Name' });
+        expect(calls[0].body).toEqual({ name: 'No Name' });
+    });
+    it('passes description + customerId through verbatim', async () => {
+        const calls = stub([
+            { json: { id: 'new3', key: 'CUS', name: 'Custom', description: 'hello', status: 'active' } },
+        ]);
+        await makeCreateProjectHandler(client)({
+            name: 'Custom', description: 'hello', customerId: '11111111-2222-3333-4444-555555555555',
+        });
+        expect(calls[0].body).toEqual({
+            name: 'Custom',
+            description: 'hello',
+            customerId: '11111111-2222-3333-4444-555555555555',
+        });
+    });
+    it('surfaces a 409 (duplicate key) as OrbotoApiError', async () => {
+        stub([
+            { ok: false, status: 409, json: { error: 'project key already exists' } },
+        ]);
+        await expect(makeCreateProjectHandler(client)({ name: 'Dup', key: 'ACME' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+    it('surfaces a 403 as OrbotoApiError', async () => {
+        stub([
+            { ok: false, status: 403, json: { error: 'forbidden' } },
+        ]);
+        await expect(makeCreateProjectHandler(client)({ name: 'NoPerms' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});
+describe('orboto_archive_project', () => {
+    it('resolves the project, then PATCHes status=archived', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: { ...PROJ, status: 'archived' } },
+        ]);
+        const res = await makeArchiveProjectHandler(client)({ projectKey: 'ACME' });
+        expect(calls[0].url).toContain('/projects/by-key/ACME');
+        expect(calls[1]).toMatchObject({
+            method: 'PATCH',
+            url: 'https://orboto.example.com/projects/p1',
+            body: { status: 'archived' },
+        });
+        expect(res.structuredContent).toMatchObject({ status: 'archived', alreadyArchived: false });
+    });
+    it('is idempotent - short-circuits with no PATCH when already archived', async () => {
+        const calls = stub([
+            { json: { ...PROJ, status: 'archived' } },
+        ]);
+        const res = await makeArchiveProjectHandler(client)({ projectKey: 'ACME' });
+        expect(calls).toHaveLength(1); // only the resolve, no PATCH
+        expect(res.content[0].text).toMatch(/already archived/);
+        expect(res.structuredContent).toMatchObject({ alreadyArchived: true });
+    });
+    it('throws a clear error when the project is unknown', async () => {
+        stub([
+            { ok: false, status: 404, json: { error: 'not found' } },
+        ]);
+        await expect(makeArchiveProjectHandler(client)({ projectKey: 'GHOST' })).rejects.toThrow(/Project "GHOST" not found/);
+    });
+    it('surfaces a 403 on PATCH as OrbotoApiError', async () => {
+        stub([
+            { json: PROJ },
+            { ok: false, status: 403, json: { error: 'forbidden' } },
+        ]);
+        await expect(makeArchiveProjectHandler(client)({ projectKey: 'ACME' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});

package/dist/tools/wiki.js

@@ -0,0 +1,185 @@
+/**
+ * ORB-855 (LLM-Wiki Phase E) - MCP tools for the LLM-Wiki.
+ *
+ * Thin REST wrappers over the Phase B/C/D routes so an interactive AI
+ * client can ingest sources, query the wiki, lint it, and write back to it
+ * mid-task. No license gate (per the soft-cap pricing model). English-only
+ * descriptions per the skill/MCP English rule.
+ */
+import { z } from 'zod';
+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.',
+    inputSchema: z.object({
+        spaceId: z.string().uuid().describe('Target doc space (find via orboto_list_doc_spaces).'),
+        url: z.string().url().max(2048).describe('Public URL to import.'),
+        parentDocId: z.string().uuid().optional().describe('Nest the source under this doc.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeWikiIngestUrlHandler(client) {
+    return async (input) => {
+        const body = { url: input.url };
+        if (input.parentDocId)
+            body.parentDocId = input.parentDocId;
+        const res = await client.post(`/spaces/${input.spaceId}/docs/ingest-url`, body);
+        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.',
+    inputSchema: z.object({
+        question: z.string().min(1).max(2000).describe('Natural-language question.'),
+        spaceId: z.string().uuid().optional().describe('Scope the search to one space; omit for the whole corpus.'),
+        limit: z.number().int().min(1).max(20).optional().describe('Max source docs to retrieve (default 5).'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeWikiAskHandler(client) {
+    return async (input) => {
+        const body = { question: input.question };
+        if (input.spaceId)
+            body.spaceId = input.spaceId;
+        if (input.limit)
+            body.limit = input.limit;
+        const res = await client.post(`/ai/ask-docs`, body);
+        const cites = res.citations.map((c) => `[${c.index}] ${c.title} - ${c.link}`).join('\n');
+        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.',
+    inputSchema: z.object({
+        spaceId: z.string().uuid().describe('The LLM-Wiki space to lint.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeWikiLintHandler(client) {
+    return async (input) => {
+        const res = await client.post(`/spaces/${input.spaceId}/llm-wiki/lint`, {});
+        const lines = res.issues.length === 0
+            ? ['No open lint issues.']
+            : res.issues.map((i) => `- [${i.kind}] ${i.message}${i.suggestedFix ? ` (fix: ${i.suggestedFix})` : ''}`);
+        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.',
+    inputSchema: z.object({
+        spaceId: z.string().uuid().describe('The wiki space to edit.'),
+        instruction: z.string().min(1).max(4000).describe('What to change, in plain language.'),
+        sourceDocId: z.string().uuid().optional().describe('A source doc to draw content from.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: false },
+};
+export function makeWikiPlanUpdateHandler(client) {
+    return async (input) => {
+        const body = { instruction: input.instruction };
+        if (input.sourceDocId)
+            body.sourceDocId = input.sourceDocId;
+        const res = await client.post(`/spaces/${input.spaceId}/docs/plan-update`, body);
+        const ops = res.ops.map((o, i) => `${i + 1}. ${o.op} ${o.title ?? ''} - ${o.summary}`).join('\n');
+        return text(`Plan ${res.planId} (expires ${res.expiresAt}):\n${ops}\n\nApply with orboto_wiki_apply_plan(planId).`, { planId: res.planId, ops: res.ops, expiresAt: res.expiresAt });
+    };
+}
+export const wikiApplyPlanToolConfig = {
+    title: 'Apply a previously-planned wiki edit',
+    description: 'Commit the page operations from a plan created by orboto_wiki_plan_update. Applies every op atomically (each page edit is snapshotted for rollback). Fails with 410 if the plan has expired (>15 min) or was already applied. Wraps POST /spaces/:id/docs/apply-plan.',
+    inputSchema: z.object({
+        spaceId: z.string().uuid(),
+        planId: z.string().uuid().describe('The planId returned by orboto_wiki_plan_update.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeWikiApplyPlanHandler(client) {
+    return async (input) => {
+        const res = await client.post(`/spaces/${input.spaceId}/docs/apply-plan`, { planId: input.planId });
+        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.',
+    inputSchema: z.object({
+        spaceId: z.string().uuid(),
+        instruction: z.string().min(1).max(4000).describe('What to record, in plain language.'),
+        sourceDocId: z.string().uuid().optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeWikiRecordHandler(client) {
+    return async (input) => {
+        const planBody = { instruction: input.instruction };
+        if (input.sourceDocId)
+            planBody.sourceDocId = input.sourceDocId;
+        const plan = await client.post(`/spaces/${input.spaceId}/docs/plan-update`, planBody);
+        const applied = await client.post(`/spaces/${input.spaceId}/docs/apply-plan`, { planId: plan.planId });
+        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.',
+    inputSchema: z.object({
+        docId: z.string().min(1).describe('The page to append to - UUID or doc key (ORB-D12 / DOC-5).'),
+        content: z.string().min(1).max(50_000).describe('Markdown section to append.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeWikiAppendSectionHandler(client) {
+    return async (input) => {
+        input.docId = await resolveDocId(client, input.docId);
+        const res = await client.post(`/docs/${input.docId}/append-section`, { content: input.content });
+        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.',
+    inputSchema: z.object({
+        spaceId: z.string().uuid(),
+        question: z.string().min(3).max(1000),
+        answer: z.string().min(1).max(50_000),
+        title: z.string().max(200).optional().describe('Page title; defaults to the question.'),
+        parentDocId: z.string().uuid().optional(),
+        citations: z.array(z.object({ docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'), title: z.string() })).max(50).optional().describe('Cited docs to smart-link (from orboto_wiki_ask).'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeWikiSaveAnswerHandler(client) {
+    return async (input) => {
+        const res = await client.post(`/ai/save-answer-to-wiki`, { ...input, citations: input.citations ?? [] });
+        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.',
+    inputSchema: z.object({
+        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+        stale: z.boolean().optional().describe('true to flag (default), false to clear.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeWikiFlagStaleHandler(client) {
+    return async (input) => {
+        input.docId = await resolveDocId(client, input.docId);
+        const res = await client.post(`/docs/${input.docId}/flag-stale`, { stale: input.stale ?? true });
+        return text(res.staleFlagged ? 'Page flagged as possibly outdated.' : 'Stale flag cleared.', { staleFlagged: res.staleFlagged });
+    };
+}

package/dist/tools/wiki.test.js

@@ -0,0 +1,104 @@
+/**
+ * ORB-855 (LLM-Wiki Phase E) - wiki MCP tool tests. The injector is a
+ * stubbed fetch; we assert each tool hits the right route with the right
+ * body and renders a sensible result, plus one error-path per surface.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { makeWikiIngestUrlHandler, makeWikiAskHandler, makeWikiLintHandler, makeWikiPlanUpdateHandler, makeWikiApplyPlanHandler, makeWikiRecordHandler, makeWikiAppendSectionHandler, makeWikiFlagStaleHandler, makeWikiSaveAnswerHandler, } from './wiki.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stubJSON(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({ url: url.toString(), method: init?.method ?? 'GET', body: typeof init?.body === 'string' ? JSON.parse(init.body) : init?.body });
+        const r = responses.shift();
+        if (!r)
+            throw new Error('unexpected extra fetch');
+        return { ok: r.ok ?? true, status: r.status ?? 200, statusText: 'OK', json: async () => ('json' in r ? r.json : {}), text: async () => '' };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const SPACE = 's0000000-0000-0000-0000-000000000001';
+const DOC = 'd0000000-0000-0000-0000-000000000001';
+describe('orboto_wiki_ingest_url', () => {
+    it('POSTs to ingest-url and reports the new source', async () => {
+        const calls = stubJSON([{ status: 201, json: { docId: DOC, title: 'Imported' } }]);
+        const res = await makeWikiIngestUrlHandler(client)({ spaceId: SPACE, url: 'https://example.com/a' });
+        expect(calls[0]).toMatchObject({ method: 'POST', url: `https://orboto.example.com/spaces/${SPACE}/docs/ingest-url`, body: { url: 'https://example.com/a' } });
+        expect(res.content[0].text).toContain('Imported');
+    });
+});
+describe('orboto_wiki_ask', () => {
+    it('POSTs to /ai/ask-docs and renders citations', async () => {
+        stubJSON([{ json: { answer: 'It uses MVCC.', citations: [{ index: 1, title: 'Concurrency', link: '/spaces/x/docs/y' }], mode: 'hybrid' } }]);
+        const res = await makeWikiAskHandler(client)({ question: 'how does concurrency work?' });
+        const txt = res.content[0].text;
+        expect(txt).toContain('It uses MVCC.');
+        expect(txt).toContain('[1] Concurrency');
+    });
+});
+describe('orboto_wiki_lint', () => {
+    it('POSTs to lint and lists issues', async () => {
+        stubJSON([{ json: { issues: [{ kind: 'orphan', message: 'Page X is orphaned', suggestedFix: 'link it', docId: DOC }], detected: 1, resolved: 0 } }]);
+        const res = await makeWikiLintHandler(client)({ spaceId: SPACE });
+        expect(res.content[0].text).toContain('[orphan] Page X is orphaned');
+    });
+    it('propagates a 403 as OrbotoApiError', async () => {
+        stubJSON([{ ok: false, status: 403, json: { error: 'Forbidden' } }]);
+        await expect(makeWikiLintHandler(client)({ spaceId: SPACE })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});
+describe('orboto_wiki_plan_update + apply_plan', () => {
+    it('plan-update returns a planId + op summary', async () => {
+        const calls = stubJSON([{ json: { planId: 'p1', ops: [{ op: 'create', title: 'New', summary: 'add page' }], expiresAt: '2026-01-01T00:15:00Z' } }]);
+        const res = await makeWikiPlanUpdateHandler(client)({ spaceId: SPACE, instruction: 'add a page about X' });
+        expect(calls[0].url).toBe(`https://orboto.example.com/spaces/${SPACE}/docs/plan-update`);
+        expect(res.content[0].text).toContain('Plan p1');
+    });
+    it('apply-plan reports touched docs', async () => {
+        stubJSON([{ json: { touchedDocs: [DOC] } }]);
+        const res = await makeWikiApplyPlanHandler(client)({ spaceId: SPACE, planId: 'p1' });
+        expect(res.content[0].text).toContain('1 page(s) updated');
+    });
+    it('apply-plan surfaces a 410 expired plan as OrbotoApiError', async () => {
+        stubJSON([{ ok: false, status: 410, json: { error: 'Plan has expired' } }]);
+        await expect(makeWikiApplyPlanHandler(client)({ spaceId: SPACE, planId: 'p1' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});
+describe('orboto_wiki_record', () => {
+    it('chains plan-update then apply-plan', async () => {
+        const calls = stubJSON([
+            { json: { planId: 'p2' } },
+            { json: { touchedDocs: [DOC] } },
+        ]);
+        const res = await makeWikiRecordHandler(client)({ spaceId: SPACE, instruction: 'note that X happened' });
+        expect(calls[0].url).toContain('/plan-update');
+        expect(calls[1].url).toContain('/apply-plan');
+        expect(res.content[0].text).toContain('1 page(s) updated');
+    });
+});
+describe('orboto_wiki_append_section', () => {
+    it('reports a no-op when nothing was appended', async () => {
+        stubJSON([{ json: { appended: false } }]);
+        const res = await makeWikiAppendSectionHandler(client)({ docId: DOC, content: 'x' });
+        expect(res.content[0].text).toMatch(/already present/);
+    });
+});
+describe('orboto_wiki_save_answer', () => {
+    it('POSTs to save-answer-to-wiki and reports created vs updated', async () => {
+        const calls = stubJSON([{ json: { docId: DOC, created: true } }]);
+        const res = await makeWikiSaveAnswerHandler(client)({ spaceId: SPACE, question: 'how?', answer: 'like this' });
+        expect(calls[0]).toMatchObject({ method: 'POST', url: 'https://orboto.example.com/ai/save-answer-to-wiki', body: { spaceId: SPACE, question: 'how?', answer: 'like this', citations: [] } });
+        expect(res.content[0].text).toMatch(/new wiki page/);
+    });
+});
+describe('orboto_wiki_flag_stale', () => {
+    it('defaults stale=true and reports the flag', async () => {
+        const calls = stubJSON([{ json: { staleFlagged: true } }]);
+        const res = await makeWikiFlagStaleHandler(client)({ docId: DOC });
+        expect(calls[0]).toMatchObject({ method: 'POST', url: `https://orboto.example.com/docs/${DOC}/flag-stale`, body: { stale: true } });
+        expect(res.content[0].text).toMatch(/outdated/);
+    });
+});

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

@@ -0,0 +1,150 @@
+/**
+ * ORB-1613 - unit tests for orboto_work_next, the collision-aware dispatch
+ * pull. Unlike orboto_work_start, this tool never resolves a ticket key
+ * client-side - the `projectKey` is passed straight through to
+ * POST /work-sessions/next, which resolves it server-side. Every test
+ * therefore stubs exactly ONE fetch call.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeWorkNextHandler } from './work-sessions.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({
+            url: url.toString(),
+            method: init?.method ?? 'GET',
+            body: init?.body ? JSON.parse(init.body) : undefined,
+        });
+        const r = responses.shift();
+        if (!r)
+            throw new Error('unexpected extra fetch');
+        return {
+            ok: r.ok ?? true,
+            status: r.status ?? 200,
+            statusText: 'OK',
+            json: async () => ('json' in r ? r.json : {}),
+            text: async () => r.text ?? '',
+        };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const SESSION = {
+    id: 'ws1',
+    ticketId: 't1',
+    role: 'implementation',
+    status: 'active',
+    startedAt: '2026-07-24T10:00:00Z',
+    leaseUntil: '2026-07-24T10:15:00Z',
+    activeTimerId: 'timer1',
+    commitSha: null,
+    ticketKey: 'ACME-42',
+};
+const RESERVED = {
+    session: SESSION,
+    reused: false,
+    rulesHash: 'abc123',
+    rulesUnchanged: false,
+    rules: 'Follow the ticket-first rule.',
+    primer: { markdown: '# Primer\nProject conventions.', totalTokens: 42 },
+    ticket: {
+        ticketKey: 'ACME-42',
+        title: 'Do the thing',
+        description: 'Needs doing.',
+        status: 'TODO',
+        statusName: 'To Do',
+        priority: 'high',
+        type: 'task',
+    },
+    checklists: [],
+    dependencies: { blockedBy: [], blocks: [] },
+    gitHealth: [],
+    siblingSessions: [],
+};
+describe('orboto_work_next', () => {
+    it('reserves the winning candidate and renders the full bundle, sending projectKey straight through', async () => {
+        const calls = stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 3 } }]);
+        const res = await makeWorkNextHandler(client)({ projectKey: 'ACME' });
+        expect(calls).toHaveLength(1);
+        expect(calls[0].method).toBe('POST');
+        expect(calls[0].url).toContain('/work-sessions/next');
+        expect(calls[0].body?.projectKey).toBe('ACME');
+        expect(String(calls[0].body?.agentSessionToken)).toMatch(/^mcp-/);
+        const text = res.content[0].text;
+        expect(text).toContain('Reserved ACME-42');
+        expect(text).toContain('ws1');
+        expect(text).toContain('## Working rules');
+        expect(text).toContain('Follow the ticket-first rule.');
+        expect(text).toContain('## Project primer');
+        expect(text).toContain('## Ticket: ACME-42');
+        expect(text).toContain('Needs doing.');
+        const structured = res.structuredContent;
+        expect(structured.reserved?.ticket.ticketKey).toBe('ACME-42');
+        expect(structured.reason).toBeNull();
+    });
+    it('caches the rules hash across calls and renders "Renewed" on a reused session', async () => {
+        const handler = makeWorkNextHandler(client);
+        stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1 } }]);
+        await handler({ projectKey: 'ACME' });
+        const calls2 = stub([{
+                json: {
+                    reserved: { ...RESERVED, reused: true, rulesUnchanged: true, rules: undefined },
+                    reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1,
+                },
+            }]);
+        const res2 = await handler({ projectKey: 'ACME' });
+        expect(calls2[0].body?.knownRulesHash).toBe('abc123');
+        const text2 = res2.content[0].text;
+        expect(text2).toContain('Unchanged since your last call');
+        expect(text2).toContain('Renewed your existing');
+    });
+    it('renders a structured empty result with a retry hint (all-leased)', async () => {
+        stub([{
+                json: {
+                    reserved: null, reason: 'all-leased', retryAfterSeconds: 420,
+                    earliestFreeAt: '2026-07-24T10:15:00Z', candidatesConsidered: 4,
+                },
+            }]);
+        const res = await makeWorkNextHandler(client)({ projectKey: 'ACME' });
+        expect(res.isError).toBeUndefined();
+        const text = res.content[0].text;
+        expect(text).toContain('all-leased');
+        expect(text).toContain('Retry in ~420s');
+        expect(text).toContain('2026-07-24T10:15:00Z');
+        expect(text).toContain('Candidates considered: 4');
+        const structured = res.structuredContent;
+        expect(structured.reserved).toBeNull();
+        expect(structured.reason).toBe('all-leased');
+        expect(structured.retryAfterSeconds).toBe(420);
+    });
+    it('renders "no derivable ETA" when the API found nothing to derive a hint from', async () => {
+        stub([{
+                json: {
+                    reserved: null, reason: 'none-matching', retryAfterSeconds: null,
+                    earliestFreeAt: null, candidatesConsidered: 0,
+                },
+            }]);
+        const res = await makeWorkNextHandler(client)({ projectKey: 'ACME' });
+        const text = res.content[0].text;
+        expect(text).toContain('none-matching');
+        expect(text).toContain('No derivable ETA');
+        expect(text).not.toContain('Retry in');
+    });
+    it('forwards role, leaseSeconds, and resourceClaims to the API', async () => {
+        const calls = stub([{ json: { reserved: RESERVED, reason: null, retryAfterSeconds: null, earliestFreeAt: null, candidatesConsidered: 1 } }]);
+        await makeWorkNextHandler(client)({
+            projectKey: 'ACME',
+            role: 'review',
+            leaseSeconds: 300,
+            resourceClaims: [{ kind: 'path', value: 'src/**', mode: 'write' }],
+            onConflict: 'queue',
+        });
+        expect(calls[0].body?.role).toBe('review');
+        expect(calls[0].body?.leaseSeconds).toBe(300);
+        expect(calls[0].body?.resourceClaims).toEqual([{ kind: 'path', value: 'src/**', mode: 'write' }]);
+        expect(calls[0].body?.onConflict).toBe('queue');
+    });
+});