@orboto/mcp 0.215.0 → 0.216.0

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/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,8 @@ 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' },
 ];
 /** 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.0",
+  "version": "0.216.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",