@orboto/mcp 0.181.0 → 0.182.0

package/dist/tools/work-sessions.js

@@ -18,14 +18,9 @@
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
 import { mcpInstanceToken, resolveTicketByKey } from './shared.js';
-const ResourceClaimShape = {
-    kind: z.enum(['path', 'named']),
-    value: z.string().min(1).max(500),
-    mode: z.enum(['read', 'write']),
-};
-/** Shared 409-body reader: the endpoint's body carries EITHER `holder`
- *  (a lease conflict) OR `claimConflicts` (a resource-claim conflict) -
- *  never both, since the lease is checked before claims are applied. */
+import { validateRulesReceipt } from '../required-rules.js';
+export { makeWorkNextHandler, workNextToolConfig } from './work-next.js';
+import { GIT_HEALTH_REASON_TEXT, ResourceClaimShape, } from './work-sessions-shared.js';
 function parseClaimConflicts(err) {
     try {
         return JSON.parse(err.body).claimConflicts;
@@ -55,12 +50,6 @@ function describe(s) {
 // Mirrors apps/mcp/src/tools/session-start.ts's local shapes - kept
 // duplicated rather than imported, same choice that file already made for
 // its own bundle types (no shared MCP-side schema layer for these).
-const GIT_HEALTH_REASON_TEXT = {
-    connection_inactive: 'connection is deactivated',
-    app_installation_suspended: 'GitHub App installation is suspended',
-    oauth_token_expired: 'OAuth token expired with no refresh path',
-    history_backfill_error: 'last history backfill failed',
-};
 export const workStartToolConfig = {
     title: 'Start a work session and load the full context bundle',
     description: 'ORB-1611 - the one-call ticket pickup. Acquires the (ticket, role) work lease with the exact same guarantees as orboto_work_session_start (exactly ONE active session per ticket+role workspace-wide, a conflict names the holder, resourceClaims apply atomically with the lease), AND in the SAME response returns the rules-hash ack (same semantics as orboto_session_start), the project primer, the ticket enriched with its description/status/priority, its checklists, its dependencies, that project\'s git connection health, and any other live sessions already on the ticket. This replaces the 8-15 separate calls (orboto_session_start, orboto_get_project_primer, orboto_get_ticket, orboto_get_checklists, orboto_list_ticket_dependencies, ...) a normal ticket pickup used to cost. Prefer this over orboto_work_session_start for picking up a ticket; use the plain tool only when you deliberately do not want the bundle (e.g. a mid-task lease renewal where you already have fresh context). A conflict never leaves a partial session behind - same rollback-on-conflict guarantee as orboto_work_session_start.',
@@ -81,7 +70,8 @@ export const workStartToolConfig = {
         onConflict: z.enum(['reject', 'queue']).optional()
             .describe('Only matters when `resourceClaims` is set. Default `reject`.'),
     }).shape,
-    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    // takeover=true cancels another holder; hints describe the worst allowed call.
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };
 export function makeWorkStartHandler(client) {
     // Per-connection rules-hash cache, mirrored from session-start.ts's
@@ -109,8 +99,7 @@ export function makeWorkStartHandler(client) {
                 agentSessionToken: token,
                 ...(lastKnownRulesHash ? { knownRulesHash: lastKnownRulesHash } : {}),
             });
-            if (res.rulesHash)
-                lastKnownRulesHash = res.rulesHash;
+            validateRulesReceipt(res, lastKnownRulesHash, 'rules');
             const lines = [
                 res.reused
                     ? `Renewed your existing ${res.session.role} session on ${args.ticketKey}.`
@@ -127,7 +116,7 @@ export function makeWorkStartHandler(client) {
             }
             lines.push('', '## Working rules');
             if (res.rulesUnchanged) {
-                lines.push(`Unchanged since your last work-start on this connection (hash ${res.rulesHash}) - keep following what you already loaded.`);
+                lines.push(`Unchanged since your last work-start on this connection (hash ${res.rulesHash}). If these rules are not currently in your context, call orboto_session_start with rulesOnly: true before proceeding.`);
             }
             else {
                 lines.push(res.rules?.trim() || '(no workspace rules configured)');
@@ -169,6 +158,7 @@ export function makeWorkStartHandler(client) {
             lines.push(res.siblingSessions.length === 0
                 ? '(none)'
                 : res.siblingSessions.map((s) => `  - [${s.role}] ${s.userFullName ?? s.userEmail ?? 'unknown'} - lease until ${s.leaseUntil}`).join('\n'));
+            lastKnownRulesHash = res.rulesHash;
             return {
                 content: [{ type: 'text', text: lines.join('\n') }],
                 structuredContent: {
@@ -249,7 +239,8 @@ export const workSessionStartToolConfig = {
         onConflict: z.enum(['reject', 'queue']).optional()
             .describe('Only matters when `resourceClaims` is set. Default `reject`: a conflicting write claim fails the WHOLE call with the conflicting holder(s) named - if this call would have created a brand-new session, that session is rolled back rather than left holding the lease without its claims. `queue`: the conflicting claim is accepted as `state: "waiting"` instead of failing; it is promoted automatically once the conflict clears (release, finish, or the next orboto_work_sessions read).'),
     }).shape,
-    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    // The optional takeover can displace someone else's active session.
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true },
 };
 export function makeWorkSessionStartHandler(client) {
     return async (args, extra) => {
@@ -423,179 +414,6 @@ export function makeWorkFinishHandler(client) {
         };
     };
 }
-/** ORB-1799 - rendered identically on every exit (reserved, empty, paused):
- *  an agent that just pulled fresh work is exactly the one about to forget
- *  the ticket it already finished. Empty array renders nothing. */
-function landedIdleLines(rows) {
-    if (!rows || rows.length === 0)
-        return [];
-    return [
-        '',
-        '## Landed, idle - finished-looking work of yours awaiting the status move',
-        ...rows.map((r) => `- ${r.ticketKey ?? r.ticketId} "${r.title}" - ${r.commitCount} commit(s) linked, no activity for ${r.idleWorkingDays} working day(s) (since ${r.lastActivityAt}).`),
-        'Verify each is actually finished, then move it into the review lane (orboto_work_finish with targetCategory "in_review", or orboto_move_ticket) - do NOT re-implement it.',
-    ];
-}
-export const workNextToolConfig = {
-    title: 'Pull and reserve the next ready ticket (worker-pool dispatch)',
-    description: 'ORB-1613 - the pull side of low-management dispatch, sibling of orboto_work_start on the "I already know which ticket" side. Picks the highest-priority ticket in a project that is READY FOR THE REQUESTED ROLE (default role implementation pulls TODO tickets; `role: "review"` pulls tickets in the in_review status category instead, and NEVER offers a ticket the caller itself implemented - the review lane primitive, ORB-1777), unblocked (every dependency closed), not already leased under the requested role, and not blocked by a conflicting resourceClaim - then reserves it with the EXACT same guarantees as orboto_work_start (atomic lease acquire + the full context bundle: rules ack, primer, ticket, checklists, dependencies, git health, siblings) in the same response. Priority then ticket number, deterministic - never a coin flip on ties. Two workers calling this concurrently never receive the SAME ticket: the underlying reservation is the identical partial-unique-index INSERT orboto_work_start uses, just walked across an ordered candidate list - a collision just advances to the next candidate. Epics are never returned (they are containers, not directly implementable). When nothing is ready, the response is a STRUCTURED result (`reserved: null`) with a `reason` (`none-matching` = no todo tickets at all; `all-blocked` = candidates exist but all have open dependencies; `all-leased` = ready candidates exist but are all currently leased or claim-conflicted; `autonomy_paused` = ORB-1774, this agent identity or the whole workspace has autonomous pulls paused by an operator - idle and wait for an operator/notify wakeup instead of retrying) and, ONLY when derivable from an actual active lease, a `retryAfterSeconds` backoff hint (`earliestFreeAt` null and `retryAfterSeconds` null means no signal exists - never a fabricated constant). This is never an error - a worker pool should back off on the hint rather than poll hot. Prefer this over orboto_work_start whenever the caller does not care WHICH ticket it gets, only that it gets the best available one right now. Every response - reserved, empty or paused - also carries `landedIdle`: YOUR OWN tickets in this project that are still in_progress with a linked commit and no activity for days (ORB-1799). Those are finished-looking work nobody handed to the review lane; move them on instead of re-implementing them.',
-    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).'),
-        role: z.enum(['implementation', 'review', 'preflight', 'integration']).optional()
-            .describe('Default `implementation`. The dispatcher only reserves a ticket whose (ticket, role) lease is free for THIS role.'),
-        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()
-            .describe('Defaults to true for `implementation`, false for the attach-only roles.'),
-        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.'),
-        onConflict: z.enum(['reject', 'queue']).optional()
-            .describe('Only matters when `resourceClaims` is set on the WINNING candidate. Default `reject`.'),
-    }).shape,
-    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
-};
-export function makeWorkNextHandler(client) {
-    // Per-connection rules-hash cache, same pattern as orboto_work_start.
-    let lastKnownRulesHash;
-    return async (args, extra) => {
-        const token = mcpInstanceToken(args.agentSessionToken, extra);
-        const res = await client.post('/work-sessions/next', {
-            projectKey: args.projectKey,
-            ...(args.agentTag ? { agentTag: args.agentTag } : {}),
-            ...(args.role ? { role: args.role } : {}),
-            ...(args.leaseSeconds ? { leaseSeconds: args.leaseSeconds } : {}),
-            ...(args.startTimer !== undefined ? { startTimer: args.startTimer } : {}),
-            ...(args.resourceClaims && args.resourceClaims.length > 0 ? { resourceClaims: args.resourceClaims } : {}),
-            ...(args.onConflict ? { onConflict: args.onConflict } : {}),
-            agentSessionToken: token,
-            ...(lastKnownRulesHash ? { knownRulesHash: lastKnownRulesHash } : {}),
-        });
-        if (!res.reserved) {
-            // ORB-1774 - a pause is an operator decision, not a backoff situation:
-            // tell the agent to idle, not to poll for a free slot.
-            if (res.reason === 'autonomy_paused') {
-                return {
-                    content: [{
-                            type: 'text',
-                            text: [
-                                'Autonomous work is PAUSED for this agent (by an operator, per-bot or workspace-wide). Do not poll for new tickets - idle and wait for an operator instruction or an agent-notify wakeup. Explicitly assigned work via orboto_work_start still runs.',
-                                ...landedIdleLines(res.landedIdle),
-                            ].join('\n'),
-                        }],
-                    structuredContent: {
-                        reserved: null,
-                        reason: res.reason,
-                        retryAfterSeconds: null,
-                        earliestFreeAt: null,
-                        candidatesConsidered: 0,
-                        ...(res.landedIdle && res.landedIdle.length > 0 ? { landedIdle: res.landedIdle } : {}),
-                    },
-                };
-            }
-            const lines = [`No ready ticket in "${args.projectKey}" right now (${res.reason}).`];
-            lines.push(res.retryAfterSeconds != null
-                ? `Retry in ~${res.retryAfterSeconds}s (earliest known free: ${res.earliestFreeAt}).`
-                : 'No derivable ETA - poll again later or check the project board.');
-            lines.push(`Candidates considered: ${res.candidatesConsidered}.`);
-            lines.push(...landedIdleLines(res.landedIdle));
-            return {
-                content: [{ type: 'text', text: lines.join('\n') }],
-                structuredContent: {
-                    reserved: null,
-                    reason: res.reason,
-                    retryAfterSeconds: res.retryAfterSeconds,
-                    earliestFreeAt: res.earliestFreeAt,
-                    candidatesConsidered: res.candidatesConsidered,
-                    ...(res.landedIdle && res.landedIdle.length > 0 ? { landedIdle: res.landedIdle } : {}),
-                },
-            };
-        }
-        const r = res.reserved;
-        if (r.rulesHash)
-            lastKnownRulesHash = r.rulesHash;
-        const lines = [
-            r.reused
-                ? `Renewed your existing ${r.session.role} session on ${r.ticket.ticketKey ?? r.session.ticketId}.`
-                : `Reserved ${r.ticket.ticketKey ?? r.session.ticketId} - started a ${r.session.role} work session.`,
-            `Session id: ${r.session.id} (pass this to orboto_work_session_finish / orboto_work_finish).`,
-            `Lease held until ${r.session.leaseUntil}; it renews automatically while you keep calling orboto.`,
-            r.session.activeTimerId ? 'Timer running.' : 'No timer started for this role.',
-        ];
-        if (r.queued && r.queued.length > 0) {
-            lines.push('Queued (waiting for a conflicting writer to release):', ...r.queued.map((q) => `  - ${q.claim.kind}:${q.claim.value} - position ${q.position}`));
-        }
-        lines.push('', '## Working rules');
-        if (r.rulesUnchanged) {
-            lines.push(`Unchanged since your last call on this connection (hash ${r.rulesHash}) - keep following what you already loaded.`);
-        }
-        else {
-            lines.push(r.rules?.trim() || '(no workspace rules configured)');
-        }
-        lines.push('', '## Project primer');
-        lines.push(r.primer.markdown.trim() || '(primer unavailable)');
-        lines.push('', `## Ticket: ${r.ticket.ticketKey ?? '?'}`);
-        lines.push(r.ticket.title);
-        lines.push(`Status: ${r.ticket.statusName ?? r.ticket.status}  Priority: ${r.ticket.priority}  Type: ${r.ticket.type}`);
-        if (r.ticket.description)
-            lines.push('', r.ticket.description);
-        lines.push('', '## Checklists');
-        if (r.checklists.length === 0) {
-            lines.push('(none)');
-        }
-        else {
-            for (const cl of r.checklists) {
-                lines.push(`${cl.title} (${cl.progress.done}/${cl.progress.total})${cl.triggersDone ? ' - triggers done' : ''}`);
-                for (const i of cl.items) {
-                    const link = i.linkedTicketKey ? ` -> [${i.linkedTicketKey}] (${i.linkedTicketStatusCategory ?? 'unknown'})` : '';
-                    lines.push(`- [${i.effectiveCompleted ? 'x' : ' '}] ${i.content}${link}`);
-                }
-            }
-        }
-        // ORB-1614 - see the comment on the other fmtDeps above.
-        const fmtDeps = (edges) => edges.length === 0 ? '(none)' : edges.map((e) => `- [${e.ticketKey ?? '?'}] ${e.title ?? `External dependency (access restricted)${e.resolved ? ' - resolved' : ' - still open'}`}${e.statusName ? ` - ${e.statusName}` : ''}`).join('\n');
-        lines.push('', '## Dependencies');
-        lines.push('Blocked by:', fmtDeps(r.dependencies.blockedBy), 'Blocks:', fmtDeps(r.dependencies.blocks));
-        const unhealthy = r.gitHealth.filter((c) => !c.healthy);
-        if (unhealthy.length > 0) {
-            lines.push('', '## Git connection health - WARNING');
-            for (const c of unhealthy) {
-                lines.push(`- "${c.name}" (${c.provider}) - ${GIT_HEALTH_REASON_TEXT[c.reason ?? ''] ?? c.reason ?? 'unknown reason'}`);
-            }
-        }
-        lines.push('', '## Other sessions on this ticket');
-        lines.push(r.siblingSessions.length === 0
-            ? '(none)'
-            : r.siblingSessions.map((s) => `  - [${s.role}] ${s.userFullName ?? s.userEmail ?? 'unknown'} - lease until ${s.leaseUntil}`).join('\n'));
-        lines.push(...landedIdleLines(res.landedIdle));
-        return {
-            content: [{ type: 'text', text: lines.join('\n') }],
-            structuredContent: {
-                reserved: {
-                    session: r.session,
-                    reused: r.reused,
-                    queued: r.queued ?? [],
-                    rulesHash: r.rulesHash,
-                    rulesUnchanged: r.rulesUnchanged,
-                    primer: r.primer,
-                    ticket: r.ticket,
-                    checklists: r.checklists,
-                    dependencies: r.dependencies,
-                    gitHealth: r.gitHealth,
-                    siblingSessions: r.siblingSessions,
-                },
-                reason: null,
-                retryAfterSeconds: null,
-                earliestFreeAt: null,
-                candidatesConsidered: res.candidatesConsidered,
-                ...(res.landedIdle && res.landedIdle.length > 0 ? { landedIdle: res.landedIdle } : {}),
-            },
-        };
-    };
-}
 // ---------------------------------------------------------------------------
 // orboto_work_sessions
 // ---------------------------------------------------------------------------

package/dist/with-metrics.js

@@ -1,5 +1,6 @@
 import { OrbotoApiError } from './orboto-client.js';
-import { shouldNudge, prependNudge, shouldGate, gateResult } from './session-nudge.js';
+import { shouldNudge, prependNudge, shouldGate, gateResult, recordSessionStartResult } from './session-nudge.js';
+import { RequiredRulesError } from './required-rules.js';
 import { applyResponseBudget, TruncationBlockAdvertisedSchema } from './response-budget.js';
 import { buildStrictInputSchema, isRawShape } from './input-schema.js';
 import { captureToolDoc, summarizeToolDescription } from './tool-docs.js';
@@ -62,8 +63,7 @@ nudge) {
         // regardless of its outcome. Applied to the returned result below.
         const wantsNudge = nudge ? shouldNudge(nudge, toolName) : false;
         // ORB-1471 - HARD session-start gate. When the workspace requires it,
-        // refuse every tool call until `orboto_session_start` has run (this also
-        // flips the "ran" flag when the tool IS session_start). The gate message
+        // refuse every tool call until `orboto_session_start` succeeds. The gate message
         // supersedes the soft nudge, so we return it directly without running the
         // handler. Disabled by default => `shouldGate` returns false and nothing
         // below changes.
@@ -92,6 +92,8 @@ nudge) {
             // as success=false in the log so dashboards reflect actual
             // user-visible failures.
             const isError = result.isError === true;
+            if (nudge)
+                recordSessionStartResult(nudge, toolName, !isError);
             void postLogEntry(client, {
                 toolName,
                 durationMs: Date.now() - start,
@@ -113,6 +115,12 @@ nudge) {
         }
         catch (err) {
             const durationMs = Date.now() - start;
+            if (nudge)
+                recordSessionStartResult(nudge, toolName, false);
+            if (err instanceof RequiredRulesError) {
+                void postLogEntry(client, { toolName, durationMs, success: false, statusCode: err.status, errorMessage: err.message, clientHint });
+                return { isError: true, content: [{ type: 'text', text: err.message }], structuredContent: { errorKey: err.errorKey, reason: err.reason, ...(err.status ? { status: err.status } : {}) } };
+            }
             // ORB-1174 - an OrbotoApiError carries a real HTTP status + message.
             // Return it as a structured isError result so the agent + human see
             // WHY (401 vs 404 vs 500) and can self-correct, instead of the

package/package.json

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