@orboto/mcp 0.178.0

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

@@ -0,0 +1,353 @@
+/**
+ * ORB-510 / ORB-513 - primer-fact tool tests.
+ *
+ * Each tool is a thin wrapper around a REST endpoint, so the tests
+ * pin the wire shape: correct HTTP method, URL with key→UUID
+ * resolution, JSON body fields, and the source-coercion contract for
+ * the `add` tool's `observed` flag.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makePrimerFactListHandler, makePrimerFactAddHandler, makePrimerFactUpdateHandler, makePrimerFactSupersedeHandler, makePrimerFactVerifyHandler, makePrimerFactDeleteHandler, primerFactAddToolConfig, primerFactSupersedeToolConfig, primerFactListToolConfig, } from './primer-facts.js';
+import { z } from 'zod';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        const u = url.toString();
+        const m = init?.method ?? 'GET';
+        const b = init?.body ? JSON.parse(init.body) : undefined;
+        calls.push({ url: u, method: m, body: b });
+        const r = responses.shift();
+        if (!r)
+            throw new Error(`unexpected extra fetch ${m} ${u}`);
+        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 projectStub = { id: 'p-uuid-1234', key: 'ORB', name: 'orboto', description: null, status: 'active' };
+const factStub = {
+    id: 'f-uuid-1111',
+    projectId: 'p-uuid-1234',
+    category: 'tech_stack',
+    key: 'package-manager',
+    value: 'pnpm 9',
+    source: 'manual',
+    verified: false,
+    verifiedBy: null,
+    verifiedAt: null,
+    lastVerifiedAt: '2026-04-30T10:00:00Z',
+    supersededById: null,
+    createdBy: 'u-uuid-1',
+    createdAt: '2026-04-30T10:00:00Z',
+    updatedAt: '2026-04-30T10:00:00Z',
+};
+// ---------------------------------------------------------------------------
+// orboto_primer_fact_list
+// ---------------------------------------------------------------------------
+describe('orboto_primer_fact_list', () => {
+    it('resolves projectKey then GETs /projects/<id>/primer-facts with filters', async () => {
+        const calls = stub([
+            { json: projectStub },
+            {
+                json: [
+                    factStub,
+                    {
+                        ...factStub,
+                        id: 'f-2',
+                        projectId: null,
+                        category: 'conventions',
+                        key: 'branching',
+                        value: 'develop -> release',
+                    },
+                ],
+            },
+        ]);
+        const res = await makePrimerFactListHandler(client)({
+            projectKey: 'ORB',
+            category: 'tech_stack',
+            verified: false,
+            includeWorkspace: true,
+        });
+        expect(calls[0].url).toContain('/projects/by-key/ORB');
+        expect(calls[1].url).toContain(`/projects/${projectStub.id}/primer-facts?`);
+        expect(calls[1].url).toContain('category=tech_stack');
+        expect(calls[1].url).toContain('verified=false');
+        expect(calls[1].url).toContain('includeWorkspace=true');
+        expect(calls[1].method).toBe('GET');
+        const text = res.content[0].text;
+        expect(text).toContain('[project]');
+        expect(text).toContain('[workspace]');
+        expect(text).toContain('tech_stack/package-manager');
+        expect(text).toContain('conventions/branching');
+    });
+    it('defaults includeWorkspace to true on the wire', async () => {
+        const calls = stub([
+            { json: projectStub },
+            { json: [] },
+        ]);
+        await makePrimerFactListHandler(client)({ projectKey: 'ORB' });
+        expect(calls[1].url).toContain('includeWorkspace=true');
+    });
+    it('renders an empty-state message when no facts match', async () => {
+        stub([
+            { json: projectStub },
+            { json: [] },
+        ]);
+        const res = await makePrimerFactListHandler(client)({ projectKey: 'ORB' });
+        expect(res.content[0].text).toBe('No primer facts in scope.');
+    });
+    it('rewrites a 403 into a permission-clarifying error', async () => {
+        stub([
+            { json: projectStub },
+            { ok: false, status: 403, json: { error: 'Forbidden' } },
+        ]);
+        await expect(makePrimerFactListHandler(client)({ projectKey: 'ORB' })).rejects.toThrow(/project:edit|admin:ai:write/);
+    });
+    it('input schema rejects an unknown category', () => {
+        const schema = z.object(primerFactListToolConfig.inputSchema);
+        const result = schema.safeParse({ projectKey: 'ORB', category: 'nonsense' });
+        expect(result.success).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// orboto_primer_fact_add
+// ---------------------------------------------------------------------------
+describe('orboto_primer_fact_add', () => {
+    it('observed=false (default) sends source=manual', async () => {
+        const calls = stub([
+            { json: projectStub },
+            { json: factStub },
+        ]);
+        await makePrimerFactAddHandler(client)({
+            projectKey: 'ORB',
+            category: 'tech_stack',
+            key: 'package-manager',
+            value: 'pnpm 9',
+        });
+        expect(calls[1].method).toBe('POST');
+        expect(calls[1].url).toContain(`/projects/${projectStub.id}/primer-facts`);
+        expect(calls[1].body).toMatchObject({
+            category: 'tech_stack',
+            key: 'package-manager',
+            value: 'pnpm 9',
+            source: 'manual',
+        });
+    });
+    it('observed=true sends source=agent_observed', async () => {
+        const calls = stub([
+            { json: projectStub },
+            { json: { ...factStub, source: 'agent_observed' } },
+        ]);
+        await makePrimerFactAddHandler(client)({
+            projectKey: 'ORB',
+            category: 'gotchas',
+            key: 'firefox-cors',
+            value: 'Firefox rejects presigned S3 URLs from internal hosts',
+            observed: true,
+        });
+        expect(calls[1].body).toMatchObject({ source: 'agent_observed' });
+    });
+    it('rewrites a 409 into a "use supersede" hint', async () => {
+        stub([
+            { json: projectStub },
+            { ok: false, status: 409, json: { error: 'duplicate', errorKey: 'errors.primer_facts.duplicate_key' } },
+        ]);
+        await expect(makePrimerFactAddHandler(client)({
+            projectKey: 'ORB',
+            category: 'tech_stack',
+            key: 'package-manager',
+            value: 'yarn',
+        })).rejects.toThrow(/orboto_primer_fact_supersede/);
+    });
+    it('input schema rejects an empty key', () => {
+        const schema = z.object(primerFactAddToolConfig.inputSchema);
+        const result = schema.safeParse({
+            projectKey: 'ORB',
+            category: 'tech_stack',
+            key: '',
+            value: 'v',
+        });
+        expect(result.success).toBe(false);
+    });
+    it('input schema rejects an unknown category', () => {
+        const schema = z.object(primerFactAddToolConfig.inputSchema);
+        const result = schema.safeParse({
+            projectKey: 'ORB',
+            category: 'nonsense',
+            key: 'k',
+            value: 'v',
+        });
+        expect(result.success).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// orboto_primer_fact_update
+// ---------------------------------------------------------------------------
+describe('orboto_primer_fact_update', () => {
+    it('PATCHes /primer-facts/<id> with only the provided fields', async () => {
+        const calls = stub([{ json: { ...factStub, value: 'pnpm 10' } }]);
+        await makePrimerFactUpdateHandler(client)({
+            factId: factStub.id,
+            value: 'pnpm 10',
+        });
+        expect(calls[0].method).toBe('PATCH');
+        expect(calls[0].url).toContain(`/primer-facts/${factStub.id}`);
+        expect(calls[0].body).toEqual({ value: 'pnpm 10' });
+    });
+    it('throws when called with no fields to update', async () => {
+        await expect(makePrimerFactUpdateHandler(client)({ factId: factStub.id })).rejects.toThrow(/at least one of/);
+    });
+    it('rewrites a 404 into a "target not found" error', async () => {
+        stub([{ ok: false, status: 404, json: { error: 'Not found' } }]);
+        await expect(makePrimerFactUpdateHandler(client)({ factId: 'missing', value: 'v' })).rejects.toThrow(/not found/);
+    });
+});
+// ---------------------------------------------------------------------------
+// orboto_primer_fact_supersede
+// ---------------------------------------------------------------------------
+describe('orboto_primer_fact_supersede', () => {
+    it('POSTs /primer-facts/<id>/supersede with category + key + value', async () => {
+        const calls = stub([{ json: { ...factStub, id: 'new-uuid', value: 'pnpm 10' } }]);
+        await makePrimerFactSupersedeHandler(client)({
+            oldFactId: factStub.id,
+            category: 'tech_stack',
+            key: 'package-manager',
+            value: 'pnpm 10',
+        });
+        expect(calls[0].method).toBe('POST');
+        expect(calls[0].url).toContain(`/primer-facts/${factStub.id}/supersede`);
+        expect(calls[0].body).toEqual({
+            category: 'tech_stack',
+            key: 'package-manager',
+            value: 'pnpm 10',
+        });
+    });
+    it('input schema rejects missing required fields', () => {
+        const schema = z.object(primerFactSupersedeToolConfig.inputSchema);
+        expect(schema.safeParse({ oldFactId: 'x', category: 'tech_stack', key: 'k' }).success).toBe(false);
+        expect(schema.safeParse({ oldFactId: 'x' }).success).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// orboto_primer_fact_verify
+// ---------------------------------------------------------------------------
+describe('orboto_primer_fact_verify', () => {
+    it('POSTs /primer-facts/<id>/verify with empty body', async () => {
+        const calls = stub([{ json: { ...factStub, verified: true, verifiedBy: 'u1', verifiedAt: 'now' } }]);
+        await makePrimerFactVerifyHandler(client)({ factId: factStub.id });
+        expect(calls[0].method).toBe('POST');
+        expect(calls[0].url).toContain(`/primer-facts/${factStub.id}/verify`);
+        expect(calls[0].body).toEqual({});
+    });
+});
+// ---------------------------------------------------------------------------
+// orboto_primer_fact_delete
+// ---------------------------------------------------------------------------
+describe('orboto_primer_fact_delete', () => {
+    it('DELETEs /primer-facts/<id>', async () => {
+        const calls = stub([{ status: 204 }]);
+        const res = await makePrimerFactDeleteHandler(client)({ factId: factStub.id });
+        expect(calls[0].method).toBe('DELETE');
+        expect(calls[0].url).toContain(`/primer-facts/${factStub.id}`);
+        const text = res.content[0].text;
+        expect(text).toContain('Deleted primer fact');
+    });
+    it('echoes the optional reason in the text output', async () => {
+        stub([{ status: 204 }]);
+        const res = await makePrimerFactDeleteHandler(client)({
+            factId: factStub.id,
+            reason: 'fact was wrong from the start',
+        });
+        const text = res.content[0].text;
+        expect(text).toContain('fact was wrong from the start');
+    });
+    it('rewrites a 404 into a "target not found" error', async () => {
+        stub([{ ok: false, status: 404, json: { error: 'Not found' } }]);
+        await expect(makePrimerFactDeleteHandler(client)({ factId: 'missing' })).rejects.toThrow(/not found/);
+    });
+});
+// ORB-1819 - the writing-for-tokens size contract, passed through from the
+// REST route's warn (200/201 + sizeWarning) / block (422) responses.
+describe('ORB-1819 size contract', () => {
+    it('add surfaces a soft-limit sizeWarning in the success text, not as an error', async () => {
+        stub([
+            { json: projectStub },
+            { status: 201, json: { ...factStub, value: 'x'.repeat(320), sizeWarning: { chars: 320, limit: 300, hint: 'move it to a doc' } } },
+        ]);
+        const res = await makePrimerFactAddHandler(client)({
+            projectKey: 'ORB', category: 'tech_stack', key: 'long-fact', value: 'x'.repeat(320),
+        });
+        expect(res.isError).toBeUndefined();
+        const text = res.content[0].text;
+        expect(text).toContain('320 chars');
+        expect(text).toContain('move it to a doc');
+    });
+    it('add turns a hard-cap 422 into a non-throwing blocked result carrying the override recipe', async () => {
+        const blockBody = JSON.stringify({
+            error: 'oversize', errorKey: 'errors.agent_content.oversize',
+            sizeWarning: { chars: 650, limit: 600, hint: 'move it to a doc and keep the doc key here' },
+        });
+        let call = 0;
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => {
+            call += 1;
+            if (call === 1)
+                return { ok: true, status: 200, statusText: 'OK', json: async () => projectStub, text: async () => '' };
+            return { ok: false, status: 422, statusText: 'Unprocessable', json: async () => ({}), text: async () => blockBody };
+        });
+        const res = await makePrimerFactAddHandler(client)({
+            projectKey: 'ORB', category: 'tech_stack', key: 'way-too-long', value: 'x'.repeat(650),
+        });
+        expect(res.isError).toBe(true);
+        const text = res.content[0].text;
+        expect(text).toContain('650');
+        expect(text).toContain('allowOversize=true');
+        expect(text).toContain('oversizeReason');
+        const sc = res.structuredContent;
+        expect(sc.blocked).toBe(true);
+        expect(sc.sizeWarning.limit).toBe(600);
+    });
+    it('add passes allowOversize + oversizeReason through to the POST body', async () => {
+        const calls = stub([
+            { json: projectStub },
+            { status: 201, json: { ...factStub, sizeWarning: { chars: 650, limit: 600, hint: 'h' } } },
+        ]);
+        await makePrimerFactAddHandler(client)({
+            projectKey: 'ORB', category: 'tech_stack', key: 'k', value: 'x'.repeat(650),
+            allowOversize: true, oversizeReason: 'genuinely needs the full spec',
+        });
+        expect(calls[1].body).toMatchObject({ allowOversize: true, oversizeReason: 'genuinely needs the full spec' });
+    });
+    it('update turns a hard-cap 422 into a non-throwing blocked result', async () => {
+        const blockBody = JSON.stringify({
+            error: 'oversize', errorKey: 'errors.agent_content.oversize',
+            sizeWarning: { chars: 700, limit: 600, hint: 'shorten it' },
+        });
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({ ok: false, status: 422, statusText: 'Unprocessable', json: async () => ({}), text: async () => blockBody }));
+        const res = await makePrimerFactUpdateHandler(client)({ factId: factStub.id, value: 'x'.repeat(700) });
+        expect(res.isError).toBe(true);
+        const sc = res.structuredContent;
+        expect(sc.blocked).toBe(true);
+    });
+    it('supersede turns a hard-cap 422 into a non-throwing blocked result', async () => {
+        const blockBody = JSON.stringify({
+            error: 'oversize', errorKey: 'errors.agent_content.oversize',
+            sizeWarning: { chars: 700, limit: 600, hint: 'shorten it' },
+        });
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({ ok: false, status: 422, statusText: 'Unprocessable', json: async () => ({}), text: async () => blockBody }));
+        const res = await makePrimerFactSupersedeHandler(client)({
+            oldFactId: factStub.id, category: 'tech_stack', key: 'k', value: 'x'.repeat(700),
+        });
+        expect(res.isError).toBe(true);
+        const sc = res.structuredContent;
+        expect(sc.blocked).toBe(true);
+    });
+});

package/dist/tools/project-listings.js

@@ -0,0 +1,116 @@
+/**
+ * ORB-799 - per-project metadata listings.
+ *
+ * Two cheap read tools that round-trip the project-scoped enum tables
+ * agents repeatedly need:
+ *
+ * - orboto_list_ticket_statuses - the workflow's status rows with
+ *     their IDs, categories, colors, and terminal flag. Needed for
+ *     typed-transition flows where the standard `move_ticket` (which
+ *     picks the first status per category) isn't precise enough.
+ *
+ * - orboto_list_labels - the per-project label catalogue with
+ *     colors. Lets agents see what labels exist before calling
+ *     `create_ticket` with a `labels` array (unknown names error).
+ *
+ * Both mirror the wrapper's `statuses <project>` / `labels <project>`
+ * subcommands.
+ */
+import { z } from 'zod';
+import { resolveProjectByKey } from './shared.js';
+// ---------------------------------------------------------------------------
+// orboto_list_ticket_statuses
+// ---------------------------------------------------------------------------
+export const listTicketStatusesToolConfig = {
+    title: 'List a project\'s ticket statuses',
+    description: 'Return the project\'s workflow rows - `{id, name, category, color, sortOrder, isTerminal}`. The `category` is the broad bucket (todo / in_progress / in_review / done / wont_fix); `name` is the workspace\'s display label (e.g. "Code Review"). Use the `id` to do typed transitions through `orboto_update_ticket` when the standard category-based move is too coarse.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeListTicketStatusesHandler(client) {
+    return async ({ projectKey }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        const statuses = await client.get(`/projects/${project.id}/ticket-statuses`);
+        const text = statuses.length === 0
+            ? `No statuses configured for ${project.key}.`
+            : statuses.map((s) => `${s.category.padEnd(12)}  "${s.name}"  ${s.color}  sort=${s.sortOrder}${s.isTerminal ? '  (terminal)' : ''}`).join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: {
+                projectKey: project.key,
+                statuses: statuses.map((s) => ({
+                    id: s.id,
+                    name: s.name,
+                    category: s.category,
+                    color: s.color,
+                    sortOrder: s.sortOrder,
+                    isTerminal: s.isTerminal,
+                })),
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_list_labels
+// ---------------------------------------------------------------------------
+export const listLabelsToolConfig = {
+    title: 'List a project\'s labels',
+    description: 'Return the project\'s label catalogue - `{id, name, color}`. Labels must be referenced by exact name when assigning via `orboto_create_ticket` (the API errors on unknown names rather than auto-creating); use this tool to discover what\'s available before assigning.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeListLabelsHandler(client) {
+    return async ({ projectKey }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        const labels = await client.get(`/projects/${project.id}/labels`);
+        const text = labels.length === 0
+            ? `No labels in ${project.key}.`
+            : labels.map((l) => `${l.name.padEnd(20)}  ${l.color}`).join('\n');
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: {
+                projectKey: project.key,
+                labels: labels.map((l) => ({ id: l.id, name: l.name, color: l.color })),
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_create_label - ORB-1041
+// ---------------------------------------------------------------------------
+export const createLabelToolConfig = {
+    title: 'Create a project label',
+    description: 'Create a label in a project so it can be assigned to tickets. Closes the gap where `orboto_create_ticket` errors on an unknown label name (labels are not auto-created). Idempotent: if a label with the same name already exists, it is returned instead of erroring. Needs project:edit.',
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key (e.g. "ACME").'),
+        name: z.string().min(1).max(100).describe('Label name.'),
+        color: z.string().optional().describe('Hex colour like "#6366f1". Defaults to indigo.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeCreateLabelHandler(client) {
+    return async ({ projectKey, name, color }) => {
+        const project = await resolveProjectByKey(client, projectKey);
+        // Idempotent: return an existing same-name label rather than erroring.
+        const existing = await client.get(`/projects/${project.id}/labels`);
+        const match = existing.find((l) => l.name.toLowerCase() === name.toLowerCase());
+        if (match) {
+            return {
+                content: [{ type: 'text', text: `Label "${match.name}" already exists in ${project.key}.` }],
+                structuredContent: { projectKey: project.key, label: { name: match.name, color: match.color }, alreadyExists: true },
+            };
+        }
+        const body = { name };
+        if (color)
+            body.color = color;
+        const created = await client.post(`/projects/${project.id}/labels`, body);
+        return {
+            content: [{ type: 'text', text: `Created label "${created.name}" (${created.color}) in ${project.key}.` }],
+            structuredContent: { projectKey: project.key, label: { name: created.name, color: created.color } },
+        };
+    };
+}

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

@@ -0,0 +1,106 @@
+/**
+ * ORB-799 - `orboto_list_ticket_statuses` + `orboto_list_labels` tests.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { makeListTicketStatusesHandler, makeListLabelsHandler, makeCreateLabelHandler } from './project-listings.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' });
+        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_list_ticket_statuses', () => {
+    it('renders status rows + structured content', async () => {
+        stub([
+            { json: PROJ },
+            { json: [
+                    { id: 's1', name: 'To Do', category: 'todo', color: '#aaa', sortOrder: 0, isTerminal: false },
+                    { id: 's2', name: 'Done', category: 'done', color: '#0a0', sortOrder: 10, isTerminal: true },
+                ] },
+        ]);
+        const res = await makeListTicketStatusesHandler(client)({ projectKey: 'ACME' });
+        expect(res.content[0].text).toContain('To Do');
+        expect(res.content[0].text).toContain('(terminal)');
+        expect(res.structuredContent).toMatchObject({
+            projectKey: 'ACME',
+            statuses: [
+                { name: 'To Do', category: 'todo', isTerminal: false },
+                { name: 'Done', category: 'done', isTerminal: true },
+            ],
+        });
+    });
+    it('empty project returns helpful text', async () => {
+        stub([{ json: PROJ }, { json: [] }]);
+        const res = await makeListTicketStatusesHandler(client)({ projectKey: 'ACME' });
+        expect(res.content[0].text).toContain('No statuses');
+    });
+    it('surfaces 404 on missing project key', async () => {
+        stub([{ ok: false, status: 404, json: { error: 'not found' } }]);
+        await expect(makeListTicketStatusesHandler(client)({ projectKey: 'NOPE' })).rejects.toThrow(/Project "NOPE" not found/);
+    });
+});
+describe('orboto_list_labels', () => {
+    it('renders label rows + structured content', async () => {
+        stub([
+            { json: PROJ },
+            { json: [
+                    { id: 'l1', name: 'bug', color: '#f00' },
+                    { id: 'l2', name: 'priority', color: '#ff0' },
+                ] },
+        ]);
+        const res = await makeListLabelsHandler(client)({ projectKey: 'ACME' });
+        expect(res.content[0].text).toContain('bug');
+        expect(res.structuredContent).toMatchObject({
+            projectKey: 'ACME',
+            labels: [
+                { name: 'bug', color: '#f00' },
+                { name: 'priority', color: '#ff0' },
+            ],
+        });
+    });
+    it('surfaces an OrbotoApiError on 403', async () => {
+        stub([
+            { json: PROJ },
+            { ok: false, status: 403, json: { error: 'forbidden' } },
+        ]);
+        await expect(makeListLabelsHandler(client)({ projectKey: 'ACME' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});
+describe('orboto_create_label (ORB-1041)', () => {
+    it('creates a new label via POST when the name is free', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: [{ id: 'l1', name: 'bug', color: '#f00' }] }, // existing labels
+            { json: { id: 'l2', name: 'security', color: '#6366f1' } }, // POST result
+        ]);
+        const res = await makeCreateLabelHandler(client)({ projectKey: 'ACME', name: 'security' });
+        const post = calls.find((c) => c.method === 'POST');
+        expect(post.url).toContain('/projects/p1/labels');
+        expect(res.structuredContent).toMatchObject({ projectKey: 'ACME', label: { name: 'security' } });
+    });
+    it('is idempotent: returns the existing label without POSTing', async () => {
+        const calls = stub([
+            { json: PROJ },
+            { json: [{ id: 'l1', name: 'Bug', color: '#f00' }] },
+        ]);
+        const res = await makeCreateLabelHandler(client)({ projectKey: 'ACME', name: 'bug' });
+        expect(calls.some((c) => c.method === 'POST')).toBe(false);
+        expect(res.structuredContent).toMatchObject({ alreadyExists: true, label: { name: 'Bug' } });
+    });
+});

package/dist/tools/query.js

@@ -0,0 +1,65 @@
+/**
+ * ORB-273 Phase F - `orboto_query`.
+ *
+ * Lets the model reach for the OQL DSL when the per-entity list
+ * tools (`orboto_list_tickets`, `orboto_my_tickets`) get too narrow:
+ * combined `assignee + dueDate + label + statusCategory` filters
+ * with explicit ORDER BY are awkward to express through tool
+ * arguments but trivial in OQL. Falls back to JQL syntax via
+ * `syntax: 'jql'` for migrants who copy-pasted a Jira query.
+ *
+ * The endpoint is `POST /query` (ORB-531) which honours PBAC,
+ * cursor-paginates, and rate-limits at 60/min. We expose the
+ * underlying envelope unchanged so a future "give me the next page"
+ * tool can plumb the cursor through.
+ */
+import { z } from 'zod';
+import { ticketLine, agentTicketListRow } from './shared.js';
+export const queryToolConfig = {
+    title: 'Run an OQL / JQL query',
+    description: 'Run a typed OQL (or Jira-shaped JQL) query against the workspace and return matching tickets. '
+        + 'OQL grammar: `field operator value [AND|OR ...] [ORDER BY ...] [LIMIT n]`. '
+        + 'Supported fields: key, status, statusName, statusCategory, priority, type, assignee, reporter, reporterType, assigneeType, labels, milestone, version, project, isPrivate, dueDate, startDate, createdAt, updatedAt, closedAt, estimatedTimeMinutes, loggedMinutes, parentKey. '
+        + 'reporterType / assigneeType are guest|internal - use `reporterType = guest OR assigneeType = guest` to pull up everything reported by or assigned to guests without listing each guest email. '
+        + 'Operators: = != < <= > >= ~ !~ IN IS [NOT] NULL IS [NOT] EMPTY. '
+        + 'Functions: currentUser(), now(), startOfWeek(), endOfWeek(), startOfMonth(), endOfMonth(), daysAgo(n). '
+        + 'Examples: '
+        + '`project = ORB AND assignee = currentUser() AND statusCategory != done`; '
+        + '`priority IN (blocker, high) AND dueDate <= now() ORDER BY dueDate ASC LIMIT 25`; '
+        + '`labels = "bug" AND createdAt >= daysAgo(7)`. '
+        + 'Reach for this tool when per-entity tools (orboto_list_tickets / orboto_my_tickets) cannot express the combined filter.',
+    inputSchema: z.object({
+        oql: z.string().min(1).max(8000).describe('The query string.'),
+        syntax: z.enum(['oql', 'jql']).default('oql').describe('"jql" accepts Jira-flavoured syntax.'),
+        cursor: z.string().optional().describe('Cursor from a previous response.'),
+        limit: z.number().int().min(1).max(100).default(25).describe('Max rows. Default 25.'),
+        verbose: z.boolean().default(false).describe('true = full rows; default is the decision fields only.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeQueryHandler(client) {
+    return async (input) => {
+        const body = {
+            oql: input.oql,
+            syntax: input.syntax ?? 'oql',
+            cursor: input.cursor,
+            limit: input.limit ?? 25,
+        };
+        const page = await client.post('/query', body);
+        const text = page.items.length === 0
+            ? 'No tickets matched.'
+            : page.items.map((t) => `- ${ticketLine(t)}`).join('\n');
+        const moreHint = page.nextCursor
+            ? `\n\n(${page.items.length} shown; pass cursor="${page.nextCursor}" to fetch the next page.)`
+            : '';
+        return {
+            content: [{ type: 'text', text: text + moreHint }],
+            structuredContent: {
+                count: page.items.length,
+                nextCursor: page.nextCursor,
+                // ORB-1699 - shared lean row; verbose restores uuid/labels/minutes.
+                tickets: page.items.map((t) => agentTicketListRow(t, input.verbose ?? false)),
+            },
+        };
+    };
+}