@orboto/mcp 0.211.2 → 0.212.0

package/dist/tools/capacity-tail.test.js

@@ -0,0 +1,152 @@
+/** ORB-2272 - build capacity for an MCP-only agent: the escape hatch carries list, claim, renew, release and windows, labelled in the metrics and held to the response budget. */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { withMetrics } from '../with-metrics.js';
+import { metricsToolName, TAIL_LABELS } from '../tail-labels.js';
+import { makeApiCallHandler } from './api-call.js';
+import { makeHelpHandler } from './help.js';
+const CLAIM = '6f1c2b1e-3d4a-4b5c-8d9e-0a1b2c3d4e5f';
+function mockApi(answer) {
+    const instrument = [];
+    const proxied = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        const body = init?.body ? JSON.parse(init.body) : undefined;
+        const u = url.toString();
+        if (u.endsWith('/admin/mcp/instrument')) {
+            instrument.push(body);
+            return new Response(JSON.stringify({ id: CLAIM }), { status: 201, headers: { 'content-type': 'application/json' } });
+        }
+        if (u.endsWith('/system/api-proxy')) {
+            proxied.push({ method: body.method, path: body.path, headers: init?.headers });
+            const { status, body: inner } = answer(body);
+            return new Response(JSON.stringify({ status, contentType: 'application/json', body: inner, encoding: 'json', truncated: false, matchedRoute: `${body.method} ${body.path}` }), { status: 200, headers: { 'content-type': 'application/json' } });
+        }
+        return new Response('not mocked', { status: 500 });
+    });
+    return { instrument, proxied };
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_test' });
+const apiCall = withMetrics(client, 'orboto_api_call', undefined, makeApiCallHandler(client));
+const flush = () => new Promise((r) => setTimeout(r, 0));
+const claimRow = (state) => ({ id: CLAIM, resourceName: 'build-host:runner-1', holderKind: 'agent-session', state, position: state === 'queued' ? 1 : null });
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+describe('ORB-2272 - capacity through orboto_api_call', () => {
+    it('claims, renews and releases as this MCP session and labels each call with its capacity tool', async () => {
+        const { instrument, proxied } = mockApi(({ method, path }) => {
+            if (method === 'POST' && path === '/capacity/claims')
+                return { status: 201, body: { ...claimRow('granted'), holders: [] } };
+            if (path.endsWith('/renew'))
+                return { status: 200, body: claimRow('granted') };
+            if (path.endsWith('/release'))
+                return { status: 200, body: claimRow('released') };
+            return { status: 200, body: { items: [claimRow('granted')], nextCursor: null } };
+        });
+        const extra = { sessionId: 'sess-1' };
+        const claimed = await apiCall({ method: 'POST', path: '/capacity/claims', body: { resource: 'build-host:runner-1', reason: 'release build', expectedMinutes: 45, priority: 'release' } }, extra);
+        expect(claimed.isError).toBeUndefined();
+        expect(claimed.structuredContent).toMatchObject({ status: 201, body: { state: 'granted', holderKind: 'agent-session' } });
+        await apiCall({ method: 'POST', path: `/capacity/claims/${CLAIM}/renew`, body: {} }, extra);
+        await apiCall({ method: 'GET', path: '/capacity/resources/build-host:runner-1' }, extra);
+        await apiCall({ method: 'GET', path: '/capacity/windows' }, extra);
+        const released = await apiCall({ method: 'POST', path: `/capacity/claims/${CLAIM}/release`, body: {} }, extra);
+        expect(released.structuredContent).toMatchObject({ status: 200, body: { state: 'released' } });
+        await flush();
+        expect(proxied.every((p) => p.headers['x-orboto-agent-session'] === 'mcp-sess-1')).toBe(true);
+        expect(instrument.map((e) => [e.toolName, e.success])).toEqual([
+            ['orboto_capacity_claim', true],
+            ['orboto_capacity_renew', true],
+            ['orboto_capacity_list', true],
+            ['orboto_capacity_windows', true],
+            ['orboto_capacity_release', true],
+        ]);
+    });
+    it('a 403 comes back as data and counts as a failed orboto_capacity_release with its status', async () => {
+        const { instrument } = mockApi(() => ({ status: 403, body: { error: 'claim_not_yours', message: 'This claim belongs to another account.' } }));
+        const res = await apiCall({ method: 'POST', path: `/capacity/claims/${CLAIM}/release`, body: {} });
+        const text = res.content[0].text;
+        expect(text).toContain('HTTP 403');
+        expect(text).toContain('403 = missing permission');
+        expect(res.structuredContent).toMatchObject({ status: 403, body: { error: 'claim_not_yours' } });
+        await flush();
+        expect(instrument).toEqual([expect.objectContaining({ toolName: 'orboto_capacity_release', success: false, statusCode: 403 })]);
+    });
+    it('a 404 on an unknown resource comes back as data and counts as a failed orboto_capacity_claim', async () => {
+        const { instrument } = mockApi(() => ({ status: 404, body: { error: 'capacity_resource_not_found' } }));
+        const res = await apiCall({ method: 'POST', path: '/capacity/claims', body: { resource: 'gpu-farm', reason: 'x', expectedMinutes: 5 } });
+        expect(res.content[0].text).toContain('HTTP 404');
+        await flush();
+        expect(instrument).toEqual([expect.objectContaining({ toolName: 'orboto_capacity_claim', success: false, statusCode: 404 })]);
+    });
+    it('a long claim list is cut to the api_call budget with an expand handle, never silently', async () => {
+        const items = Array.from({ length: 80 }, (_, i) => ({ ...claimRow('queued'), id: `${CLAIM.slice(0, -2)}${String(i).padStart(2, '0')}`, reason: 'nightly unity build '.repeat(6) }));
+        const { instrument } = mockApi(() => ({ status: 200, body: { items, nextCursor: 'next' } }));
+        const res = await apiCall({ method: 'GET', path: '/capacity/claims', query: { active: true } });
+        const text = res.content[0].text;
+        expect(text).toContain('orboto_response_expand');
+        expect(res.structuredContent.__truncation?.handle).toBeTruthy();
+        await flush();
+        expect(instrument[0]).toMatchObject({ toolName: 'orboto_capacity_list', success: true });
+        expect(Number(instrument[0].truncatedChars)).toBeGreaterThan(0);
+    });
+});
+describe('ORB-2272 - metrics labels of the capacity tail', () => {
+    it('maps every capacity route an agent calls and leaves everything else as orboto_api_call', () => {
+        const cases = [
+            ['GET', '/capacity/resources', 'orboto_capacity_list'],
+            ['GET', '/capacity/resources/build-host:runner-1', 'orboto_capacity_list'],
+            ['GET', '/capacity/resources/build-host:runner-1/queue', 'orboto_capacity_list'],
+            ['GET', '/capacity/claims', 'orboto_capacity_list'],
+            ['GET', `/capacity/claims/${CLAIM}`, 'orboto_capacity_list'],
+            ['post', '/capacity/claims/', 'orboto_capacity_claim'],
+            ['POST', `/capacity/claims/${CLAIM}/renew`, 'orboto_capacity_renew'],
+            ['POST', `/capacity/claims/${CLAIM}/release`, 'orboto_capacity_release'],
+            ['GET', '/capacity/windows', 'orboto_capacity_windows'],
+            ['GET', '/capacity/resources/build-host:runner-1/plan', 'orboto_capacity_plan'],
+            ['POST', '/capacity/resources/unity:build/plan?book=true', 'orboto_capacity_plan'],
+            ['POST', '/capacity/seeds/nightly-unity', 'orboto_capacity_seed'],
+            ['POST', '/capacity/seeds/other', 'orboto_api_call'],
+            ['POST', '/capacity/resources', 'orboto_api_call'],
+            ['POST', `/capacity/claims/${CLAIM}/yield`, 'orboto_api_call'],
+            ['GET', '/capacity', 'orboto_api_call'],
+            ['GET', '/projects', 'orboto_api_call'],
+        ];
+        for (const [method, path, label] of cases)
+            expect(metricsToolName('orboto_api_call', { method, path }), `${method} ${path}`).toBe(label);
+        expect(metricsToolName('orboto_get_ticket', { method: 'POST', path: '/capacity/claims' })).toBe('orboto_get_ticket');
+        expect(new Set(TAIL_LABELS.map((l) => l.label))).toEqual(new Set(['orboto_capacity_list', 'orboto_capacity_claim', 'orboto_capacity_renew', 'orboto_capacity_release', 'orboto_capacity_windows', 'orboto_capacity_plan', 'orboto_capacity_seed', 'orboto_capacity_stats']));
+    });
+    it('ORB-2275 - labels the metrics read as orboto_capacity_stats, with or without a query', () => {
+        expect(metricsToolName('orboto_api_call', { method: 'GET', path: '/capacity/metrics' })).toBe('orboto_capacity_stats');
+        expect(metricsToolName('orboto_api_call', { method: 'get', path: '/capacity/metrics?resource=build-host:runner-1' })).toBe('orboto_capacity_stats');
+        expect(metricsToolName('orboto_api_call', { method: 'POST', path: '/capacity/metrics' })).toBe('orboto_api_call');
+    });
+});
+describe('ORB-2275 - capacity metrics through orboto_api_call', () => {
+    it('reads the 24-hour and 7-day metrics per resource, a 403 without admin:agents:read comes back as data and counts as a failed orboto_capacity_stats', async () => {
+        const window = { grants: 3, waitSecondsMax: 600, holds: 2, expirations: 1, yields: 0, queueDepthMax: 2 };
+        let allowed = true;
+        const { instrument, proxied } = mockApi(() => (allowed
+            ? { status: 200, body: { items: [{ resourceName: 'build-host:runner-1', queueDepth: 1, overrunning: 0, last24h: window, last7d: window }], nextCursor: null } }
+            : { status: 403, body: { error: 'Forbidden', errorKey: 'errors.permissions.forbidden' } }));
+        const ok = await apiCall({ method: 'GET', path: '/capacity/metrics', query: { resource: 'build-host:runner-1' } }, {});
+        expect(JSON.stringify(ok.structuredContent)).toContain('"waitSecondsMax":600');
+        allowed = false;
+        const denied = await apiCall({ method: 'GET', path: '/capacity/metrics' }, {});
+        expect(denied.structuredContent).toMatchObject({ status: 403 });
+        await flush();
+        expect(proxied.map((p) => `${p.method} ${p.path}`)).toEqual(['GET /capacity/metrics', 'GET /capacity/metrics']);
+        expect(instrument.map((e) => [e.toolName, e.success])).toEqual([['orboto_capacity_stats', true], ['orboto_capacity_stats', false]]);
+        expect(new Set(TAIL_LABELS.map((l) => l.label))).toEqual(new Set(['orboto_capacity_list', 'orboto_capacity_claim', 'orboto_capacity_renew', 'orboto_capacity_release', 'orboto_capacity_windows', 'orboto_capacity_plan', 'orboto_capacity_seed', 'orboto_capacity_stats']));
+    });
+});
+describe('ORB-2272 - orboto_help topic capacity', () => {
+    it('serves the claim, renew, release, windows and plan recipes', async () => {
+        const res = await makeHelpHandler()({ topic: 'capacity' });
+        const text = res.content[0].text;
+        for (const needle of ['"path":"/capacity/claims"', '/renew', '/release', '/capacity/windows', 'sessionEnd', '?toolset=full', 'ORBOTO_MCP_TOOLSET=full', 'capacity-holds', 'A curated agent has no orboto_session_check', 'session-check --session-end', '"path":"/capacity/metrics"', 'admin:agents:read'])
+            expect(text).toContain(needle);
+        for (const needle of ['"path":"/capacity/claims"', '/renew', '/release', '/capacity/windows', '/plan', '"book":true', 'graceMinutes', 'capacity plan <resource> --for 45m --book', 'sessionEnd', '?toolset=full', 'ORBOTO_MCP_TOOLSET=full', 'capacity-holds', 'A curated agent has no orboto_session_check', 'session-check --session-end', '/capacity/seeds/nightly-unity', 'capacity wait <claimId> --hold -- <command...>', 'takes no slot'])
+            expect(text).toContain(needle);
+    });
+});

