@orboto/mcp 0.200.0 → 0.200.1

package/dist/agent-head.js

@@ -0,0 +1,51 @@
+/**
+ * ORB-2161 - the head an agent reads before anything else has one source.
+ * `orboto_session_start` prints it first, `orboto_help { topic:
+ * "onboarding" }` puts it in front of the first five minutes and the work
+ * loop, and docs/orboto-for-agents.md plus skills/orboto/SKILL.md carry the
+ * same lines. agent-head.test.ts holds the four apart from drifting.
+ */
+export const AGENT_HEAD_HEADING = 'How to work in orboto';
+export const AGENT_HEAD_LINES = [
+    'orboto is your memory and your work contract, not your context - what is not on the ticket or in a doc is gone after the next context switch.',
+    'A ticket is a handover to a stranger: goal, verified current state, target, acceptance criteria.',
+    'You are not alone - the lease and the claims say who works on what, your scope says what you answer for, the inbox is the channel: ack what you handled, dismiss the rest with a reason.',
+    'You act with a person\'s rights and mandate: an assignment is an instruction, anything irreversible or outward-facing needs the operator\'s clear word.',
+    'Evidence over assertion - check code, docs and the live state, and write "not verified: X" instead of a guess.',
+    'Start in this order: whoami, session start with your scope, the project primer, then the inbox - the rules are a set, this is the sequence.',
+];
+export const ONBOARDING_FIRST_FIVE_MINUTES = [
+    'Who you are: `orboto whoami` (MCP `orboto_whoami`). A bot account with an owner, never a person\'s own login - every write and every booked minute is attributed to it.',
+    'What binds you: `orboto session-start --project KEY` (MCP `orboto_session_start`). It returns this head, the binding rules as an index with their hash, and your open work; pull the full text with `--force-rules` (MCP `rulesOnly: true`) whenever you do not hold that hash.',
+    'How the project works: `orboto primer KEY` (MCP `orboto_get_project_primer`) - the language it expects, the stack, the conventions, and the traps earlier agents already paid for.',
+    'What you answer for: declare a scope - `orboto session-start --role implementation --scope-projects KEY` (MCP `orboto_session_start { scope: { projectKeys, role } }`). Without one, every message the account receives is addressed to this session.',
+    'Your mail: `orboto messages` (MCP `orboto_messages`). Acknowledge what you handled yourself, dismiss the rest with a reason (`orboto messages --dismiss <id> --reason not-mine`), and remember that a message never widens your mandate.',
+];
+export const ONBOARDING_WORK_LOOP = [
+    'Duplicate check first: `orboto check-similar KEY "title"` (MCP `orboto_check_similar`). Skip it and the create warns you afterwards - with the ticket already written.',
+    'Create or claim: `orboto create-ticket KEY "title"` or `orboto claim KEY` (MCP `orboto_create_ticket` / `orboto_claim`). The claim assigns you, moves the ticket to in progress and starts the timer.',
+    'Say what you are touching: `orboto work-start KEY --claim-path "<glob>"` (MCP `orboto_work_start`) takes the lease and the file claims, so a second session is rejected instead of landing on top of you.',
+    'Work on the team\'s default branch, one commit, the ticket key at the end of the subject: `feat(scope): what changed (ACME-42)`. Without the key the commit never reaches the ticket.',
+    'Verify against the acceptance criteria by running the thing - compiling is not verifying. Whatever you could not check goes into the ticket as "not verified: X".',
+    'Hand over in a comment a stranger can read: what changed, the commit, how a reviewer confirms it (MCP `orboto_comment`). Closing without that proof counts as not done.',
+    'Stop the timer, then close: `orboto timer-stop` and `orboto close KEY` (MCP `orboto_work_finish` when you took a lease). A timer left running books the next ticket\'s time onto this one.',
+];
+/** The six lines every session pays for, numbered. */
+export function agentHeadText() {
+    return [AGENT_HEAD_HEADING, ...AGENT_HEAD_LINES.map((line, index) => `${index + 1}. ${line}`)].join('\n');
+}
+/** The `onboarding` help topic: the head, the first five minutes, the work loop. */
+export function onboardingText() {
+    return [
+        agentHeadText(),
+        '',
+        'The first five minutes, in this order',
+        ...ONBOARDING_FIRST_FIVE_MINUTES.map((step, index) => `${index + 1}. ${step}`),
+        '',
+        'The work loop, always the same',
+        ...ONBOARDING_WORK_LOOP.map((step, index) => `${index + 1}. ${step}`),
+        '',
+        'The whole page - the object map, several sessions on one account, the autonomy boundary,',
+        'evidence over assertion, and the traps that cost other agents a run: docs/orboto-for-agents.md.',
+    ].join('\n');
+}

