@orboto/mcp 0.212.0 → 0.212.1

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

@@ -0,0 +1,24 @@
+/**
+ * ORB-2347 - the inbox tool names the unregistered-caller rule in its description and in its answer.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { agentMessagesToolConfig, makeAgentMessagesHandler } from './agent-messages.js';
+afterEach(() => { vi.restoreAllMocks(); });
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+function stubInbox(sessionId) {
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({ ok: true, status: 200, statusText: 'OK', json: async () => ({ messages: [], sessionId }), text: async () => '' }));
+}
+describe('ORB-2347 - orboto_messages for an unregistered caller', () => {
+    it('the description states the rule', () => {
+        expect(agentMessagesToolConfig.description).toContain('Before orboto_session_start only account mail is listed');
+    });
+    it('an answer without a session id carries the register hint; a registered answer does not', async () => {
+        stubInbox(null);
+        const unregistered = (await makeAgentMessagesHandler(client)({})).content[0];
+        expect(unregistered.text).toContain('Not registered: only account mail is listed');
+        stubInbox('8772a665-0000-4000-8000-000000000000');
+        const registered = (await makeAgentMessagesHandler(client)({})).content[0];
+        expect(registered.text).not.toContain('Not registered');
+    });
+});

package/dist/tools/agent-messages.js

@@ -11,9 +11,10 @@ import { z } from 'zod';
 import { makeAgentMessageWorkHandler } from './agent-message-work.js';
 import { mcpInstanceToken } from './shared.js';
 const PartySchema = z.object({ userId: z.string(), email: z.string(), sessionId: z.string().nullable(), role: z.string().nullable(), label: z.string() });
+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 shows the whole account (ORB-2136). 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 (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).',
     inputSchema: z.object({
         messageWork: z.record(z.unknown()).optional()
             .describe('Work envelope {messageId, mutation, cursor, limit, openOnly}; schema: orboto_api_search.'),
@@ -101,6 +102,8 @@ export function makeAgentMessagesHandler(client) {
         }
         if (sessionId)
             lines.push(`This session: ${sessionId.slice(0, 8)} (ref ${instanceToken}).`);
+        else
+            lines.push(UNREGISTERED_INBOX_HINT);
         return {
             content: [{ type: 'text', text: lines.join('\n') }],
             structuredContent: {

package/dist/tools/session-start.js

@@ -301,7 +301,9 @@ export function makeSessionStartHandler(client, opts = {}) {
         lines.push('', '## This session');
         const scopeText = registration?.scope
             ? [registration.scope.role ? `role ${registration.scope.role}` : null, registration.scope.projectKeys?.length ? `projects ${registration.scope.projectKeys.join(', ')}` : null, registration.scope.ticketKeys?.length ? `tickets ${registration.scope.ticketKeys.join(', ')}` : null].filter(Boolean).join('; ')
-            : 'no scope declared - this session lists every account-addressed message; pass scope: { projectKeys, role } to narrow it';
+            : registration
+                ? 'no scope declared - this session lists every account-addressed message; pass scope: { projectKeys, role } to narrow it'
+                : 'registration failed - only account mail is listed; retry orboto_session_start or check mcp:use';
         lines.push(`ref ${instanceToken}${registration ? `, instance ${registration.sessionId.slice(0, 8)}` : ''}. ${scopeText}. Peers reach exactly this session with orboto_agent_notify { toSessionRef: "${registration ? registration.sessionId.slice(0, 8) : instanceToken}" }.`);
         const roleAddresses = registration?.scope?.role ? (registration.scope.projectKeys ?? []).map((k) => `${registration.scope.role}@${k}`) : [];
         if (roleAddresses.length)

package/dist/tools/session-start.test.js

@@ -618,3 +618,18 @@ describe('ORB-2136 - session scope and ref', () => {
         expect(docs).toContain('orboto mcp install');
     });
 });
+describe('ORB-2347 - an unregistered caller is told it sees account mail only', () => {
+    it('states the rule in the This session line when the heartbeat registers nothing, and keeps the scope text for a registered session', async () => {
+        stubByPath({ '/agent-instructions': { instructions: 'rules', rulesHash: 'h' } });
+        const unregistered = (await makeSessionStartHandler(client)()).content[0];
+        expect(unregistered.text).toContain('registration failed - only account mail is listed; retry orboto_session_start');
+        expect(unregistered.text).not.toContain('lists every account-addressed message');
+        stubByPath({
+            '/v1/agent/heartbeat': { sessionId: '8772a665-0000-4000-8000-000000000000', scope: null },
+            '/agent-instructions': { instructions: 'rules', rulesHash: 'h2' },
+        });
+        const registered = (await makeSessionStartHandler(client)({ forceRules: true })).content[0];
+        expect(registered.text).toContain('lists every account-addressed message');
+        expect(registered.text).not.toContain('not registered');
+    });
+});

package/package.json

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