@orboto/mcp 0.198.0 → 0.200.0

package/README.md

@@ -6,7 +6,25 @@ Model Context Protocol server for [orboto](https://orboto.io) - a self-hosted ti
 
 ## Quickstart
 
-There are two ways to authenticate the stdio proxy:
+The shortest path is the [orboto CLI](https://www.npmjs.com/package/orboto):
+
+```bash
+npm i -g orboto
+orboto login
+orboto mcp install            # writes the "orboto" server entry into ./.mcp.json
+orboto mcp install --scope user   # or into the Claude Code user config
+```
+
+The entry it writes runs `orboto mcp serve`, which installs and starts
+`@orboto/mcp` at **the version of the instance it connects to**, so the tool
+schemas always match that API. The proxy versions are cached under
+`~/.orboto/mcp/<version>/`, the entry carries no credential, and
+`orboto mcp status` prints the instance version, the cached proxies and the
+entry of the current directory. In Claude Code, `orboto claude` then starts a
+session with the wake channel loaded.
+
+Everything below configures the proxy by hand, for clients the CLI does not
+write. There are two ways to authenticate the stdio proxy:
 
 - **OAuth login (recommended for people).** Omit `ORBOTO_API_KEY`. On first use the proxy opens your browser to the orboto login (which is your SSO login when SSO is configured), you approve once, and it keeps a short-lived, self-refreshing session cached on disk. Nothing to paste, nothing long-lived.
 - **API key (service accounts / CI).** Set `ORBOTO_API_KEY` to an `orb_…` key from **Profile → API keys → Generate**. Best for headless machines with no browser.
@@ -104,6 +122,8 @@ Omit `ORBOTO_API_KEY` to use OAuth login instead. `codex mcp add` writes the sam
 | `ORBOTO_MCP_TOOLSET` | no | `minimal`, `curated` (default) or `full`. Curated is the measured high-frequency set (31 tools, ~7.8k tokens of schemas at connect) - the whole REST API stays reachable via `orboto_api_search` + `orboto_api_call`. `full` registers every named tool (175, ~39.5k tokens). `minimal` is the daily loop only (12 tools, ~2.8k tokens including the instructions block) for local models with an 8k/16k context window. HTTP clients can pick per connection instead: `?toolset=minimal` on the `/mcp` URL or an `x-orboto-toolset: minimal` header. |
 | `ORBOTO_MCP_PORT` | no | Listen port when transport is `http`. Default `3100`. |
 | `ORBOTO_MCP_CLIENT` | no | User-agent suffix that lands in the API audit log. Useful for filtering audit rows by client. |
+| `ORBOTO_MCP_CHANNEL` | no | `1` (default) makes the stdio proxy a Claude Code channel: it follows the session's inbox stream and pushes each message as a `notifications/claude/channel` event that wakes the session (`claude --dangerously-load-development-channels server:orboto`, ORB-2140). `0` disables it. |
+| `ORBOTO_MCP_CHANNEL_DIGEST_MINUTES` | no | Digest window for `info` / `complete` inbox mail on the channel. Default `15`; `0` delivers every message at once. Requests, errors, questions and mail older than five minutes always go out immediately. |
 
 ## Version compatibility
 

package/dist/claude-context.js

@@ -0,0 +1,47 @@
+/**
+ * ORB-2149 - what a wake of this session costs. `orboto claude-statusline`
+ * writes one file per Claude Code session; the proxy reports the freshest one
+ * for its own directory. Two sessions in one directory, or none, report
+ * nothing - the ledger then says "unknown", never an estimate.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+export const CLAUDE_CONTEXT_MAX_AGE_MS = 10 * 60_000;
+export function claudeContextDir() {
+    return path.join(homedir(), '.orboto', 'claude-context');
+}
+/** The one fresh report for `dir`; ambiguity and absence both mean "unknown". */
+export function readClaudeContext(dir, now = Date.now(), root = claudeContextDir()) {
+    let names;
+    try {
+        names = readdirSync(root).filter((n) => n.endsWith('.json'));
+    }
+    catch {
+        return null;
+    }
+    const fresh = [];
+    for (const name of names) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(path.join(root, name), 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (parsed.cwd !== dir)
+            continue;
+        const updated = typeof parsed.updatedAt === 'string' ? Date.parse(parsed.updatedAt) : NaN;
+        if (!Number.isFinite(updated) || now - updated > CLAUDE_CONTEXT_MAX_AGE_MS)
+            continue;
+        if (typeof parsed.contextTokens !== 'number' || !Number.isFinite(parsed.contextTokens))
+            continue;
+        fresh.push({
+            contextTokens: Math.max(0, Math.round(parsed.contextTokens)),
+            ...(typeof parsed.contextWindowSize === 'number' && Number.isFinite(parsed.contextWindowSize)
+                ? { contextWindowSize: Math.max(0, Math.round(parsed.contextWindowSize)) }
+                : {}),
+        });
+    }
+    return fresh.length === 1 ? fresh[0] : null;
+}

package/dist/claude-context.test.js

@@ -0,0 +1,38 @@
+/**
+ * ORB-2149 - the proxy reports a context size only when exactly one fresh
+ * report belongs to its directory.
+ */
+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 { readClaudeContext } from './claude-context.js';
+let root;
+beforeEach(() => {
+    root = mkdtempSync(path.join(tmpdir(), 'orboto-ctx-'));
+    mkdirSync(root, { recursive: true });
+});
+afterEach(() => { rmSync(root, { recursive: true, force: true }); });
+function write(name, body) {
+    writeFileSync(path.join(root, name), JSON.stringify(body));
+}
+describe('ORB-2149 - claude statusline context reports', () => {
+    it('reports the one fresh file for this directory', () => {
+        write('a.json', { cwd: '/work/repo', contextTokens: 120_000, contextWindowSize: 200_000, updatedAt: new Date().toISOString() });
+        write('b.json', { cwd: '/elsewhere', contextTokens: 5, updatedAt: new Date().toISOString() });
+        expect(readClaudeContext('/work/repo', Date.now(), root)).toEqual({ contextTokens: 120_000, contextWindowSize: 200_000 });
+    });
+    it('reports nothing for a stale report, an unknown directory, a broken file or two sessions in one directory', () => {
+        write('stale.json', { cwd: '/work/repo', contextTokens: 1, updatedAt: new Date(Date.now() - 20 * 60_000).toISOString() });
+        expect(readClaudeContext('/work/repo', Date.now(), root)).toBeNull();
+        expect(readClaudeContext('/nothing/here', Date.now(), root)).toBeNull();
+        write('broken.json', { cwd: '/work/two' });
+        expect(readClaudeContext('/work/two', Date.now(), root)).toBeNull();
+        write('one.json', { cwd: '/work/two', contextTokens: 10, updatedAt: new Date().toISOString() });
+        write('two.json', { cwd: '/work/two', contextTokens: 20, updatedAt: new Date().toISOString() });
+        expect(readClaudeContext('/work/two', Date.now(), root)).toBeNull();
+    });
+    it('reports nothing when the directory does not exist', () => {
+        expect(readClaudeContext('/work/repo', Date.now(), path.join(root, 'missing'))).toBeNull();
+    });
+});

package/dist/connect-script.js

@@ -0,0 +1,30 @@
+/**
+ * ORB-2157 - the one source of the script an agent follows when a person
+ * asks it to set orboto up. `orboto_help { topic: "connect" }` returns it,
+ * docs/connect-your-agent.md, docs/claude-code.md and skills/orboto/SKILL.md
+ * carry the same sentences, and connect-script.test.ts holds them together.
+ */
+export const CONNECT_SCRIPT_HEADING = 'If you are an AI agent helping a person set this up';
+export const CONNECT_SCRIPT_STEPS = [
+    'Work one step per message: say in one sentence what the step does and why, run it, show the result, and only then move on.',
+    'Run every step you can run yourself - `orboto connect --yes` checks Node and Claude Code, writes the `orboto` server entry for this directory and prints the exact start command with the standing arguments.',
+    'Hand the person only the steps that need a human: the browser login, quitting and restarting the session with that command, confirming the servers from `.mcp.json` and the local-development prompt, and, on a Team or Enterprise plan, the one Owner switch that allows channels.',
+    'Give every command the person runs verbatim in its own code block, never paraphrased and never merged into prose.',
+    'Verify before you continue: `orboto whoami` for the identity, `orboto mcp status` for the entry of this directory, `orboto connect --verify` for the channel.',
+    'Never paste a reference page into the chat - link it and keep the message to the step you are on.',
+    'Never ask for an API key, a password or a token in the chat; `orboto login` writes the credential itself.',
+    'When a check fails, name the cause from the troubleshooting table, fix it, and repeat the check before the next step.',
+    'Finish with `orboto connect --verify` and one real first task, so the person sees their own tickets rather than a success message.',
+];
+/** The help topic's body: the heading, the numbered steps, the pages to link. */
+export function connectScriptText() {
+    const steps = CONNECT_SCRIPT_STEPS.map((step, index) => `${index + 1}. ${step}`);
+    return [
+        CONNECT_SCRIPT_HEADING,
+        '',
+        ...steps,
+        '',
+        'The pages to link instead of pasting: docs/connect-your-agent.md (the first hour, in plain words),',
+        'docs/claude-code.md (start commands, standing arguments, troubleshooting table), docs/mcp-setup.md (any other client).',
+    ].join('\n');
+}

package/dist/connect-script.test.js

@@ -0,0 +1,42 @@
+/**
+ * ORB-2157 - the setup script has one source. The help topic, the two docs
+ * pages and the skill are checked against it, so a sentence cannot be
+ * improved in one place and stay old in the other three.
+ */
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { CONNECT_SCRIPT_HEADING, CONNECT_SCRIPT_STEPS, connectScriptText } from './connect-script.js';
+import { makeHelpHandler } from './tools/help.js';
+const read = (relative) => readFileSync(new URL(`../../../${relative}`, import.meta.url), 'utf8');
+const CARRIERS = ['docs/connect-your-agent.md', 'docs/claude-code.md', 'skills/orboto/SKILL.md'];
+describe('the connect script', () => {
+    it('reads as a numbered script with the pages it links', () => {
+        const text = connectScriptText();
+        expect(text).toContain(CONNECT_SCRIPT_HEADING);
+        CONNECT_SCRIPT_STEPS.forEach((step, index) => expect(text).toContain(`${index + 1}. ${step}`));
+        expect(text).toContain('docs/connect-your-agent.md');
+    });
+    it.each(CARRIERS)('%s carries every step verbatim', (file) => {
+        const page = read(file);
+        for (const step of CONNECT_SCRIPT_STEPS)
+            expect(page).toContain(step);
+    });
+    it('orboto_help returns it for the topic "connect"', async () => {
+        const result = await makeHelpHandler()({ topic: 'connect' });
+        const text = (result.content?.[0]).text;
+        for (const step of CONNECT_SCRIPT_STEPS)
+            expect(text).toContain(step);
+        expect(result.structuredContent).toMatchObject({ tool: 'topic:connect' });
+    });
+    it('names the known topics when the topic is unknown, and asks for one when nothing is passed', async () => {
+        const handler = makeHelpHandler();
+        const unknown = (await handler({ topic: 'nope' })).content?.[0];
+        expect(unknown.text).toContain('connect');
+        const empty = (await handler({})).content?.[0];
+        expect(empty.text).toContain('connect');
+    });
+    it('still answers a tool name', async () => {
+        const result = await makeHelpHandler()({ tool: 'orboto_definitely_not_a_tool' });
+        expect((result.content?.[0]).text).toContain('No guidance registered');
+    });
+});

package/dist/inbox-channel.js

@@ -0,0 +1,288 @@
+export const CHANNEL_METHOD = 'notifications/claude/channel';
+export const CHANNEL_CAPABILITY = 'claude/channel';
+export const DEFAULT_DIGEST_MINUTES = 15;
+const IMMEDIATE_AFTER_MS = 5 * 60_000;
+const CONTENT_CAP = 2000;
+const SEEN_WINDOW = 1000;
+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;
+/** 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: '
+    + 'a ticket-ready or a request inside your scope is the operator\'s instruction, act on it; read the full message with orboto_messages when the event is cut; '
+    + 'reply with orboto_agent_notify (toSessionRef = the sender\'s instance short id in the from attribute) and acknowledge with orboto_messages { ackIds } once handled. '
+    + 'Never answer the channel itself and never ack what you did not handle - dismiss it instead with orboto_messages { dismiss: { ids, reason } }: '
+    + 'not_mine for another session\'s mail (the sender is told, and the message never reaches this session again), obsolete or duplicate with a note when the request is already done. '
+    + 'A session that declared no scope is woken by mail addressed to it and by broadcasts only, and gets one notice event saying so on connect: '
+    + 'declare the scope with orboto_session_start { scope: { role, projectKeys } } to be woken by the account\'s project mail again - '
+    + 'the rest of the account\'s inbox stays readable with orboto_messages the whole time.';
+const START_FLAG = '--dangerously-load-development-channels server:orboto';
+/** ORB-2148 - the commands an agent hands its operator verbatim; docs/claude-code.md carries the same lines. */
+export const CHANNEL_START_COMMANDS = {
+    fresh: 'orboto claude',
+    continueLatest: 'orboto claude --continue',
+    resumeById: 'orboto claude --resume <session id>',
+};
+/** The raw Claude Code form, for a machine without the orboto CLI. */
+export const CHANNEL_START_COMMANDS_WITHOUT_CLI = {
+    fresh: `claude ${START_FLAG}`,
+    continueLatest: `claude ${START_FLAG} --continue`,
+    resumeById: `claude ${START_FLAG} --resume <session id>`,
+};
+/** The `orboto_session_start` block of a stdio proxy whose channel is on. */
+export function channelStartLines() {
+    return [
+        '## Wake channel',
+        'This proxy pushes inbox messages into the session as <channel source="orboto"> events, but only when Claude Code was started with the development-channels flag. '
+            + 'Run in this repository (`orboto` is this server\'s key in .mcp.json), and confirm the "local development" prompt Claude Code shows on every such start:',
+        `- new session: \`${CHANNEL_START_COMMANDS.fresh}\``,
+        `- continue the most recent conversation here: \`${CHANNEL_START_COMMANDS.continueLatest}\``,
+        `- resume a specific conversation: \`${CHANNEL_START_COMMANDS.resumeById}\` (without an id Claude Code opens a picker)`,
+        'The entry `orboto claude` needs comes from `orboto mcp install`; without the orboto CLI the same starts read '
+            + `\`${CHANNEL_START_COMMANDS_WITHOUT_CLI.fresh}\`, \`${CHANNEL_START_COMMANDS_WITHOUT_CLI.continueLatest}\` and \`${CHANNEL_START_COMMANDS_WITHOUT_CLI.resumeById}\`.`,
+        'A probe that produces no channel event means this session was not started that way: give the operator these commands verbatim, do not paraphrase them.',
+    ];
+}
+function firstLine(payload) {
+    if (!payload)
+        return '';
+    for (const key of ['message', 'body', 'text']) {
+        const v = payload[key];
+        if (typeof v === 'string' && v.trim())
+            return v.trim();
+    }
+    return '';
+}
+function waitedMinutes(createdAt, now) {
+    const t = Date.parse(createdAt.replace(' ', 'T').replace(/\+00$/, '+00:00'));
+    if (Number.isNaN(t))
+        return 0;
+    return Math.max(0, Math.floor((now - t) / 60_000));
+}
+/** A message goes out at once when it asks for something or already waited; the rest is digest material. */
+export function isImmediate(m, now, digestMinutes) {
+    if (digestMinutes <= 0)
+        return true;
+    if (m.kind === 'request' || m.kind === 'error')
+        return true;
+    if (waitedMinutes(m.createdAt, now) * 60_000 >= IMMEDIATE_AFTER_MS)
+        return true;
+    return ASK.test(`${m.subject} ${firstLine(m.payload)}`);
+}
+export function renderEvent(m, now) {
+    const from = m.from?.label ?? m.fromUserId ?? 'unknown';
+    const to = m.to?.label ?? 'you';
+    const text = firstLine(m.payload);
+    const body = text.length > CONTENT_CAP ? `${text.slice(0, CONTENT_CAP)} [... cut, read the rest with orboto_messages]` : text;
+    const lines = [
+        `[${m.kind}] ${m.subject}`,
+        `from ${from} to ${to}${m.projectKey ? ` | project ${m.projectKey}` : ''} | id ${m.id}${m.threadId ? ` | thread ${m.threadId}` : ''}`,
+    ];
+    if (body)
+        lines.push(body);
+    const waited = waitedMinutes(m.createdAt, now);
+    return {
+        content: lines.join('\n'),
+        meta: {
+            id: m.id, kind: m.kind, project: m.projectKey ?? '',
+            from: from, from_session: (m.from?.sessionId ?? '').slice(0, 8), to_session: (m.to?.sessionId ?? '').slice(0, 8),
+            waited_min: String(waited),
+        },
+    };
+}
+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)}` : ''}`);
+    }
+    return { content: lines.join('\n'), meta: { kind: 'digest', count: String(batch.length), waited_min: String(waitedMinutes(batch[0].createdAt, now)) } };
+}
+export class InboxChannel {
+    opts;
+    log;
+    now;
+    digestMinutes;
+    abort = new AbortController();
+    closed = false;
+    retryTimer = null;
+    digestTimer = null;
+    backoff = MIN_BACKOFF_MS;
+    since;
+    lastId = null;
+    seen = new Set();
+    seenOrder = [];
+    batch = [];
+    /** Counters an operator can read from the log; tests read them directly. */
+    stats = { delivered: 0, digested: 0, duplicates: 0, reconnects: 0, notices: 0 };
+    constructor(opts) {
+        this.opts = opts;
+        this.log = opts.log ?? ((msg) => { try {
+            process.stderr.write(`[orboto-mcp-channel] ${msg}\n`);
+        }
+        catch { /* ignore */ } });
+        this.now = opts.now ?? (() => Date.now());
+        this.digestMinutes = opts.digestMinutes ?? DEFAULT_DIGEST_MINUTES;
+        this.since = opts.since ?? new Date(this.now()).toISOString();
+    }
+    start() {
+        void this.loop();
+    }
+    close() {
+        this.closed = true;
+        if (this.retryTimer) {
+            clearTimeout(this.retryTimer);
+            this.retryTimer = null;
+        }
+        if (this.digestTimer) {
+            clearTimeout(this.digestTimer);
+            this.digestTimer = null;
+        }
+        try {
+            this.abort.abort();
+        }
+        catch { /* ignore */ }
+    }
+    /** Feed one message as the stream would; exported for tests and for the digest policy. */
+    async deliver(m) {
+        if (!m?.id)
+            return;
+        if (this.seen.has(m.id)) {
+            this.stats.duplicates += 1;
+            return;
+        }
+        this.remember(m.id);
+        this.lastId = m.id;
+        if (isImmediate(m, this.now(), this.digestMinutes)) {
+            await this.emit(renderEvent(m, this.now()));
+            this.stats.delivered += 1;
+            return;
+        }
+        this.batch.push(m);
+        this.stats.digested += 1;
+        if (!this.digestTimer) {
+            this.digestTimer = setTimeout(() => { this.digestTimer = null; void this.flushDigest(); }, this.digestMinutes * 60_000);
+        }
+    }
+    /** ORB-2151 - a server notice (the scope hint) is emitted as-is and never becomes the replay anchor. */
+    async deliverNotice(notice, content) {
+        if (!content)
+            return;
+        this.stats.notices += 1;
+        await this.emit({ content, meta: { kind: 'notice', notice } });
+    }
+    async flushDigest() {
+        if (this.batch.length === 0)
+            return;
+        const batch = this.batch.splice(0);
+        await this.emit(renderDigest(batch, this.now()));
+    }
+    remember(id) {
+        this.seen.add(id);
+        this.seenOrder.push(id);
+        if (this.seenOrder.length > SEEN_WINDOW) {
+            const gone = this.seenOrder.shift();
+            if (gone)
+                this.seen.delete(gone);
+        }
+    }
+    async emit(event) {
+        try {
+            await this.opts.mcp.server.notification({ method: CHANNEL_METHOD, params: { content: event.content, meta: event.meta } });
+            this.log(`channel event → ${event.meta.kind} ${event.meta.id ?? ''}`.trim());
+        }
+        catch (err) {
+            this.log(`channel notification failed: ${err.message}`);
+        }
+    }
+    async loop() {
+        while (!this.closed) {
+            try {
+                await this.consume();
+                this.backoff = MIN_BACKOFF_MS;
+            }
+            catch (err) {
+                if (this.closed)
+                    return;
+                this.log(`inbox stream closed: ${err instanceof Error ? err.message : String(err)} - retrying in ${this.backoff}ms`);
+            }
+            if (this.closed)
+                return;
+            this.stats.reconnects += 1;
+            await new Promise((resolve) => { this.retryTimer = setTimeout(resolve, this.backoff); });
+            this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF_MS);
+        }
+    }
+    async consume() {
+        const fetchFn = this.opts.fetchFn ?? fetch;
+        this.abort = new AbortController();
+        const since = this.lastId ?? this.since;
+        const url = `${this.opts.baseUrl.replace(/\/$/, '')}/v1/agent/messages/stream?since=${encodeURIComponent(since)}`;
+        const bearer = this.opts.tokenProvider ? await this.opts.tokenProvider.getAccessToken() : (this.opts.apiKey ?? '');
+        const res = await fetchFn(url, {
+            method: 'GET',
+            headers: { Authorization: `Bearer ${bearer}`, Accept: 'text/event-stream', 'x-orboto-agent-session': this.opts.instanceToken },
+            signal: this.abort.signal,
+        });
+        if (!res.ok || !res.body)
+            throw new Error(`inbox stream handshake failed (status=${res.status})`);
+        this.log(`inbox channel connected (since ${since})`);
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = '';
+        let lastFrame = this.now();
+        const heartbeat = setInterval(() => {
+            if (this.now() - lastFrame > HEARTBEAT_GRACE_MS) {
+                try {
+                    this.abort.abort();
+                }
+                catch { /* ignore */ }
+            }
+        }, 30_000);
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                lastFrame = this.now();
+                buf += decoder.decode(value, { stream: true });
+                let idx;
+                while ((idx = buf.indexOf('\n\n')) !== -1) {
+                    const frame = buf.slice(0, idx);
+                    buf = buf.slice(idx + 2);
+                    const line = frame.split('\n').find((l) => l.startsWith('data: '));
+                    if (!line)
+                        continue;
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(line.slice(6));
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (parsed.notice) {
+                        await this.deliverNotice(parsed.notice, parsed.content ?? '');
+                        continue;
+                    }
+                    await this.deliver(parsed);
+                }
+            }
+        }
+        finally {
+            clearInterval(heartbeat);
+            try {
+                reader.releaseLock();
+            }
+            catch { /* ignore */ }
+        }
+    }
+}
+/** ORB-2140 - the digest window from the environment; NaN or negative fall back to the default. */
+export function digestMinutesFromEnv(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return DEFAULT_DIGEST_MINUTES;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : DEFAULT_DIGEST_MINUTES;
+}

