@orboto/mcp 0.220.0 → 0.221.0

package/dist/manifest-size.test.js

@@ -49,6 +49,8 @@ afterEach(() => { vi.restoreAllMocks(); });
  * the resource.
  * ORB-2465 added no named tool: the live notice rides the escape hatch
  * (full = 171,194 chars, 6 free).
+ * ORB-2502 gave `orboto_messages` a `since` parameter inside the ceiling: the
+ * limit lost its schema default and the project hint shrank (full = 171,197).
  *
  * @see ORB-1805, ORB-1669, ORB-1910
  */

package/dist/tail-labels.js

@@ -20,6 +20,17 @@ export const TAIL_LABELS = [
     { method: 'PATCH', path: new RegExp(`^/projects/${SEG}/chat-bot/routes/${SEG}$`), label: 'orboto_chat_bot_route' },
     { method: 'DELETE', path: new RegExp(`^/projects/${SEG}/chat-bot/routes/${SEG}$`), label: 'orboto_chat_bot_route' },
     { method: 'POST', path: /^\/chat-bot\/links\/(confirm|[^/]+\/revoke)$/, label: 'orboto_chat_bot_link' },
+    { method: 'GET', path: /^\/admin\/integrations\/lexware(\/(readiness|events|deliveries))?$/, label: 'orboto_lexware_connection' },
+    { method: 'POST', path: /^\/admin\/integrations\/lexware\/test$/, label: 'orboto_lexware_connection' },
+    { method: 'POST', path: /^\/admin\/integrations\/lexware(\/(rotate-key|subscriptions))?$/, label: 'orboto_lexware_admin' },
+    { method: 'PATCH', path: /^\/admin\/integrations\/lexware$/, label: 'orboto_lexware_admin' },
+    { method: 'DELETE', path: /^\/admin\/integrations\/lexware(\/subscriptions)?$/, label: 'orboto_lexware_admin' },
+    { method: 'GET', path: new RegExp(`^/customers/${SEG}/lexware-contact$`), label: 'orboto_lexware_contact' },
+    { method: 'PUT', path: new RegExp(`^/customers/${SEG}/lexware-contact$`), label: 'orboto_lexware_contact' },
+    { method: 'DELETE', path: new RegExp(`^/customers/${SEG}/lexware-contact$`), label: 'orboto_lexware_contact' },
+    { method: 'POST', path: new RegExp(`^/customers/${SEG}/lexware-billing-runs(/preview|/${SEG}/refresh)?$`), label: 'orboto_lexware_billing_run' },
+    { method: 'GET', path: new RegExp(`^/customers/${SEG}/lexware-billing-runs(/summary)?$`), label: 'orboto_lexware_billing_run' },
+    { method: 'GET', path: /^\/admin\/integrations\/lexware\/billing-runs$/, label: 'orboto_lexware_billing_run' },
     { method: 'POST', path: /^\/v1\/agent\/broadcast\/live$/, label: 'orboto_agent_notice' },
     { method: 'GET', path: new RegExp(`^/v1/agent/broadcasts/live(/${SEG})?$`), label: 'orboto_agent_notice_status' },
     { method: 'GET', path: new RegExp(`^/v1/agent/messages/${SEG}/attachments(/${SEG}/url)?$`), label: 'orboto_agent_message_attachments' },

package/dist/tools/agent-messages-compact.test.js

@@ -0,0 +1,51 @@
+/**
+ * ORB-2502 - orboto_messages lists the newest 10 unread compactly with the exact count; all:true keeps every message in full.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeAgentMessagesHandler } from './agent-messages.js';
+afterEach(() => { vi.restoreAllMocks(); });
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const party = (label) => ({ userId: 'u', email: 'e', sessionId: null, role: null, label });
+const message = {
+    id: 'm1', fromUserId: 'u1', toUserId: 'u2', fromSessionId: null, toSessionId: null, from: party('Ada'), to: party('Bot'),
+    kind: 'request', subject: 'review', payload: { message: 'x'.repeat(1_000) }, threadId: null, projectKey: 'ORB',
+    createdAt: '2026-10-01T10:00:00Z', deliveredAt: null, readAt: null, dismissed: null,
+    excerpt: `message: ${'x'.repeat(291)}`, payloadChars: 1_009,
+};
+function stubInbox(urls) {
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => {
+        urls.push(String(url));
+        return {
+            ok: true, status: 200, statusText: 'OK', text: async () => '',
+            json: async () => ({ messages: [message], sessionId: 'cbb52195-0000-4000-8000-000000000000', counts: { unread: 14, olderThan7Days: 12 } }),
+        };
+    });
+}
+describe('ORB-2502 - the compact inbox on MCP', () => {
+    it('asks for the newest 10 compactly, prints the excerpt and the count, and leaves the payload out of the structured answer', async () => {
+        const urls = [];
+        stubInbox(urls);
+        const result = await makeAgentMessagesHandler(client)({ since: '2026-09-30T00:00:00Z' }, { sessionId: 'abc' });
+        expect(urls[0]).toContain('limit=10');
+        expect(urls[0]).toContain('compact=true');
+        expect(urls[0]).toContain('since=2026-09-30T00%3A00%3A00Z');
+        const text = result.content[0].text;
+        expect(text).toContain(`\n  message: ${'x'.repeat(291)}\n  ... 709 more characters (all:true prints everything)`);
+        expect(text).toContain('14 unread, 12 older than 7 days (all, limit N, since)');
+        expect(text).not.toContain('payload:');
+        expect(result.structuredContent).toMatchObject({ messages: [{ id: 'm1', payload: null }] });
+    });
+    it('all:true prints every message in full as before, with the limit of 50', async () => {
+        const urls = [];
+        stubInbox(urls);
+        const result = await makeAgentMessagesHandler(client)({ all: true }, { sessionId: 'abc' });
+        expect(urls[0]).toContain('all=true');
+        expect(urls[0]).toContain('limit=50');
+        expect(urls[0]).not.toContain('compact');
+        const text = result.content[0].text;
+        expect(text).toContain(`payload: {"message":"${'x'.repeat(1_000)}"}`);
+        expect(text).not.toContain('older than 7 days');
+        expect(result.structuredContent).toMatchObject({ messages: [{ payload: { message: 'x'.repeat(1_000) } }] });
+    });
+});

package/dist/tools/agent-messages.js

@@ -14,13 +14,14 @@ const PartySchema = z.object({ userId: z.string(), email: z.string(), sessionId:
 const UNREGISTERED_INBOX_HINT = 'Not registered: only account mail is listed. Register with orboto_session_start to see the mail addressed to your session.';
 export const agentMessagesToolConfig = {
     title: 'Agent inbox and message work',
-    description: 'Your inbox as THIS session sees it. It holds mail to this session, account mail inside your declared scope, broadcasts; sibling-session mail and own sends stay out, all:true is the account view (ORB-2136). Before orboto_session_start only account mail is listed; register to see mail addressed to your session (ORB-2347). messageWork carries durable work ownership - claim before executing. ackIds acks: it completes an unclaimed request; claimed work with open steps is refused until messageWork completes or blocks it. dismiss is the third answer: not_mine hides it here and tells the sender, obsolete/duplicate close it for the account (note or duplicateOf required). Never leave mail you read and judged. Reply via orboto_agent_notify with threadId (toSessionRef = from.sessionId reaches that instance).',
+    description: 'Your inbox as THIS session sees it. It holds mail to this session, account mail inside your declared scope, broadcasts; sibling-session mail and own sends stay out, all:true is the account view with every message in full (ORB-2136). By default it lists the newest 10 unread, newest first, each as a header plus the first 300 payload characters, then the line `N unread, M older than 7 days`; limit and since (ISO time or message id) narrow it (ORB-2502). Before orboto_session_start only account mail is listed; register to see mail addressed to your session (ORB-2347). messageWork carries durable work ownership - claim before executing. ackIds acks: it completes an unclaimed request; claimed work with open steps is refused until messageWork completes or blocks it. dismiss is the third answer: not_mine hides it here and tells the sender, obsolete/duplicate close it for the account (note or duplicateOf required). Never leave mail you read and judged. Reply via orboto_agent_notify with threadId (toSessionRef = from.sessionId reaches that instance).',
     inputSchema: z.object({
         messageWork: z.record(z.unknown()).optional()
             .describe('Work envelope {messageId, mutation, cursor, limit, openOnly}; schema: orboto_api_search.'),
         all: z.boolean().default(false),
-        limit: z.number().int().min(1).max(200).default(50),
-        project: z.string().min(1).max(64).optional().describe('Project key/UUID; includes unscoped mail.'),
+        limit: z.number().int().min(1).max(200).optional(),
+        since: z.string().optional(),
+        project: z.string().min(1).max(64).optional().describe('Key/UUID; includes unscoped mail.'),
         includeOwnSends: z.boolean().default(false),
         ackIds: z.array(z.string().uuid()).max(200).optional().describe('Message ids to mark read.'),
         dismiss: z.object({
@@ -55,6 +56,16 @@ export const agentMessagesToolConfig = {
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
 };
+/** ORB-2502 - the compact view: the header, the first 300 payload characters indented, and how much was left out. */
+function compactLines(m, header) {
+    const excerpt = m.excerpt ?? '';
+    const rest = (m.payloadChars ?? 0) - Array.from(excerpt).length;
+    return [
+        header,
+        ...(excerpt ? excerpt.replace(/\n+$/, '').split('\n').map((line) => `  ${line}`) : []),
+        ...(rest > 0 ? [`  ... ${rest} more characters (all:true prints everything)`] : []),
+    ];
+}
 export function makeAgentMessagesHandler(client) {
     return async (args, extra) => {
         if (args.messageWork) {
@@ -80,23 +91,30 @@ export function makeAgentMessagesHandler(client) {
             const res = await client.post('/v1/agent/messages/ack', { ids: args.ackIds, instanceToken: mcpInstanceToken(undefined, extra) });
             acked = res.acked;
         }
+        const compact = !args.all;
         const q = new URLSearchParams();
         if (args.all)
             q.set('all', 'true');
-        if (args.limit)
-            q.set('limit', String(args.limit));
+        q.set('limit', String(args.limit ?? (compact ? 10 : 50)));
+        if (compact)
+            q.set('compact', 'true');
+        if (args.since)
+            q.set('since', args.since);
         if (args.project)
             q.set('project', args.project);
         const instanceToken = mcpInstanceToken(undefined, extra);
         if (!args.includeOwnSends)
             q.set('excludeRef', instanceToken);
-        const { messages, sessionId } = await client.get(`/v1/agent/messages${q.toString() ? `?${q.toString()}` : ''}`, { instanceToken });
+        const { messages, sessionId, counts } = await client.get(`/v1/agent/messages?${q.toString()}`, { instanceToken });
+        const header = (m) => `[${m.kind}]${m.projectKey ? ` [${m.projectKey}]` : ''} ${m.subject} (from ${m.from?.label ?? m.fromUserId} to ${m.to?.label ?? m.toUserId}, ${m.createdAt}, id ${m.id}${m.threadId ? `, thread ${m.threadId}` : ''})`;
         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.from?.label ?? m.fromUserId} to ${m.to?.label ?? m.toUserId}, ${m.createdAt}, id ${m.id}${m.threadId ? `, thread ${m.threadId}` : ''})${m.payload ? ` payload: ${JSON.stringify(m.payload)}` : ''}`);
+            : messages.flatMap((m) => (compact ? compactLines(m, header(m)) : [`${header(m)}${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 (toSessionRef = the sender's instance short id reaches that session only).`);
         }
+        if (compact && counts)
+            lines.push(`${counts.unread} unread, ${counts.olderThan7Days} older than 7 days (all, limit N, since)`);
         if (args.dismiss) {
             lines.unshift(`Dismissed ${dismissedCount} message(s) as ${args.dismiss.reason}${closedCount > 0 ? `, ${closedCount} closed for the account` : ''}${feedbackSent > 0 ? `, ${feedbackSent} sender(s) told about the misroute` : ''}.`);
         }
@@ -110,7 +128,7 @@ export function makeAgentMessagesHandler(client) {
                 sessionId: sessionId ?? null,
                 messages: messages.map((m) => ({
                     id: m.id, fromUserId: m.fromUserId, from: m.from, to: m.to, kind: m.kind, subject: m.subject,
-                    payload: m.payload, threadId: m.threadId, projectKey: m.projectKey ?? null,
+                    payload: compact ? null : m.payload, threadId: m.threadId, projectKey: m.projectKey ?? null,
                     createdAt: m.createdAt, readAt: m.readAt, dismissed: m.dismissed ?? null,
                 })),
                 acked,

package/dist/tools/lexware-tail.test.js

@@ -0,0 +1,38 @@
+/** ORB-2508 - the Lexware connection reaches an MCP-only agent through the escape hatch; every call is labelled in the metrics. */
+import { describe, expect, it } from 'vitest';
+import { metricsToolName } from '../tail-labels.js';
+const call = (method, path) => metricsToolName('orboto_api_call', { method, path });
+describe('ORB-2508 - Lexware tail labels', () => {
+    it('labels status, readiness, logs and the profile test as orboto_lexware_connection', () => {
+        for (const path of ['/admin/integrations/lexware', '/admin/integrations/lexware/readiness', '/admin/integrations/lexware/events?limit=20', '/admin/integrations/lexware/deliveries']) {
+            expect(call('GET', path), path).toBe('orboto_lexware_connection');
+        }
+        expect(call('POST', '/admin/integrations/lexware/test')).toBe('orboto_lexware_connection');
+    });
+    it('labels the operator writes as orboto_lexware_admin', () => {
+        expect(call('POST', '/admin/integrations/lexware')).toBe('orboto_lexware_admin');
+        expect(call('POST', '/admin/integrations/lexware/rotate-key')).toBe('orboto_lexware_admin');
+        expect(call('POST', '/admin/integrations/lexware/subscriptions')).toBe('orboto_lexware_admin');
+        expect(call('PATCH', '/admin/integrations/lexware')).toBe('orboto_lexware_admin');
+        expect(call('DELETE', '/admin/integrations/lexware/subscriptions')).toBe('orboto_lexware_admin');
+        expect(call('DELETE', '/admin/integrations/lexware')).toBe('orboto_lexware_admin');
+    });
+    it('labels the customer contact mapping as orboto_lexware_contact (ORB-2511)', () => {
+        const path = '/customers/6f1c2b1e-3d4a-4b5c-8d9e-0a1b2c3d4e5f/lexware-contact';
+        for (const method of ['GET', 'PUT', 'DELETE'])
+            expect(call(method, path), method).toBe('orboto_lexware_contact');
+        expect(call('GET', `${path}?name=Acme&page=1`)).toBe('orboto_lexware_contact');
+    });
+    it('labels the billing run preview, create, list and refresh as orboto_lexware_billing_run (ORB-2512)', () => {
+        const base = '/customers/6f1c2b1e-3d4a-4b5c-8d9e-0a1b2c3d4e5f/lexware-billing-runs';
+        for (const path of [`${base}/preview`, base, `${base}/7a1c2b1e-3d4a-4b5c-8d9e-0a1b2c3d4e5f/refresh`])
+            expect(call('POST', path), path).toBe('orboto_lexware_billing_run');
+        expect(call('GET', `${base}?limit=20`)).toBe('orboto_lexware_billing_run');
+        expect(call('GET', `${base}/summary?from=2026-10-01&to=2026-10-31`)).toBe('orboto_lexware_billing_run');
+        expect(call('GET', '/admin/integrations/lexware/billing-runs')).toBe('orboto_lexware_billing_run');
+        expect(call('DELETE', base)).toBe('orboto_api_call');
+    });
+    it('leaves the public receiver unlabelled', () => {
+        expect(call('POST', '/inbound/lexware/6f1c2b1e-3d4a-4b5c-8d9e-0a1b2c3d4e5f')).toBe('orboto_api_call');
+    });
+});

package/dist/tools/update-project.js

@@ -54,23 +54,38 @@ export function makeUpdateProjectHandler(client) {
         };
     };
 }
+/** ORB-2503 - a customer by UUID or by case-insensitive exact name; an ambiguous or unknown name is refused with the candidates. */
+export async function resolveCustomerRef(client, ref) {
+    const wanted = ref.trim();
+    if (UUID_RE.test(wanted))
+        return wanted;
+    const rows = await client.get(`/customers?includeInactive=true&search=${encodeURIComponent(wanted)}`);
+    const exact = rows.filter((c) => c.name.trim().toLowerCase() === wanted.toLowerCase());
+    if (exact.length === 1)
+        return exact[0].id;
+    if (exact.length > 1)
+        throw new Error(`Customer name "${wanted}" is ambiguous: ${exact.map((c) => `${c.name} (${c.id})`).join(', ')}. Pass the id.`);
+    if (rows.length === 0)
+        throw new Error(`No customer named "${wanted}".`);
+    throw new Error(`No customer named exactly "${wanted}"; candidates: ${rows.map((c) => c.name).join(', ')}.`);
+}
 export const createProjectToolConfig = {
-    title: 'Create a new project',
-    description: 'Create a project with an optional key (auto-derived if omitted). Requires project:create or super-admin. Returns identity, status and the measured readiness checklist with fix actions. Reuse its auto-created doc space via orboto_list_doc_spaces.',
+    title: 'Create a project',
+    description: 'Create a project (key auto-derived if omitted). Agents pass customer or internal. Needs project:create. Returns readiness with fix actions; its doc space is auto-created.',
     inputSchema: z.object({
-        name: z.string().min(1).max(255).describe('Project name.'),
-        key: z.string().min(2).max(10).regex(PROJECT_KEY_RE).optional()
-            .describe('Key; auto-derived if omitted.'),
-        description: z.string().nullable().optional().describe('Description.'),
-        customerId: z.string().regex(UUID_RE).nullable().optional()
-            .describe('Customer UUID.'),
+        name: z.string().min(1).max(255),
+        key: z.string().min(2).max(10).regex(PROJECT_KEY_RE).optional(),
+        description: z.string().nullable().optional(),
+        customerId: z.string().regex(UUID_RE).nullable().optional(),
+        customer: z.string().min(1).optional().describe('Customer name or UUID.'),
+        internal: z.string().min(3).max(200).optional().describe('Reason for no customer.'),
         language: z.enum(LOCALE_CODES).nullable().optional()
-            .describe('Content language; null/omitted inherits workspace.'),
+            .describe('Null inherits workspace.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
 export function makeCreateProjectHandler(client) {
-    return async ({ name, key, description, customerId, language }) => {
+    return async ({ name, key, description, customerId, customer, internal, language }) => {
         const body = { name };
         if (key !== undefined)
             body.key = key;
@@ -78,6 +93,10 @@ export function makeCreateProjectHandler(client) {
             body.description = description;
         if (customerId !== undefined)
             body.customerId = customerId;
+        if (customer !== undefined)
+            body.customerId = await resolveCustomerRef(client, customer);
+        if (internal !== undefined)
+            Object.assign(body, { internal: true, internalReason: internal });
         if (language !== undefined)
             body.language = language;
         const created = await client.post('/projects', body);
@@ -96,6 +115,8 @@ export function makeCreateProjectHandler(client) {
                 description: created.description,
                 status: created.status,
                 language: created.language ?? null,
+                customerId: created.customerId ?? null,
+                internal: created.internal ?? false,
             },
         };
     };

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

@@ -128,6 +128,32 @@ describe('orboto_create_project', () => {
             customerId: '11111111-2222-3333-4444-555555555555',
         });
     });
+    it('ORB-2503 - resolves customer by case-insensitive exact name before the POST', async () => {
+        const calls = stub([
+            { json: [{ id: 'c-2', name: 'Acme Labs' }, { id: 'c-1', name: 'ACME' }] },
+            { json: { readiness, id: 'new4', key: 'AC', name: 'Acme app', description: null, status: 'active', customerId: 'c-1', internal: false } },
+        ]);
+        const res = await makeCreateProjectHandler(client)({ name: 'Acme app', customer: 'acme' });
+        expect(calls[0].url).toBe('https://orboto.example.com/customers?includeInactive=true&search=acme');
+        expect(calls[1].body).toEqual({ name: 'Acme app', customerId: 'c-1' });
+        expect(res.structuredContent).toMatchObject({ customerId: 'c-1', internal: false });
+    });
+    it('ORB-2503 - refuses an ambiguous customer name with the candidates and never POSTs', async () => {
+        const calls = stub([{ json: [{ id: 'c-1', name: 'Acme' }, { id: 'c-2', name: 'acme' }] }]);
+        await expect(makeCreateProjectHandler(client)({ name: 'X', customer: 'ACME' }))
+            .rejects.toThrow(/ambiguous: Acme \(c-1\), acme \(c-2\)/);
+        expect(calls).toHaveLength(1);
+    });
+    it('ORB-2503 - refuses an unknown customer name and lists near matches', async () => {
+        stub([{ json: [{ id: 'c-1', name: 'Acme Labs' }] }]);
+        await expect(makeCreateProjectHandler(client)({ name: 'X', customer: 'Acme' }))
+            .rejects.toThrow(/candidates: Acme Labs/);
+    });
+    it('ORB-2503 - sends internal with its reason', async () => {
+        const calls = stub([{ json: { readiness, id: 'new5', key: 'OPS', name: 'Ops', description: null, status: 'active', customerId: null, internal: true } }]);
+        await makeCreateProjectHandler(client)({ name: 'Ops', internal: 'Our own infrastructure' });
+        expect(calls[0].body).toEqual({ name: 'Ops', internal: true, internalReason: 'Our own infrastructure' });
+    });
     it('surfaces a 409 (duplicate key) as OrbotoApiError', async () => {
         stub([
             { ok: false, status: 409, json: { error: 'project key already exists' } },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.220.0",
+  "version": "0.221.0",
   "description": "Model Context Protocol server for orboto - exposes tickets, projects, milestones, time, docs, primer-facts, alerts and absences as MCP tools for Claude Desktop / Cursor / Copilot Chat / any MCP-aware AI client.",
   "license": "MIT",
   "type": "module",