@orboto/mcp 0.182.5 → 0.183.0

package/dist/manifest-size.test.js

@@ -55,7 +55,14 @@ afterEach(() => { vi.restoreAllMocks(); });
  * schema to the minimum (one describe() on `page`); ceiling re-pinned to
  * 32,500 (~6 % headroom), deliberately, for that one addition.
  */
-const CURATED_MAX_CHARS = 32_500;
+// ORB-1959 - re-pinned at 37,500 (measured 36,714): the four agent
+// coordination tools (messages, notify, broadcast, heartbeat) joined the
+// curated tier so an agent on the DEFAULT connection can fetch, act on and
+// ack its mail - the binding workspace rule the old manifest made impossible
+// to follow. Their descriptions were cut to the load-bearing facts first
+// (286 chars); the remaining ~4.2k chars are input/output schemas and the
+// per-tool keys the SDK emits. Decision by the operator, 2026-09-06.
+const CURATED_MAX_CHARS = 37_500;
 const FULL_MAX_CHARS = 155_000;
 /**
  * ORB-1805 - the estimator the ticket measured the failure with
@@ -91,7 +98,7 @@ const MINIMAL_MAX_TOKENS = 3_100;
  */
 // ORB-1910 - re-pinned with CURATED_MAX_CHARS (32,500 / 3.6): the curated set
 // gained orboto_report_feedback; measured 8,514 estimated tokens.