package/dist/inbox-channel.test.js

@@ -0,0 +1,140 @@
+/**
+ * ORB-2140 - the inbox channel: stream messages become channel notifications,
+ * digest policy, dedupe across reconnects, and the capability declaration.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
+import { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS, CHANNEL_METHOD, InboxChannel, digestMinutesFromEnv, isImmediate, renderEvent } from './inbox-channel.js';
+import { buildOrbotoMcpServer } from './server.js';
+function mockMcp() {
+    const notification = vi.fn().mockResolvedValue(undefined);
+    return { mcp: { server: { notification } }, notification };
+}
+function sse(frames) {
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+        start(controller) {
+            for (const frame of frames)
+                controller.enqueue(encoder.encode(`data: ${JSON.stringify(frame)}\n\n`));
+            controller.close();
+        },
+    });
+    return new Response(stream, { status: 200, headers: { 'content-type': 'text/event-stream' } });
+}
+const NOW = Date.parse('2026-09-18T10:00:00Z');
+const msg = (over = {}) => ({
+    id: 'm1', fromUserId: 'u-spec', kind: 'request', subject: 'ticket-ready:ORB-1', payload: { message: 'please take it' },
+    threadId: null, projectKey: 'ORB', createdAt: '2026-09-18 09:59:30+00',
+    from: { email: 'spec@orboto.io', sessionId: 'aaaaaaaa-0000-4000-8000-000000000000', role: 'spec', label: 'spec@orboto.io (spec, aaaaaaaa)' },
+    to: { email: 'claude@orboto.io', sessionId: 'bbbbbbbb-0000-4000-8000-000000000000', role: 'integrator', label: 'claude@orboto.io (integrator, bbbbbbbb)' },
+    ...over,
+});
+beforeEach(() => { vi.useFakeTimers(); vi.setSystemTime(NOW); });
+afterEach(() => { vi.useRealTimers(); vi.restoreAllMocks(); });
+describe('renderEvent / isImmediate', () => {
+    it('names both parties, carries id, project and thread, and caps the body', () => {
+        const e = renderEvent(msg({ threadId: 't1', payload: { message: 'x'.repeat(2500) } }), NOW);
+        expect(e.content.split('\n')[0]).toBe('[request] ticket-ready:ORB-1');
+        expect(e.content.split('\n')[1]).toBe('from spec@orboto.io (spec, aaaaaaaa) to claude@orboto.io (integrator, bbbbbbbb) | project ORB | id m1 | thread t1');
+        expect(e.content).toContain('[... cut, read the rest with orboto_messages]');
+        expect(e.meta).toMatchObject({ id: 'm1', kind: 'request', project: 'ORB', from_session: 'aaaaaaaa', to_session: 'bbbbbbbb', waited_min: '0' });
+    });
+    it('request, error, a question and a message that waited over five minutes go out at once; plain info is digest material', () => {
+        expect(isImmediate(msg({ kind: 'info', payload: { message: 'pushed abc' } }), NOW, 15)).toBe(false);
+        expect(isImmediate(msg({ kind: 'request' }), NOW, 15)).toBe(true);
+        expect(isImmediate(msg({ kind: 'error', payload: null }), NOW, 15)).toBe(true);
+        expect(isImmediate(msg({ kind: 'info', payload: { message: 'can you check?' } }), NOW, 15)).toBe(true);
+        expect(isImmediate(msg({ kind: 'info', payload: { message: 'old' }, createdAt: '2026-09-18 09:50:00+00' }), NOW, 15)).toBe(true);
+        expect(isImmediate(msg({ kind: 'info', payload: { message: 'pushed abc' } }), NOW, 0)).toBe(true);
+    });
+    it('reads the digest window from the environment with a safe default', () => {
+        expect(digestMinutesFromEnv(undefined)).toBe(15);
+        expect(digestMinutesFromEnv('0')).toBe(0);
+        expect(digestMinutesFromEnv('7.9')).toBe(7);
+        expect(digestMinutesFromEnv('nope')).toBe(15);
+        expect(digestMinutesFromEnv('-3')).toBe(15);
+    });
+});
+describe('InboxChannel', () => {
+    it('turns each streamed message into one channel notification and batches info into a digest', async () => {
+        const { mcp, notification } = mockMcp();
+        const fetchFn = vi.fn().mockResolvedValueOnce(sse([
+            msg(),
+            msg({ id: 'm2', kind: 'info', subject: 'pushed 1', payload: { message: 'ok' }, createdAt: '2026-09-18 09:59:50+00' }),
+            msg({ id: 'm3', kind: 'complete', subject: 'done 2', payload: null, createdAt: '2026-09-18 09:59:55+00' }),
+        ])).mockImplementation(() => new Promise(() => { }));
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-proc', mcp, fetchFn, log: () => { }, digestMinutes: 15 });
+        channel.start();
+        await vi.waitFor(() => expect(notification).toHaveBeenCalledTimes(1));
+        const first = notification.mock.calls[0][0];
+        expect(first.method).toBe(CHANNEL_METHOD);
+        expect(first.params.meta.id).toBe('m1');
+        expect(fetchFn.mock.calls[0][1].headers['x-orboto-agent-session']).toBe('mcp-proc');
+        expect(String(fetchFn.mock.calls[0][0])).toContain('/v1/agent/messages/stream?since=2026-09-18T10%3A00%3A00.000Z');
+        expect(channel.stats).toMatchObject({ delivered: 1, digested: 2 });
+        await vi.advanceTimersByTimeAsync(15 * 60_000);
+        expect(notification).toHaveBeenCalledTimes(2);
+        const digest = notification.mock.calls[1][0];
+        expect(digest.params.meta).toMatchObject({ kind: 'digest', count: '2' });
+        expect(digest.params.content).toContain('- [info] pushed 1');
+        expect(digest.params.content).toContain('- [complete] done 2');
+        channel.close();
+    });
+    it('reconnects from the last delivered id and never delivers a message twice', async () => {
+        const { mcp, notification } = mockMcp();
+        const fetchFn = vi.fn()
+            .mockResolvedValueOnce(sse([msg()]))
+            .mockResolvedValueOnce(sse([msg(), msg({ id: 'm9', subject: 'second' })]))
+            .mockImplementation(() => new Promise(() => { }));
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-proc', mcp, fetchFn, log: () => { }, digestMinutes: 0 });
+        channel.start();
+        await vi.waitFor(() => expect(notification).toHaveBeenCalledTimes(1));
+        await vi.advanceTimersByTimeAsync(2_000);
+        await vi.waitFor(() => expect(notification).toHaveBeenCalledTimes(2));
+        expect(String(fetchFn.mock.calls[1][0])).toContain('since=m1');
+        expect(channel.stats).toMatchObject({ delivered: 2, duplicates: 1 });
+        expect(channel.stats.reconnects).toBeGreaterThanOrEqual(1);
+        channel.close();
+    });
+    it('ORB-2151 - a server notice becomes its own event and never becomes the replay anchor', async () => {
+        const { mcp, notification } = mockMcp();
+        const hint = { notice: 'declare_scope', sessionId: 'cccccccc-0000-4000-8000-000000000000', content: 'declare your scope: orboto_session_start { scope: { role, projectKeys } }' };
+        const fetchFn = vi.fn()
+            .mockResolvedValueOnce(sse([hint, msg()]))
+            .mockImplementation(() => new Promise(() => { }));
+        const channel = new InboxChannel({ baseUrl: 'https://x.test', apiKey: 'orb_k', instanceToken: 'mcp-proc', mcp, fetchFn, log: () => { }, digestMinutes: 0 });
+        channel.start();
+        await vi.waitFor(() => expect(notification).toHaveBeenCalledTimes(2));
+        const first = notification.mock.calls[0][0];
+        expect(first.params.meta).toEqual({ kind: 'notice', notice: 'declare_scope' });
+        expect(first.params.content).toContain('orboto_session_start');
+        expect(channel.stats).toMatchObject({ notices: 1, delivered: 1 });
+        await vi.advanceTimersByTimeAsync(2_000);
+        await vi.waitFor(() => expect(fetchFn).toHaveBeenCalledTimes(2));
+        expect(String(fetchFn.mock.calls[1][0])).toContain('since=m1');
+        channel.close();
+    });
+});
+describe('server capability', () => {
+    async function connect(channel) {
+        vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('offline test'));
+        const server = await buildOrbotoMcpServer({ baseUrl: 'https://x.test', apiKey: 'orb_k', channel });
+        const client = new Client({ name: 't', version: '0' });
+        const [a, b] = InMemoryTransport.createLinkedPair();
+        await Promise.all([server.connect(a), client.connect(b)]);
+        return { server, client };
+    }
+    it('declares claude/channel and the channel instructions only when asked (stdio)', async () => {
+        const on = await connect(true);
+        expect(on.client.getServerCapabilities()?.experimental).toHaveProperty(CHANNEL_CAPABILITY);
+        expect(on.client.getInstructions()).toContain(CHANNEL_INSTRUCTIONS.slice(0, 40));
+        await on.client.close();
+        await on.server.close();
+        const off = await connect(false);
+        expect(off.client.getServerCapabilities()?.experimental ?? {}).not.toHaveProperty(CHANNEL_CAPABILITY);
+        expect(off.client.getInstructions() ?? '').not.toContain('Inbox channel:');
+        await off.client.close();
+        await off.server.close();
+    });
+});

package/dist/index.js

@@ -53,10 +53,28 @@ async function main() {
             console.error(`[orboto-mcp] ${err.message}`);
             process.exit(1);
         }
-        const server = await buildOrbotoMcpServer(clientConfig);
+        const channel = (process.env.ORBOTO_MCP_CHANNEL ?? '1') !== '0';
+        const server = await buildOrbotoMcpServer({ ...clientConfig, channel, instanceToken: (await import('./tools/shared.js')).mcpProcessInstance() });
         const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
         const stdio = new StdioServerTransport();
         await server.connect(stdio);
+        if (channel) {
+            const { InboxChannel, digestMinutesFromEnv } = await import('./inbox-channel.js');
+            const { mcpProcessInstance } = await import('./tools/shared.js');
+            const instanceToken = mcpProcessInstance();
+            const inbox = new InboxChannel({ ...clientConfig, instanceToken, mcp: server, digestMinutes: digestMinutesFromEnv(process.env.ORBOTO_MCP_CHANNEL_DIGEST_MINUTES) });
+            inbox.start();
+            const { readClaudeContext } = await import('./claude-context.js');
+            const beat = () => {
+                const context = readClaudeContext(process.cwd());
+                preflightClient.post('/v1/agent/heartbeat', { clientInfo: { channel: 'claude-code', ...(context ?? {}) } }, { instanceToken })
+                    .catch((err) => { console.error(`[orboto-mcp] channel heartbeat failed: ${err.message}`); });
+            };
+            beat();
+            const beats = setInterval(beat, 60_000);
+            beats.unref?.();
+            stdio.onclose = () => { clearInterval(beats); inbox.close(); };
+        }
         return;
     }
     if (transport === 'http') {

package/dist/manifest-size.test.js

@@ -31,11 +31,19 @@ afterEach(() => { vi.restoreAllMocks(); });
  * session scope schema, agent_notify the toSessionRef, and orboto_messages
  * renders sender and receiver identities in its output schema (measured
  * curated = 38,640, full = 168,029 chars, minimal = 3,140 tokens).
+ * ORB-2150 raised the curated ceiling to 39,700: `orboto_messages` gained
+ * the `dismiss` envelope and the per-message `dismissed` record, which is
+ * the surface that stops foreign mail from waking every session of a
+ * shared account (measured curated = 39,461 chars / 10,961 tokens).
+ * ORB-2149 raised the full ceiling to 171,200: `orboto_agent_wakes` puts
+ * the wake ledger and the delivery precision per session and per sender
+ * in the full toolset (measured full = 170,030 chars); the curated tier
+ * reaches it through the escape hatch and is unchanged.
  *
  * @see ORB-1805, ORB-1669, ORB-1910
  */