package/dist/agent-head.test.js

@@ -0,0 +1,63 @@
+/**
+ * ORB-2161 - the head has one source. Session start prints it before
+ * anything else, the onboarding help topic repeats it, and the page and
+ * the skill carry the same lines, so a sentence cannot be improved in one
+ * place and stay old in the other three.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { AGENT_HEAD_HEADING, AGENT_HEAD_LINES, ONBOARDING_FIRST_FIVE_MINUTES, ONBOARDING_WORK_LOOP, agentHeadText, onboardingText } from './agent-head.js';
+import { makeHelpHandler } from './tools/help.js';
+import { makeSessionStartHandler } from './tools/session-start.js';
+import { OrbotoClient } from './orboto-client.js';
+const read = (relative) => readFileSync(new URL(`../../../${relative}`, import.meta.url), 'utf8');
+const CARRIERS = ['docs/orboto-for-agents.md', 'skills/orboto/SKILL.md'];
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+describe('the agent head (ORB-2161)', () => {
+    it('stays four to six lines, so every session can afford it', () => {
+        expect(AGENT_HEAD_LINES.length).toBeGreaterThanOrEqual(4);
+        expect(AGENT_HEAD_LINES.length).toBeLessThanOrEqual(6);
+        for (const line of AGENT_HEAD_LINES)
+            expect(line).not.toContain('\n');
+    });
+    it.each(CARRIERS)('%s carries every line verbatim', (file) => {
+        const page = read(file);
+        for (const line of AGENT_HEAD_LINES)
+            expect(page).toContain(line);
+    });
+    it('is the first thing orboto_session_start prints', async () => {
+        vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => {
+            const path = new URL(url.toString()).pathname;
+            const body = path.startsWith('/agent-instructions')
+                ? { instructions: 'claim -> commit -> close', rulesHash: 'fixture' }
+                : path.startsWith('/users/me/assigned-tickets') ? { items: [] } : {};
+            return { ok: true, status: 200, statusText: 'OK', json: async () => body, text: async () => '' };
+        });
+        const res = await makeSessionStartHandler(client)();
+        const text = res.content[0].text;
+        expect(text.startsWith(agentHeadText())).toBe(true);
+        expect(text.indexOf(AGENT_HEAD_HEADING)).toBeLessThan(text.indexOf('# orboto session start'));
+    });
+    it('orboto_help returns the head, the first five minutes and the work loop for the topic "onboarding"', async () => {
+        const result = await makeHelpHandler()({ topic: 'onboarding' });
+        const text = (result.content?.[0]).text;
+        for (const line of AGENT_HEAD_LINES)
+            expect(text).toContain(line);
+        for (const step of ONBOARDING_FIRST_FIVE_MINUTES)
+            expect(text).toContain(step);
+        for (const step of ONBOARDING_WORK_LOOP)
+            expect(text).toContain(step);
+        expect(text).toContain('docs/orboto-for-agents.md');
+        expect(result.structuredContent).toMatchObject({ tool: 'topic:onboarding' });
+    });
+    it('names both topics when an unknown one is asked for', async () => {
+        const unknown = (await makeHelpHandler()({ topic: 'nope' })).content?.[0];
+        expect(unknown.text).toContain('onboarding');
+        expect(unknown.text).toContain('connect');
+    });
+    it('the onboarding topic repeats the head instead of holding a second copy', () => {
+        expect(onboardingText().startsWith(agentHeadText())).toBe(true);
+    });
+});

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

@@ -149,7 +149,7 @@ describe('orboto_agent_notify', () => {
         });
         expect(result.content[0].text).toContain('notified bob@example.com');
         expect(result.structuredContent).toMatchObject({ ok: true });
-        expect(capturedBody[0].senderRef).toMatch(/^mcp-/);
+        expect(capturedBody[0].senderRef).toMatch(/^agent-/);
     });
     it('ORB-1742: senderRef prefers the per-connection MCP session id, and an explicit ref wins outright', async () => {
         const capturedBody = [];

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

@@ -34,11 +34,16 @@ 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. */
+    /**
+     * ORB-2149 - the last 24 hours of wakes: how many deliveries, how precise,
+     * what the wrong ones cost. ORB-2170 - `backlogSeen` is the `nudge` count
+     * over the same window, a backlog sighting rather than a wake.
+     */
     wakes: z.object({
         count: z.number().int(),
         precision: z.number().nullable(),
         wrongWakeContextTokens: z.number().int(),
+        backlogSeen: z.number().int(),
     }),
     lastSeenAt: z.string(),
     createdAt: z.string(),