package/dist/tools/docs.js

@@ -94,7 +94,7 @@ export function makeGetDocHandler(client) {
 }
 export const createDocSpaceToolConfig = {
     title: 'Create a doc space',
-    description: 'Create a new wiki space. IMPORTANT: every project ALREADY has an auto-generated general space (slug `<key>-general`, system-generated, holds the AI primer + manual notes) - do NOT create a second space just to hold a project\'s docs. Call orboto_list_doc_spaces first and reuse the existing project space; only create a new one for a genuinely separate collection. `type=global` creates a workspace-wide space (super-admin only); `type=project` creates a space scoped to a project - pass `projectKey` (e.g. "ORB"); a raw `projectId` UUID is still accepted for back-compat. The slug is derived from `name` when omitted. Returns the new space row.',
+    description: 'Create a new wiki space. IMPORTANT: every project ALREADY has an auto-generated general space (slug `<key>-general`, system-generated, holds the AI primer + manual notes) - do NOT create a second space just to hold a project\'s docs. Call orboto_list_doc_spaces first and reuse the existing project space; only create a new one for a genuinely separate collection. `type=global` creates a workspace-wide space (super-admin only); `type=project` creates a space scoped to a project - pass `projectKey` (e.g. "ORB"); a raw `projectId` UUID is still accepted for back-compat. The slug is derived from `name` when omitted. A project space needs `project:edit` on the target project (404 otherwise). Returns the new space row.',
     inputSchema: z.object({
         name: z.string().min(1).max(100).describe('Display name.'),
         type: z.enum(['global', 'project']).describe('Scope: workspace-wide or project-scoped.'),
@@ -199,7 +199,7 @@ export function makeUpdateDocSpaceHandler(client) {
 }
 export const deleteDocSpaceToolConfig = {
     title: 'Delete a doc space',
-    description: 'DESTRUCTIVE - cascades through every doc in the space (the pages themselves are gone, not just hidden). System-generated project primer spaces refuse deletion (they cascade only when the owning project is deleted). Returns success silently; 404 surfaces as an OrbotoApiError.',
+    description: 'DESTRUCTIVE - cascades through every doc in the space (the pages themselves are gone, not just hidden). System-generated project primer spaces refuse deletion (they cascade only when the owning project is deleted). Needs `project:edit` on the space\'s project (global spaces: super-admin): 404 for a space the caller cannot see or that does not exist, 403 for one they cannot manage. Returns success silently; errors surface as an OrbotoApiError.',
     inputSchema: z.object({
         spaceId: z.string().uuid(),
     }).shape,
@@ -377,7 +377,7 @@ export const moveDocToolConfig = {
     inputSchema: z.object({
         docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
         parentDocId: z.string().uuid().nullable().optional().describe('null = top-level; UUID = nest under that doc.'),
-        spaceId: z.string().uuid().optional().describe('Move into a different space. Caller must be member of both.'),
+        spaceId: z.string().uuid().optional().describe('Move into a different space. Caller must be member of both; the parent must live in the target space, and without parentDocId the doc lands at the top level.'),
         sortOrder: z.number().int().optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
@@ -409,7 +409,7 @@ export function makeMoveDocHandler(client) {
 }
 export const duplicateDocSpaceToolConfig = {
     title: 'Duplicate a doc space (clone the space + the docs you can read)',
-    description: 'Fork a doc space with its readable doc tree. The new space\'s name becomes `<source> (copy)`, parent-child relationships in the tree are preserved via UUID remap. Useful when an agent wants to iterate on a runbook space without mutating the original.',
+    description: 'Fork a doc space along with its doc tree. Needs manage rights on the source space; only docs the caller can read are copied. The new space\'s name becomes `<source> (copy)`, parent-child relationships in the tree are preserved via UUID remap. Useful when an agent wants to iterate on a runbook space without mutating the original.',
     inputSchema: z.object({
         spaceId: z.string().uuid().describe('Source space to duplicate.'),
     }).shape,

package/dist/tools/help.js

@@ -11,14 +11,15 @@ import { z } from 'zod';
 import { getToolDoc, listToolDocNames } from '../tool-docs.js';
 import { connectScriptText } from '../connect-script.js';
 import { onboardingText } from '../agent-head.js';
+import { capacityGuideText } from './capacity-guide.js';
 /** ORB-2157, ORB-2161 - guidance that belongs to no single tool, addressed by topic. */
-const TOPICS = { connect: connectScriptText, onboarding: onboardingText };
+const TOPICS = { connect: connectScriptText, onboarding: onboardingText, capacity: capacityGuideText };
 export const helpToolConfig = {
     title: 'Full guidance for one orboto tool',
-    description: 'Return the complete guidance text for one orboto tool by name. Manifest descriptions are one-line summaries; this adds the workflows, warnings and edge cases. 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.',
+    description: 'Return the complete guidance text for one orboto tool by name. Manifest descriptions are one-line summaries; this adds the workflows, warnings and edge cases. 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, topic: "capacity" the build capacity recipes.',
     inputSchema: z.object({
         tool: z.string().min(1).max(128).optional().describe('Tool name, e.g. orboto_create_ticket.'),
-        topic: z.enum(['connect', 'onboarding']).optional().describe('Guidance topic instead of a tool.'),
+        topic: z.enum(['connect', 'onboarding', 'capacity']).optional().describe('Guidance topic instead of a tool.'),
     }).shape,
     outputSchema: z.object({
         tool: z.string(),

package/dist/tools/live-transcript.js

@@ -0,0 +1,93 @@
+/** Mirrors LIVE_TRANSCRIPT_EVENT_KINDS of @orboto/shared-schema; the MCP package ships without it, apps/api/src/test/agent-live-mcp-drift.test.ts pins the copy. */
+export const LIVE_KINDS = [
+    'text', 'tool_call', 'tool_result', 'question', 'permission_prompt', 'limit_prompt', 'login', 'status',
+    'user_prompt', 'assistant_text', 'tool_group', 'turn_end', 'usage', 'context', 'checkout',
+];
+/** The cut one rendered line keeps; the full line stays in structuredContent. */
+export const LIVE_LINE_CHARS = 600;
+const USAGE_LABEL = { five_hour: '5h', seven_day: 'weekly', spend_limit: 'spend', other: 'other' };
+const TOOL_VERBS = {
+    read: ['read 1 file', 'read {n} files'],
+    edit: ['edited 1 file', 'edited {n} files'],
+    search: ['ran 1 search', 'ran {n} searches'],
+    shell: ['ran 1 shell command', 'ran {n} shell commands'],
+    orboto: ['called orboto once', 'called orboto {n} times'],
+    web: ['fetched 1 web page', 'fetched {n} web pages'],
+    agent: ['started 1 agent', 'started {n} agents'],
+    mcp: ['called 1 MCP tool', 'called {n} MCP tools'],
+    other: ['used 1 other tool', 'used {n} other tools'],
+};
+function seconds(ms) {
+    const total = Math.floor(ms / 1000);
+    if (total < 60)
+        return `${total}s`;
+    const minutes = Math.floor(total / 60);
+    return minutes < 60 ? `${minutes}m ${total % 60}s` : `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+}
+function cut(text, limit = LIVE_LINE_CHARS) {
+    const flat = text.replace(/\s+/g, ' ').trim();
+    return flat.length > limit ? `${flat.slice(0, limit)} [cut, ${flat.length - limit} more chars in structuredContent]` : flat;
+}
+/** One line of the transcript as text an agent reads. */
+export function renderLiveEvent(event) {
+    switch (event.kind) {
+        case 'text': return `${event.role}: ${cut(event.text)}`;
+        case 'tool_call': return `-> ${event.name} ${cut(event.input, 200)}`;
+        case 'tool_result': return `<- ${event.isError ? 'error' : 'ok'}: ${cut(event.text, 200)}`;
+        case 'question': return `? ${cut(event.text)}`;
+        case 'permission_prompt': return `! permission ${event.tool}: ${cut(event.text)}`;
+        case 'limit_prompt': return `limit: ${cut(event.text)}${event.resetsAt ? ` (resets ${event.resetsAt})` : ''}`;
+        case 'login': return `login (${event.harness}): ${event.url}`;
+        case 'status': return `[${event.state}${event.detail ? `: ${cut(event.detail, 200)}` : ''}${event.model ? `, ${event.model}` : ''}]`;
+        case 'user_prompt': return `> ${cut(event.text)}`;
+        case 'assistant_text': return `assistant: ${cut(event.text)}`;
+        case 'tool_group': {
+            const counts = event.counts.map((c) => (TOOL_VERBS[c.kind] ?? TOOL_VERBS.other)[c.count === 1 ? 0 : 1].replace('{n}', String(c.count))).join(', ') || 'no tool calls';
+            const items = event.items.slice(0, 8).map((item) => `\n    ${item.name} ${cut(item.summary, 160)}${item.isError ? ' [error]' : ''}`).join('');
+            const more = event.items.length > 8 || (event.omittedItems ?? 0) > 0 ? `\n    (+${event.items.length - Math.min(8, event.items.length) + (event.omittedItems ?? 0)} more calls)` : '';
+            return `* ${counts} (${seconds(event.durationMs)}${event.final ? '' : ', running'})${items}${more}`;
+        }
+        case 'turn_end': return `-- turn ${event.outcome} after ${seconds(event.durationMs)}${event.model ? `, ${event.model}` : ''}${event.effort ? ` (${event.effort})` : ''}`;
+        case 'usage': return `[usage: ${event.windows.map((w) => `${USAGE_LABEL[w.window] ?? w.window} ${Math.round(w.usedPercent)}%${w.resetsAt ? ` (resets ${w.resetsAt})` : ''}`).join(', ')}]`;
+        case 'context': return `[context ${Math.round(event.percent)}%${event.tokens !== undefined && event.windowSize !== undefined ? `, ${event.tokens} of ${event.windowSize} tokens` : ''}]`;
+        case 'checkout': {
+            if (event.repository === 'none')
+                return `[checkout: no repository (${event.reason ?? 'unknown'})]`;
+            const upstream = event.upstream ? `, upstream ${event.upstream.ref} +${event.upstream.ahead}/-${event.upstream.behind}` : ', no upstream';
+            return `[diff +${event.insertions} -${event.deletions}, ${event.filesChanged} files on ${event.branch ?? '?'} against ${event.base ?? 'HEAD'}${upstream}]`;
+        }
+    }
+}
+/** The lines of a page without the running tool group snapshots a later line of the same group replaces. */
+export function latestLines(items) {
+    return items.filter((line, index) => line.event.kind !== 'tool_group' || line.event.final
+        || !items.slice(index + 1).some((later) => later.event.kind === 'tool_group' && later.event.groupId === line.event.groupId));
+}
+export function renderTranscriptLines(items) {
+    return latestLines(items).map((line) => `${line.seq} ${line.at} ${renderLiveEvent(line.event)}`);
+}
+/** The resource answer's cap; it runs outside the tool budget, so it cuts itself, explicitly. */
+export const LIVE_RESOURCE_CHARS = 4000;
+/** The newest lines that fit the resource cap, oldest first, with an explicit note of what was left out. */
+export function renderTranscriptResource(sessionId, page) {
+    const sorted = [...page.items].sort((a, b) => a.seq - b.seq);
+    const lines = renderTranscriptLines(sorted);
+    const head = `# Live session ${sessionId}\n_lastSeq ${page.lastSeq}; newest lines, masked._\n`;
+    const kept = [];
+    let size = head.length;
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        if (size + lines[index].length + 1 > LIVE_RESOURCE_CHARS - 200)
+            break;
+        kept.unshift(lines[index]);
+        size += lines[index].length + 1;
+    }
+    const omitted = lines.length - kept.length;
+    const note = omitted > 0 || (sorted[0]?.seq ?? 1) > 1
+        ? `\n[truncated: earlier lines are not shown here - page the rest with orboto_api_call get /agents/live-sessions/${sessionId}/transcript?afterSeq=N${omitted > 0 ? `; ${omitted} of the newest ${lines.length} did not fit` : ''}]`
+        : '';
+    return `${head}\n${kept.length ? kept.join('\n') : '_No lines yet._'}${note}`;
+}
+export async function readTranscriptResource(client, sessionId) {
+    const page = await client.get(`/agents/live-sessions/${encodeURIComponent(sessionId)}/transcript?order=desc&limit=60`);
+    return renderTranscriptResource(sessionId, page);
+}

package/dist/tools/live-transcript.test.js

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { LIVE_KINDS, LIVE_RESOURCE_CHARS, renderLiveEvent, renderTranscriptResource, } from './live-transcript.js';
+const SESSION = '6b2d8e1f-4a3c-4d5e-8f70-112233445566';
+function line(seq, event) {
+    return { id: `00000000-0000-4000-8000-${String(seq).padStart(12, '0')}`, sessionId: SESSION, seq, at: '2026-09-30T10:00:00.000Z', maskedCount: 0, event };
+}
+const conversation = [
+    { kind: 'user_prompt', text: 'Wie ist der Stand von ACME-129?' },
+    { kind: 'assistant_text', text: 'Ich schaue mir **ACME-129** an.' },
+    { kind: 'tool_group', groupId: 'g-1', final: false, counts: [{ kind: 'read', count: 1 }], durationMs: 10_000, items: [] },
+    {
+        kind: 'tool_group', groupId: 'g-1', final: true, durationMs: 22_000,
+        counts: [{ kind: 'read', count: 2 }, { kind: 'shell', count: 5 }, { kind: 'orboto', count: 1 }],
+        items: [
+            { toolUseId: 't1', name: 'Read', kind: 'read', summary: 'README.md' },
+            { toolUseId: 't2', name: 'Bash', kind: 'shell', summary: 'curl -H \'Authorization: Bearer [secret]\' https://x', isError: true },
+        ],
+    },
+    { kind: 'permission_prompt', questionId: 'q1', tool: 'Bash', text: 'Run rm -rf dist?' },
+    { kind: 'turn_end', durationMs: 1_351_000, model: 'claude-opus-5-5', effort: 'high', outcome: 'done' },
+    { kind: 'usage', windows: [{ window: 'five_hour', usedPercent: 36, resetsAt: '2026-09-30T15:00:00Z' }, { window: 'seven_day', usedPercent: 67 }] },
+    { kind: 'context', percent: 51, tokens: 510_000, windowSize: 1_000_000 },
+    { kind: 'checkout', repository: 'git', branch: 'acme-12-preview', base: 'main', upstream: { ref: 'origin/acme-12-preview', ahead: 2, behind: 0 }, filesChanged: 2, insertions: 42, deletions: 7, files: [] },
+    { kind: 'checkout', repository: 'none', reason: 'detached_head', filesChanged: 0, insertions: 0, deletions: 0, files: [] },
+];
+describe('live transcript rendering', () => {
+    it('knows every kind the contract names and renders each to one non-empty line head', () => {
+        expect(LIVE_KINDS).toHaveLength(15);
+        expect(renderLiveEvent(conversation[conversation.length - 2])).toBe('[diff +42 -7, 2 files on acme-12-preview against main, upstream origin/acme-12-preview +2/-0]');
+        expect(renderLiveEvent(conversation[conversation.length - 1])).toBe('[checkout: no repository (detached_head)]');
+        for (const event of conversation)
+            expect(renderLiveEvent(event).length).toBeGreaterThan(3);
+    });
+});
+describe('orboto://live/{sessionId}/transcript', () => {
+    it('keeps the newest lines within its cap and says what it left out', () => {
+        const items = Array.from({ length: 60 }, (_, i) => line(200 - i, { kind: 'assistant_text', text: `Zeile ${200 - i} ${'y'.repeat(300)}` }));
+        const text = renderTranscriptResource(SESSION, { items, lastSeq: 200 });
+        expect(text.length).toBeLessThanOrEqual(LIVE_RESOURCE_CHARS);
+        expect(text).toContain('Zeile 200');
+        expect(text).not.toContain('Zeile 141 ');
+        expect(text).toMatch(/\[truncated: earlier lines are not shown here - page the rest with orboto_api_call get \/agents\/live-sessions\/[^ ]+\/transcript\?afterSeq=N; \d+ of the newest 60 did not fit\]/);
+    });
+    it('shows a short session whole', () => {
+        const text = renderTranscriptResource(SESSION, { items: conversation.map((event, i) => line(i + 1, event)).reverse(), lastSeq: 8 });
+        expect(text).not.toContain('[truncated');
+        expect(text.indexOf('> Wie ist')).toBeLessThan(text.indexOf('[context 51%'));
+    });
+});

package/dist/tools/session-check.js

@@ -1,26 +1,41 @@
 /** ORB-2223 - the completion check: what this session still owes before its turn may end, and the explicit pause. */
 import { z } from 'zod';
+import { mcpInstanceToken, mcpProcessInstance } from './shared.js';
+import { describeCapacityRelease, releaseSessionCapacity } from './capacity-session.js';
 export const sessionCheckToolConfig = {
     title: 'Completion check',
-    description: 'Before a turn ends: what this session still owes. verdict continue or may_stop, text says why; it lists, never re-runs. pause with a reason, then resume.',
+    description: 'Before a turn ends: what this session still owes. verdict continue or may_stop, text says why; it lists, never re-runs. may_stop releases its granted capacity claims, sessionEnd all. pause with a reason, then resume.',
     inputSchema: z.object({
         action: z.enum(['check', 'pause', 'resume']).default('check'),
         reason: z.string().min(3).max(500).optional(),
+        sessionEnd: z.boolean().optional(),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };
 export function makeSessionCheckHandler(client) {
-    return async (args) => {
+    return async (args, extra) => {
         const action = args.action ?? 'check';
+        const instanceToken = mcpInstanceToken(undefined, extra);
         if (action === 'pause' && !args.reason) {
             return { isError: true, content: [{ type: 'text', text: 'action pause needs a reason: why the session stops on purpose.' }] };
         }
         if (action !== 'check') {
-            const res = await client.post(`/agents/session/${action}`, action === 'pause' ? { reason: args.reason } : {});
+            const res = await client.post(`/agents/session/${action}`, action === 'pause' ? { reason: args.reason } : {}, { instanceToken });
             const text = res.pause ? `Paused since ${res.pause.pausedAt}: ${res.pause.reason}` : 'Not paused - the completion check holds runnable work again.';
             return { content: [{ type: 'text', text }], structuredContent: res };
         }
-        const res = await client.get('/agents/session/unfinished');
-        return { content: [{ type: 'text', text: res.text }], structuredContent: res };
+        const res = await client.get('/agents/session/unfinished', { instanceToken });
+        let capacity = null;
+        if (args.sessionEnd === true) {
+            capacity = await releaseSessionCapacity(client, res.sessionId, 'all', 'agent session ended', instanceToken);
+        }
+        else if (res.verdict === 'may_stop') {
+            capacity = await releaseSessionCapacity(client, res.sessionId, 'granted', 'completion check: may_stop', instanceToken, { respectHolds: instanceToken === mcpProcessInstance() });
+        }
+        const note = capacity ? describeCapacityRelease(capacity) : '';
+        return {
+            content: [{ type: 'text', text: note ? `${res.text}\n${note}` : res.text }],
+            structuredContent: { ...res, ...(capacity ? { capacityReleased: capacity.released, capacityReleaseFailed: capacity.failed } : {}) },
+        };
     };
 }

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

@@ -8,7 +8,7 @@ describe('orboto_session_check', () => {
         const body = { sessionId: 's1', verdict: 'continue', reason: 'runnable', text: 'orboto completion guard: this session still owns runnable authorized work, so the turn does not end yet.' };
         const get = vi.fn().mockResolvedValue(body);
         const result = await makeSessionCheckHandler({ get })({});
-        expect(get).toHaveBeenCalledWith('/agents/session/unfinished');
+        expect(get).toHaveBeenCalledWith('/agents/session/unfinished', { instanceToken: expect.stringMatching(/^agent-/) });
         expect(textOf(result)).toContain('does not end yet');
         expect(result.structuredContent).toMatchObject({ verdict: 'continue' });
     });
@@ -19,8 +19,8 @@ describe('orboto_session_check', () => {
         const handler = makeSessionCheckHandler({ post });
         expect((await handler({ action: 'pause' })).isError).toBe(true);
         expect(textOf(await handler({ action: 'pause', reason: 'Waiting for the release window' }))).toContain('Waiting for the release window');
-        expect(post).toHaveBeenCalledWith('/agents/session/pause', { reason: 'Waiting for the release window' });
+        expect(post).toHaveBeenCalledWith('/agents/session/pause', { reason: 'Waiting for the release window' }, { instanceToken: expect.stringMatching(/^agent-/) });
         expect(textOf(await handler({ action: 'resume' }))).toContain('Not paused');
-        expect(post).toHaveBeenLastCalledWith('/agents/session/resume', {});
+        expect(post).toHaveBeenLastCalledWith('/agents/session/resume', {}, { instanceToken: expect.stringMatching(/^agent-/) });
     });
 });

package/dist/tools/session-start.js

@@ -303,6 +303,9 @@ export function makeSessionStartHandler(client, opts = {}) {
             ? [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}" }.`);
+        const roleAddresses = registration?.scope?.role ? (registration.scope.projectKeys ?? []).map((k) => `${registration.scope.role}@${k}`) : [];
+        if (roleAddresses.length)
+            lines.push(`Address form: peers reach this session and every other ${registration.scope.role} of the project with orboto_agent_notify { to: "${roleAddresses[0]}" } (${roleAddresses.join(', ')}); address a role, never a session id copied from a log.`);
         if (registration?.scope)
             lines.push(identityLine(registration));
         if (opts.channel)

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

@@ -552,6 +552,7 @@ describe('ORB-2136 - session scope and ref', () => {
         const text = res.content[0].text;
         expect(text).toContain('ref mcp-abc123, instance cbb52195. role integrator; projects ORB');
         expect(text).toContain('toSessionRef: "cbb52195"');
+        expect(text).toContain('Address form: peers reach this session and every other integrator of the project with orboto_agent_notify { to: "integrator@ORB" }');
         expect(text).toContain('from spec@orboto.io (spec, s1)');
         expect(res.structuredContent).toMatchObject({ session: { ref: 'mcp-abc123', id: 'cbb52195-0000-4000-8000-000000000000', scope: { role: 'integrator', projectKeys: ['ORB'] } } });
     });

package/dist/with-metrics.js

@@ -5,6 +5,7 @@ import { applyResponseBudget, TruncationBlockAdvertisedSchema } from './response
 import { buildStrictInputSchema, isRawShape } from './input-schema.js';
 import { captureToolDoc, summarizeToolDescription } from './tool-docs.js';
 import { postLogEntry, redactSecrets } from './mcp-instrument.js';
+import { envelopeStatus, metricsToolName } from './tail-labels.js';
 /**
  * ORB-1174 - turn an OrbotoApiError into an actionable, agent-visible
  * tool-error message. Before this, a thrown error reached the MCP runtime
@@ -57,17 +58,20 @@ export function withMetrics(client, toolName, clientHint, handler, nudge) {
             });
             return gated;
         }
+        const label = metricsToolName(toolName, args);
         try {
             const handlerResult = await handler(args, extra);
             const budgeted = applyResponseBudget(toolName, handlerResult);
             const result = budgeted.result;
-            const isError = result.isError === true;
+            const inner = label === toolName ? undefined : envelopeStatus(handlerResult.structuredContent);
+            const isError = result.isError === true || (inner !== undefined && inner >= 400);
             if (nudge)
-                recordSessionStartResult(nudge, toolName, !isError);
+                recordSessionStartResult(nudge, toolName, result.isError !== true);
             void postLogEntry(client, {
-                toolName,
+                toolName: label,
                 durationMs: Date.now() - start,
                 success: !isError,
+                ...(inner !== undefined && inner >= 400 ? { statusCode: inner } : {}),
                 errorMessage: isError && result.content[0] && 'text' in result.content[0]
                     ? redactSecrets(String(result.content[0].text)).slice(0, 500)
                     : undefined,
@@ -88,12 +92,12 @@ export function withMetrics(client, toolName, clientHint, handler, nudge) {
             }
             if (err instanceof OrbotoApiError) {
                 const text = formatApiError(err);
-                void postLogEntry(client, { toolName, durationMs, success: false, statusCode: err.status, errorMessage: redactSecrets(text).slice(0, 500), clientHint });
+                void postLogEntry(client, { toolName: label, durationMs, success: false, statusCode: err.status, errorMessage: redactSecrets(text).slice(0, 500), clientHint });
                 const errResult = { isError: true, content: [{ type: 'text', text }] };
                 return wantsNudge ? prependNudge(errResult) : errResult;
             }
             void postLogEntry(client, {
-                toolName,
+                toolName: label,
                 durationMs,
                 success: false,
                 errorMessage: redactSecrets(err instanceof Error ? err.message : String(err)).slice(0, 500),

package/package.json

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