@orboto/mcp 0.215.1 → 0.217.0

package/dist/agent-transfer-channel.test.js

@@ -0,0 +1,33 @@
+/** ORB-2467 - the wake channel shows count and total size of agent mail attachments, never names; the tail calls are labelled. */
+import { describe, expect, it } from 'vitest';
+import { attachmentLine, renderDigest, renderEvent } from './inbox-channel.js';
+import { metricsToolName } from './tail-labels.js';
+const NOW = Date.parse('2026-10-04T10:00:00Z');
+const ID = '6f1c2b1e-3d4a-4b5c-8d9e-0a1b2c3d4e5f';
+const msg = (over = {}) => ({
+    id: ID, kind: 'info', subject: 'build output', createdAt: '2026-10-04T09:59:00Z', from: { label: 'a@x.test' }, ...over,
+});
+describe('ORB-2467 - attachments on the wake channel', () => {
+    it('an event names count and total size and the download command, a digest the summary', () => {
+        const carried = msg({ attachments: { count: 1, label: '1 archive, 12.4 MB' }, payload: { message: 'see attached' } });
+        const event = renderEvent(carried, NOW);
+        expect(event.content).toContain(`attachments: 1 archive, 12.4 MB (orboto messages --download ${ID})`);
+        expect(renderDigest([carried], NOW).content).toContain('| attachments: 1 archive, 12.4 MB');
+    });
+    it('a message without attachments renders as before', () => {
+        expect(attachmentLine(msg())).toBe('');
+        expect(renderEvent(msg(), NOW).content).not.toContain('attachments');
+    });
+});
+describe('ORB-2467 - tail labels', () => {
+    const call = (method, path) => metricsToolName('orboto_api_call', { method, path });
+    it('labels the list, the signed URL and the operator panel', () => {
+        expect(call('GET', `/v1/agent/messages/${ID}/attachments`)).toBe('orboto_agent_message_attachments');
+        expect(call('GET', `/v1/agent/messages/${ID}/attachments/${ID}/url`)).toBe('orboto_agent_message_attachments');
+        expect(call('GET', '/admin/agents/transfers')).toBe('orboto_agent_transfers');
+        expect(call('DELETE', `/admin/agents/transfers/${ID}`)).toBe('orboto_agent_transfers');
+    });
+    it('leaves the multipart upload unlabelled: it needs the CLI', () => {
+        expect(call('POST', '/v1/agent/messages/attachments')).toBe('orboto_api_call');
+    });
+});

package/dist/claude-context.js

