@orboto/mcp 0.222.2 → 0.224.0

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

@@ -11,10 +11,12 @@ import { OrbotoClient } from '../orboto-client.js';
 import { makeSessionStartHandler } from './session-start.js';
 import { _forgetDeclaredScopes, rememberedScope } from '../session-scope-memory.js';
 import { CHANNEL_START_COMMANDS, CHANNEL_START_COMMANDS_WITHOUT_CLI } from '../inbox-channel.js';
-import { readFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ORBOTO_HOOK_EVENTS, agentContextKey } from '../agent-context.js';
 import { makeResponseExpandHandler } from './response-expand.js';
 import { applyResponseBudget, budgetFor, DEFAULT_BUDGET_CHARS } from '../response-budget.js';
-import { hostname } from 'node:os';
+import { hostname, tmpdir } from 'node:os';
 import { localSessionHost } from './shared.js';
 beforeEach(() => { vi.restoreAllMocks(); });
 afterEach(() => { vi.restoreAllMocks(); });
@@ -120,8 +122,8 @@ describe('orboto_session_start (ORB-1093)', () => {
         expect(text).not.toContain('Git connection health - WARNING');
     });
 });
-describe('orboto_session_start - rules-hash ack (ORB-1607)', () => {
-    it('sends no knownRulesHash on the first call, then passes the received hash back on the second', async () => {
+describe('orboto_session_start - rules-hash ack (ORB-1607, ORB-2576)', () => {
+    it('sends no knownRulesHash on the first call, then passes the received hash back inside the same agent context', async () => {
         const calls = [];
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url) => {
             const u = new URL(url.toString());
@@ -141,7 +143,8 @@ describe('orboto_session_start - rules-hash ack (ORB-1607)', () => {
             const key = Object.keys(fallback).find((k) => (u.pathname + u.search).startsWith(k));
             return { ok: true, status: 200, statusText: 'OK', json: async () => (key ? fallback[key] : {}), text: async () => '' };
         });
-        const handler = makeSessionStartHandler(client);
+        let context = 'claude-code sess-a 2026-10-18T10:00:00Z';
+        const handler = makeSessionStartHandler(client, { agentContext: () => context });
         const first = await handler();
         const firstCall = calls.find((c) => c.startsWith('/agent-instructions'));
         expect(firstCall).toBe('/agent-instructions');
@@ -155,13 +158,23 @@ describe('orboto_session_start - rules-hash ack (ORB-1607)', () => {
         const secondCall = calls.find((c) => c.startsWith('/agent-instructions'));
         expect(secondCall).toBe('/agent-instructions?knownRulesHash=abc123def456');
         const secondText = second.content[0].text;
-        expect(secondText).toContain('Unchanged since this connection last delivered them');
+        expect(secondText).toContain('Unchanged since this agent context received them in full');
         expect(secondText).toContain('forceRules=true');
         expect(secondText).not.toContain('keep following what you already loaded');
         expect(secondText).not.toContain('claim -> commit -> close');
         const secondStructured = second.structuredContent;
         expect(secondStructured.rulesHash).toBe('abc123def456');
         expect(secondStructured.rulesUnchanged).toBe(true);
+        calls.length = 0;
+        context = 'claude-code sess-a 2026-10-18T11:00:00Z';
+        const afterCompaction = await handler();
+        expect(calls.find((c) => c.startsWith('/agent-instructions'))).toBe('/agent-instructions');
+        expect(afterCompaction.content[0].text).toContain('claim -> commit -> close');
+        calls.length = 0;
+        context = '';
+        await handler();
+        await handler();
+        expect(calls.filter((c) => c.startsWith('/agent-instructions'))).toEqual(['/agent-instructions', '/agent-instructions']);
     });
     it('a fresh handler (new connection) starts with no cached hash again', async () => {
         const calls = stubByPath({
@@ -175,6 +188,46 @@ describe('orboto_session_start - rules-hash ack (ORB-1607)', () => {
         expect(call).toBe('/agent-instructions');
     });
 });
+describe('orboto_session_start - knowledge layers and project facts (ORB-2575)', () => {
+    const FACTS_TEXT = '## Where knowledge lives\n- Rules: binding behaviour.\n\n## Project facts\n### ORB (project id proj-1): 1 of 3 facts\n- tech_stack/stack: Go and Postgres\n2 more: `orboto primer ORB`';
+    const facts = (text) => ({
+        source: 'session', unknown: [], text,
+        projects: [{ projectKey: 'ORB', projectId: 'proj-1', total: 3, facts: [{ category: 'tech_stack', key: 'stack', value: 'Go and Postgres', observed: false }] }],
+        workspace: { total: 0, facts: [] },
+    });
+    const base = {
+        '/users/me/assigned-tickets': { items: [] },
+        '/users/me': { email: 'dev@x.io', fullName: 'Dev' },
+        '/agent-instructions': { instructions: 'RULE TEXT', rulesHash: 'h1' },
+        '/time/timer': {},
+    };
+    it('prints the layers and the facts right after the rules, and summarises the counts', async () => {
+        const calls = stubByPath({ ...base, '/project-facts': facts(FACTS_TEXT) });
+        const res = await makeSessionStartHandler(client)();
+        const text = res.content[0].text;
+        expect(calls).toContain('/project-facts');
+        expect(text).toContain(`RULE TEXT\n\n${FACTS_TEXT}\n\n## Your in-progress work`);
+        expect(res.structuredContent.projectFacts).toEqual({
+            source: 'session', projects: [{ projectKey: 'ORB', total: 3, shown: 1 }], workspace: { total: 0, shown: 0 }, unknown: [],
+        });
+    });
+    it('a long facts block is cut with a handle to the rest', async () => {
+        const long = `${FACTS_TEXT}\n${Array.from({ length: 80 }, (_, i) => `- other/fact-${i}: ${'v'.repeat(60)}`).join('\n')}`;
+        stubByPath({ ...base, '/project-facts': facts(long) });
+        const res = await makeSessionStartHandler(client)();
+        const text = res.content[0].text;
+        const handle = res.structuredContent.projectFacts.handle;
+        expect(handle).toBeTruthy();
+        expect(text).toContain(`orboto_response_expand { handle: "${handle}", path: "projectFacts" }`);
+        expect(text).not.toContain('fact-79');
+    });
+    it('an API without the block, or with a malformed one, leaves the section out', async () => {
+        stubByPath({ ...base, '/project-facts': { text: '## Project facts' } });
+        const res = await makeSessionStartHandler(client)();
+        expect(res.content[0].text).not.toContain('## Project facts');
+        expect(res.structuredContent.projectFacts).toBeUndefined();
+    });
+});
 describe('orboto_session_start - ticketKey bundle (ORB-1607)', () => {
     const bundleStubs = {
         '/projects/by-key/ORB': { id: 'proj-1', key: 'ORB', name: 'orboto' },
@@ -263,9 +316,28 @@ describe('orboto_session_start - context cost (ORB-1697)', () => {
         expect(text).toContain('THE FULL RULE TEXT');
         expect(text).not.toContain('forceRules=true');
     });
-    it('without forceRules the ack path is still used - the saving is not lost', async () => {
+    it('ORB-2576 - a subagent inside a running session gets the rules in full', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'orboto-mcp-subagent-'));
+        mkdirSync(join(dir, '.claude'), { recursive: true });
+        writeFileSync(join(dir, '.claude', 'settings.local.json'), JSON.stringify({ hooks: Object.fromEntries(ORBOTO_HOOK_EVENTS.map((e) => [e, [{ hooks: [{ type: 'command', command: 'orboto claude-hook' }] }]])) }));
+        const turn = (extra) => {
+            mkdirSync(join(dir, '.orboto', 'claude-turn'), { recursive: true });
+            writeFileSync(join(dir, '.orboto', 'claude-turn', 'sess-a.json'), JSON.stringify({ sessionId: 'sess-a', cwd: dir, state: 'idle', contextStartedAt: '2026-10-18T10:00:00Z', ...extra }));
+        };
+        const env = { CLAUDE_CODE_SESSION_ID: 'sess-a' };
         const calls = stubByPath(rulesStub);
-        const handler = makeSessionStartHandler(client);
+        const handler = makeSessionStartHandler(client, { agentContext: () => agentContextKey(env, dir) });
+        turn({});
+        await handler();
+        turn({ activeSubagents: ['agent-1'], contextStartedAt: '2026-10-18T10:05:00Z' });
+        calls.length = 0;
+        const inSubagent = await handler();
+        expect(calls.find((c) => c.startsWith('/agent-instructions'))).toBe('/agent-instructions');
+        expect(inSubagent.content[0].text).toContain('THE FULL RULE TEXT');
+    });
+    it('without forceRules the ack path is still used inside one agent context - the saving is not lost', async () => {
+        const calls = stubByPath(rulesStub);
+        const handler = makeSessionStartHandler(client, { agentContext: () => 'claude-code sess-a 2026-10-18T10:00:00Z' });
         await handler();
         calls.length = 0;
         await handler();
@@ -412,7 +484,7 @@ describe('ORB-1818 - rules index instead of the full rule text', () => {
     const BLOCK_TITLES = Array.from({ length: 27 }, (_, i) => `Rule block number ${i + 1} - a realistic operator-authored title`);
     const RULES_TEXT = BLOCK_TITLES.map((t, i) => `${t}\n${'x'.repeat(650)}${i}`).join('\n\n');
     const RULES_INDEX = BLOCK_TITLES.map((title) => ({ title, chars: 651 }));
-    const rulesFull = { instructions: RULES_TEXT, rulesHash: 'hash1818aaaa', rulesIndex: RULES_INDEX, rulesChars: RULES_TEXT.length };
+    const rulesFull = { instructions: RULES_TEXT, rulesHash: 'hash1818aaaa', rulesIndex: RULES_INDEX, rulesChars: RULES_TEXT.length, rulesDelivery: 'index' };
     function stubDigest(rules) {
         return stubByPath({
             '/users/me/assigned-tickets': {
@@ -469,9 +541,9 @@ describe('ORB-1818 - rules index instead of the full rule text', () => {
         expect(chunks.join('')).toBe(RULES_TEXT);
     });
     it('an acked hash returns neither the text NOR the index', async () => {
-        const handler = makeSessionStartHandler(client);
+        const handler = makeSessionStartHandler(client, { agentContext: () => 'claude-code sess-a 2026-10-18T10:00:00Z' });
         stubDigest(rulesFull);
-        await handler();
+        await handler({ forceRules: true });
         vi.restoreAllMocks();
         stubDigest({ rulesHash: 'hash1818aaaa', rulesUnchanged: true });
         const second = await handler();
@@ -480,7 +552,7 @@ describe('ORB-1818 - rules index instead of the full rule text', () => {
         expect(structured.rulesIndex).toBeUndefined();
         expect(structured.rules).toBe('');
         const text = second.content[0].text;
-        expect(text).toContain('Unchanged since this connection last delivered them');
+        expect(text).toContain('Unchanged since this agent context received them in full');
         expect(text).toContain('rulesOnly=true');
         expect(text).not.toContain('Rule block number 1');
     });
@@ -521,6 +593,31 @@ describe('ORB-1818 - rules index instead of the full rule text', () => {
         await handler({ rulesOnly: true });
         expect(calls[0]).toBe('/agent-instructions');
     });
+    it('ORB-2576 - a set under the bound comes in full even with an index', async () => {
+        stubDigest({ ...rulesFull, rulesDelivery: 'full' });
+        const res = await makeSessionStartHandler(client)();
+        expect(res.structuredContent.rulesDelivery).toBe('full');
+        expect(res.content[0].text).toContain(RULES_TEXT);
+    });
+    it('ORB-2576 - above the bound every must-read rule comes in full after the titles', async () => {
+        const index = RULES_INDEX.map((e, i) => (i === 1 ? { ...e, mustRead: true, body: 'MUST READ BODY' } : e));
+        stubDigest({ ...rulesFull, rulesIndex: index });
+        const res = await makeSessionStartHandler(client)();
+        const text = res.content[0].text;
+        expect(text).toContain('so the titles are printed and the 1 must-read rule(s) in full.');
+        expect(text).toContain(`2. ${BLOCK_TITLES[1]} (must read, in full below)`);
+        expect(text).toContain(`### Must read: ${BLOCK_TITLES[1]}\nMUST READ BODY`);
+        expect(res.structuredContent.mustRead).toEqual([BLOCK_TITLES[1]]);
+    });
+    it('ORB-2576 - an index delivery is no receipt: the next start in the same context sends no known hash', async () => {
+        const handler = makeSessionStartHandler(client, { agentContext: () => 'claude-code sess-a 2026-10-18T10:00:00Z' });
+        stubDigest(rulesFull);
+        await handler();
+        vi.restoreAllMocks();
+        const calls = stubDigest(rulesFull);
+        await handler();
+        expect(calls.find((c) => c.startsWith('/agent-instructions'))).toBe('/agent-instructions');
+    });
     it('an API too old to send an index still delivers the full rules inline', async () => {
         stubDigest({ instructions: RULES_TEXT, rulesHash: 'oldapi' });
         const res = await makeSessionStartHandler(client)();

package/dist/tools/update-project.js

@@ -13,7 +13,7 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
 const LOCALE_CODES = ['en', 'de', 'fr', 'es', 'it', 'nl', 'pt', 'ru', 'pl', 'tr', 'cs', 'da', 'sv', 'no', 'fi', 'ja', 'zh', 'ko'];
 export const updateProjectToolConfig = {
     title: 'Update a project\'s metadata',
-    description: 'Patch a project (`name`, `description`, `key`, `status`, `branchTemplate`, `customerId`, `language`). At least one field must be set. Use `status: "archived"` or `"closed"` to take a project out of active rotation. Renaming the `key` also rewrites every ticket\'s `PROJ-N` reference - handle with care. `language` sets the project\'s expected ticket language (one of the 18 supported locales); pass null to inherit the workspace language.',
+    description: 'Patch a project; set at least one field. `status` archived or closed leaves rotation. A `key` rename rewrites `PROJ-N` references. `language` null inherits. `noLaneReason`: no headless lane needed (bots work interactively); null clears.',
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Current project key.'),
         patch: z.object({
@@ -28,6 +28,7 @@ export const updateProjectToolConfig = {
                 .describe('Customer UUID; null detaches.'),
             language: z.enum(LOCALE_CODES).nullable().optional()
                 .describe('Content language; null inherits workspace.'),
+            noLaneReason: z.string().nullable().optional(),
         }).refine((p) => Object.keys(p).length > 0, { message: 'patch must include at least one field' }),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
@@ -49,6 +50,7 @@ export function makeUpdateProjectHandler(client) {
                 description: updated.description,
                 status: updated.status,
                 language: updated.language ?? null,
+                noLaneReason: updated.noLaneReason ?? null,
                 spec: updated.spec,
             },
         };

package/dist/tools/update-project.test.js

@@ -30,6 +30,16 @@ function stub(responses) {
 const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
 const PROJ = { id: 'p1', key: 'ACME', name: 'Acme', description: null, status: 'active' };
 describe('orboto_update_project', () => {
+    it('ORB-2569 records and clears the no-lane decision, string or null', async () => {
+        const calls = stub([{ json: PROJ }, { json: { ...PROJ, noLaneReason: 'Bots work interactively' } }, { json: PROJ }, { json: { ...PROJ, noLaneReason: null } }]);
+        const handler = makeUpdateProjectHandler(client);
+        const set = await handler({ projectKey: 'ACME', patch: { noLaneReason: 'Bots work interactively' } });
+        expect(calls[1]).toMatchObject({ method: 'PATCH', body: { noLaneReason: 'Bots work interactively' } });
+        expect(set.structuredContent).toMatchObject({ noLaneReason: 'Bots work interactively' });
+        const cleared = await handler({ projectKey: 'ACME', patch: { noLaneReason: null } });
+        expect(calls[3]).toMatchObject({ body: { noLaneReason: null } });
+        expect(cleared.structuredContent).toMatchObject({ noLaneReason: null });
+    });
     it('PATCHes only the supplied fields', async () => {
         const calls = stub([
             { json: PROJ },

package/dist/version-guard.test.js

@@ -16,6 +16,8 @@ import { VERSION } from './version.js';
 const SRC = dirname(fileURLToPath(import.meta.url));
 const pkg = createRequire(import.meta.url)('../package.json');
 const ALLOWED = new Set(['version.ts']);
+/** ORB-2584 - the channel-start cut-over is a protocol version pinned to shared-schema by channel-start.test.ts, not the package version. */
+const ALLOWED_LINES = [/^export const CHANNEL_START_CUTOVER_VERSION = '\d+\.\d+\.\d+';$/];
 function walk(dir, acc = []) {
     for (const entry of readdirSync(dir)) {
         const full = join(dir, entry);
@@ -38,7 +40,7 @@ describe('ORB-1173 - version literal guard', () => {
         for (const file of walk(SRC)) {
             const text = readFileSync(file, 'utf8');
             text.split('\n').forEach((line, i) => {
-                if (semverLiteral.test(line))
+                if (semverLiteral.test(line) && !ALLOWED_LINES.some((allowed) => allowed.test(line.trim())))
                     offenders.push(`${file.replace(SRC, 'src')}:${i + 1}: ${line.trim()}`);
             });
         }

package/package.json

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