-const CURATED_SCHEMA_MAX_TOKENS = 9_050;
+const CURATED_SCHEMA_MAX_TOKENS = 10_450; // ORB-1959: measured 10,198 with the coordination tools
 async function measuredManifest(toolset) {
     const server = await buildOrbotoMcpServer({
         baseUrl: 'https://orboto.example.com',
@@ -129,8 +136,9 @@ describe('ORB-1521 - eager-load manifest size', () => {
         // eslint-disable-next-line no-console
         console.log(`[manifest-size] curated: ${count} tools, ${chars} chars (~${estTokens(chars)} tokens)`);
         // 31 = the ORB-1741-dieted set + the two ORB-1694 bulk tools (each
-        // REPLACES dozens of per-call responses, so they earn their slot).
-        expect(count).toBeLessThanOrEqual(32);
+        // REPLACES dozens of per-call responses, so they earn their slot);
+        // ORB-1910 added report_feedback, ORB-1959 the four coordination tools.
+        expect(count).toBeLessThanOrEqual(36);
         expect(chars).toBeLessThanOrEqual(CURATED_MAX_CHARS);
         expect(estTokens(chars)).toBeLessThanOrEqual(CURATED_SCHEMA_MAX_TOKENS);
     });

package/dist/tools/agent-coordination.js

@@ -17,7 +17,7 @@ import { z } from 'zod';
 import { mcpInstanceToken } from './shared.js';
 export const agentHeartbeatToolConfig = {
     title: 'Agent heartbeat (Multi-Agent Coordination)',
-    description: 'Register or refresh this agent\'s presence in the workspace. Call on startup AND every ~30 s thereafter; rows missing for >90 s count as offline. Returns the `sessionToken` to persist + send on subsequent heartbeats so the same row is bumped instead of churning new ones. `status` can be `idle` (default), `working` (set `workingOnTicketId` too if relevant), or `blocked`. `capabilities` is a free-form list of strings the operator can use to filter (e.g. `["read-only", "writes-tickets", "writes-code"]`). `clientInfo` describes the runtime - fill `name` with the agent runtime (`claude-desktop`, `claude-code`, `dispatcher-daemon`, `cursor`, ...).',
+    description: 'Register or refresh this agent\'s presence. Call on startup and every ~30 s; rows older than 90 s count as offline. Persist the returned sessionToken and send it on later heartbeats. status: idle (default) | working (+workingOnTicketId) | blocked. capabilities: free-form strings for operator filters. clientInfo.name = the runtime (claude-code, cursor, ...).',
     inputSchema: z.object({
         sessionToken: z.string().nullable().optional(),
         status: z.enum(['idle', 'working', 'blocked']).optional(),
@@ -96,7 +96,7 @@ export function makeAgentPresenceHandler(client) {
 }
 export const agentNotifyToolConfig = {
     title: 'Notify another agent / user',
-    description: 'Dispatch a fire-and-forget message to a target user (bot or human) identified by email. The recipient sees it via the standard notification channel - in-app for human users, MCP push for subscribed agents (ORB-706). Use cases: lead agent telling a worker a sub-task is ready; a worker reporting back to the orchestrator; a CI agent pinging a reviewer when a PR is staged. The `kind` field tags the semantic intent so the recipient can filter (`info` for general updates, `request` when a response is expected, `complete` when reporting a finished sub-task). `payload` is a free-form jsonb blob.',
+    description: 'Send a fire-and-forget message to a user (bot or human) by email; it lands in their inbox (orboto_messages) and, for humans, in-app. kind: info | request (answer expected) | complete (sub-task done) | error. payload: free-form JSON; threadId links a reply to the message it answers.',
     inputSchema: z.object({
         targetEmail: z.string().email(),
         kind: z.enum(['info', 'request', 'complete', 'error']).default('info'),
@@ -106,10 +106,10 @@ export const agentNotifyToolConfig = {
         threadId: z.string().uuid().optional(),
         // ORB-1732 - optional project scope: address "the agent working project
         // X" when the recipient identity runs multiple sessions.
-        project: z.string().min(1).max(64).optional().describe('Project key (ORB) or UUID: scope the message to the recipient session working that project. Recipients fetching with a project filter see scoped messages for their project plus unscoped ones.'),
+        project: z.string().min(1).max(64).optional().describe('Project key or UUID: scope the message to the recipient session working that project.'),
         // ORB-1742 - defaults to this MCP session's instance token so a shared
         // identity never wakes itself with its own outbound mail.
-        senderRef: z.string().min(1).max(128).optional().describe('Sender-session ref for self-echo exclusion. Defaults to this MCP session automatically - only override when sending on behalf of another session.'),
+        senderRef: z.string().min(1).max(128).optional().describe('Sender-session ref for self-echo exclusion; defaults to this MCP session.'),
     }).shape,
     outputSchema: z.object({
         ok: z.literal(true),
@@ -122,7 +122,7 @@ export const agentNotifyToolConfig = {
 // ---------------------------------------------------------------------------
 export const agentBroadcastToolConfig = {
     title: 'Scoped broadcast to other agents',
-    description: 'Fan-out a message to every subscribed agent in a scope. `scopeType=workspace` reaches every internal member; `scopeType=project` reaches members of `scopeId` (project UUID); `scopeType=topic` reaches everyone subscribed to the topic string. The recipient sees it via a `notifications/resources/updated` push on `orboto://broadcast/<scope>/<scope_id>`. Use for lead-agent → workers (workspace), project-team status updates (project), or ad-hoc cross-cutting coordination (topic). Retention is 24 h - late subscribers can replay via the resource read.',
+    description: 'Fan-out to every agent in a scope: workspace (all internal members), project (members of scopeId = project UUID) or topic (any string). Each recipient gets an inbox copy (orboto_messages, ackable); live subscribers also get a resources/updated push on orboto://broadcast/<scope>/<scope_id>. The scope replay keeps agent_broadcast_retention_days (default 7).',
     inputSchema: z.object({
         scopeType: z.enum(['workspace', 'project', 'topic']),
         scopeId: z.string().default(''),

package/dist/tools/agent-messages.js

@@ -11,13 +11,13 @@ 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.',
+    description: 'Your store-and-forward inbox: messages other agents sent you plus broadcasts to your scopes (payload.broadcast names the scope). Default = unread, marked delivered on fetch; ackIds marks read. Reply via orboto_agent_notify with threadId = the message id.',
     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.'),
+        project: z.string().min(1).max(64).optional().describe('Project key or UUID: scoped messages for this project plus unscoped ones. Ack only 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).'),
+        includeOwnSends: z.boolean().default(false).describe('true = also list messages this session sent (hidden by default so a shared identity never wakes itself).'),
         ackIds: z.array(z.string().uuid()).max(200).optional().describe('Message ids to mark as read'),
     }).shape,
     outputSchema: z.object({

package/dist/tools/backup.js

@@ -14,7 +14,7 @@ const mb = (n) => `${Math.round((n / 1024 / 1024) * 10) / 10} MB`;
 // ---------------------------------------------------------------------------
 export const createFullBackupToolConfig = {
     title: 'Create + download a full workspace backup',
-    description: 'Create an on-demand FULL workspace backup (database + storage) and return the ZIP as a base64 application/zip resource attachment - create, wait and download in one call (the server runs the export as a background run and this tool polls it; large workspaces can take minutes). Requires admin:backup:export. For the scheduled named jobs use orboto_trigger_backup instead.',
+    description: 'Create an on-demand FULL workspace backup (database + storage) and return the ZIP as a base64 application/zip resource attachment - create, wait and download in one call (the server runs the export as a background run and this tool polls it; large workspaces can take minutes). Rows and file references share one snapshot; missing or incomplete files fail the run, never return a partial ZIP. Requires admin:backup:export. For the scheduled named jobs use orboto_trigger_backup instead.',
     inputSchema: z.object({}).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };

package/dist/tools/backup.test.js

@@ -68,20 +68,22 @@ describe('orboto_create_full_backup (ORB-1301 / async since ORB-1717)', () => {
             vi.useRealTimers();
         }
     });
-    it('a failed run surfaces the error instead of a partial ZIP', async () => {
+    it.each(['disk full', 'Backup source object is missing, unreadable or incomplete'])('a failed run surfaces %s instead of a partial ZIP', async (message) => {
         vi.useFakeTimers();
+        const download = vi.spyOn(client, 'getBinary');
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, _init) => {
             const u = url.toString();
             if (u.endsWith('/admin/backup/full')) {
                 return { ok: true, status: 202, statusText: 'Accepted', headers: new Headers({ 'content-type': 'application/json' }), json: async () => ({ runId: 'run-2' }), text: async () => '' };
             }
-            return { ok: true, status: 200, statusText: 'OK', headers: new Headers({ 'content-type': 'application/json' }), json: async () => ({ status: 'failed', errorMessage: 'disk full' }), text: async () => '' };
+            return { ok: true, status: 200, statusText: 'OK', headers: new Headers({ 'content-type': 'application/json' }), json: async () => ({ status: 'failed', errorMessage: message }), text: async () => '' };
         });
         try {
             const pending = makeCreateFullBackupHandler(client)();
-            const assertion = expect(pending).rejects.toThrow('disk full');
+            const assertion = expect(pending).rejects.toThrow(message);
             await vi.advanceTimersByTimeAsync(6_000);
             await assertion;
+            expect(download).not.toHaveBeenCalled();
         }
         finally {
             vi.useRealTimers();

package/dist/toolset.js

@@ -81,7 +81,10 @@ export const MINIMAL_TOOLS = new Set([
     'orboto_close_ticket',
     'orboto_timer_start',
     'orboto_timer_stop',
-    // Everything else, on demand
+    // Everything else, on demand (ORB-1959 measured orboto_messages at ~3k
+    // chars - a fifth of this tier's whole window - so the inbox stays in
+    // curated, where the default connection lives; minimal is the explicit
+    // small-model opt-in and reaches the inbox through orboto_api_call).
     'orboto_api_search',
     'orboto_api_call',
 ]);
@@ -118,6 +121,17 @@ export const CURATED_TOOLS = new Set([
     'orboto_timer_stop', // 772
     'orboto_log_time', // 130
     'orboto_get_timer', // 43
+    // ORB-1959 - agent coordination on the DEFAULT connection. Without
+    // these four an agent on curated could neither receive nor acknowledge
+    // mail (broadcasts included, they land in the inbox since ORB-1959),
+    // announce itself (heartbeat / presence) nor reach another agent - the
+    // workspace rules demand exactly that, and every fresh `mcp add` forgot
+    // the ?toolset=full workaround. Four small schemas; measured cost in
+    // manifest-size.test.ts.
+    'orboto_messages',
+    'orboto_agent_notify',
+    'orboto_agent_broadcast',
+    'orboto_agent_heartbeat',
     // Transport plumbing + the escape hatch itself
     'orboto_response_expand',
     // ORB-1741 - the way back from one-line manifest summaries: full

package/dist/toolset.test.js

@@ -54,6 +54,13 @@ describe('toolInToolset', () => {
         expect(toolInToolset('orboto_claim', 'curated')).toBe(true);
         expect(toolInToolset('orboto_api_call', 'curated')).toBe(true);
     });
+    // ORB-1959 - coordination is part of the default connection, not an opt-in.
+    it('curated carries the four agent-coordination tools; minimal stays the 12-tool loop', () => {
+        for (const name of ['orboto_messages', 'orboto_agent_notify', 'orboto_agent_broadcast', 'orboto_agent_heartbeat']) {
+            expect(toolInToolset(name, 'curated'), name).toBe(true);
+            expect(toolInToolset(name, 'minimal'), name).toBe(false);
+        }
+    });
     it('minimal admits only the daily loop + the escape hatch', () => {
         expect(toolInToolset('orboto_claim', 'minimal')).toBe(true);
         expect(toolInToolset('orboto_api_search', 'minimal')).toBe(true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.182.5",
+  "version": "0.183.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",