@orboto/mcp 0.205.1 → 0.206.0

package/dist/server.js

@@ -27,6 +27,7 @@ import { agentBroadcastToolConfig, makeAgentBroadcastHandler, } from './tools/ag
 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 { sessionCheckToolConfig, makeSessionCheckHandler } from './tools/session-check.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';
@@ -209,6 +210,7 @@ export async function buildOrbotoMcpServer(opts) {
     reg('orboto_message_work', agentMessageWorkToolConfig, makeAgentMessageWorkHandler(client));
     reg('orboto_messages', agentMessagesToolConfig, makeAgentMessagesHandler(client));
     reg('orboto_agent_wakes', agentWakesToolConfig, makeAgentWakesHandler(client));
+    reg('orboto_session_check', sessionCheckToolConfig, makeSessionCheckHandler(client));
     reg('orboto_agent_broadcast', agentBroadcastToolConfig, makeAgentBroadcastHandler(client));
     reg('orboto_list_projects', listProjectsToolConfig, makeListProjectsHandler(client));
     reg('orboto_get_project', getProjectToolConfig, makeGetProjectHandler(client));

package/dist/tools/agent-coordination.js

@@ -84,11 +84,12 @@ export function makeAgentPresenceHandler(client) {
 }
 export const agentNotifyToolConfig = {
     title: 'Notify another agent / user',
-    description: 'Send a fire-and-forget message to a user (bot or human) by email; it lands in their inbox (orboto_messages) and, for humans, in-app. kind: info | request (answer expected) | complete (sub-task done) | error. payload: free-form JSON; threadId links a reply to the message it answers. toSessionRef (instance short id, session ref or id) reaches ONE session of the account; project scopes an account message to sessions declared on it (ORB-2136).',
+    description: 'Message a user (bot or human) by email; lands in their inbox (orboto_messages), for humans in-app. kind: request|error = work inside the scope the recipient holds (request needs project or toSessionRef + outcome); info = information; complete = result (needs outcome). payload: free-form JSON; threadId links a reply to the message it answers. toSessionRef (instance short id, session ref or id) reaches ONE session of the account; project scopes an account message to sessions declared on it (ORB-2136).',
     inputSchema: z.object({
         targetEmail: z.string().email(),
         kind: z.enum(['info', 'request', 'complete', 'error']).default('info'),
         subject: z.string().min(1).max(200),
+        outcome: z.string().min(10).max(1000).optional(),
         payload: z.record(z.string(), z.unknown()).optional(),
         threadId: z.string().uuid().optional(),
         project: z.string().min(1).max(64).optional().describe('Project key or UUID: scope the message to the recipient session working that project.'),
@@ -126,8 +127,22 @@ export function makeAgentBroadcastHandler(client) {
         };
     };
 }
+/** ORB-2223 - the message-kind definition this versioned sender enforces; the API only warns. */
+export function notifyDefinitionError(args) {
+    const kind = args.kind ?? 'info';
+    if ((kind === 'request' || kind === 'complete') && !args.outcome?.trim()) {
+        return `Invalid arguments: \`outcome\` is required for a ${kind} - the outcome sentence (what must be true when it is done, or what was delivered).`;
+    }
+    if (kind === 'request' && !args.project && !args.toSessionRef) {
+        return 'Invalid arguments: a request needs a target - `project` (key or UUID) or `toSessionRef`.';
+    }
+    return null;
+}
 export function makeAgentNotifyHandler(client) {
     return async (args, extra) => {
+        const invalid = notifyDefinitionError(args);
+        if (invalid)
+            return { isError: true, content: [{ type: 'text', text: invalid }] };
         const senderRef = mcpInstanceToken(args.senderRef, extra);
         const res = await client.post('/v1/agent/notify', { ...args, senderRef }, { instanceToken: mcpInstanceToken(undefined, extra) });
         const target = res.toSessionId ? `${args.targetEmail} session ${res.toSessionId.slice(0, 8)}` : args.targetEmail;

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

@@ -135,16 +135,28 @@ describe('orboto_agent_notify', () => {
             };
         });
         const handler = makeAgentNotifyHandler(client);
+        const refused = await handler({ targetEmail: 'bob@example.com', kind: 'request', subject: 'Please review ORB-42' });
+        expect(refused.isError).toBe(true);
+        expect(refused.content[0].text).toContain('`outcome` is required for a request');
+        const noTarget = await handler({ targetEmail: 'bob@example.com', kind: 'request', subject: 'Please review ORB-42', outcome: 'ORB-42 has a review verdict' });
+        expect(noTarget.content[0].text).toContain('`project` (key or UUID) or `toSessionRef`');
+        const noOutcome = await handler({ targetEmail: 'bob@example.com', kind: 'complete', subject: 'Done' });
+        expect(noOutcome.content[0].text).toContain('`outcome` is required for a complete');
+        expect(capturedBody).toHaveLength(0);
         const result = await handler({
             targetEmail: 'bob@example.com',
             kind: 'request',
             subject: 'Please review ORB-42',
+            outcome: 'ORB-42 has a review verdict',
+            project: 'ORB',
             payload: { ticketKey: 'ORB-42' },
         });
         expect(capturedBody[0]).toMatchObject({
             targetEmail: 'bob@example.com',
             kind: 'request',
             subject: 'Please review ORB-42',
+            outcome: 'ORB-42 has a review verdict',
+            project: 'ORB',
             payload: { ticketKey: 'ORB-42' },
         });
         expect(result.content[0].text).toContain('notified bob@example.com');

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 acks: it completes an unclaimed request, never claimed work. 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).',
+    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 acks: it completes an unclaimed request; claimed work with open steps is refused until messageWork completes or blocks it. 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.'),

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

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { AgentSessionScopeSchema } from './agent-session-scope.js';
 const WorkSessionResourceClaimSchema = z.object({
     kind: z.enum(['path', 'named']), value: z.string().min(1).max(500), mode: z.enum(['read', 'write']),
-    state: z.enum(['granted', 'waiting']).optional(), requestedAt: z.string().optional(),
+    state: z.enum(['granted', 'waiting']).optional(), requestedAt: z.string().optional(), grantedAt: z.string().optional(),
 });
 /** ORB-2209 - one account reference, shared by `actsAs` and `owner`. */
 const AgentAccountRefSchema = z.object({ id: z.string().uuid(), name: z.string().nullable(), email: z.string() });

package/dist/tools/session-check.js

@@ -0,0 +1,26 @@
+/** ORB-2223 - the completion check: what this session still owes before its turn may end, and the explicit pause. */
+import { z } from 'zod';
+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.',
+    inputSchema: z.object({
+        action: z.enum(['check', 'pause', 'resume']).default('check'),
+        reason: z.string().min(3).max(500).optional(),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+};
+export function makeSessionCheckHandler(client) {
+    return async (args) => {
+        const action = args.action ?? 'check';
+        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 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 };
+    };
+}

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

@@ -0,0 +1,26 @@
+import { describe, expect, it, vi } from 'vitest';
+import { makeSessionCheckHandler } from './session-check.js';
+function textOf(result) {
+    return result.content[0].text;
+}
+describe('orboto_session_check', () => {
+    it('returns the plain-language completion check and the structured reconciliation', async () => {
+        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(textOf(result)).toContain('does not end yet');
+        expect(result.structuredContent).toMatchObject({ verdict: 'continue' });
+    });
+    it('pauses with a reason and resumes, and refuses a pause without one', async () => {
+        const post = vi.fn()
+            .mockResolvedValueOnce({ sessionId: 's1', pause: { pausedAt: '2026-09-24T20:00:00Z', reason: 'Waiting for the release window' } })
+            .mockResolvedValueOnce({ sessionId: 's1', pause: null });
+        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(textOf(await handler({ action: 'resume' }))).toContain('Not paused');
+        expect(post).toHaveBeenLastCalledWith('/agents/session/resume', {});
+    });
+});

package/dist/tools/work-next.js

@@ -27,9 +27,9 @@ export const workNextToolConfig = {
     inputSchema: z.object({
         projectKey: z.string().min(1).describe('Project key (e.g. "ACME") or UUID.'),
         agentTag: z.string().min(1).max(64).optional()
-            .describe('ORB-1772 - preferred-not-exclusive routing tag: tickets labeled `agent:<tag>` rank first for a matching caller, foreign `agent:*` tags rank last but stay eligible. Lowercased server-side. Set it to this worker\'s routing tag (often the model or fleet lane name).'),
+            .describe('ORB-1772 - preferred routing tag: `agent:<tag>` tickets rank first, foreign `agent:*` last but eligible. Lowercased; often the model or fleet lane name.'),
         role: z.enum(['implementation', 'review', 'preflight', 'integration', 'spec']).optional()
-            .describe('Default `implementation`. The dispatcher only reserves a ticket whose (ticket, role) lease is free for THIS role.'),
+            .describe('Default `implementation`; reserves only a ticket whose (ticket, role) lease is free.'),
         leaseSeconds: z.number().int().min(60).max(86_400).optional()
             .describe('How long the lease should hold without renewal. Default 900 (15 min).'),
         startTimer: z.boolean().optional()
@@ -37,11 +37,11 @@ export const workNextToolConfig = {
         agentSessionToken: z.string().optional()
             .describe('Stable per-agent-instance token. Omit to use this MCP connection\'s own instance id.'),
         resourceClaims: z.array(z.object(ResourceClaimShape)).max(50).optional()
-            .describe('ORB-1610 - resource claims to acquire alongside the reservation, AND to filter candidates: a ticket already held under a conflicting GRANTED write claim elsewhere is skipped even when its (ticket, role) lease is free.'),
+            .describe('ORB-1610 - claims to acquire with the reservation; a ticket under a conflicting granted write claim is skipped.'),
         onConflict: z.enum(['reject', 'queue']).optional()
             .describe('Only matters when `resourceClaims` is set on the WINNING candidate. Default `reject`.'),
         peek: z.boolean().optional()
-            .describe('ORB-1930 - answer "is there work for me?" WITHOUT reserving anything: the same candidate walk (role pool, lane caps, labels, dependencies, leases), but no lease, no timer, no lane quota consumed. Returns `candidate` (the ticket a real pull would reserve right now) or the usual empty reason. Use it before spending a model turn on self-tasking.'),
+            .describe('ORB-1930 - "is there work for me?" without reserving: the same candidate walk, no lease, timer or lane quota; returns `candidate` or the empty reason.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };

package/dist/tools/work-sessions.js

@@ -363,7 +363,7 @@ export const workFinishToolConfig = {
         sessionId: z.string().uuid().describe('The id returned by orboto_work_start / orboto_work_session_start.'),
         outcome: z.enum(['finished', 'cancelled']).optional()
             .describe('`finished` (default) drives the ticket transition below. `cancelled` = abandoned attempt; time is still booked, the ticket is left untouched.'),
-        commitSha: z.string().optional().describe('The commit this session produced. Recorded as an attestation immediately, verified asynchronously once git ingestion catches up - never blocks this call.'),
+        commitSha: z.string().optional().describe('The commit this session produced; an attestation now, verified once git ingestion catches up.'),
         verification: z.object({
             reviewOfSessionId: z.string().uuid().optional().describe('Exact independent implementation work session this review examined.'),
             reviewVerdict: z.enum(['approved', 'rework']).optional().describe('Explicit review outcome, paired with reviewOfSessionId; never inferred from later ticket status.'),
@@ -373,8 +373,8 @@ export const workFinishToolConfig = {
             notes: z.string().optional(),
         }).optional().describe('Which gates you actually ran and what they said. This is the attestation a reviewer reads cold.'),
         targetCategory: z.enum(['todo', 'in_progress', 'in_review', 'done', 'wont_fix']).optional()
-            .describe('Default `done`. Use `in_review` when a human should look at it first. Only applied for an implementation session with outcome `finished`.'),
-        note: z.string().optional().describe('The completion note posted on the ticket. Auto-generated (booked time + commit + verification summary) when omitted.'),
+            .describe('Default `done`; `in_review` when a human should look first. Implementation sessions with outcome `finished` only.'),
+        note: z.string().optional().describe('The completion note on the ticket; generated from booked time, commit and verification when omitted.'),
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
 };

package/package.json

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