@orboto/mcp 0.178.0

package/dist/tools/agent-instructions.js

@@ -0,0 +1,172 @@
+/**
+ * ORB-1089 - MCP tools to manage the configurable coding-agent
+ * working-rule blocks. Mirrors the REST CRUD (admin:ai:read/write
+ * gated server-side; a 403 means the caller's key lacks the slug).
+ * Part of the 4-way sync (REST + MCP + skill + in-app chat).
+ */
+import { z } from 'zod';
+import { sizeBlockResult } from './shared.js';
+// ORB-1819 - the writing contract, verbatim in every write-tool
+// description so the writing agent sees it at the moment of writing.
+const RULE_WRITING_CONTRACT = ' Rule: title = one imperative sentence; body <= 400 chars, Rule / Why / How, no long examples, nothing another block says.';
+// ORB-1700 - a LIST answers "what exists"; the body belongs to the
+// follow-up read (blockId input below). First line, hard-capped.
+function excerptOf(body) {
+    const firstLine = body.split('\n', 1)[0] ?? '';
+    return firstLine.length > 200 ? `${firstLine.slice(0, 199)}\u2026` : firstLine;
+}
+function renderBlock(b) {
+    const flag = b.enabled ? '' : ' [disabled]';
+    const kind = b.builtinKey ? `default:${b.builtinKey}` : 'custom';
+    return `- ${b.title}${flag}  (${kind}, ${b.body.length} chars, id ${b.id})\n  ${excerptOf(b.body)}`;
+}
+export const listAgentInstructionsToolConfig = {
+    title: 'MANAGE the workspace coding-agent rule blocks (admin)',
+    description: 'ADMIN/MANAGEMENT tool - lists the individual rule BLOCKS at a scope (workspace: needs admin:ai:read; project: needs project:edit; personal: your own) so they can be edited/toggled/reordered. This is NOT how you read the rules to follow. To LOAD the rules you must follow as an agent, call orboto_session_start instead - it returns the complete assembled rule set.',
+    inputSchema: z.object({
+        scope: z.enum(['workspace', 'customer', 'project', 'personal']).default('workspace'),
+        projectId: z.string().uuid().optional().describe('Required for scope=project.'),
+        customerId: z.string().uuid().optional().describe('Required for scope=customer.'),
+        blockId: z.string().uuid().optional().describe('Return THIS block with its full body (ORB-1700). Without it the list carries excerpts + contentChars only.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+function scopeQs(scope, projectId, customerId) {
+    const p = new URLSearchParams({ scope });
+    if (projectId)
+        p.set('projectId', projectId);
+    if (customerId)
+        p.set('customerId', customerId);
+    return p.toString();
+}
+export function makeListAgentInstructionsHandler(client) {
+    return async (input = {}) => {
+        const res = await client.get(`/agent-instructions/blocks?${scopeQs(input.scope ?? 'workspace', input.projectId, input.customerId)}`);
+        // ORB-1700 - full body for ONE explicitly named block, in one call.
+        if (input.blockId) {
+            const block = res.blocks.find((b) => b.id === input.blockId);
+            if (!block) {
+                return {
+                    content: [{ type: 'text', text: `No rule block with id ${input.blockId} at this scope.` }],
+                    structuredContent: { block: null },
+                    isError: true,
+                };
+            }
+            return {
+                content: [{ type: 'text', text: `# ${block.title}${block.enabled ? '' : ' [disabled]'}\n\n${block.body}` }],
+                structuredContent: { block },
+            };
+        }
+        // ORB-1700 - list = metadata + excerpt. The assembled 24k rule text is
+        // NOT re-shipped here (it rode along on every management call and cost
+        // 238 Mtok over 3 calls); agents load the rules via orboto_session_start.
+        const text = res.blocks.length
+            ? res.blocks.map(renderBlock).join('\n')
+            : 'No rule blocks configured.';
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: {
+                // Array order = sortOrder; builtinKey only when it is one; the
+                // descriptive TITLE is the excerpt (bodies via blockId).
+                blocks: res.blocks.map((b) => ({
+                    id: b.id,
+                    title: b.title,
+                    enabled: b.enabled,
+                    contentChars: b.body.length,
+                    ...(b.builtinKey ? { builtinKey: b.builtinKey } : {}),
+                })),
+                bodyHint: 'Full body of one block: re-call with blockId. The assembled agent-facing rule set comes from orboto_session_start.',
+            },
+        };
+    };
+}
+export const createAgentInstructionToolConfig = {
+    title: 'Add a custom coding-agent rule block',
+    description: 'Create a custom rule block at a scope: workspace (every agent; admin:ai:write), customer (every project of one customer; customer:write), project (one project; project:edit), or personal (your own). For scope=customer pass customerId; for scope=project pass projectId.'
+        + RULE_WRITING_CONTRACT,
+    inputSchema: z.object({
+        title: z.string().min(1).max(120),
+        body: z.string().min(1).max(8000).describe('The rule text the agent should follow.'),
+        scope: z.enum(['workspace', 'customer', 'project', 'personal']).default('workspace'),
+        projectId: z.string().uuid().optional().describe('Required for scope=project.'),
+        customerId: z.string().uuid().optional().describe('Required for scope=customer.'),
+        enabled: z.boolean().optional(),
+        sortOrder: z.number().int().optional(),
+        allowOversize: z.boolean().optional().describe('Override the hard size-cap block (400*2 chars). Only after a call was blocked.'),
+        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true - why this body genuinely needs the length. Audit-logged.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeCreateAgentInstructionHandler(client) {
+    return async (input) => {
+        const { scope, projectId, customerId, ...body } = input;
+        let row;
+        try {
+            row = await client.post(`/agent-instructions/blocks?${scopeQs(scope ?? 'workspace', projectId, customerId)}`, body);
+        }
+        catch (err) {
+            const blocked = sizeBlockResult(err, 'Rule block create');
+            if (blocked)
+                return blocked;
+            throw err;
+        }
+        const warn = row.sizeWarning ? `\n⚠ ${row.body.length} chars, over the ${row.sizeWarning.limit}-char soft limit. ${row.sizeWarning.hint}` : '';
+        return { content: [{ type: 'text', text: `Created rule block "${row.title}" (id ${row.id}).${warn}` }], structuredContent: row };
+    };
+}
+export const updateAgentInstructionToolConfig = {
+    title: 'Edit / toggle / reorder a coding-agent rule block',
+    description: 'Patch a rule block: title, body, enabled (toggle a rule on/off), or sortOrder. Works on default AND custom blocks (defaults keep their builtinKey and can be reset later). Needs admin:ai:write.'
+        + RULE_WRITING_CONTRACT,
+    inputSchema: z.object({
+        id: z.string().uuid(),
+        title: z.string().min(1).max(120).optional(),
+        body: z.string().min(1).max(8000).optional(),
+        enabled: z.boolean().optional(),
+        sortOrder: z.number().int().optional(),
+        allowOversize: z.boolean().optional().describe('Override the hard size-cap block (400*2 chars). Only after a call was blocked.'),
+        oversizeReason: z.string().min(10).max(500).optional().describe('Required with allowOversize=true - why this body genuinely needs the length. Audit-logged.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeUpdateAgentInstructionHandler(client) {
+    return async (input) => {
+        const { id, ...patch } = input;
+        let row;
+        try {
+            row = await client.patch(`/agent-instructions/blocks/${id}`, patch);
+        }
+        catch (err) {
+            const blocked = sizeBlockResult(err, 'Rule block update');
+            if (blocked)
+                return blocked;
+            throw err;
+        }
+        const warn = row.sizeWarning ? `\n⚠ ${row.body.length} chars, over the ${row.sizeWarning.limit}-char soft limit. ${row.sizeWarning.hint}` : '';
+        return { content: [{ type: 'text', text: `Updated rule block "${row.title}" (enabled: ${row.enabled}).${warn}` }], structuredContent: row };
+    };
+}
+export const resetAgentInstructionToolConfig = {
+    title: 'Reset a default rule block to its shipped text',
+    description: 'Restore a seeded DEFAULT rule block (one with a builtinKey) to the text orboto ships. No-op for custom blocks. Needs admin:ai:write.',
+    inputSchema: z.object({ id: z.string().uuid() }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeResetAgentInstructionHandler(client) {
+    return async (input) => {
+        const row = await client.post(`/agent-instructions/blocks/${input.id}/reset`, {});
+        return { content: [{ type: 'text', text: `Reset rule block "${row.title}" to its default text.` }], structuredContent: row };
+    };
+}
+export const deleteAgentInstructionToolConfig = {
+    title: 'Delete a custom coding-agent rule block',
+    description: 'Delete a CUSTOM rule block. Default (builtin) blocks cannot be deleted - disable them via update instead. Needs admin:ai:write.',
+    inputSchema: z.object({ id: z.string().uuid() }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
+};
+export function makeDeleteAgentInstructionHandler(client) {
+    return async (input) => {
+        await client.delete(`/agent-instructions/blocks/${input.id}`);
+        return { content: [{ type: 'text', text: `Deleted rule block ${input.id}.` }], structuredContent: { id: input.id, deleted: true } };
+    };
+}

package/dist/tools/agent-instructions.test.js

@@ -0,0 +1,124 @@
+/**
+ * ORB-1089 - agent-instruction management MCP tools. Assert the
+ * outgoing wire shape (method + URL + body) against the admin REST
+ * surface, catching shape drift at the unit layer.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeListAgentInstructionsHandler, makeCreateAgentInstructionHandler, makeUpdateAgentInstructionHandler, makeResetAgentInstructionHandler, makeDeleteAgentInstructionHandler, } from './agent-instructions.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 BLOCK = { id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa', builtinKey: null, title: 'Rule', body: 'do the thing', enabled: true, sortOrder: 10 };
+describe('agent-instruction MCP tools (ORB-1089)', () => {
+    it('ORB-1700: list returns metadata + excerpt, never full bodies or the assembled text', async () => {
+        const calls = stubJSON([{ json: { blocks: [BLOCK], assembled: 'do the thing' } }]);
+        const res = await makeListAgentInstructionsHandler(client)();
+        expect(calls[0].method).toBe('GET');
+        expect(calls[0].url).toContain('/agent-instructions/blocks?scope=workspace');
+        const sc = res.structuredContent;
+        expect(sc.assembled).toBeUndefined();
+        expect(sc.blocks[0].body).toBeUndefined();
+        expect(sc.blocks[0].contentChars).toBe(BLOCK.body.length);
+        expect(Object.keys(sc.blocks[0]).sort()).toEqual(['contentChars', 'enabled', 'id', 'title']);
+    });
+    it('ORB-1700: blockId returns the one block with its full body in one call', async () => {
+        stubJSON([{ json: { blocks: [BLOCK], assembled: 'x' } }]);
+        const res = await makeListAgentInstructionsHandler(client)({ blockId: BLOCK.id });
+        const sc = res.structuredContent;
+        expect(sc.block.body).toBe(BLOCK.body);
+    });
+    it('create at project scope carries scope + projectId', async () => {
+        const calls = stubJSON([{ status: 201, json: BLOCK }]);
+        await makeCreateAgentInstructionHandler(client)({ title: 'P', body: 'b', scope: 'project', projectId: '22222222-2222-2222-2222-222222222222' });
+        expect(calls[0].url).toContain('scope=project');
+        expect(calls[0].url).toContain('projectId=22222222-2222-2222-2222-222222222222');
+    });
+    it('create POSTs title + body', async () => {
+        const calls = stubJSON([{ status: 201, json: BLOCK }]);
+        await makeCreateAgentInstructionHandler(client)({ title: 'Rule', body: 'do the thing' });
+        expect(calls[0].method).toBe('POST');
+        expect(calls[0].url).toContain('/agent-instructions/blocks?scope=workspace');
+        expect(calls[0].body).toEqual({ title: 'Rule', body: 'do the thing' });
+    });
+    it('update PATCHes by id without the id in the body', async () => {
+        const calls = stubJSON([{ json: { ...BLOCK, enabled: false } }]);
+        await makeUpdateAgentInstructionHandler(client)({ id: BLOCK.id, enabled: false });
+        expect(calls[0]).toMatchObject({ method: 'PATCH', url: `https://orboto.example.com/agent-instructions/blocks/${BLOCK.id}`, body: { enabled: false } });
+        expect(calls[0].body).not.toHaveProperty('id');
+    });
+    it('reset POSTs to the reset sub-path', async () => {
+        const calls = stubJSON([{ json: BLOCK }]);
+        await makeResetAgentInstructionHandler(client)({ id: BLOCK.id });
+        expect(calls[0]).toMatchObject({ method: 'POST', url: `https://orboto.example.com/agent-instructions/blocks/${BLOCK.id}/reset` });
+    });
+    it('delete DELETEs by id', async () => {
+        const calls = stubJSON([{ json: {} }]);
+        const res = await makeDeleteAgentInstructionHandler(client)({ id: BLOCK.id });
+        expect(calls[0]).toMatchObject({ method: 'DELETE', url: `https://orboto.example.com/agent-instructions/blocks/${BLOCK.id}` });
+        expect(res.structuredContent).toMatchObject({ deleted: true });
+    });
+    // ORB-1819 - the writing-for-tokens size contract, passed through from
+    // the REST route's warn (200 + sizeWarning) / block (422) responses.
+    describe('ORB-1819 size contract', () => {
+        it('create surfaces a soft-limit sizeWarning in the success text, not as an error', async () => {
+            const oversizeBlock = { ...BLOCK, body: 'x'.repeat(450), sizeWarning: { chars: 450, limit: 400, hint: 'move it to a doc' } };
+            stubJSON([{ status: 201, json: oversizeBlock }]);
+            const res = await makeCreateAgentInstructionHandler(client)({ title: 'Long', body: 'x'.repeat(450) });
+            expect(res.isError).toBeUndefined();
+            const text = res.content[0].text;
+            expect(text).toContain('450 chars');
+            expect(text).toContain('move it to a doc');
+        });
+        it('create turns a hard-cap 422 into a non-throwing blocked result carrying the override recipe', async () => {
+            const blockBody = JSON.stringify({
+                error: 'This rule content is 850 characters, over the 800-character hard limit.',
+                errorKey: 'errors.agent_content.oversize',
+                sizeWarning: { chars: 850, limit: 800, hint: 'move it to a doc and keep the doc key here' },
+            });
+            vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({ ok: false, status: 422, statusText: 'Unprocessable', json: async () => ({}), text: async () => blockBody }));
+            const res = await makeCreateAgentInstructionHandler(client)({ title: 'Way too long', body: 'x'.repeat(850) });
+            expect(res.isError).toBe(true);
+            const text = res.content[0].text;
+            expect(text).toContain('850');
+            expect(text).toContain('allowOversize=true');
+            expect(text).toContain('oversizeReason');
+            const sc = res.structuredContent;
+            expect(sc.blocked).toBe(true);
+            expect(sc.sizeWarning.limit).toBe(800);
+        });
+        it('create passes allowOversize + oversizeReason through to the POST body', async () => {
+            const calls = stubJSON([{ status: 201, json: { ...BLOCK, sizeWarning: { chars: 850, limit: 800, hint: 'h' } } }]);
+            await makeCreateAgentInstructionHandler(client)({
+                title: 'Long', body: 'x'.repeat(850), allowOversize: true, oversizeReason: 'genuinely needs the full list',
+            });
+            expect(calls[0].body).toMatchObject({ allowOversize: true, oversizeReason: 'genuinely needs the full list' });
+        });
+        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: 900, limit: 800, hint: 'shorten it' },
+            });
+            vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({ ok: false, status: 422, statusText: 'Unprocessable', json: async () => ({}), text: async () => blockBody }));
+            const res = await makeUpdateAgentInstructionHandler(client)({ id: BLOCK.id, body: 'x'.repeat(900) });
+            expect(res.isError).toBe(true);
+            const sc = res.structuredContent;
+            expect(sc.blocked).toBe(true);
+        });
+    });
+});

package/dist/tools/agent-messages.js

@@ -0,0 +1,75 @@
+/**
+ * ORB-1727 - `orboto_messages`: fetch + ack the caller's agent inbox.
+ *
+ * The store-and-forward half of agent messaging (epic ORB-1726): send via
+ * `orboto_agent_notify` (which now persists a durable inbox row), receive
+ * HERE. While mail is pending, every tool response carries a one-line
+ * pointer to this tool (appended centrally in with-metrics.ts from the
+ * api's `x-orboto-agent-mail` response header - no polling anywhere).
+ */
+import { z } from 'zod';
+import { mcpInstanceToken } from './shared.js';
+export const agentMessagesToolConfig = {
+    title: 'Fetch / acknowledge your agent inbox',
+    description: 'Read the messages other agents sent you while you were not connected (store-and-forward inbox; sending happens via orboto_agent_notify). Default lists UNREAD messages and marks them delivered; pass ackIds to acknowledge messages as read (acked messages stop triggering the pending-mail pointer on tool responses and prune after 30 days). Reply by calling orboto_agent_notify with threadId = the message id you are answering.',
+    inputSchema: z.object({
+        all: z.boolean().default(false).describe('true = include already-read messages'),
+        limit: z.number().int().min(1).max(200).default(50),
+        project: z.string().min(1).max(64).optional().describe('Project key or UUID: narrow to messages scoped to this project PLUS unscoped ones. Pass the project you are working when your identity runs multiple sessions; only ack messages that are yours.'),
+        // ORB-1742 - self-echo exclusion, on by default for MCP sessions.
+        includeOwnSends: z.boolean().default(false).describe('true = ALSO list messages this very session sent (they are hidden by default so a shared identity never wakes itself with its own outbound mail).'),
+        ackIds: z.array(z.string().uuid()).max(200).optional().describe('Message ids to mark as read'),
+    }).shape,
+    outputSchema: z.object({
+        messages: z.array(z.object({
+            id: z.string(),
+            fromUserId: z.string(),
+            kind: z.string(),
+            subject: z.string(),
+            payload: z.record(z.string(), z.unknown()).nullable(),
+            threadId: z.string().nullable(),
+            projectKey: z.string().nullable(),
+            createdAt: z.string(),
+            readAt: z.string().nullable(),
+        })),
+        acked: z.number().int(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeAgentMessagesHandler(client) {
+    return async (args, extra) => {
+        let acked = 0;
+        if (args.ackIds && args.ackIds.length > 0) {
+            const res = await client.post('/v1/agent/messages/ack', { ids: args.ackIds });
+            acked = res.acked;
+        }
+        const q = new URLSearchParams();
+        if (args.all)
+            q.set('all', 'true');
+        if (args.limit)
+            q.set('limit', String(args.limit));
+        if (args.project)
+            q.set('project', args.project);
+        if (!args.includeOwnSends) {
+            q.set('excludeRef', mcpInstanceToken(undefined, extra));
+        }
+        const { messages } = await client.get(`/v1/agent/messages${q.toString() ? `?${q.toString()}` : ''}`);
+        const lines = messages.length === 0
+            ? [acked > 0 ? `Acknowledged ${acked} message(s). Inbox empty.` : 'Inbox empty.']
+            : messages.map((m) => `[${m.kind}]${m.projectKey ? ` [${m.projectKey}]` : ''} ${m.subject} (from ${m.fromUserId}, ${m.createdAt}, id ${m.id}${m.threadId ? `, thread ${m.threadId}` : ''})${m.payload ? ` payload: ${JSON.stringify(m.payload)}` : ''}`);
+        if (messages.length > 0) {
+            lines.push(`Acknowledge with ackIds once handled; reply via orboto_agent_notify with threadId.`);
+        }
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                messages: messages.map((m) => ({
+                    id: m.id, fromUserId: m.fromUserId, kind: m.kind, subject: m.subject,
+                    payload: m.payload, threadId: m.threadId, projectKey: m.projectKey ?? null,
+                    createdAt: m.createdAt, readAt: m.readAt,
+                })),
+                acked,
+            },
+        };
+    };
+}

package/dist/tools/ai-status.js

@@ -0,0 +1,55 @@
+/**
+ * ORB-564 - `orboto_ai_status`.
+ *
+ * Pre-flight check for agents: is the workspace's AI provider configured?
+ * Wraps `GET /ai/status`. Two flags come back - chat features and
+ * embeddings - because Anthropic-only deployments have chat fully
+ * wired but cannot produce embeddings, and RAG-style features
+ * (`ask-docs`, similar-tickets rerank, partial-overlap detection)
+ * need both.
+ *
+ * Today no MCP tool requires AI directly - every `orboto_*` tool is a
+ * thin REST wrapper that does its own thing. The dependency lives on
+ * the skill side (`orboto ask-docs`) and on chat-only LLM calls the
+ * agent host might make. This tool exists so an agent can plan around
+ * the workspace shape before calling those skill shortcuts or before
+ * suggesting AI-gated features to the operator.
+ */
+import { z } from 'zod';
+export const aiStatusToolConfig = {
+    title: 'Check whether the orboto workspace has AI configured',
+    description: 'Pre-flight check for AI-gated operations. Returns two flags: `configured` (chat / completion provider set up - required by `ask-docs`, summarisation, ticket polish, suggest-title, suggest-priority, suggest-labels, translate, NL search, retro generation, daily digest, milestone risk, ticket split) and `embeddingsConfigured` (embedding provider set up - required by RAG features like `ask-docs` and similar-tickets rerank), plus `visionEnabled` (image attachments allowed in AI calls - the `ai_vision_enabled` workspace toggle). Anthropic-only deployments return `embeddingsConfigured: false` because Anthropic does not produce embeddings. Call this before invoking AI-gated skill shortcuts so you can plan around a workspace that has AI disabled.',
+    inputSchema: z.object({}).shape,
+    outputSchema: z.object({
+        configured: z.boolean(),
+        embeddingsConfigured: z.boolean(),
+        visionEnabled: z.boolean(),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeAiStatusHandler(client) {
+    return async () => {
+        const status = await client.get('/ai/status');
+        const visionEnabled = status.visionEnabled ?? false;
+        const lines = [];
+        lines.push(`Chat / completion AI: ${status.configured ? 'configured' : 'NOT configured'}`);
+        lines.push(`Embeddings: ${status.embeddingsConfigured ? 'configured' : 'NOT configured'}`);
+        lines.push(`Vision (image attachments): ${visionEnabled ? 'enabled' : 'disabled'}`);
+        if (!status.configured) {
+            lines.push('');
+            lines.push('AI-gated operations (skill `ask-docs`, summarisation, suggest-*, etc.) will fail with a 400 until the workspace operator configures an AI provider in Admin → AI Settings.');
+        }
+        else if (!status.embeddingsConfigured) {
+            lines.push('');
+            lines.push('RAG features (`ask-docs`, similar-tickets rerank, partial-overlap detection) need an embedding-capable provider - Anthropic-only setups do not have one.');
+        }
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                configured: status.configured,
+                embeddingsConfigured: status.embeddingsConfigured,
+                visionEnabled,
+            },
+        };
+    };
+}

package/dist/tools/ai-status.test.js

@@ -0,0 +1,43 @@
+/**
+ * ORB-564 - `orboto_ai_status` tool mapping test.
+ */
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeAiStatusHandler } from './ai-status.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function mockFetch(json) {
+    return vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+        ok: true, status: 200, statusText: 'OK',
+        json: async () => json,
+    });
+}
+describe('tools/ai-status', () => {
+    const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+    it('reports all flags when fully configured + vision on (ORB-1264)', async () => {
+        mockFetch({ configured: true, embeddingsConfigured: true, visionEnabled: true });
+        const result = await makeAiStatusHandler(client)();
+        expect(result.structuredContent).toEqual({ configured: true, embeddingsConfigured: true, visionEnabled: true });
+        expect(result.content[0].text).toContain('Chat / completion AI: configured');
+        expect(result.content[0].text).toContain('Embeddings: configured');
+        expect(result.content[0].text).toContain('Vision (image attachments): enabled');
+    });
+    it('warns about RAG features when only chat is configured', async () => {
+        mockFetch({ configured: true, embeddingsConfigured: false, visionEnabled: false });
+        const result = await makeAiStatusHandler(client)();
+        expect(result.structuredContent).toEqual({ configured: true, embeddingsConfigured: false, visionEnabled: false });
+        const text = result.content[0].text;
+        expect(text).toContain('Chat / completion AI: configured');
+        expect(text).toContain('Embeddings: NOT configured');
+        expect(text).toContain('Vision (image attachments): disabled');
+        expect(text).toContain('RAG features');
+    });
+    it('treats an older server omitting visionEnabled as disabled', async () => {
+        mockFetch({ configured: false, embeddingsConfigured: false });
+        const result = await makeAiStatusHandler(client)();
+        expect(result.structuredContent).toEqual({ configured: false, embeddingsConfigured: false, visionEnabled: false });
+        const text = result.content[0].text;
+        expect(text).toContain('Chat / completion AI: NOT configured');
+        expect(text).toContain('AI-gated operations');
+    });
+});

package/dist/tools/ai-usage.js

@@ -0,0 +1,68 @@
+/**
+ * ORB-1321 - `orboto_ai_usage`.
+ *
+ * Operator diagnostic for AI *consumption*: total calls / tokens in+out /
+ * errors over a date range, plus per-user, per-operation, and per-day
+ * breakdowns and the AI-Chat slice. Wraps GET /admin/ai/usage.
+ *
+ * Complements the other two AI diagnostics: `orboto_ai_status` says whether AI
+ * is configured; `orboto_embedding_status` covers the embedding pipeline's
+ * health; this one answers "how much are we spending / how many calls are
+ * erroring". Aggregates only (no per-row error text). admin:ai:read gated
+ * (403 for non-admin callers).
+ */
+import { z } from 'zod';
+export const aiUsageToolConfig = {
+    title: 'AI usage (calls / tokens / errors)',
+    description: 'Operator diagnostic for AI consumption over a date range (defaults to the last 30 days). Returns totals (calls, tokens in / out, error count) plus per-user, per-operation and per-day breakdowns and the AI-Chat slice (conversation count + top chat users). Use this to see spend / call volume / which operations run most / how many calls are erroring. Aggregates only - not the per-row error messages. Pair with orboto_embedding_status (pipeline health) and orboto_ai_status (is AI configured). Requires admin:ai:read - 403 for non-admin callers.',
+    inputSchema: z.object({
+        start: z.string().optional().describe('Range start, YYYY-MM-DD (inclusive). Defaults to 30 days ago.'),
+        end: z.string().optional().describe('Range end, YYYY-MM-DD (inclusive). Defaults to today.'),
+    }).shape,
+    outputSchema: z.object({
+        calls: z.number(),
+        tokensIn: z.number(),
+        tokensOut: z.number(),
+        errors: z.number(),
+        chatConversations: z.number(),
+        topOperations: z.array(z.object({ operation: z.string(), calls: z.number() })),
+        topUsers: z.array(z.object({ userName: z.string().nullable(), calls: z.number(), tokensIn: z.number(), tokensOut: z.number() })),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeAiUsageHandler(client) {
+    return async (args) => {
+        const qs = new URLSearchParams();
+        if (args.start)
+            qs.set('start', args.start);
+        if (args.end)
+            qs.set('end', args.end);
+        const suffix = qs.toString() ? `?${qs.toString()}` : '';
+        const u = await client.get(`/admin/ai/usage${suffix}`);
+        const topOps = u.perOperation.slice(0, 8);
+        const topUsers = u.perUser.slice(0, 8);
+        const lines = [];
+        lines.push(`AI usage${args.start || args.end ? ` (${args.start ?? 'start'} → ${args.end ?? 'today'})` : ' (last 30 days)'}`);
+        lines.push(`Totals: ${u.totals.calls} calls · ${u.totals.tokensIn} tokens in · ${u.totals.tokensOut} out · ${u.totals.errors} errors`);
+        if (u.totals.errors > 0) {
+            lines.push(`  ⚠ ${u.totals.errors} call(s) errored - check Admin → AI → Usage (or the ai_usage_log) for the messages; aggregates don't carry them.`);
+        }
+        if (topOps.length)
+            lines.push(`Top operations: ${topOps.map((o) => `${o.operation} (${o.calls})`).join(', ')}`);
+        if (topUsers.length)
+            lines.push(`Top users: ${topUsers.map((x) => `${x.userName ?? 'unknown'} (${x.calls})`).join(', ')}`);
+        lines.push(`AI Chat: ${u.chatConversations} conversation(s)`);
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                calls: u.totals.calls,
+                tokensIn: u.totals.tokensIn,
+                tokensOut: u.totals.tokensOut,
+                errors: u.totals.errors,
+                chatConversations: u.chatConversations,
+                topOperations: topOps,
+                topUsers: topUsers.map((x) => ({ userName: x.userName, calls: x.calls, tokensIn: x.tokensIn, tokensOut: x.tokensOut })),
+            },
+        };
+    };
+}

package/dist/tools/analytics.js

@@ -0,0 +1,72 @@
+/**
+ * ORB-1032 - `orboto_analytics`. One multiplexed read tool over the project
+ * analytics suite + Earned Value, since AI is a main feature. Inherits the
+ * ORB-1031 permission gate: the API returns 403 for reports the caller
+ * can't see (budget / earned-value money mode need budget:view).
+ */
+import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
+import { resolveProjectByKey } from './shared.js';
+import { resolveMilestoneByNameOrId } from './milestones.js';
+const REPORTS = ['overview', 'burndown', 'velocity', 'cycle-time', 'workload', 'budget', 'collaboration', 'earned-value', 'estimation-accuracy', 'flow-time', 'flow-metrics', 'forecast', 'bottleneck'];
+export const analyticsToolConfig = {
+    title: 'Project analytics',
+    description: "Read a project's analytics or Earned Value. `report`: overview, burndown, velocity, cycle-time, workload, budget, collaboration, earned-value, estimation-accuracy, flow-time, flow-metrics, forecast, or bottleneck. `collaboration` classifies tickets human-only / agent-only / mixed from the agent-work stamps (time entries, comments, activities), with agent share of effort per project / milestone / member and a weekly trend - use it for 'who works with agents and what comes out of it' questions; `milestone` scopes it. `bottleneck` shows which status clogs the flow (longest-dwell status + trend), delivery predictability (lead/cycle variance), and the worst-aging open tickets with assignee. `forecast` is a Monte-Carlo delivery forecast (probabilistic 'done by X' date with p50/p85/p95 bands from historical throughput) - reach for it on 'when will this be done / how long for N tickets' questions instead of guessing from cycle time; `milestone` scopes its remaining set. `flow-metrics` gives Kanban flow: current WIP (leaf tickets only - `epicWip`/`epicWipByCategory` report epics separately, `excludedEpicsCount` says how many), weekly throughput, flow efficiency (active vs queue time), aging WIP, and a cumulative flow diagram. `flow-time` shows lead vs cycle vs effort side-by-side as median + p75/p90 (NOT just mean - the legacy cycle-time report's mean hid a 0-day median); sub-day medians round to 0 in the Days fields, so also check the parallel `leadMinutes`/`cycleMinutes` fields for fast-moving cohorts. `estimation-accuracy` is the estimate-vs-actual calibration (multiplier + confidence; degrades through tracked-effort -> cycle-time -> lead-time and reports insufficient rather than inventing a number) - reach for estimation-accuracy + flow-time + forecast for grounded effort/duration answers instead of free-reasoning from cycle time. For `bottleneck`/`flow-time`/`flow-metrics`/`estimation-accuracy`, prefer the `byWorkOrigin`/`cohortsByWorkOrigin`/`predictabilityByWorkOrigin` fields (agent/human/mixed/unknown, derived from WHO actually did the work) over the legacy `byCohort`/`cohorts`/`predictability` fields (agents/humans/combined, derived from account type only) - an agent operating through a human account reads correctly under workOrigin but not under accountType, so the two can disagree on the same ticket set. `unknown` is a real bucket, not a rounding error: it counts tickets with NO agent-work stamp anywhere, and you must read the other three against it - a big `unknown` means the split covers only a slice of the sample. Note also that `is_agent_work` only exists from its migration onward with no backfill, so on a workspace with history predating it the `human` bucket carries pre-stamp rows that nobody actually measured; cross-check a surprising human-heavy split against the `collaboration` weekly trend before drawing a conclusion from it. `milestone` scopes burndown + earned-value + forecast; `mode` (hours|money) applies to earned-value. Requires `analytics:view`; `budget` and the earned-value MONEY mode additionally require `budget:view` (you'll get a permission error otherwise).",
+    inputSchema: z.object({
+        projectKey: z.string().min(1).describe('Project key (e.g. "ORB").'),
+        report: z.enum(REPORTS).describe('Which report to return.'),
+        milestone: z.string().optional().describe('Milestone name (burndown / earned-value / forecast / collaboration).'),
+        mode: z.enum(['hours', 'money']).optional().describe('earned-value unit (default hours). Money needs budget:view.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeAnalyticsHandler(client) {
+    return async (input) => {
+        const project = await resolveProjectByKey(client, input.projectKey);
+        let milestoneId;
+        if (input.milestone && (input.report === 'burndown' || input.report === 'earned-value' || input.report === 'forecast' || input.report === 'collaboration')) {
+            // ORB-1696 - shared resolver: key (ORB-M3), name or UUID, ambiguous
+            // name -> explicit error. Matches create_ticket/set_milestone/OQL.
+            const m = await resolveMilestoneByNameOrId(client, project.id, input.milestone);
+            milestoneId = m.id;
+        }
+        const path = (() => {
+            switch (input.report) {
+                case 'earned-value': {
+                    const qs = new URLSearchParams();
+                    if (milestoneId)
+                        qs.set('milestoneId', milestoneId);
+                    if (input.mode)
+                        qs.set('mode', input.mode);
+                    return `/projects/${project.id}/earned-value${qs.toString() ? `?${qs}` : ''}`;
+                }
+                case 'burndown':
+                    return `/projects/${project.id}/analytics/burndown${milestoneId ? `?milestoneId=${milestoneId}` : ''}`;
+                case 'forecast':
+                    return `/projects/${project.id}/analytics/forecast${milestoneId ? `?milestoneId=${milestoneId}` : ''}`;
+                case 'collaboration':
+                    return `/projects/${project.id}/analytics/collaboration${milestoneId ? `?milestoneId=${milestoneId}` : ''}`;
+                default:
+                    return `/projects/${project.id}/analytics/${input.report}`;
+            }
+        })();
+        let data;
+        try {
+            data = await client.get(path);
+        }
+        catch (err) {
+            if (err instanceof OrbotoApiError && err.status === 403) {
+                const need = input.report === 'budget' || (input.report === 'earned-value' && input.mode === 'money') ? 'budget:view' : 'analytics:view';
+                return {
+                    content: [{ type: 'text', text: `Not permitted: the ${input.report} report needs the ${need} permission on ${project.key}.` }],
+                    structuredContent: { error: 'forbidden', report: input.report, requiredPermission: need },
+                };
+            }
+            throw err;
+        }
+        return {
+            content: [{ type: 'text', text: `${input.report} for ${project.key}:\n${JSON.stringify(data, null, 2)}` }],
+            structuredContent: { report: input.report, projectKey: project.key, data },
+        };
+    };
+}