-const CURATED_MAX_CHARS = 39_000;
-const FULL_MAX_CHARS = 169_000;
+const CURATED_MAX_CHARS = 39_700;
+const FULL_MAX_CHARS = 171_200;
 /**
  * ORB-1805 - the estimator the ticket measured the failure with
  * (`n_keep: 13533 >= n_ctx: 8192` in LM Studio): characters / 3.6. It is
@@ -56,7 +64,7 @@ const MINIMAL_MAX_TOKENS = 3_200;
  * The curated tier is ratcheted on its TOOL SCHEMAS (the instructions
  * block has its own budget, enforced in instructions-budget.test.ts).
  */
-const CURATED_SCHEMA_MAX_TOKENS = 10_800;
+const CURATED_SCHEMA_MAX_TOKENS = 11_000;
 async function measuredManifest(toolset) {
     const server = await buildOrbotoMcpServer({
         baseUrl: 'https://orboto.example.com',

package/dist/orboto-client.js

@@ -22,6 +22,7 @@ export class OrbotoClient {
     baseHeaders;
     apiKey;
     tokenProvider;
+    instanceToken;
     constructor(config) {
         this.baseUrl = config.baseUrl.replace(/\/+$/, '');
         if (!config.apiKey && !config.tokenProvider) {
@@ -29,6 +30,7 @@ export class OrbotoClient {
         }
         this.apiKey = config.apiKey;
         this.tokenProvider = config.tokenProvider;
+        this.instanceToken = config.instanceToken;
         const ua = config.userAgentSuffix
             ? `orboto-mcp/${VERSION} (${config.userAgentSuffix})`
             : `orboto-mcp/${VERSION}`;
@@ -60,6 +62,7 @@ export class OrbotoClient {
         const doFetch = async (token) => {
             const headers = {
                 ...this.baseHeaders,
+                ...(this.instanceToken ? { 'x-orboto-agent-session': this.instanceToken } : {}),
                 ...(accept ? { Accept: accept } : {}),
                 ...(init.headers ?? {}),
                 Authorization: `Bearer ${token}`,

package/dist/orboto-client.test.js

@@ -126,4 +126,19 @@ describe('preflightMcpSession', () => {
         const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
         await expect(preflightMcpSession(client)).rejects.toBeInstanceOf(OrbotoApiError);
     });
+    it('ORB-2151: a client built with an instance token names the session on every request; an explicit token wins', async () => {
+        const seen = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+            seen.push((init?.headers ?? {}));
+            return { ok: true, status: 200, statusText: 'OK', json: async () => ({}), text: async () => '' };
+        });
+        const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test', instanceToken: 'mcp-proc' });
+        await client.get('/users/me');
+        await client.post('/projects/p/tickets', { title: 't' });
+        await client.post('/v1/agent/heartbeat', {}, { instanceToken: 'mcp-explicit' });
+        expect(seen.map((h) => h['x-orboto-agent-session'])).toEqual(['mcp-proc', 'mcp-proc', 'mcp-explicit']);
+        const plain = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+        await plain.get('/users/me');
+        expect(seen[3]['x-orboto-agent-session']).toBeUndefined();
+    });
 });

package/dist/server.js

@@ -15,6 +15,7 @@ import { draftCustomerReplyToolConfig, makeDraftCustomerReplyHandler } from './t
 import { embeddingStatusToolConfig, makeEmbeddingStatusHandler } from './tools/embedding-status.js';
 import { aiUsageToolConfig, makeAiUsageHandler } from './tools/ai-usage.js';
 import { sessionStartToolConfig, makeSessionStartHandler } from './tools/session-start.js';
+import { CHANNEL_CAPABILITY, CHANNEL_INSTRUCTIONS } from './inbox-channel.js';
 import { loadRequiredRules } from './required-rules.js';
 import { responseExpandToolConfig, makeResponseExpandHandler } from './tools/response-expand.js';
 import { helpToolConfig, makeHelpHandler } from './tools/help.js';
@@ -25,6 +26,7 @@ import { agentHeartbeatToolConfig, makeAgentHeartbeatHandler, agentPresenceToolC
 import { agentBroadcastToolConfig, makeAgentBroadcastHandler, } from './tools/agent-coordination.js';
 import { agentMessageWorkToolConfig, makeAgentMessageWorkHandler } from './tools/agent-message-work.js';
 import { agentMessagesToolConfig, makeAgentMessagesHandler } from './tools/agent-messages.js';
+import { agentWakesToolConfig, makeAgentWakesHandler } from './tools/agent-wakes.js';
 import { listProjectsToolConfig, makeListProjectsHandler } from './tools/list-projects.js';
 import { getProjectToolConfig, makeGetProjectHandler } from './tools/get-project.js';
 import { projectReadinessToolConfig, makeProjectReadinessHandler } from './tools/project-readiness.js';
@@ -155,18 +157,22 @@ export async function buildOrbotoMcpServer(opts) {
     catch {
         workingRules = 'Workspace rules are unavailable. Built-in hints are not a substitute. Call orboto_session_start with forceRules and retry after connectivity or authentication recovers.';
     }
+    const channelHint = opts.channel ? [CHANNEL_INSTRUCTIONS] : [];
     const server = new McpServer({ name: 'orboto', version: VERSION }, {
         capabilities: {
             resources: { subscribe: true, listChanged: true },
+            ...(opts.channel ? { experimental: { [CHANNEL_CAPABILITY]: {} } } : {}),
         },
         instructions: toolset === 'minimal'
             ? [
                 staticMcpHints(toolset),
                 'FIRST ACTION: call `orboto_session_start` - it returns the binding workspace rules plus your in-progress work. Re-run it after any context compaction. Non-negotiables: claim or create a ticket before touching code, one commit per ticket with the ticket key in the subject, push after each commit, never mark work done that is not done.',
+                ...channelHint,
             ].join('\n\n')
             : assembleInstructions([
                 staticMcpHints(toolset),
                 'FIRST ACTION this session: call the `orboto_session_start` tool - it returns the complete, authoritative binding rules you must follow (plus your in-progress work). Re-run it after any context compaction. If the rules below look cut off, `orboto_session_start` and the `orboto://rules` resource always have the full set. (Do NOT use `orboto_list_agent_instructions` to read the rules - that manages rule blocks for admins.) Core non-negotiables: ticket-first (claim or create a ticket before touching code), one commit per ticket with the ticket key in the subject line, push after each commit, and never mark work done that is not actually done.',
+                ...channelHint,
             ].join('\n\n'), workingRules),
     });
     const nudgeState = createNudgeState(requireSessionStart);
@@ -183,7 +189,7 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_draft_customer_reply', draftCustomerReplyToolConfig, makeDraftCustomerReplyHandler(client));
     reg('orboto_embedding_status', embeddingStatusToolConfig, makeEmbeddingStatusHandler(client));
     reg('orboto_ai_usage', aiUsageToolConfig, makeAiUsageHandler(client));
-    reg('orboto_session_start', sessionStartToolConfig, makeSessionStartHandler(client));
+    reg('orboto_session_start', sessionStartToolConfig, makeSessionStartHandler(client, { channel: opts.channel }));
     reg('orboto_response_expand', responseExpandToolConfig, makeResponseExpandHandler());
     reg('orboto_help', helpToolConfig, makeHelpHandler());
     reg('orboto_api_search', apiSearchToolConfig, makeApiSearchHandler(client));
@@ -198,6 +204,7 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_agent_notify', agentNotifyToolConfig, makeAgentNotifyHandler(client));
     reg('orboto_message_work', agentMessageWorkToolConfig, makeAgentMessageWorkHandler(client));
     reg('orboto_messages', agentMessagesToolConfig, makeAgentMessagesHandler(client));
+    reg('orboto_agent_wakes', agentWakesToolConfig, makeAgentWakesHandler(client));
     reg('orboto_agent_broadcast', agentBroadcastToolConfig, makeAgentBroadcastHandler(client));
     reg('orboto_list_projects', listProjectsToolConfig, makeListProjectsHandler(client));
     reg('orboto_get_project', getProjectToolConfig, makeGetProjectHandler(client));

package/dist/tool-parameters.test.js

@@ -1,5 +1,10 @@
 /**
  * ORB-1805 - the schema diet must never cost a PARAMETER.
+ *
+ * ORB-2157 - one reviewed baseline edit: `orboto_help.tool` is no longer
+ * required, because the tool now also answers `topic` ("connect" returns the
+ * setup script). The parameter itself is untouched and still the only way to
+ * ask for a tool's guidance; a call with neither says which topics exist.
  */
 import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
 import { readFileSync } from 'node:fs';

package/dist/tools/agent-messages.js

@@ -13,7 +13,7 @@ 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() });
 export const agentMessagesToolConfig = {
     title: 'Agent inbox and message work',
-    description: 'Your inbox as THIS session sees it: 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 is a plain read receipt: no claim needed, finishes nothing. Reply via orboto_agent_notify with threadId (toSessionRef = from.sessionId reaches that instance).',
+    description: 'Your inbox as THIS session sees it: 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 is a plain read receipt: no claim needed, finishes nothing. 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.'),
@@ -22,6 +22,12 @@ export const agentMessagesToolConfig = {
         project: z.string().min(1).max(64).optional().describe('Project 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({
+            ids: z.array(z.string().uuid()).min(1).max(200),
+            reason: z.enum(['not_mine', 'obsolete', 'duplicate']),
+            note: z.string().max(500).optional(),
+            duplicateOf: z.string().uuid().optional(),
+        }).optional().describe('Dismiss with a reason; obsolete/duplicate need note or duplicateOf.'),
     }).shape,
     outputSchema: z.object({
         work: z.record(z.unknown()).optional(),
@@ -38,8 +44,13 @@ export const agentMessagesToolConfig = {
             projectKey: z.string().nullable(),
             createdAt: z.string(),
             readAt: z.string().nullable(),
+            dismissed: z.object({
+                reason: z.string(), note: z.string().nullable(), duplicateOf: z.string().nullable(), createdAt: z.string(),
+            }).nullable(),
         })),
         acked: z.number().int(),
+        dismissed: z.number().int().optional(),
+        closed: z.number().int().optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
 };
@@ -51,6 +62,18 @@ export function makeAgentMessagesHandler(client) {
             const result = await makeAgentMessageWorkHandler(client)(args.messageWork, extra);
             return { content: result.content, structuredContent: { messages: [], acked: 0, work: result.structuredContent } };
         }
+        let dismissedCount = 0;
+        let closedCount = 0;
+        let feedbackSent = 0;
+        if (args.dismiss) {
+            const res = await client.post('/v1/agent/messages/dismiss', {
+                ...args.dismiss,
+                instanceToken: mcpInstanceToken(undefined, extra),
+            });
+            dismissedCount = res.dismissed;
+            closedCount = res.closed;
+            feedbackSent = res.feedbackSent;
+        }
         let acked = 0;
         if (args.ackIds && args.ackIds.length > 0) {
             const res = await client.post('/v1/agent/messages/ack', { ids: args.ackIds, instanceToken: mcpInstanceToken(undefined, extra) });
@@ -73,6 +96,9 @@ export function makeAgentMessagesHandler(client) {
         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 (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` : ''}.`);
+        }
         if (sessionId)
             lines.push(`This session: ${sessionId.slice(0, 8)} (ref ${instanceToken}).`);
         return {
@@ -82,9 +108,11 @@ export function makeAgentMessagesHandler(client) {
                 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,
-                    createdAt: m.createdAt, readAt: m.readAt,
+                    createdAt: m.createdAt, readAt: m.readAt, dismissed: m.dismissed ?? null,
                 })),
                 acked,
+                dismissed: dismissedCount,
+                closed: closedCount,
             },
         };
     };