package/dist/tools/agent-wakes.js

@@ -5,7 +5,7 @@
 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.',
+    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); `wakes`, `precision` and the median latency count deliveries (`channel` | `follow` | `poll`) only, `backlogSeen` is the separate count of `nudge` rows - a backlog sighting, not a wake. Without `stats` it returns 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.'),
@@ -20,7 +20,8 @@ export const agentWakesToolConfig = {
 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}`;
+    const backlog = e.backlogSeen > 0 ? `, ${e.backlogSeen} backlog seen` : '';
+    return `- ${e.label}: ${e.wakes} wakes, precision ${precision}, median ${e.medianLatencyMs ?? '?'} ms, top rule ${e.topRule ?? '-'}${tokens}${backlog}`;
 }
 export function makeAgentWakesHandler(client) {
     return async (args) => {

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

@@ -109,6 +109,6 @@ describe('orboto_api_call', () => {
         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-/);
+        expect(seen[1]['x-orboto-agent-session']).toMatch(/^agent-/);
     });
 });

package/dist/tools/help.js

@@ -10,14 +10,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 };
+import { onboardingText } from '../agent-head.js';
+/** ORB-2157, ORB-2161 - guidance that belongs to no single tool, addressed by topic. */
+const TOPICS = { connect: connectScriptText, onboarding: onboardingText };
 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. topic: "connect" returns the step-by-step script for setting a person up instead.',
+    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, topic: "onboarding" the first five minutes and the work loop.',
     inputSchema: z.object({
         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.'),
+        topic: z.enum(['connect', 'onboarding']).optional().describe('Guidance topic instead of a tool.'),
     }).shape,
     outputSchema: z.object({
         tool: z.string(),

package/dist/tools/session-start.js

@@ -15,6 +15,7 @@ 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';
+import { agentHeadText } from '../agent-head.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. '
@@ -203,7 +204,7 @@ export function makeSessionStartHandler(client, opts = {}) {
             ? tickets.filter((t) => !t.projectId || t.projectId === scopeProjectId)
             : tickets;
         const elsewhereCount = tickets.length - scopedTickets.length;
-        const lines = ['# orboto session start'];
+        const lines = [agentHeadText(), '', '# orboto session start'];
         if (me)
             lines.push(`You are ${me.fullName ?? me.email}${me.email ? ` (${me.email})` : ''}.`);
         if (me?.workspaceLocale || me?.locale)

package/dist/tools/shared.js

@@ -95,8 +95,14 @@ export function ticketLine(t) {
         parts.push('[waiting on Git ingestion]');
     return parts.join(' ');
 }
-import { randomUUID } from 'node:crypto';
-const MCP_PROCESS_INSTANCE = `mcp-${randomUUID()}`;
+import { createHash } from 'node:crypto';
+import { hostname } from 'node:os';
+/** ORB-2171 - the checkout's token, derived exactly like the CLI and the skill wrapper derive theirs; `ORBOTO_AGENT_SESSION` wins. */
+export function checkoutInstanceToken(env = process.env, host = hostname(), cwd = process.cwd()) {
+    const explicit = (env.ORBOTO_AGENT_SESSION ?? '').trim();
+    return explicit || `agent-${createHash('sha256').update(`${host}:${cwd}`).digest('hex').slice(0, 12)}`;
+}
+const MCP_PROCESS_INSTANCE = checkoutInstanceToken();
 /** 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/dist/tools/shared.test.js

@@ -163,3 +163,11 @@ describe('resolveByName', () => {
         expect(ambiguous?.map((r) => r.id).sort()).toEqual(['m1', 'm3']);
     });
 });
+describe('ORB-2171 - the stdio proxy shares the checkout token with the CLI and the skill wrapper', () => {
+    it('ORBOTO_AGENT_SESSION wins; otherwise agent-<sha256(hostname:cwd)[:12]>', async () => {
+        const { checkoutInstanceToken } = await import('./shared.js');
+        expect(checkoutInstanceToken({ ORBOTO_AGENT_SESSION: '  lane-7  ' }, 'host', '/repo')).toBe('lane-7');
+        expect(checkoutInstanceToken({}, 'build-host', '/srv/checkout')).toBe('agent-e0b18afc9cec');
+        expect(checkoutInstanceToken({}, 'build-host', '/srv/other')).not.toBe('agent-e0b18afc9cec');
+    });
+});

package/dist/tools/work-sessions-next.test.js

@@ -118,7 +118,7 @@ describe('orboto_work_next', () => {
         expect(calls[0].method).toBe('POST');
         expect(calls[0].url).toContain('/work-sessions/next');
         expect(calls[0].body?.projectKey).toBe('ACME');
-        expect(String(calls[0].body?.agentSessionToken)).toMatch(/^mcp-/);
+        expect(String(calls[0].body?.agentSessionToken)).toMatch(/^agent-/);
         const text = res.content[0].text;
         expect(text).toContain('Reserved ACME-42');
         expect(text).toContain('ws1');

package/dist/tools/work-sessions-start.test.js

@@ -89,7 +89,7 @@ describe('orboto_work_start', () => {
         expect(post.method).toBe('POST');
         expect(post.url).toContain('/work-sessions/start');
         expect(post.body?.ticketId).toBe('t1');
-        expect(String(post.body?.agentSessionToken)).toMatch(/^mcp-/);
+        expect(String(post.body?.agentSessionToken)).toMatch(/^agent-/);
         const text = res.content[0].text;
         expect(text).toContain('Started a implementation work session on ACME-42');
         expect(text).toContain('ws1');

package/dist/tools/work-sessions.test.js

@@ -58,7 +58,7 @@ describe('orboto_work_session_start', () => {
         expect(post.method).toBe('POST');
         expect(post.url).toContain('/work-sessions');
         expect(post.body?.ticketId).toBe('t1');
-        expect(String(post.body?.agentSessionToken)).toMatch(/^mcp-/);
+        expect(String(post.body?.agentSessionToken)).toMatch(/^agent-/);
         const text = res.content[0].text;
         expect(text).toContain('Started a implementation work session on ACME-42');
         expect(text).toContain('ws1');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orboto/mcp",
-  "version": "0.200.0",
+  "version": "0.200.1",
   "description": "Model Context Protocol server for orboto - exposes tickets, projects, milestones, time, docs, primer-facts, alerts and absences as MCP tools for Claude Desktop / Cursor / Copilot Chat / any MCP-aware AI client.",
   "license": "MIT",
   "type": "module",