@orboto/mcp 0.178.0

package/dist/tools/docs.test.js

@@ -0,0 +1,365 @@
+/**
+ * ORB-912 - doc-spaces CRUD + list-docs-in-space tool tests.
+ *
+ * Same fetch-stub harness as docs-ai.test.ts. Each test asserts both
+ * the outgoing wire shape (URL + method + body) and the structured
+ * content the model gets back, because the API's response Zod
+ * validator rejects off-shape rows and we want to catch drift at the
+ * unit-test layer rather than against a live API.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { makeCreateDocSpaceHandler, makeUpdateDocSpaceHandler, makeDeleteDocSpaceHandler, makeListDocsInSpaceHandler, makeGetDocHandler, makeCreateDocHandler, makeUpdateDocHandler, makeDeleteDocHandler, makeMoveDocHandler, } from './docs.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 PROJECT_SCOPED_SPACE = {
+    id: '11111111-1111-1111-1111-111111111111',
+    name: 'Backend Runbooks',
+    slug: 'backend-runbooks',
+    description: 'Ops + on-call notes for the API.',
+    icon: '📘',
+    type: 'project',
+    projectId: '22222222-2222-2222-2222-222222222222',
+    isPublic: false,
+};
+describe('orboto_create_doc_space', () => {
+    it('POSTs with name + type + projectId and surfaces the new id', async () => {
+        const calls = stubJSON([{ status: 201, json: PROJECT_SCOPED_SPACE }]);
+        const res = await makeCreateDocSpaceHandler(client)({
+            name: 'Backend Runbooks',
+            type: 'project',
+            projectId: PROJECT_SCOPED_SPACE.projectId,
+            icon: '📘',
+        });
+        expect(calls[0]).toMatchObject({
+            method: 'POST',
+            url: 'https://orboto.example.com/spaces',
+            body: {
+                name: 'Backend Runbooks',
+                type: 'project',
+                projectId: PROJECT_SCOPED_SPACE.projectId,
+                icon: '📘',
+            },
+        });
+        expect(res.content[0].text).toContain('Backend Runbooks');
+        expect(res.structuredContent).toMatchObject({
+            id: PROJECT_SCOPED_SPACE.id,
+            name: 'Backend Runbooks',
+            type: 'project',
+        });
+    });
+    it('resolves a projectKey to the UUID before POSTing (ORB-1042)', async () => {
+        const calls = stubJSON([
+            { json: { id: PROJECT_SCOPED_SPACE.projectId, key: 'ORB', name: 'orboto', status: 'active' } }, // by-key resolve
+            { status: 201, json: PROJECT_SCOPED_SPACE },
+        ]);
+        await makeCreateDocSpaceHandler(client)({ name: 'Backend Runbooks', type: 'project', projectKey: 'ORB' });
+        expect(calls[0].url).toContain('/projects/by-key/ORB');
+        expect(calls[1]).toMatchObject({
+            method: 'POST',
+            url: 'https://orboto.example.com/spaces',
+            body: { name: 'Backend Runbooks', type: 'project', projectId: PROJECT_SCOPED_SPACE.projectId },
+        });
+    });
+    it('errors when type=project and neither projectKey nor projectId is given', async () => {
+        stubJSON([]);
+        await expect(makeCreateDocSpaceHandler(client)({ name: 'Orphan', type: 'project' })).rejects.toThrow(/projectKey/);
+    });
+    it('passes through 403 from the API as OrbotoApiError', async () => {
+        stubJSON([{ ok: false, status: 403, json: { error: 'Only super-admins can create global spaces' } }]);
+        await expect(makeCreateDocSpaceHandler(client)({ name: 'Workspace Wiki', type: 'global' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});
+describe('orboto_update_doc_space', () => {
+    it('PATCHes only the fields the caller passed', async () => {
+        const calls = stubJSON([{ json: { ...PROJECT_SCOPED_SPACE, name: 'API Runbooks' } }]);
+        await makeUpdateDocSpaceHandler(client)({
+            spaceId: PROJECT_SCOPED_SPACE.id,
+            name: 'API Runbooks',
+        });
+        expect(calls[0]).toMatchObject({
+            method: 'PATCH',
+            url: `https://orboto.example.com/spaces/${PROJECT_SCOPED_SPACE.id}`,
+            body: { name: 'API Runbooks' },
+        });
+    });
+    it('refuses no-op calls before hitting the API', async () => {
+        const calls = stubJSON([]);
+        await expect(makeUpdateDocSpaceHandler(client)({ spaceId: PROJECT_SCOPED_SPACE.id })).rejects.toThrow(/at least one field/);
+        expect(calls).toHaveLength(0);
+    });
+});
+describe('orboto_delete_doc_space', () => {
+    it('DELETEs the space id and returns a deleted flag', async () => {
+        const calls = stubJSON([{ status: 204, json: undefined }]);
+        const res = await makeDeleteDocSpaceHandler(client)({ spaceId: PROJECT_SCOPED_SPACE.id });
+        expect(calls[0]).toMatchObject({
+            method: 'DELETE',
+            url: `https://orboto.example.com/spaces/${PROJECT_SCOPED_SPACE.id}`,
+        });
+        expect(res.structuredContent).toMatchObject({ deleted: true });
+    });
+    it('lets a 403 (system-generated space) bubble up', async () => {
+        stubJSON([{ ok: false, status: 403, json: { error: 'This space is auto-generated…' } }]);
+        await expect(makeDeleteDocSpaceHandler(client)({ spaceId: PROJECT_SCOPED_SPACE.id })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});
+describe('orboto_list_docs_in_space', () => {
+    const ROOT = {
+        id: 'a1111111-0000-0000-0000-000000000001',
+        spaceId: PROJECT_SCOPED_SPACE.id,
+        parentDocId: null,
+        title: 'Architecture',
+        content: '...',
+        slug: 'architecture',
+        docKey: 'ORB-D1',
+        visibility: 'workspace',
+        sortOrder: 0,
+        icon: null,
+        updatedAt: '2026-05-17T13:00:00.000Z',
+    };
+    const CHILD = {
+        ...ROOT,
+        id: 'a1111111-0000-0000-0000-000000000002',
+        parentDocId: ROOT.id,
+        title: 'Queue worker retry semantics',
+        sortOrder: 0,
+    };
+    it('renders an indented tree text + flat structured list', async () => {
+        stubJSON([{ json: [CHILD, ROOT] /* deliberately unsorted to verify the local sort */ }]);
+        const res = await makeListDocsInSpaceHandler(client)({ spaceId: PROJECT_SCOPED_SPACE.id });
+        const text = res.content[0].text;
+        expect(text.indexOf('Architecture')).toBeLessThan(text.indexOf('Queue worker'));
+        expect(text).toMatch(/\s\s- .*Queue worker/);
+        const docs = res.structuredContent.docs;
+        expect(docs).toHaveLength(2);
+    });
+    it('surfaces the doc key in the tree text + structured rows (ORB-1004)', async () => {
+        stubJSON([{ json: [ROOT] }]);
+        const res = await makeListDocsInSpaceHandler(client)({ spaceId: PROJECT_SCOPED_SPACE.id });
+        expect(res.content[0].text).toContain('ORB-D1');
+        const docs = res.structuredContent.docs;
+        expect(docs[0].docKey).toBe('ORB-D1');
+    });
+    it('handles the empty-space case without rendering an empty list', async () => {
+        stubJSON([{ json: [] }]);
+        const res = await makeListDocsInSpaceHandler(client)({ spaceId: PROJECT_SCOPED_SPACE.id });
+        expect(res.content[0].text).toContain('No docs');
+        expect(res.structuredContent).toMatchObject({ docs: [] });
+    });
+});
+const DOC = {
+    id: 'd0000000-0000-0000-0000-000000000001',
+    spaceId: PROJECT_SCOPED_SPACE.id,
+    parentDocId: null,
+    title: 'Retry semantics',
+    content: '# Retry semantics\n\n200ms × 2^n.',
+    slug: 'retry-semantics',
+    docKey: 'ORB-D7',
+    visibility: 'workspace',
+    sortOrder: 0,
+    icon: null,
+    updatedAt: '2026-05-17T13:30:00.000Z',
+};
+describe('orboto_get_doc (ORB-1004 key support)', () => {
+    it('fetches by UUID via /docs/:id', async () => {
+        const calls = stubJSON([{ json: DOC }, { json: [] }]);
+        const res = await makeGetDocHandler(client)({ docId: DOC.id });
+        expect(calls[0].url).toBe(`https://orboto.example.com/docs/${DOC.id}`);
+        expect(res.structuredContent.doc.docKey).toBe('ORB-D7');
+    });
+    it('resolves a doc key via /docs/by-key/:key, then backlinks by UUID', async () => {
+        const calls = stubJSON([{ json: DOC }, { json: [] }]);
+        const res = await makeGetDocHandler(client)({ docId: 'ORB-D7' });
+        expect(calls[0].url).toBe('https://orboto.example.com/docs/by-key/ORB-D7');
+        expect(calls[1].url).toBe(`https://orboto.example.com/docs/${DOC.id}/backlinks`);
+        expect(res.content[0].text).toContain('Key: ORB-D7');
+    });
+});
+describe('orboto_create_doc', () => {
+    it('POSTs to /spaces/:id/docs with title + content', async () => {
+        const calls = stubJSON([{ status: 201, json: DOC }]);
+        const res = await makeCreateDocHandler(client)({
+            spaceId: PROJECT_SCOPED_SPACE.id,
+            title: 'Retry semantics',
+            content: '# Retry semantics\n\n200ms × 2^n.',
+        });
+        expect(calls[0]).toMatchObject({
+            method: 'POST',
+            url: `https://orboto.example.com/spaces/${PROJECT_SCOPED_SPACE.id}/docs`,
+            body: { title: 'Retry semantics', content: '# Retry semantics\n\n200ms × 2^n.' },
+        });
+        expect(res.structuredContent).toMatchObject({ id: DOC.id, title: DOC.title });
+    });
+    it('passes parentDocId + visibility through', async () => {
+        const calls = stubJSON([{ status: 201, json: { ...DOC, parentDocId: 'p1' } }]);
+        await makeCreateDocHandler(client)({
+            spaceId: PROJECT_SCOPED_SPACE.id,
+            title: 'Sub-page',
+            parentDocId: 'a1111111-0000-0000-0000-000000000099',
+            visibility: 'specific',
+        });
+        expect(calls[0].body).toMatchObject({
+            title: 'Sub-page',
+            parentDocId: 'a1111111-0000-0000-0000-000000000099',
+            visibility: 'specific',
+        });
+    });
+});
+describe('orboto_update_doc', () => {
+    // ORB-1084 - write tools accept the human-readable doc key: the key
+    // resolves via /docs/by-key, then the PATCH targets the UUID.
+    it('resolves a doc key to the UUID before writing', async () => {
+        const calls = stubJSON([
+            { json: DOC }, // by-key resolve
+            { json: { ...DOC, content: 'appended' } }, // the PATCH
+        ]);
+        await makeUpdateDocHandler(client)({ docId: 'DOC-4', content: 'appended' });
+        expect(calls[0]).toMatchObject({ method: 'GET', url: 'https://orboto.example.com/docs/by-key/DOC-4' });
+        expect(calls[1]).toMatchObject({
+            method: 'PATCH',
+            url: `https://orboto.example.com/docs/${DOC.id}`,
+            body: { content: 'appended' },
+        });
+    });
+    it('PATCHes only the content field when only content was supplied', async () => {
+        const calls = stubJSON([{ json: { ...DOC, content: 'new body' } }]);
+        await makeUpdateDocHandler(client)({ docId: DOC.id, content: 'new body' });
+        expect(calls[0]).toMatchObject({
+            method: 'PATCH',
+            url: `https://orboto.example.com/docs/${DOC.id}`,
+            body: { content: 'new body' },
+        });
+        expect(Object.keys(calls[0].body)).toEqual(['content']);
+    });
+    it('refuses the no-op call before hitting the API', async () => {
+        const calls = stubJSON([]);
+        await expect(makeUpdateDocHandler(client)({ docId: DOC.id })).rejects.toThrow(/at least one field/);
+        expect(calls).toHaveLength(0);
+    });
+});
+describe('orboto_delete_doc', () => {
+    it('DELETEs the doc id', async () => {
+        const calls = stubJSON([{ status: 204, json: undefined }]);
+        const res = await makeDeleteDocHandler(client)({ docId: DOC.id });
+        expect(calls[0]).toMatchObject({ method: 'DELETE', url: `https://orboto.example.com/docs/${DOC.id}` });
+        expect(res.structuredContent).toMatchObject({ deleted: true });
+    });
+    it('surfaces a 403 from the system-generated-doc guard', async () => {
+        stubJSON([{ ok: false, status: 403, json: { error: 'This doc is auto-managed…' } }]);
+        await expect(makeDeleteDocHandler(client)({ docId: DOC.id })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});
+describe('orboto_move_doc', () => {
+    it('POSTs to /docs/:id/move with the supplied fields only', async () => {
+        const calls = stubJSON([{ json: { ...DOC, parentDocId: 'newParent', sortOrder: 5 } }]);
+        await makeMoveDocHandler(client)({
+            docId: DOC.id,
+            parentDocId: 'b1111111-0000-0000-0000-000000000001',
+            sortOrder: 5,
+        });
+        expect(calls[0]).toMatchObject({
+            method: 'POST',
+            url: `https://orboto.example.com/docs/${DOC.id}/move`,
+            body: { parentDocId: 'b1111111-0000-0000-0000-000000000001', sortOrder: 5 },
+        });
+    });
+    it('refuses an empty move', async () => {
+        const calls = stubJSON([]);
+        await expect(makeMoveDocHandler(client)({ docId: DOC.id })).rejects.toThrow(/at least one/);
+        expect(calls).toHaveLength(0);
+    });
+    it('allows reparenting to root (parentDocId=null)', async () => {
+        const calls = stubJSON([{ json: { ...DOC, parentDocId: null } }]);
+        await makeMoveDocHandler(client)({ docId: DOC.id, parentDocId: null });
+        expect(calls[0].body).toEqual({ parentDocId: null });
+    });
+});
+import { makeDuplicateDocSpaceHandler, makeResolveDocSmartLinksHandler, } from './docs.js';
+describe('orboto_duplicate_doc_space', () => {
+    it('POSTs /spaces/:id/duplicate and surfaces the new space id', async () => {
+        const calls = stubJSON([{
+                status: 201,
+                json: { ...PROJECT_SCOPED_SPACE, id: 'newspace0-0000-0000-0000-000000000001', name: 'Backend Runbooks (copy)', slug: 'backend-runbooks-copy' },
+            }]);
+        const res = await makeDuplicateDocSpaceHandler(client)({ spaceId: PROJECT_SCOPED_SPACE.id });
+        expect(calls[0]).toMatchObject({
+            method: 'POST',
+            url: `https://orboto.example.com/spaces/${PROJECT_SCOPED_SPACE.id}/duplicate`,
+        });
+        expect(res.structuredContent).toMatchObject({
+            sourceSpaceId: PROJECT_SCOPED_SPACE.id,
+            newSpaceId: 'newspace0-0000-0000-0000-000000000001',
+            name: 'Backend Runbooks (copy)',
+        });
+    });
+    it('bubbles up a 404 for an unknown source space', async () => {
+        stubJSON([{ ok: false, status: 404, json: { error: 'Not found' } }]);
+        await expect(makeDuplicateDocSpaceHandler(client)({ spaceId: '00000000-0000-0000-0000-000000000000' })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});
+describe('orboto_resolve_doc_smart_links', () => {
+    it('POSTs the items array and surfaces resolved + unresolved entries', async () => {
+        const calls = stubJSON([{
+                json: [
+                    { type: 'ticket', id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa', title: 'Auth bug', url: '/p/orb/t/ORB-42', ticketKey: 'ORB-42', projectKey: 'ORB' },
+                    // Note: the doc UUID below is in the input below but absent from the response - verifies "unresolved" surfacing.
+                ],
+            }]);
+        const res = await makeResolveDocSmartLinksHandler(client)({
+            items: [
+                { type: 'ticket', id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa' },
+                { type: 'doc', id: 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb' },
+            ],
+        });
+        expect(calls[0]).toMatchObject({
+            method: 'POST',
+            url: 'https://orboto.example.com/docs/resolve-links',
+            body: {
+                items: [
+                    { type: 'ticket', id: 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa' },
+                    { type: 'doc', id: 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb' },
+                ],
+            },
+        });
+        const text = res.content[0].text;
+        expect(text).toContain('Auth bug');
+        expect(text).toContain('Unresolved');
+        expect(text).toContain('doc:bbbbbbbb');
+        expect(res.structuredContent).toMatchObject({
+            resolved: [{ type: 'ticket', ticketKey: 'ORB-42' }],
+            unresolved: [{ type: 'doc' }],
+        });
+    });
+    it('handles the all-resolved case without an Unresolved section', async () => {
+        stubJSON([{
+                json: [{ type: 'doc', id: 'd', title: 'Found', url: '/x' }],
+            }]);
+        const res = await makeResolveDocSmartLinksHandler(client)({
+            items: [{ type: 'doc', id: 'd' }],
+        });
+        expect(res.content[0].text).not.toContain('Unresolved');
+    });
+});

package/dist/tools/embedding-status.js

@@ -0,0 +1,100 @@
+/**
+ * ORB-1309 - `orboto_embedding_status`.
+ *
+ * Operator diagnostic for the embedding pipeline: provider/model/dims, coverage
+ * (embedded vs total, and how many are PENDING - never-embedded / stale - per
+ * tickets / comments / docs and overall), the circuit-breaker state, and when
+ * the last embedding was written. Wraps GET /admin/ai/embedding-status.
+ *
+ * `orboto_ai_status` only reports whether embeddings are configured; this is the
+ * deeper surface for "why is semantic search / duplicate detection / ask-docs
+ * stale" - a tripped breaker, a stuck queue, or a provider that stopped
+ * responding. Admin:ai:read gated (403 for non-admin callers).
+ */
+import { z } from 'zod';
+export const embeddingStatusToolConfig = {
+    title: 'Embedding pipeline status (coverage + circuit breaker)',
+    description: 'Operator diagnostic for AI search / embeddings. Returns the configured provider/model + vector dimensions, coverage (embedded vs total, and how many are PENDING - never-embedded / stale - per tickets / comments / docs and overall), the circuit-breaker state (tripped + reason + consecutive failures), and when the last embedding was written. Use this to diagnose why semantic search / duplicate detection / ask-docs are stale or empty - e.g. a tripped breaker, a stuck queue, or a provider that stopped responding. Deeper than orboto_ai_status (which only says whether embeddings are configured). Requires admin:ai:read - returns 403 for non-admin callers.',
+    inputSchema: z.object({}).shape,
+    outputSchema: z.object({
+        configured: z.boolean(),
+        provider: z.string().nullable(),
+        model: z.string().nullable(),
+        dimensions: z.number(),
+        embedded: z.number(),
+        total: z.number(),
+        embeddable: z.number(),
+        pending: z.number(),
+        noContent: z.number(),
+        breakerTripped: z.boolean(),
+        breakerReason: z.string().nullable(),
+        billingGated: z.boolean(),
+        billingGateReason: z.string().nullable(),
+        allowanceRemainingMicrocents: z.number().nullable(),
+        allowanceGrantMicrocents: z.number().nullable(),
+        overageMode: z.string().nullable(),
+        lastEmbeddedAt: z.string().nullable(),
+        stalled: z.boolean(),
+        stalledMinutes: z.number().nullable(),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeEmbeddingStatusHandler(client) {
+    return async () => {
+        const s = await client.get('/admin/ai/embedding-status');
+        const o = s.coverage.overall;
+        const lines = [];
+        if (!s.configured) {
+            lines.push('Embeddings: NOT configured - no embedding provider set in Admin → AI Settings.');
+        }
+        else {
+            lines.push(`Embeddings: ${s.provider} / ${s.model} · ${s.dimensions} dims`);
+            lines.push(`Coverage: ${o.embedded} / ${o.embeddable} embeddable embedded · ${o.pending} pending${o.noContent > 0 ? ` · ${o.noContent} with no embeddable content (excluded)` : ''}`);
+            lines.push(`  tickets ${s.coverage.ticket.embedded}/${s.coverage.ticket.embeddable} · comments ${s.coverage.comment.embedded}/${s.coverage.comment.embeddable} · docs ${s.coverage.doc.embedded}/${s.coverage.doc.embeddable} (embeddable)`);
+            lines.push(`Circuit breaker: ${s.breaker.tripped ? `TRIPPED - ${s.breaker.lastTrippedReason ?? 'unknown reason'} (${s.breaker.consecutiveFailures} consecutive failures)` : 'ok'}`);
+            // ORB-1715 - a billing gate is the one cause the customer can fix
+            // themselves; name it instead of letting it read as a provider fault.
+            if (s.billingGate?.gated) {
+                lines.push(`BILLING GATE: managed AI is paused for billing${s.billingGate.reason ? ` (${s.billingGate.reason})` : ''} since ${s.billingGate.blockedAt ?? 'unknown'}. The workspace admin resolves this in their orboto account; queued items embed automatically after the unblock.`);
+            }
+            // ORB-1719 - spend visibility so an agent can warn BEFORE the gate.
+            if (s.spend?.allowanceGrantMicrocents != null && s.spend.allowanceConsumedMicrocents != null) {
+                const eur = (mc) => (mc / 1_000_000).toFixed(2);
+                lines.push(`Included AI this month: ${eur(s.spend.allowanceConsumedMicrocents)} of ${eur(s.spend.allowanceGrantMicrocents)} EUR used${s.spend.allowanceRemainingMicrocents != null ? ` · ${eur(s.spend.allowanceRemainingMicrocents)} EUR left` : ''} · overage ${s.spend.overageMode ?? 'unknown'}`);
+            }
+            lines.push(`Last embedded: ${s.lastEmbeddedAt ?? 'never'}`);
+            if (s.stalled) {
+                lines.push('');
+                lines.push(`STALLED - ${o.pending} pending, breaker healthy, but nothing has embedded for ${s.stalledMinutes} min. The provider is likely failing transiently (e.g. Ollama down / model unloaded); those errors don't trip the breaker. Check the embedding provider, then re-run the backfill.`);
+            }
+            else if (o.pending > 0 && !s.breaker.tripped) {
+                lines.push('');
+                lines.push(`${o.pending} pending with a healthy breaker - trigger a backfill from Admin → AI Settings, or check the embedding worker / provider throughput if the count isn't draining.`);
+            }
+        }
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                configured: s.configured,
+                provider: s.provider,
+                model: s.model,
+                dimensions: s.dimensions,
+                embedded: o.embedded,
+                total: o.total,
+                embeddable: o.embeddable,
+                pending: o.pending,
+                noContent: o.noContent,
+                breakerTripped: s.breaker.tripped,
+                breakerReason: s.breaker.lastTrippedReason,
+                billingGated: s.billingGate?.gated ?? false,
+                billingGateReason: s.billingGate?.reason ?? null,
+                allowanceRemainingMicrocents: s.spend?.allowanceRemainingMicrocents ?? null,
+                allowanceGrantMicrocents: s.spend?.allowanceGrantMicrocents ?? null,
+                overageMode: s.spend?.overageMode ?? null,
+                lastEmbeddedAt: s.lastEmbeddedAt,
+                stalled: s.stalled,
+                stalledMinutes: s.stalledMinutes,
+            },
+        };
+    };
+}

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

@@ -0,0 +1,86 @@
+/**
+ * ORB-1715 - `orboto_embedding_status` tool mapping test. Pins the consumed
+ * response shape (incl. the OCP-D24 billing-gate block) so an api-side field
+ * rename breaks the build here instead of silently dropping the diagnostic.
+ */
+import { describe, expect, it, vi, beforeEach, afterEach } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeEmbeddingStatusHandler } from './embedding-status.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+const BASE_STATUS = {
+    configured: true,
+    provider: 'orboto',
+    model: 'Qwen/Qwen3-Embedding-8B',
+    dimensions: 1024,
+    coverage: {
+        ticket: { embedded: 10, total: 12, embeddable: 11 },
+        comment: { embedded: 5, total: 5, embeddable: 5 },
+        doc: { embedded: 2, total: 3, embeddable: 3 },
+        overall: { embedded: 17, total: 20, embeddable: 19, pending: 2, noContent: 1 },
+    },
+    breaker: { tripped: false, trippedUntil: null, consecutiveFailures: 0, lastTrippedReason: null },
+    billingGate: null,
+    spend: null,
+    lastEmbeddedAt: '2026-08-12T10:00:00.000Z',
+    stalled: false,
+    stalledMinutes: null,
+};
+function mockFetch(json) {
+    return vi.spyOn(globalThis, 'fetch').mockResolvedValue({
+        ok: true, status: 200, statusText: 'OK',
+        json: async () => json,
+    });
+}
+describe('tools/embedding-status', () => {
+    const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+    it('maps the healthy shape (no gate, no trip)', async () => {
+        mockFetch(BASE_STATUS);
+        const result = await makeEmbeddingStatusHandler(client)();
+        expect(result.structuredContent).toMatchObject({
+            configured: true, pending: 2, breakerTripped: false,
+            billingGated: false, billingGateReason: null,
+        });
+        const text = result.content[0].text;
+        expect(text).toContain('Circuit breaker: ok');
+        expect(text).not.toContain('BILLING GATE');
+    });
+    it('surfaces the billing gate with its reason instead of a provider fault', async () => {
+        mockFetch({
+            ...BASE_STATUS,
+            billingGate: { gated: true, blockedAt: '2026-08-12T06:45:00.000Z', reason: 'allowance_exhausted', source: 'signal', updatedAt: '2026-08-12T06:50:00.000Z' },
+        });
+        const result = await makeEmbeddingStatusHandler(client)();
+        expect(result.structuredContent).toMatchObject({
+            billingGated: true, billingGateReason: 'allowance_exhausted',
+        });
+        const text = result.content[0].text;
+        expect(text).toContain('BILLING GATE');
+        expect(text).toContain('allowance_exhausted');
+        // Contract guarantee: never vendor prose on any surface.
+        expect(text).not.toContain('Key is blocked');
+    });
+    it('surfaces the spend state so agents can warn before the gate (ORB-1719)', async () => {
+        mockFetch({
+            ...BASE_STATUS,
+            spend: {
+                month: '2026-08-01', allowanceGrantMicrocents: 4_000_000, allowanceConsumedMicrocents: 3_500_000,
+                allowanceRemainingMicrocents: 500_000, overageMode: 'hard_gate', overageCapEurCents: null,
+                overageConsumedMicrocents: null, walletBalanceMicrocents: null, walletFunded: true,
+                updatedAt: '2026-08-13T09:00:00.000Z',
+            },
+        });
+        const result = await makeEmbeddingStatusHandler(client)();
+        expect(result.structuredContent).toMatchObject({
+            allowanceRemainingMicrocents: 500_000, allowanceGrantMicrocents: 4_000_000, overageMode: 'hard_gate',
+        });
+        const text = result.content[0].text;
+        expect(text).toContain('3.50 of 4.00 EUR used');
+    });
+    it('tolerates an older api without the billingGate field', async () => {
+        const { billingGate: _omitted, ...legacy } = BASE_STATUS;
+        mockFetch(legacy);
+        const result = await makeEmbeddingStatusHandler(client)();
+        expect(result.structuredContent).toMatchObject({ billingGated: false, billingGateReason: null });
+    });
+});

package/dist/tools/free-busy.js

@@ -0,0 +1,49 @@
+/**
+ * ORB-625 - `orboto_free_busy`. Read a batch of users' near-term capacity
+ * (planned + booked + external-busy vs contractual capacity) so an agent can
+ * pick an available assignee. Wraps GET /users/free-busy, which is gated by
+ * the workspace `free_busy_team_visibility` toggle (disabled → 403 for
+ * non-admins) and the per-user opt-out (→ status 'unknown').
+ */
+import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
+export const freeBusyToolConfig = {
+    title: 'User free/busy',
+    description: "Look up near-term capacity (free/busy) for one or more users so you can pick an available assignee. Returns, per user, a `status` (available | busy | overcapacity | absent | unknown) and per-bucket entries with plannedMinutes (plan-blocks), bookedMinutes (logged time), capacityMinutes (contractual), onAbsence, and externalBusyMinutes. `unknown` means the user opted out or the workspace hides their data from you. Requires the workspace free/busy toggle to be enabled (or admin rights); otherwise you get a not-permitted result. `userIds` is a list of user UUIDs (get them from orboto_list_users). Optional `from`/`to` (YYYY-MM-DD, default the next 2 weeks) and `granularity` (day | week, default day).",
+    inputSchema: z.object({
+        userIds: z.array(z.string().uuid()).min(1).max(200).describe('User UUIDs to look up.'),
+        from: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('Range start (YYYY-MM-DD). Default: today.'),
+        to: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('Range end inclusive (YYYY-MM-DD). Default: today + 13 days.'),
+        granularity: z.enum(['day', 'week']).optional().describe('Bucket size. Default: day.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeFreeBusyHandler(client) {
+    return async (input) => {
+        const qs = new URLSearchParams();
+        qs.set('userIds', input.userIds.join(','));
+        if (input.from)
+            qs.set('from', input.from);
+        if (input.to)
+            qs.set('to', input.to);
+        if (input.granularity)
+            qs.set('granularity', input.granularity);
+        let data;
+        try {
+            data = await client.get(`/users/free-busy?${qs.toString()}`);
+        }
+        catch (err) {
+            if (err instanceof OrbotoApiError && err.status === 403) {
+                return {
+                    content: [{ type: 'text', text: 'Not permitted: free/busy visibility is disabled for this workspace (admins only).' }],
+                    structuredContent: { error: 'forbidden' },
+                };
+            }
+            throw err;
+        }
+        return {
+            content: [{ type: 'text', text: `Free/busy:\n${JSON.stringify(data, null, 2)}` }],
+            structuredContent: data,
+        };
+    };
+}

package/dist/tools/free-busy.test.js

@@ -0,0 +1,46 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeFreeBusyHandler } from './free-busy.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+function stub(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => {
+        calls.push(url.toString());
+        const r = responses.shift();
+        if (!r)
+            throw new Error(`unexpected extra fetch to ${url}`);
+        const status = r.status ?? 200;
+        return { ok: status < 400, status, statusText: 'x', json: async () => ('json' in r ? r.json : {}), text: async () => '' };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const U1 = '11111111-1111-1111-1111-111111111111';
+const U2 = '22222222-2222-2222-2222-222222222222';
+describe('orboto_free_busy (ORB-625)', () => {
+    it('batches the user-ids into a single GET /users/free-busy call', async () => {
+        const payload = { users: [{ userId: U1, entries: [], status: 'available' }, { userId: U2, entries: [], status: 'busy' }] };
+        const calls = stub([{ json: payload }]);
+        const res = await makeFreeBusyHandler(client)({ userIds: [U1, U2] });
+        expect(calls).toHaveLength(1);
+        expect(calls[0]).toContain('/users/free-busy?');
+        expect(calls[0]).toContain(`userIds=${encodeURIComponent(`${U1},${U2}`)}`);
+        expect(res.structuredContent.users).toHaveLength(2);
+        expect(res.structuredContent.users[0]).toMatchObject({ userId: U1, status: 'available' });
+    });
+    it('passes the window + granularity through', async () => {
+        const calls = stub([{ json: { users: [] } }]);
+        await makeFreeBusyHandler(client)({ userIds: [U1], from: '2026-07-01', to: '2026-07-14', granularity: 'week' });
+        expect(calls[0]).toContain('from=2026-07-01');
+        expect(calls[0]).toContain('to=2026-07-14');
+        expect(calls[0]).toContain('granularity=week');
+    });
+    it('returns a readable not-permitted result on 403 (workspace toggle off)', async () => {
+        stub([{ status: 403, json: { error: 'Free/busy availability is disabled for this workspace.' } }]);
+        const res = await makeFreeBusyHandler(client)({ userIds: [U1] });
+        expect(res.structuredContent).toMatchObject({ error: 'forbidden' });
+        const first = res.content[0];
+        expect(String(first.text)).toMatch(/not permitted/i);
+    });
+});