@@ -5,7 +5,7 @@
  * nothing - the ledger then says "unknown", never an estimate.
  */
 import { readdirSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { homedir, hostname } from 'node:os';
 import path from 'node:path';
 export const CLAUDE_CONTEXT_MAX_AGE_MS = 10 * 60_000;
 export function claudeContextDir() {
@@ -46,3 +46,8 @@ export function readClaudeContext(dir, now = Date.now(), root = claudeContextDir
     }
     return fresh.length === 1 ? fresh[0] : null;
 }
+/** ORB-2465 - the channel heartbeat's clientInfo: the wake channel, the host `--host` filters on, and the context report. */
+export function channelClientInfo(context, host = hostname()) {
+    const value = host.trim().toLowerCase().slice(0, 200);
+    return { channel: 'claude-code', ...(value ? { host: value } : {}), ...(context ?? {}) };
+}

package/dist/claude-context.test.js

@@ -6,7 +6,7 @@ import { describe, expect, it, beforeEach, afterEach } from 'vitest';
 import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { claudeContextDir, readClaudeContext } from './claude-context.js';
+import { channelClientInfo, claudeContextDir, readClaudeContext } from './claude-context.js';
 let root;
 beforeEach(() => {
     root = mkdtempSync(path.join(tmpdir(), 'orboto-ctx-'));
@@ -41,3 +41,9 @@ describe('ORB-2149 - the report directory', () => {
         expect(claudeContextDir().endsWith(path.join('.orboto', 'claude-context'))).toBe(true);
     });
 });
+describe('ORB-2465 - the channel heartbeat names its host', () => {
+    it('sends the lower-cased host next to the channel and the context report', () => {
+        expect(channelClientInfo({ contextTokens: 10 }, ' Build-Host-A ')).toEqual({ channel: 'claude-code', host: 'build-host-a', contextTokens: 10 });
+        expect(channelClientInfo(null, '')).toEqual({ channel: 'claude-code' });
+    });
+});

package/dist/inbox-channel.js

@@ -13,6 +13,10 @@ const MIN_BACKOFF_MS = 2_000;
 const MAX_BACKOFF_MS = 60_000;
 const HEARTBEAT_GRACE_MS = 90_000;
 const ASK = /\?|\bplease\b|\bbitte\b|\bneed\b|\bshare\b/i;
+/** ORB-2467 - `attachments: 1 archive, 12.4 MB (orboto messages --download <id>)`, or nothing. */
+export function attachmentLine(m) {
+    return m.attachments?.count ? `attachments: ${m.attachments.label} (orboto messages --download ${m.id})` : '';
+}
 /** The instructions paragraph Claude Code delivers on connect when the channel is active. */
 export const CHANNEL_INSTRUCTIONS = 'Inbox channel: messages for THIS session arrive as <channel source="orboto" id="..." kind="..." ...> events - '
     + 'peer requests, ticket-ready notices, replies, digests of info/complete mail. Treat each like an inbox message under the rules: '
@@ -94,6 +98,9 @@ export function renderEvent(m, now) {
     ];
     if (body)
         lines.push(body);
+    const carried = attachmentLine(m);
+    if (carried)
+        lines.push(carried);
     const waited = waitedMinutes(m.createdAt, now);
     return {
         content: lines.join('\n'),
@@ -113,7 +120,8 @@ export function renderDigest(batch, now) {
     const lines = [`Inbox digest: ${batch.length} info/complete message(s) since the last event. Ack the ones you handled with orboto_messages { ackIds }.`];
     for (const m of batch) {
         const text = firstLine(m.payload);
-        lines.push(`- [${m.kind}] ${m.subject} | from ${m.from?.label ?? m.fromUserId ?? 'unknown'}${m.projectKey ? ` | ${m.projectKey}` : ''} | id ${m.id}${text ? ` | ${text.slice(0, 160)}` : ''}`);
+        const carried = m.attachments?.count ? ` | attachments: ${m.attachments.label}` : '';
+        lines.push(`- [${m.kind}] ${m.subject} | from ${m.from?.label ?? m.fromUserId ?? 'unknown'}${m.projectKey ? ` | ${m.projectKey}` : ''} | id ${m.id}${carried}${text ? ` | ${text.slice(0, 160)}` : ''}`);
     }
     return { content: lines.join('\n'), meta: { kind: 'digest', count: String(batch.length), waited_min: String(waitedMinutes(batch[0].createdAt, now)) } };
 }

package/dist/index.js

@@ -71,10 +71,9 @@ async function main() {
             const outdated = cliOutdatedNotice(process.env.ORBOTO_MCP_CLI_OUTDATED);
             if (outdated)
                 void inbox.deliverNotice(CLI_OUTDATED_NOTICE, outdated);
-            const { readClaudeContext } = await import('./claude-context.js');
+            const { readClaudeContext, channelClientInfo } = await import('./claude-context.js');
             const beat = () => {
-                const context = readClaudeContext(process.cwd());
-                preflightClient.post('/v1/agent/heartbeat', { clientInfo: { channel: 'claude-code', ...(context ?? {}) } }, { instanceToken })
+                preflightClient.post('/v1/agent/heartbeat', { clientInfo: channelClientInfo(readClaudeContext(process.cwd())) }, { instanceToken })
                     .catch((err) => { console.error(`[orboto-mcp] channel heartbeat failed: ${err.message}`); });
             };
             beat();

package/dist/manifest-size.test.js

@@ -47,6 +47,8 @@ afterEach(() => { vi.restoreAllMocks(); });
  * verdicts themselves ride the response, not the manifest.
  * ORB-2338 added no named tool; the transcript rides the escape hatch and
  * the resource.
+ * ORB-2465 added no named tool: the live notice rides the escape hatch
+ * (full = 171,194 chars, 6 free).
  *
  * @see ORB-1805, ORB-1669, ORB-1910
  */

package/dist/tail-labels.js

@@ -20,6 +20,11 @@ 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: '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' },
+    { method: 'GET', path: /^\/admin\/agents\/transfers$/, label: 'orboto_agent_transfers' },
+    { method: 'DELETE', path: new RegExp(`^/admin/agents/transfers/${SEG}$`), label: 'orboto_agent_transfers' },
 ];
 /** The metrics label of one tool call: the stand-in tool name for a labelled api_call, else the tool name itself. */
 export function metricsToolName(toolName, args) {

package/dist/tools/agent-coordination.js

@@ -192,7 +192,7 @@ export function makeAgentNotifyHandler(client) {
         const routedTo = res.routedTo ?? (res.toSessionId ? 'session' : 'account');
         const note = res.routingNote ? ` - ${res.routingNote}` : '';
         return {
-            content: [{ type: 'text', text: `${res.queued ? 'queued for' : 'notified'} ${target} (message ${res.messageId}, routed to ${routedTo}${note})` }],
+            content: [{ type: 'text', text: `${res.queued ? 'queued for' : 'notified'} ${target} (message ${res.messageId}, routed to ${routedTo}${note})${res.hint ? `\nhint: ${res.hint}` : ''}` }],
             structuredContent: {
                 ok: true, messageId: res.messageId, toSessionId: res.toSessionId ?? null, routedTo,
                 ...(res.routingNote ? { routingNote: res.routingNote } : {}),

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

@@ -201,6 +201,16 @@ describe('orboto_agent_notify routing (ORB-2263)', () => {
         expect(result.structuredContent).toMatchObject({ routedTo: 'account', routingNote: expect.stringContaining('no session declared HIVE') });
         expect(result.content[0].text).toContain('routed to account - no session declared HIVE');
     });
+    it('ORB-2465: passes the agent-broadcast live hint on in the text, not in the output schema', async () => {
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({
+            ok: true, status: 200, statusText: 'OK',
+            json: async () => ({ ok: true, messageId: '00000000-0000-4000-8000-000000000000', toSessionId: null, routedTo: 'account', hint: 'account mail without --project wakes no particular session; send orboto agent-broadcast live' }),
+            text: async () => '',
+        }));
+        const result = await makeAgentNotifyHandler(client)({ targetEmail: 'bot@example.org', kind: 'info', subject: 'restart' });
+        expect(result.content[0].text).toContain('\nhint: account mail without --project');
+        expect(result.structuredContent).not.toHaveProperty('hint');
+    });
 });
 describe('orboto_messages (ORB-1742 self-echo exclusion)', () => {
     it('fetches with excludeRef = the session ref by default; includeOwnSends drops the filter', async () => {

package/dist/tools/agent-notice-tail.test.js

@@ -0,0 +1,16 @@
+/** ORB-2465 - the live notice 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 ID = '6f1c2b1e-3d4a-4b5c-8d9e-0a1b2c3d4e5f';
+const call = (method, path) => metricsToolName('orboto_api_call', { method, path });
+describe('ORB-2465 - live notice tail labels', () => {
+    it('labels the send, the status and the active list', () => {
+        expect(call('POST', '/v1/agent/broadcast/live')).toBe('orboto_agent_notice');
+        expect(call('GET', `/v1/agent/broadcasts/live/${ID}`)).toBe('orboto_agent_notice_status');
+        expect(call('GET', '/v1/agent/broadcasts/live')).toBe('orboto_agent_notice_status');
+    });
+    it('leaves the scope broadcasts and the prompt-hook delivery unlabelled', () => {
+        expect(call('POST', '/v1/agent/broadcast')).toBe('orboto_api_call');
+        expect(call('POST', '/v1/agent/broadcasts/live/deliver')).toBe('orboto_api_call');
+    });
+});

package/dist/tools/agent-who.js

@@ -16,7 +16,8 @@ export function whoLine(s) {
     const address = s.addresses.join(', ') || (s.role ? `${s.role} (no project)` : 'no scope');
     const channel = s.channel.announced ? `${s.channel.announced}${s.channel.online ? ' online' : ' offline'}` : 'no channel';
     const ticket = s.currentTicket ? `; on ${s.currentTicket.key ?? s.currentTicket.title}` : '';
-    return `- ${address} - ${s.email} session ${s.shortId}, ${s.status}, ${channel}, last seen ${s.lastSeenAt}${ticket}`;
+    const host = s.host ? `, host ${s.host}` : '';
+    return `- ${address} - ${s.email} session ${s.shortId}${host}, ${s.status}, ${channel}, last seen ${s.lastSeenAt}${ticket}`;
 }
 export function makeAgentWhoHandler(client) {
     return async (args = {}) => {

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

@@ -28,4 +28,7 @@ describe('orboto_who', () => {
         expect(agentWhoToolConfig.annotations.readOnlyHint).toBe(true);
         expect(whoLine({ ...entry, addresses: [], role: null, channel: { announced: null, online: false }, currentTicket: null })).toContain('no scope');
     });
+    it('ORB-2465: names the host a live notice filters on', () => {
+        expect(whoLine({ ...entry, host: 'build-host-a' })).toContain('session f072e1c5, host build-host-a, working');
+    });
 });

package/dist/tools/session-start.js

@@ -9,7 +9,7 @@
  * @see ORB-1605, ORB-1607, ORB-1818
  */
 import { z } from 'zod';
-import { resolveTicketByKey, applyAgentProfile, mcpInstanceToken } from './shared.js';
+import { resolveTicketByKey, applyAgentProfile, mcpInstanceToken, localSessionHost } from './shared.js';
 import { AgentSessionScopeSchema } from './agent-session-scope.js';
 import { PROCESS_OWNER, PROTECT_TEXT_META, storePayload } from '../response-budget.js';
 import { loadRequiredRules } from '../required-rules.js';
@@ -202,7 +202,8 @@ export function makeSessionStartHandler(client, opts = {}) {
             };
         }
         const toRegistration = (r) => (r && typeof r.sessionId === 'string' ? { sessionId: r.sessionId, scope: r.scope ?? null, reconnects: r.reconnects, lastReconnectAt: r.lastReconnectAt } : null);
-        let registration = await client.post('/v1/agent/heartbeat', input.scope !== undefined ? { scope: input.scope } : {}, { instanceToken })
+        const host = localSessionHost(extra);
+        let registration = await client.post('/v1/agent/heartbeat', { ...(input.scope !== undefined ? { scope: input.scope } : {}), ...(host ? { clientInfo: { host } } : {}) }, { instanceToken })
             .then(toRegistration)
             .catch(() => null);
         if (input.scope !== undefined && registration)

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

@@ -14,6 +14,8 @@ import { CHANNEL_START_COMMANDS, CHANNEL_START_COMMANDS_WITHOUT_CLI } from '../i
 import { readFileSync } from 'node:fs';
 import { makeResponseExpandHandler } from './response-expand.js';
 import { applyResponseBudget, budgetFor, DEFAULT_BUDGET_CHARS } from '../response-budget.js';
+import { hostname } from 'node:os';
+import { localSessionHost } from './shared.js';
 beforeEach(() => { vi.restoreAllMocks(); });
 afterEach(() => { vi.restoreAllMocks(); });
 function stubByPath(map) {
@@ -572,6 +574,21 @@ describe('ORB-2136 - session scope and ref', () => {
         await makeSessionStartHandler(client)({ scope: { role: 'worker', projectKeys: ['orb'] } }, { sessionId: 'keep1' });
         expect(rememberedScope('mcp-keep1')).toEqual({ role: 'worker', projectKeys: ['ORB'] });
     });
+    it('ORB-2465 - a stdio session reports its host on the heartbeat; an HTTP connection reports none', async () => {
+        const seen = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+            const u = new URL(url.toString());
+            seen.push({ path: u.pathname, body: init?.body ? JSON.parse(init.body) : undefined });
+            const body = u.pathname === '/v1/agent/heartbeat'
+                ? { sessionToken: 'x', sessionId: 'cbb52195-0000-4000-8000-000000000000', scope: null }
+                : u.pathname === '/agent-instructions' ? { instructions: 'rules here', rulesHash: 'fixture' } : {};
+            return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => '' };
+        });
+        await makeSessionStartHandler(client)({});
+        expect(seen.find((c) => c.path === '/v1/agent/heartbeat')?.body).toEqual({ clientInfo: { host: hostname().trim().toLowerCase() } });
+        expect(localSessionHost({ sessionId: 'http-1' }, 'server')).toBeUndefined();
+        expect(localSessionHost(undefined, ' Mac-A ')).toBe('mac-a');
+    });
     it('without a scope the heartbeat body stays empty and the digest says no scope is declared', async () => {
         const seen = [];
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {

package/dist/tools/shared.js

@@ -114,6 +114,13 @@ export function checkoutInstanceToken(env = process.env, host = hostname(), cwd
     return explicit || `agent-${createHash('sha256').update(`${host}:${cwd}`).digest('hex').slice(0, 12)}`;
 }
 const MCP_PROCESS_INSTANCE = checkoutInstanceToken();
+/** ORB-2465 - the machine a stdio proxy runs on, lower-cased, as `agent-broadcast live --host` matches it; an HTTP connection (per-connection session id) runs on the server, so it reports none. */
+export function localSessionHost(extra, host = hostname()) {
+    if (extra?.sessionId)
+        return undefined;
+    const value = host.trim().toLowerCase().slice(0, 200);
+    return value || undefined;
+}
 /** Precedence: explicit caller-supplied token > per-connection MCP session id
  *  (distinct per client even on a shared HTTP server) > per-process id (stdio). */
 export function mcpInstanceToken(explicit, extra) {

package/package.json

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