package/dist/tools/agent-presence-schema.js

@@ -5,7 +5,7 @@ const WorkSessionResourceClaimSchema = z.object({
     state: z.enum(['granted', 'waiting']).optional(), requestedAt: z.string().optional(),
 });
 export const AgentInventoryKindSchema = z.enum(['agent', 'human']);
-export const AgentConnectionTypeSchema = z.enum(['api_key', 'oauth', 'lane', 'external_token', 'live_events', 'web']);
+export const AgentConnectionTypeSchema = z.enum(['api_key', 'oauth', 'lane', 'external_token', 'live_events', 'web', 'channel']);
 export const AgentInventoryConnectionSchema = z.object({ type: AgentConnectionTypeSchema, label: z.string() });
 export const AgentInventoryProjectSchema = z.object({ id: z.string().uuid(), key: z.string(), name: z.string() });
 export const AgentInventoryEntrySchema = z.object({
@@ -34,6 +34,12 @@ export const AgentInventoryEntrySchema = z.object({
     scope: AgentSessionScopeSchema.nullable(),
     /** ORB-2136 - unread inbox messages this session would list. */
     unreadMessages: z.number().int(),
+    /** ORB-2149 - the last 24 hours of wakes: how many, how precise, what the wrong ones cost. */
+    wakes: z.object({
+        count: z.number().int(),
+        precision: z.number().nullable(),
+        wrongWakeContextTokens: z.number().int(),
+    }),
     lastSeenAt: z.string(),
     createdAt: z.string(),
 });

package/dist/tools/agent-wakes.js

@@ -0,0 +1,60 @@
+/**
+ * ORB-2149 - the wake ledger: what woke this session, by which rule, what it
+ * did with it and what it cost.
+ */
+import { z } from 'zod';
+export const agentWakesToolConfig = {
+    title: 'Wake ledger',
+    description: 'Who woke this account\'s sessions, which visibility rule delivered the message (addressed | scope_project | scope_ticket | broadcast | unscoped_session | account_view), what the woken session did with it (handled | not_mine | obsolete | duplicate | expired | pending) and what the wake cost in context tokens. `stats: true` returns delivery precision per woken session and per sender over `hours` (operator read, needs admin:agents:read); without it the ledger rows of your own account, newest first. Use it to prove a misrouting sender instead of describing it in prose.',
+    inputSchema: z.object({
+        stats: z.boolean().default(false).describe('Precision per session and per sender instead of rows.'),
+        hours: z.number().int().min(1).max(720).optional().describe('Stats window, default 24.'),
+        sessionId: z.string().uuid().optional().describe('Narrow to one woken session.'),
+        project: z.string().min(1).max(64).optional().describe('Project key or UUID.'),
+        outcome: z.enum(['pending', 'handled', 'not_mine', 'obsolete', 'duplicate', 'expired']).optional(),
+        limit: z.number().int().min(1).max(200).optional().describe('Default: 50.'),
+        cursor: z.string().optional().describe('Opaque cursor from a previous response.'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+function statsLine(e) {
+    const precision = e.precision === null ? 'unjudged' : `${Math.round(e.precision * 100)}%`;
+    const tokens = e.wrongWakeContextTokens > 0 ? `, wrong wakes cost ${e.wrongWakeContextTokens} tokens` : '';
+    return `- ${e.label}: ${e.wakes} wakes, precision ${precision}, median ${e.medianLatencyMs ?? '?'} ms, top rule ${e.topRule ?? '-'}${tokens}`;
+}
+export function makeAgentWakesHandler(client) {
+    return async (args) => {
+        const qs = new URLSearchParams();
+        if (args.sessionId)
+            qs.set('sessionId', args.sessionId);
+        if (args.stats) {
+            if (args.hours)
+                qs.set('hours', String(args.hours));
+            const res = await client.get(`/admin/agents/wake-stats${qs.toString() ? `?${qs.toString()}` : ''}`);
+            const text = [
+                `Last ${res.hours} h - woken sessions:`,
+                ...(res.sessions.length ? res.sessions.map(statsLine) : ['- (no wakes)']),
+                'Senders:',
+                ...(res.senders.length ? res.senders.map(statsLine) : ['- (none)']),
+            ].join('\n');
+            return { content: [{ type: 'text', text }], structuredContent: res };
+        }
+        if (args.project)
+            qs.set('project', args.project);
+        if (args.outcome)
+            qs.set('outcome', args.outcome);
+        if (args.limit)
+            qs.set('limit', String(args.limit));
+        if (args.cursor)
+            qs.set('cursor', args.cursor);
+        const res = await client.get(`/v1/agent/wakes${qs.toString() ? `?${qs.toString()}` : ''}`);
+        const lines = res.rows.length === 0
+            ? '(no wakes recorded)'
+            : res.rows.map((r) => `- ${r.wokenAt} ${r.subject} - from ${r.senderLabel} via ${r.rule}/${r.transport} -> ${r.outcome}`
+                + `${r.latencyMs === null ? '' : ` (${r.latencyMs} ms`}${r.contextTokens === null ? r.latencyMs === null ? '' : ')' : `, ${r.contextTokens} ctx tokens)`}`).join('\n');
+        return {
+            content: [{ type: 'text', text: lines + (res.nextCursor ? `\n\n(next cursor: ${res.nextCursor})` : '') }],
+            structuredContent: res,
+        };
+    };
+}

package/dist/tools/api-call.js

@@ -9,6 +9,7 @@
  * instead of surfacing as an opaque tool failure.
  */
 import { z } from 'zod';
+import { mcpInstanceToken } from './shared.js';
 export const apiCallToolConfig = {
     title: 'Call any orboto REST endpoint',
     description: 'Execute one REST API request - the escape hatch for every endpoint without a named tool. '
@@ -28,7 +29,7 @@ export const apiCallToolConfig = {
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
 };
 export function makeApiCallHandler(client) {
-    return async (input) => {
+    return async (input, extra) => {
         let body = input.body;
         if (typeof body === 'string') {
             try {
@@ -41,7 +42,7 @@ export function makeApiCallHandler(client) {
             path: input.path,
             ...(input.query ? { query: input.query } : {}),
             ...(body !== undefined ? { body } : {}),
-        });
+        }, { instanceToken: mcpInstanceToken(undefined, extra) });
         const bodyText = envelope.encoding === 'json'
             ? JSON.stringify(envelope.body, null, 1)
             : String(envelope.body ?? '');

package/dist/tools/api-call.test.js

@@ -100,4 +100,15 @@ describe('orboto_api_call', () => {
         const res = await makeApiCallHandler(client)({ method: 'GET', path: '/export' });
         expect(res.content[0].text).toContain('truncated by the proxy cap');
     });
+    it('ORB-2144: the proxy request carries this MCP session as x-orboto-agent-session', async () => {
+        const seen = [];
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (_url, init) => {
+            seen.push((init?.headers ?? {}));
+            return { ok: true, status: 200, statusText: 'OK', json: async () => ({ status: 200, contentType: 'application/json', body: { sessionId: 's' }, encoding: 'json', truncated: false, matchedRoute: '/v1/agent/heartbeat' }), text: async () => '' };
+        });
+        await makeApiCallHandler(client)({ method: 'POST', path: '/v1/agent/heartbeat', body: { scope: { role: 'spec' } } }, { sessionId: 'abc123' });
+        expect(seen[0]['x-orboto-agent-session']).toBe('mcp-abc123');
+        await makeApiCallHandler(client)({ method: 'GET', path: '/v1/agent/messages' });
+        expect(seen[1]['x-orboto-agent-session']).toMatch(/^mcp-/);
+    });
 });

package/dist/tools/docs.js

@@ -42,7 +42,7 @@ export async function resolveDocId(client, docIdOrKey) {
 }
 export const getDocToolConfig = {
     title: 'Get a doc by id or key',
-    description: 'Return the doc content (Markdown) plus backlinks (other docs that reference this doc, or tickets/milestones the doc is linked from). Accepts either the doc UUID or its human-readable key (e.g. ORB-D12 / DOC-5).',
+    description: 'Return the doc content (Markdown) plus backlinks (other docs that reference this doc, or tickets/milestones the doc is linked from). Accepts either the doc UUID or its human-readable key (e.g. ORB-D12 / DOC-5). A UUID read also reports `embedding.state` - embedded | pending | stale | not_embeddable - so a caller waits for semantic search instead of guessing (ORB-2154).',
     inputSchema: z.object({
         docId: z.string().min(1).describe('Doc UUID or human-readable key (ORB-D12 / DOC-5). Discover via orboto_list_doc_spaces or orboto_search.'),
     }).shape,
@@ -56,7 +56,7 @@ export function makeGetDocHandler(client) {
         const backlinks = await client.get(`/docs/${doc.id}/backlinks`).catch(() => []);
         const lines = [
             `# ${doc.icon ? `${doc.icon} ` : ''}${doc.title}`,
-            `${doc.docKey ? `Key: ${doc.docKey}  ·  ` : ''}ID: ${doc.id}  ·  Visibility: ${doc.visibility}  ·  Updated: ${doc.updatedAt}`,
+            `${doc.docKey ? `Key: ${doc.docKey}  ·  ` : ''}ID: ${doc.id}  ·  Visibility: ${doc.visibility}  ·  Updated: ${doc.updatedAt}${doc.embedding ? `  ·  Embedding: ${doc.embedding.state}` : ''}`,
             '',
             doc.content || '_(empty)_',
         ];
@@ -80,6 +80,7 @@ export function makeGetDocHandler(client) {
                     parentDocId: doc.parentDocId,
                     spaceId: doc.spaceId,
                     slug: doc.slug,
+                    embedding: doc.embedding ?? null,
                 },
                 backlinks: backlinks.map((b) => ({
                     sourceDocId: b.sourceDocId,

package/dist/tools/help.js

@@ -9,11 +9,15 @@
  */
 import { z } from 'zod';
 import { getToolDoc, listToolDocNames } from '../tool-docs.js';
+import { connectScriptText } from '../connect-script.js';
+/** ORB-2157 - guidance that belongs to no single tool, addressed by topic. */
+const TOPICS = { connect: connectScriptText };
 export const helpToolConfig = {
     title: 'Full guidance for one orboto tool',
-    description: 'Return the complete guidance text (workflows, warnings, edge cases) for one orboto tool by name - manifest descriptions are one-line summaries, this is the rest. Call it before first use of an unfamiliar write tool.',
+    description: 'Return the complete guidance text (workflows, warnings, edge cases) for one orboto tool by name - manifest descriptions are one-line summaries, this is the rest. Call it before first use of an unfamiliar write tool. topic: "connect" returns the step-by-step script for setting a person up instead.',
     inputSchema: z.object({
-        tool: z.string().min(1).max(128).describe('Tool name, e.g. orboto_create_ticket.'),
+        tool: z.string().min(1).max(128).optional().describe('Tool name, e.g. orboto_create_ticket.'),
+        topic: z.enum(['connect']).optional().describe('Guidance topic instead of a tool.'),
     }).shape,
     outputSchema: z.object({
         tool: z.string(),
@@ -23,7 +27,19 @@ export const helpToolConfig = {
 };
 export function makeHelpHandler() {
     return async (args) => {
-        const name = args.tool.trim();
+        const topic = args.topic?.trim();
+        if (topic) {
+            const render = TOPICS[topic];
+            const text = render
+                ? render()
+                : `No guidance registered for topic "${topic}". Known topics: ${Object.keys(TOPICS).join(', ')}`;
+            return { content: [{ type: 'text', text }], structuredContent: { tool: `topic:${topic}`, guidance: render ? text : '' } };
+        }
+        const name = (args.tool ?? '').trim();
+        if (!name) {
+            const text = `Name a tool, or a topic: ${Object.keys(TOPICS).join(', ')}.`;
+            return { content: [{ type: 'text', text }], structuredContent: { tool: '', guidance: '' } };
+        }
         const doc = getToolDoc(name) ?? getToolDoc(`orboto_${name}`);
         if (!doc) {
             const known = listToolDocNames();

package/dist/tools/session-start.js

@@ -14,6 +14,7 @@ import { AgentSessionScopeSchema } from './agent-session-scope.js';
 import { PROTECT_TEXT_META, storePayload } from '../response-budget.js';
 import { loadRequiredRules } from '../required-rules.js';
 import { GIT_HEALTH_REASON_TEXT } from './git-health-reasons.js';
+import { channelStartLines } from '../inbox-channel.js';
 export const sessionStartToolConfig = {
     title: 'Load the rules you must follow + re-orient',
     description: 'THE canonical way to LOAD the binding workspace rules you must follow as an agent. Run it as your FIRST action in a session and immediately AFTER any context compaction. Returns a one-line-per-rule INDEX of the binding working-rules plus their hash (or a compact "unchanged" ack on a repeat call within the same connection) - read the index, then call this tool again with `rulesOnly: true` to read the full text of the rules whenever you do not already hold that exact hash, and expand before acting on any rule whose title touches what you are about to do. Also returns your in-progress tickets - each flagged LANDED, IDLE when it has a linked commit but has not moved for days, i.e. finished work you never handed to review - your running timer, and a warning if a project\'s git connection looks unhealthy (commit ingestion may be stalled). Pass `ticketKey` to also get a one-shot bundle for that ticket: project primer, the full ticket with dependencies + checklists, that project\'s git health, and any other agent sessions currently on it - replacing several separate calls. (Do NOT use orboto_list_agent_instructions to read the rules - that tool MANAGES/edits rule blocks for admins; this one is what you read to know how to work.) Registers this session (a heartbeat on its instance row) and is otherwise read-only. '
@@ -128,7 +129,7 @@ async function buildTicketBundle(client, ticketKey) {
         },
     };
 }
-export function makeSessionStartHandler(client) {
+export function makeSessionStartHandler(client, opts = {}) {
     let lastKnownRulesHash;
     return async (input = {}, extra) => {
         const instanceToken = mcpInstanceToken(undefined, extra);
@@ -256,6 +257,8 @@ export function makeSessionStartHandler(client) {
             ? [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';
         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}" }.`);
+        if (opts.channel)
+            lines.push('', ...channelStartLines());
         if (pendingMessages.length > 0) {
             lines.push('', '## Agent messages - unread');
             for (const m of pendingMessages)

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

@@ -9,6 +9,8 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { OrbotoClient } from '../orboto-client.js';
 import { makeSessionStartHandler } from './session-start.js';
+import { CHANNEL_START_COMMANDS, CHANNEL_START_COMMANDS_WITHOUT_CLI } from '../inbox-channel.js';
+import { readFileSync } from 'node:fs';
 import { makeResponseExpandHandler } from './response-expand.js';
 import { applyResponseBudget, budgetFor, DEFAULT_BUDGET_CHARS } from '../response-budget.js';
 beforeEach(() => { vi.restoreAllMocks(); });
@@ -566,4 +568,35 @@ describe('ORB-2136 - session scope and ref', () => {
         expect(seen.find((c) => c.path === '/v1/agent/heartbeat')?.body).toEqual({});
         expect(res.content[0].text).toContain('no scope declared');
     });
+    it('ORB-2148: a stdio proxy with the channel on hands over the exact start commands; other servers stay silent', async () => {
+        const fixture = {
+            '/users/me/assigned-tickets': { items: [] },
+            '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
+            '/agent-instructions': { instructions: 'rules here', rulesHash: 'fixture' },
+            '/time/timer': {},
+        };
+        stubByPath(fixture);
+        const on = (await makeSessionStartHandler(client, { channel: true })()).content[0].text;
+        expect(on).toContain('## Wake channel');
+        for (const cmd of Object.values(CHANNEL_START_COMMANDS))
+            expect(on).toContain(`\`${cmd}\``);
+        for (const cmd of Object.values(CHANNEL_START_COMMANDS_WITHOUT_CLI))
+            expect(on).toContain(`\`${cmd}\``);
+        expect(on).toContain('orboto claude --continue');
+        expect(on).toContain('orboto claude --resume <session id>');
+        expect(on).toContain('orboto mcp install');
+        expect(on).toContain('local development');
+        stubByPath(fixture);
+        const off = (await makeSessionStartHandler(client)()).content[0].text;
+        expect(off).not.toContain('## Wake channel');
+        expect(off).not.toContain('--dangerously-load-development-channels');
+    });
+    it('ORB-2148: docs/claude-code.md carries both command forms', () => {
+        const docs = readFileSync(new URL('../../../../docs/claude-code.md', import.meta.url), 'utf8');
+        for (const cmd of Object.values(CHANNEL_START_COMMANDS))
+            expect(docs).toContain(cmd);
+        for (const cmd of Object.values(CHANNEL_START_COMMANDS_WITHOUT_CLI))
+            expect(docs).toContain(cmd);
+        expect(docs).toContain('orboto mcp install');
+    });
 });

package/dist/tools/shared.js

@@ -102,6 +102,10 @@ const MCP_PROCESS_INSTANCE = `mcp-${randomUUID()}`;
 export function mcpInstanceToken(explicit, extra) {
     return explicit ?? (extra?.sessionId ? `mcp-${extra.sessionId}` : MCP_PROCESS_INSTANCE);
 }
+/** ORB-2140 - the stdio process's own instance token, the one the inbox channel follows the stream with. */
+export function mcpProcessInstance() {
+    return MCP_PROCESS_INSTANCE;
+}
 /** ORB-1753 - the caller's self-declared agent profile from the process
  *  environment (stdio servers / runners). The api-key standing profile
  *  (ORB-1751) already covers keys server-side; these env vars let a

package/package.json

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