@orboto/mcp 0.178.0

package/dist/tools/milestones.js

@@ -0,0 +1,279 @@
+/**
+ * ORB-244 Phase B - milestone tools, expanded in ORB-799 with CRUD.
+ *
+ * `orboto_list_milestones` and `orboto_get_milestone` share this file
+ * because they're cheap neighbours (same API root, same resolution
+ * chain). The `get` tool also pulls the `/progress` endpoint so the
+ * model sees ticket-count breakdowns alongside the metadata.
+ *
+ * ORB-799 added the write half of the surface to close wrapper-parity:
+ *
+ *   - orboto_create_milestone - mirrors `orboto.mjs create-milestone`.
+ *     `startDate`/`endDate` are both optional; a milestone without dates
+ *     is a legitimate object (analytics/Gantt/templates treat null dates
+ *     as "no dates").
+ * - orboto_close_milestone - close + optional archive. Resolves the
+ *     milestone by name OR UUID against the includeClosed=true list so
+ *     re-closing an already-closed milestone is idempotent.
+ * - orboto_update_milestone - patch name / dates / private flag.
+ */
+import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
+import { resolveProjectByKey, resolveByName } from './shared.js';
+const UUID_RE = /^[0-9a-f-]{36}$/i;
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+/** ORB-1059 - a milestone key looks like `ORB-M3`. */
+const MILESTONE_KEY_RE = /^[A-Za-z0-9]+-M\d+$/i;
+// ---------------------------------------------------------------------------
+// orboto_list_milestones
+// ---------------------------------------------------------------------------
+export const listMilestonesToolConfig = {
+    title: 'List milestones',
+    description: 'List milestones in a project, newest first.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeListMilestonesHandler(client) {
+    return async ({ projectKey }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        const milestones = await client.get(`/projects/${project.id}/milestones`);
+        const text = milestones.length === 0
+            ? `No milestones in project ${project.key}.`
+            : milestones.map((m) => {
+                const range = [m.startDate, m.endDate].filter(Boolean).join(' → ') || 'no dates';
+                const key = m.milestoneKey ? `${m.milestoneKey} · ` : '';
+                return `- ${key}${m.name} [${m.status}] (${range})`;
+            }).join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: {
+                project: { key: project.key },
+                milestones: milestones.map((m) => ({
+                    // ORB-1179 - surface the uuid alongside the milestone key.
+                    id: m.id,
+                    milestoneKey: m.milestoneKey ?? null,
+                    name: m.name,
+                    status: m.status,
+                    startDate: m.startDate,
+                    endDate: m.endDate,
+                    isPrivate: m.isPrivate,
+                })),
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_get_milestone
+// ---------------------------------------------------------------------------
+export const getMilestoneToolConfig = {
+    title: 'Get milestone details',
+    description: 'Return milestone metadata plus ticket-count breakdown by status (to do / in progress / done / …).',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
+        milestone: z.string().min(1).describe('Key ("ORB-M3"), name, or UUID. Name matching normalises HTML entities/case/whitespace.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeGetMilestoneHandler(client) {
+    return async ({ projectKey, milestone }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        // ORB-1068 - resolve key / name / UUID through the shared resolver
+        // instead of an exact-name find, so `ORB-M19` works here too.
+        const m = await resolveMilestoneByNameOrId(client, project.id, milestone);
+        // Progress comes from a separate endpoint; tolerate 404 gracefully
+        // in case a future API rename drops it so the tool still returns
+        // the metadata half.
+        const progress = await client.get(`/projects/${project.id}/milestones/${m.id}/progress`).catch((err) => {
+            if (err instanceof OrbotoApiError && err.status === 404)
+                return null;
+            throw err;
+        });
+        const lines = [
+            `${m.milestoneKey ? `${m.milestoneKey} · ` : ''}${m.name} [${m.status}]`,
+            `Dates: ${m.startDate ?? '(no start)'} → ${m.endDate ?? '(no end)'}`,
+            m.isPrivate ? 'Private: yes' : null,
+        ].filter((l) => l !== null);
+        if (progress) {
+            const done = progress.byStatus.DONE ?? 0;
+            const inProgress = progress.byStatus.IN_PROGRESS ?? 0;
+            const inReview = progress.byStatus.IN_REVIEW ?? 0;
+            const todo = progress.byStatus.TODO ?? 0;
+            const wontFix = progress.byStatus.WONT_FIX ?? 0;
+            const percent = progress.total > 0 ? Math.round((done / progress.total) * 100) : 0;
+            lines.push('', `Progress: ${percent}% done (${done}/${progress.total})`, `  to do: ${todo} · in progress: ${inProgress} · in review: ${inReview} · won't fix: ${wontFix}`);
+        }
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                milestone: {
+                    id: m.id,
+                    milestoneKey: m.milestoneKey ?? null,
+                    name: m.name,
+                    status: m.status,
+                    startDate: m.startDate,
+                    endDate: m.endDate,
+                    isPrivate: m.isPrivate,
+                },
+                progress,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_create_milestone - ORB-799
+// ---------------------------------------------------------------------------
+export const createMilestoneToolConfig = {
+    title: 'Create a milestone',
+    description: 'Create a milestone in a project. `startDate` + `endDate` are optional - omit them (or pass null) for a milestone with no dates. The caller must have `milestone:create`.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
+        name: z.string().min(1).describe('Milestone name (unique within the project).'),
+        startDate: z.string().regex(DATE_RE).nullable().optional().describe('YYYY-MM-DD or null.'),
+        endDate: z.string().regex(DATE_RE).nullable().optional().describe('YYYY-MM-DD or null.'),
+        isPrivate: z.boolean().optional().describe('Project members only. Default: false.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeCreateMilestoneHandler(client) {
+    return async ({ projectKey, name, startDate, endDate, isPrivate }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        const body = {
+            name,
+            startDate,
+            endDate,
+            isPrivate: isPrivate ?? false,
+        };
+        const created = await client.post(`/projects/${project.id}/milestones`, body);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Created milestone "${created.name}" in ${project.key} (status: ${created.status ?? 'active'}).`,
+                }],
+            structuredContent: {
+                id: created.id,
+                name: created.name,
+                status: created.status,
+                startDate: created.startDate,
+                endDate: created.endDate,
+                isPrivate: created.isPrivate,
+                projectKey: project.key,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_close_milestone - ORB-799
+// ---------------------------------------------------------------------------
+/** Resolve a milestone by name OR UUID against the includeClosed list,
+ *  so closing an already-completed milestone (re-close), archiving a
+ *  completed milestone, and re-pointing a ticket onto any milestone all
+ *  work without the caller pre-fetching. UUID is the unambiguous handle:
+ *  a name that matches more than one milestone throws (listing the
+ *  candidate UUIDs) rather than silently returning the first match
+ *  (ORB-1058). Accepts the human-readable milestone key (`ORB-M3`,
+ *  ORB-1059) as well as name and UUID. */
+export async function resolveMilestoneByNameOrId(client, projectId, nameOrId) {
+    const all = await client.get(`/projects/${projectId}/milestones?includeClosed=true`);
+    if (UUID_RE.test(nameOrId)) {
+        const byId = all.find((x) => x.id === nameOrId);
+        if (!byId) {
+            throw new Error(`No milestone with id "${nameOrId}" in the project (including closed/archived).`);
+        }
+        return byId;
+    }
+    // ORB-1059 - accept the human-readable key (`ORB-M3`), case-insensitive.
+    if (MILESTONE_KEY_RE.test(nameOrId)) {
+        const byKey = all.find((x) => x.milestoneKey?.toLowerCase() === nameOrId.toLowerCase());
+        if (!byKey) {
+            throw new Error(`No milestone with key "${nameOrId}" in the project (including closed/archived).`);
+        }
+        return byKey;
+    }
+    // ORB-1826 - exact (raw) name match wins first; falls back to a unique
+    // normalised match (HTML-entity-decoded, trimmed, whitespace-collapsed,
+    // casefolded) so `"QA & Testing"` resolves against a milestone
+    // literally named `"QA & Testing"`. Ambiguous either way still errors,
+    // listing the candidates.
+    const { match, ambiguous } = resolveByName(all, nameOrId, (m) => m.name);
+    if (ambiguous) {
+        const list = ambiguous.map((m) => `"${m.name}" (${m.id})`).join(', ');
+        throw new Error(`Milestone name "${nameOrId}" is ambiguous - ${ambiguous.length} milestones match: ${list}. Pass the milestone's UUID instead.`);
+    }
+    if (!match) {
+        throw new Error(`Milestone "${nameOrId}" not found in the project (including closed/archived).`);
+    }
+    return match;
+}
+export const closeMilestoneToolConfig = {
+    title: 'Close (or archive) a milestone',
+    description: 'Move a milestone to `completed` (default) or `archived` (pass `archive=true`). Looks up the milestone by name or UUID, including already-closed ones, so re-closing is idempotent. Useful when a release ships and you want to lock the milestone but keep the tickets on it.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1),
+        milestone: z.string().min(1).describe('Milestone name or UUID.'),
+        archive: z.boolean().optional().describe('Set true to archive (status=archived) instead of merely completing.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeCloseMilestoneHandler(client) {
+    return async ({ projectKey, milestone, archive }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        const found = await resolveMilestoneByNameOrId(client, project.id, milestone);
+        const target = archive ? 'archived' : 'completed';
+        const updated = await client.patch(`/projects/${project.id}/milestones/${found.id}`, { status: target });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Milestone "${updated.name}" → ${updated.status}.`,
+                }],
+            structuredContent: {
+                id: updated.id,
+                name: updated.name,
+                status: updated.status,
+                projectKey: project.key,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_update_milestone - ORB-799
+// ---------------------------------------------------------------------------
+export const updateMilestoneToolConfig = {
+    title: 'Update a milestone\'s fields',
+    description: 'Patch a milestone (`name`, `customerSummary`, `startDate`, `endDate`, `isPrivate`). At least one field must be set. `customerSummary` is the customer-facing text shown in the customer project report instead of any internal text. Use `orboto_close_milestone` to flip status to completed/archived - this tool intentionally does NOT touch the status field so closing remains a clear semantic operation.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1),
+        milestone: z.string().min(1).describe('Milestone name or UUID to identify the target.'),
+        patch: z.object({
+            name: z.string().min(1).optional(),
+            customerSummary: z.string().max(2000).nullable().optional().describe('Customer-facing summary shown in the customer report instead of internal text.'),
+            startDate: z.string().regex(DATE_RE).nullable().optional(),
+            endDate: z.string().regex(DATE_RE).nullable().optional(),
+            isPrivate: z.boolean().optional(),
+        }).refine((p) => Object.keys(p).length > 0, { message: 'patch must include at least one field' }),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeUpdateMilestoneHandler(client) {
+    return async ({ projectKey, milestone, patch }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        const found = await resolveMilestoneByNameOrId(client, project.id, milestone);
+        const updated = await client.patch(`/projects/${project.id}/milestones/${found.id}`, patch);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Updated milestone "${updated.name}" (${Object.keys(patch).join(', ')}).`,
+                }],
+            structuredContent: {
+                id: updated.id,
+                name: updated.name,
+                status: updated.status,
+                startDate: updated.startDate,
+                endDate: updated.endDate,
+                isPrivate: updated.isPrivate,
+                projectKey: project.key,
+            },
+        };
+    };
+}

package/dist/tools/milestones.test.js

@@ -0,0 +1,60 @@
+/**
+ * ORB-1826 - `resolveMilestoneByNameOrId` name-matching coverage.
+ *
+ * Production MCP error log: `Milestone "QA & Testing" not found` for a
+ * milestone literally named "QA & Testing" - the resolver did an exact,
+ * case-sensitive `===` with no entity decode. "Normalise, never reject."
+ */
+import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { resolveMilestoneByNameOrId } from './milestones.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function mockMilestones(rows) {
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({
+        ok: true,
+        status: 200,
+        statusText: 'OK',
+        json: async () => rows,
+        text: async () => JSON.stringify(rows),
+    }));
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const M1_UUID = '11111111-1111-1111-1111-111111111111';
+const M2_UUID = '22222222-2222-2222-2222-222222222222';
+const ROWS = [
+    { id: M1_UUID, projectId: 'p1', name: 'QA & Testing', status: 'active', startDate: null, endDate: null, isPrivate: false, milestoneKey: 'ORB-M98' },
+    { id: M2_UUID, projectId: 'p1', name: 'Launch Readiness', status: 'active', startDate: null, endDate: null, isPrivate: false, milestoneKey: 'ORB-M99' },
+];
+describe('resolveMilestoneByNameOrId', () => {
+    it('resolves an already-clean exact name', async () => {
+        mockMilestones(ROWS);
+        const m = await resolveMilestoneByNameOrId(client, 'p1', 'QA & Testing');
+        expect(m.id).toBe(M1_UUID);
+    });
+    it('resolves an HTML-entity-escaped name to the same milestone', async () => {
+        mockMilestones(ROWS);
+        const m = await resolveMilestoneByNameOrId(client, 'p1', 'QA & Testing');
+        expect(m.id).toBe(M1_UUID);
+    });
+    it('resolves case and whitespace variants', async () => {
+        mockMilestones(ROWS);
+        expect((await resolveMilestoneByNameOrId(client, 'p1', 'qa & testing')).id).toBe(M1_UUID);
+        mockMilestones(ROWS);
+        expect((await resolveMilestoneByNameOrId(client, 'p1', '  QA   &   Testing  ')).id).toBe(M1_UUID);
+    });
+    it('still resolves by key and by UUID', async () => {
+        mockMilestones(ROWS);
+        expect((await resolveMilestoneByNameOrId(client, 'p1', 'orb-m98')).id).toBe(M1_UUID);
+        mockMilestones(ROWS);
+        expect((await resolveMilestoneByNameOrId(client, 'p1', M2_UUID)).id).toBe(M2_UUID);
+    });
+    it('throws not-found for an unknown name', async () => {
+        mockMilestones(ROWS);
+        await expect(resolveMilestoneByNameOrId(client, 'p1', 'Nonexistent')).rejects.toThrow(/not found/);
+    });
+    it('throws ambiguous, listing candidates, when two names normalise to the same key', async () => {
+        mockMilestones([...ROWS, { id: '33333333-3333-3333-3333-333333333333', name: 'qa & testing' }]);
+        await expect(resolveMilestoneByNameOrId(client, 'p1', 'QA & Testing')).rejects.toThrow(/ambiguous/);
+    });
+});

package/dist/tools/my-tickets.js

@@ -0,0 +1,65 @@
+/**
+ * ORB-244 Phase B - `orboto_my_tickets`.
+ *
+ * The caller's own assignments. Maps to
+ * `GET /users/me/assigned-tickets`, which already does the
+ * right thing visibility-wise (only tickets the user can see,
+ * scoped to their project memberships).
+ */
+import { z } from 'zod';
+import { agentTicketListRow } from './shared.js';
+export const myTicketsToolConfig = {
+    title: 'My assigned tickets',
+    description: 'List tickets assigned to the authenticated user, optionally filtered to a status category. Useful when the user says "what am I working on?"',
+    inputSchema: z.object({
+        statusCategory: z
+            .enum(['todo', 'in_progress', 'in_review', 'done', 'wont_fix'])
+            .optional()
+            .describe('Filter to one workflow category. Omit for all non-done.'),
+        limit: z.number().int().min(1).max(50).default(25),
+        verbose: z.boolean().default(false).describe('true = full rows; default is the decision fields only.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+// The API route's `statuses` param is the uppercase LEGACY status
+// enum (TODO/IN_PROGRESS/IN_REVIEW/DONE/WONT_FIX). The MCP tool
+// accepts the lower-case category enum the rest of the surface uses;
+// map here.
+const CATEGORY_TO_LEGACY = {
+    todo: 'TODO',
+    in_progress: 'IN_PROGRESS',
+    in_review: 'IN_REVIEW',
+    done: 'DONE',
+    wont_fix: 'WONT_FIX',
+};
+export function makeMyTicketsHandler(client) {
+    return async (input) => {
+        const qs = new URLSearchParams();
+        qs.set('limit', String(input.limit ?? 25));
+        if (input.statusCategory) {
+            qs.set('statuses', CATEGORY_TO_LEGACY[input.statusCategory]);
+        }
+        else {
+            // Default: exclude done + wont_fix so "what am I working on?"
+            // returns open work rather than a lifetime history.
+            qs.set('statuses', 'TODO,IN_PROGRESS,IN_REVIEW');
+        }
+        const page = await client.get(`/users/me/assigned-tickets?${qs}`);
+        const text = page.items.length === 0
+            ? 'No tickets assigned to you matching that filter.'
+            : page.items.map((t) => {
+                const key = t.ticketKey ?? t.id.slice(0, 8);
+                const due = t.dueDate ? ` (due ${t.dueDate})` : '';
+                return `- [${key}] ${t.title} - ${t.status}, ${t.priority}${due}`;
+            }).join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: {
+                count: page.items.length,
+                hasMore: !!page.nextCursor,
+                // ORB-1699 - shared lean row; verbose restores uuid/labels/minutes.
+                tickets: page.items.map((t) => agentTicketListRow(t, input.verbose ?? false)),
+            },
+        };
+    };
+}

package/dist/tools/personal-facts.js

@@ -0,0 +1,72 @@
+/**
+ * ORB-862 (LLM-Wiki Phase L) - personal AI-preference facts.
+ *
+ * The caller's OWN personal primer facts (communication style, coding
+ * conventions, domain self-description). Privacy-strict: every route is
+ * owner-scoped server-side, so these tools can only ever touch the
+ * authenticated user's own facts - never another user's. English-only.
+ */
+import { z } from 'zod';
+function text(t, structured) {
+    return { content: [{ type: 'text', text: t }], ...(structured ? { structuredContent: structured } : {}) };
+}
+const CATEGORY = z.enum(['tech_stack', 'conventions', 'deployment', 'architecture', 'integrations', 'gotchas', 'commands', 'other']);
+export const personalFactListToolConfig = {
+    title: 'List my personal AI preferences',
+    description: 'List the calling user\'s own personal primer facts (their AI preferences). Privacy-strict - only your own facts, never another user\'s. These load into the project primer for your sessions only when you have enabled the opt-in in Profile -> AI Preferences. Wraps GET /users/me/primer-facts.',
+    inputSchema: z.object({}).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makePersonalFactListHandler(client) {
+    return async () => {
+        const facts = await client.get('/users/me/primer-facts');
+        const body = facts.length === 0 ? 'No personal preferences set.' : facts.map((f) => `- [${f.category}] ${f.key}: ${f.value}`).join('\n');
+        return text(body, { facts });
+    };
+}
+export const personalFactAddToolConfig = {
+    title: 'Add a personal AI preference',
+    description: 'Record a personal primer fact for the calling user (e.g. communication style, coding convention). Owner-scoped. Wraps POST /users/me/primer-facts.',
+    inputSchema: z.object({
+        category: CATEGORY.describe('Closest category (e.g. conventions for communication/coding style).'),
+        key: z.string().min(1).max(100).describe('Short machine-readable key, e.g. "tone".'),
+        value: z.string().min(1).max(4000),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makePersonalFactAddHandler(client) {
+    return async (input) => {
+        const row = await client.post('/users/me/primer-facts', input);
+        return text(`Added personal preference "${row.key}" (id: ${row.id}).`, { id: row.id });
+    };
+}
+export const personalFactUpdateToolConfig = {
+    title: 'Update a personal AI preference',
+    description: 'Update one of the calling user\'s personal primer facts. Owner-scoped - you can only edit your own. Wraps PATCH /users/me/primer-facts/:id.',
+    inputSchema: z.object({
+        id: z.string().uuid(),
+        category: CATEGORY.optional(),
+        key: z.string().min(1).max(100).optional(),
+        value: z.string().min(1).max(4000).optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makePersonalFactUpdateHandler(client) {
+    return async (input) => {
+        const { id, ...body } = input;
+        const row = await client.patch(`/users/me/primer-facts/${id}`, body);
+        return text(`Updated personal preference "${row.key}".`, { id: row.id });
+    };
+}
+export const personalFactDeleteToolConfig = {
+    title: 'Delete a personal AI preference',
+    description: 'Delete one of the calling user\'s personal primer facts. Owner-scoped. Wraps DELETE /users/me/primer-facts/:id.',
+    inputSchema: z.object({ id: z.string().uuid() }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makePersonalFactDeleteHandler(client) {
+    return async (input) => {
+        await client.delete(`/users/me/primer-facts/${input.id}`);
+        return text('Deleted.', { deleted: true });
+    };
+}

package/dist/tools/personal-facts.test.js

@@ -0,0 +1,45 @@
+/**
+ * ORB-862 - personal-fact MCP tools route to the owner-scoped endpoints.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makePersonalFactListHandler, makePersonalFactAddHandler, makePersonalFactUpdateHandler, makePersonalFactDeleteHandler, } from './personal-facts.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 ID = 'p0000000-0000-0000-0000-000000000001';
+describe('personal-fact MCP tools (ORB-862)', () => {
+    it('list hits GET /users/me/primer-facts', async () => {
+        const calls = stubJSON([{ json: [{ id: ID, category: 'conventions', key: 'tone', value: 'terse' }] }]);
+        const res = await makePersonalFactListHandler(client)();
+        expect(calls[0].url).toBe('https://orboto.example.com/users/me/primer-facts');
+        expect(res.content[0].text).toContain('tone: terse');
+    });
+    it('add POSTs the fact', async () => {
+        const calls = stubJSON([{ status: 201, json: { id: ID, key: 'tone' } }]);
+        await makePersonalFactAddHandler(client)({ category: 'conventions', key: 'tone', value: 'terse' });
+        expect(calls[0]).toMatchObject({ method: 'POST', url: 'https://orboto.example.com/users/me/primer-facts', body: { category: 'conventions', key: 'tone', value: 'terse' } });
+    });
+    it('update PATCHes by id', async () => {
+        const calls = stubJSON([{ json: { id: ID, key: 'tone' } }]);
+        await makePersonalFactUpdateHandler(client)({ id: ID, value: 'very terse' });
+        expect(calls[0]).toMatchObject({ method: 'PATCH', url: `https://orboto.example.com/users/me/primer-facts/${ID}`, body: { value: 'very terse' } });
+    });
+    it('delete DELETEs by id', async () => {
+        const calls = stubJSON([{ status: 204 }]);
+        const res = await makePersonalFactDeleteHandler(client)({ id: ID });
+        expect(calls[0]).toMatchObject({ method: 'DELETE', url: `https://orboto.example.com/users/me/primer-facts/${ID}` });
+        expect(res.content[0].text).toBe('Deleted.');
+    });
+});