@orboto/mcp 0.192.0 → 0.194.0

package/dist/tool-docs.js

@@ -1,18 +1,7 @@
 /**
  * ORB-1741 - the manifest diet (epic ORB-1691).
  *
- * Every tool description in the manifest is STANDING context cost: an
- * eager-loading client pays it on connect, every session. The curated
- * toolset (ORB-1520) cut the tool COUNT; this module cuts the per-tool
- * TEXT. At registration time (with-metrics.ts) the full description is
- * captured here and the wire manifest carries only a one-sentence
- * summary; `orboto_help { tool }` serves the full guidance lazily - the
- * same deferred-docs pattern ToolSearch uses for deferred tools.
- *
- * The full texts stay where they always lived - in each tool file's
- * `description` - so authors keep writing complete guidance and nothing
- * is lost: the summary is DERIVED (first sentence, or a hand-written
- * override for the few whose first sentence overruns the cap).
+ * @see ORB-1520
  */
 /** Soft cap for a wire description; the ratchet in manifest-size.test.ts
  *  enforces the aggregate outcome. */

package/dist/tool-docs.test.js

@@ -34,7 +34,7 @@ describe('summarizeToolDescription', () => {
         const s = summarizeToolDescription('orboto_unknown_tool', long);
         expect(s.length).toBeLessThanOrEqual(SUMMARY_MAX_CHARS);
         expect(s.endsWith('...')).toBe(true);
-        expect(s).not.toMatch(/\swor\.\.\.$/); // never cuts inside a word
+        expect(s).not.toMatch(/\swor\.\.\.$/);
     });
 });
 describe('orboto_help handler', () => {
@@ -67,20 +67,14 @@ describe('live manifest vs help registry (no guidance lost)', () => {
             expect(tools.length).toBeGreaterThan(150);
             for (const t of tools) {
                 const wire = t.description ?? '';
-                // Acceptance: no registered wire description exceeds the cap.
                 expect(wire.length, `${t.name} wire description too long`).toBeLessThanOrEqual(SUMMARY_MAX_CHARS);
-                // The full text is behind the registry and STARTS where the
-                // summary came from (override tools aside, whose full text is
-                // still captured verbatim).
                 const full = getToolDoc(t.name);
                 expect(full, `${t.name} missing from the help registry`).toBeTruthy();
                 expect(summarizeToolDescription(t.name, full)).toBe(wire);
             }
-            // Spot-check the measured worst offender end to end via the tool.
             const res = await client.callTool({ name: 'orboto_help', arguments: { tool: 'orboto_create_ticket' } });
-            // First block can be the ORB-1331 session-start nudge - join all.
             const text = res.content.map((c) => c.text ?? '').join('\n');
-            expect(text.length).toBeGreaterThan(1000); // the old 2.9k essay, intact
+            expect(text.length).toBeGreaterThan(1000);
             expect(text).toContain('Duplicate-detection safety-net');
         }
         finally {

package/dist/tool-parameters.test.js

@@ -1,24 +1,5 @@
 /**
  * ORB-1805 - the schema diet must never cost a PARAMETER.
- *
- * The diet trims description text: tool prose moved into
- * `orboto_help` / the skill's REFERENCE.md, per-parameter prose
- * shortened to the phrase a caller acts on. What it must never do is
- * drop a field, flip a required field to optional, or shrink an enum -
- * those are the changes that silently break a caller.
- *
- * `tool-parameters.baseline.json` is the snapshot taken from the FULL
- * manifest immediately BEFORE the ORB-1805 diet: for every tool, every
- * property path in its input schema (nested objects and array items
- * included, as dotted paths), its required list, and every enum's
- * values. This test walks the live manifest the same way and fails on
- * any loss.
- *
- * Direction matters: it is a SUPERSET check. Adding a parameter, making
- * a required one optional-to-required is caught, and adding an enum
- * value is fine - only removal fails. Re-baseline ONLY when a parameter
- * is intentionally removed (which is an API break in its own right and
- * belongs in its own ticket), never to make this test go quiet.
  */
 import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
 import { readFileSync } from 'node:fs';

package/dist/tools/absence-writes.js

@@ -2,19 +2,9 @@
  * ORB-933 - write-side MCP tools for absences and the two admin tables
  * that ride alongside them (public holidays, company closures).
  *
- * - orboto_update_public_holiday - PATCH /admin/public-holidays/:id
- * - orboto_update_company_closure - PATCH /admin/company-closures/:id
- * - orboto_update_absence - PATCH /absences/:id
- *
- * Today these surfaces only had POST + DELETE - typo correction or date
- * fix meant delete + recreate, losing the original row id. PATCH fills
- * that gap. Listing endpoints stay on the existing routes (no read tools
- * here yet - that's Phase 3 of the CRUD parity epic, ORB-935).
+ * @see ORB-935
  */
 import { z } from 'zod';
-// ---------------------------------------------------------------------------
-// orboto_update_public_holiday
-// ---------------------------------------------------------------------------
 export const updatePublicHolidayToolConfig = {
     title: 'Edit a public holiday',
     description: 'Correct a typo or wrong date on a public holiday without losing the row id. Admin-only (`admin:absences:write`). Pass only the fields you want to change; at least one field is required.',
@@ -38,9 +28,6 @@ export function makeUpdatePublicHolidayHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_update_company_closure
-// ---------------------------------------------------------------------------
 export const updateCompanyClosureToolConfig = {
     title: 'Edit a company closure',
     description: 'Update a workspace-wide non-working block (company offsite, holiday shutdown). Admin-only (`admin:absences:write`). Pass only the fields you want to change; at least one field is required. If only one of `startDate`/`endDate` is passed, the other is left as-is - the API still validates start ≤ end after the partial patch.',
@@ -63,9 +50,6 @@ export function makeUpdateCompanyClosureHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_update_absence
-// ---------------------------------------------------------------------------
 export const updateAbsenceToolConfig = {
     title: 'Edit a pending or draft absence request',
     description: 'Edit your own absence request before a reviewer acts on it. Locked once the status is `approved`, `rejected`, or `cancelled` - those transitions go through the approve / reject / cancel endpoints, not this one. Caller must be the absence owner or a super-admin. `durationDays` is recomputed automatically when dates move (uses the owner\'s working-day rules + holidays + closures).',

package/dist/tools/admin-translations.js

@@ -1,16 +1,5 @@
 /**
  * ORB-893 - admin-translation review queue MCP tools.
- *
- * Three thin wrappers around `/admin/tickets/translations*`:
- *
- * - `orboto_admin_translation_list` - paginated list of
- *    auto-translated tickets (pending review by default, or `all`).
- * - `orboto_admin_translation_approve` - stamp the row reviewed.
- * - `orboto_admin_translation_revert` - restore the pre-translation
- *    title + description from the audit comment.
- *
- * All three require `admin:translation_review` (super-admin holds it
- * by default).
  */
 import { z } from 'zod';
 export const listAdminTranslationsToolConfig = {

package/dist/tools/admin-writes.js

@@ -1,22 +1,5 @@
 /**
  * ORB-244 Phase C Group 4 - admin-only tools.
- *
- * These three are listed under "write tools" in the ticket because
- * they're privileged surfaces, but two of them (`list_users`,
- * `get_audit_log`) are read-only - the gating is what makes them
- * "writes" from a permission perspective. `trigger_backup` is the
- * only true mutation.
- *
- * Gating: the API enforces super-admin via the `admin:*` permission
- * slugs. A non-admin's request lands a 403 from the API, which
- * surfaces as OrbotoApiError on the MCP side. The tools themselves
- * don't double-check - that would race against the API anyway. We
- * just rewrite 403 into a clear message.
- *
- * Tools:
- * - orboto_list_users - admin user directory with cursor pagination
- * - orboto_get_audit_log - recent admin / mutation events
- * - orboto_trigger_backup - run a configured backup job by name
  */
 import { z } from 'zod';
 import { OrbotoApiError } from '../orboto-client.js';
@@ -28,9 +11,6 @@ function rewrite403(action) {
         throw err;
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_list_users
-// ---------------------------------------------------------------------------
 export const listUsersToolConfig = {
     title: 'List workspace users (admin)',
     description: 'Return the workspace user directory. Super-admin only. Useful for AI agents that need to look up an email beyond their visible project members (e.g. to assign someone who isn\'t on the current project yet). Imported placeholder users (`*@imported.ghost`) are hidden by default; set `showGhosts=true` to include them.',
@@ -79,9 +59,6 @@ export function makeListUsersHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_get_audit_log
-// ---------------------------------------------------------------------------
 export const getAuditLogToolConfig = {
     title: 'Read the workspace audit log (admin)',
     description: 'Recent audit events - admin actions, role changes, ticket deletions, federation handshakes, etc. Super-admin only. Filter by actor or entity to narrow the window.',
@@ -99,7 +76,6 @@ export function makeGetAuditLogHandler(client) {
         if (entityType)
             qs.set('entityType', entityType);
         if (actorEmail) {
-            // Resolve actor email → userId via the admin users list.
             const userPage = await client.get(`/admin/users?search=${encodeURIComponent(actorEmail)}&limit=10`).catch(rewrite403('audit log lookup'));
             const actor = userPage.items.find((u) => u.email.toLowerCase() === actorEmail.toLowerCase());
             if (!actor)
@@ -111,7 +87,6 @@ export function makeGetAuditLogHandler(client) {
             ? 'No matching audit entries.'
             : page.items.map((e) => {
                 const who = e.actorName ?? e.actorEmail ?? '(system)';
-                // ORB-1368 - mark agent-performed actions.
                 const agentMark = e.isAgentWork ? ' [agent]' : '';
                 const what = e.entityType
                     ? ` ${e.entityType}${e.entityId ? `:${e.entityId.slice(0, 8)}` : ''}`
@@ -134,9 +109,6 @@ export function makeGetAuditLogHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_trigger_backup
-// ---------------------------------------------------------------------------
 export const triggerBackupToolConfig = {
     title: 'Run a configured backup job now (admin)',
     description: 'Manually trigger a backup job by name. Resolves to the job\'s UUID via /admin/backup/jobs and POSTs to the run endpoint. Super-admin only.',

package/dist/tools/admin-writes.test.js

@@ -65,7 +65,6 @@ describe('orboto_get_audit_log', () => {
             { json: { items: [], nextCursor: null } },
         ]);
         await makeGetAuditLogHandler(client)({ actorEmail: 'ada@acme' });
-        // Call 0 = users-search lookup, Call 1 = audit-log with actorId=u1
         expect(calls[0].url).toContain('/admin/users');
         expect(calls[1].url).toContain('actorId=u1');
     });

package/dist/tools/agent-coordination.js

@@ -1,23 +1,13 @@
 /**
  * ORB-705 - MCP coordination tools.
  *
- * Three tools layered on the ORB-704 REST surface:
- *   orboto_agent_heartbeat - wraps POST /v1/agent/heartbeat. Returns
- *     the sessionToken the agent persists for next call.
- *   orboto_agent_presence - wraps GET /v1/agent/presence. Returns
- *     active sessions visible to the caller (own only for non-admin,
- *     workspace-wide for super-admin).
- *   orboto_agent_notify - wraps the existing notification surface
- *     to dispatch a directed message to another agent / user.
- *     Routing target is identified by email (works for both bots and
- *     humans). Fire-and-forget; the recipient sees it via the
- *     standard notifications channel (ORB-706 wires the bridge).
+ * @see ORB-704, ORB-706
  */
 import { z } from 'zod';
 import { mcpInstanceToken } from './shared.js';
 export const agentHeartbeatToolConfig = {
     title: 'Agent heartbeat (Multi-Agent Coordination)',
-    description: 'Register or refresh this agent\'s presence. Call on startup and every ~30 s; rows older than 90 s count as offline. Persist the returned sessionToken and send it on later heartbeats. status: idle (default) | working (+workingOnTicketId) | blocked. capabilities: free-form strings for operator filters. clientInfo.name = the runtime (claude-code, cursor, ...).',
+    description: 'Register or refresh this agent\'s presence with status detail. A live connection already counts as online (an open MCP event stream, `orboto messages --follow`, the agent WebSocket) - the heartbeat adds status: idle (default) | working (+workingOnTicketId) | blocked, capabilities (free-form strings for operator filters) and clientInfo.name (the runtime), and is the only presence path for turn-based clients without a standing connection. Rows older than 90 s count as offline; persist the returned sessionToken and send it on later heartbeats.',
     inputSchema: z.object({
         sessionToken: z.string().nullable().optional(),
         status: z.enum(['idle', 'working', 'blocked']).optional(),
@@ -102,13 +92,8 @@ export const agentNotifyToolConfig = {
         kind: z.enum(['info', 'request', 'complete', 'error']).default('info'),
         subject: z.string().min(1).max(200),
         payload: z.record(z.string(), z.unknown()).optional(),
-        // ORB-1727 - reply chaining: the id of the inbox message being answered.
         threadId: z.string().uuid().optional(),
-        // ORB-1732 - optional project scope: address "the agent working project
-        // X" when the recipient identity runs multiple sessions.
         project: z.string().min(1).max(64).optional().describe('Project key or UUID: scope the message to the recipient session working that project.'),
-        // ORB-1742 - defaults to this MCP session's instance token so a shared
-        // identity never wakes itself with its own outbound mail.
         senderRef: z.string().min(1).max(128).optional().describe('Sender-session ref for self-echo exclusion; defaults to this MCP session.'),
     }).shape,
     outputSchema: z.object({
@@ -117,9 +102,6 @@ export const agentNotifyToolConfig = {
     }).shape,
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
 };
-// ---------------------------------------------------------------------------
-// orboto_agent_broadcast (ORB-964)
-// ---------------------------------------------------------------------------
 export const agentBroadcastToolConfig = {
     title: 'Scoped broadcast to other agents',
     description: 'Fan-out to every agent in a scope: workspace (all internal members), project (members of scopeId = project UUID) or topic (any string). Each recipient gets an inbox copy (orboto_messages, ackable); live subscribers also get a resources/updated push on orboto://broadcast/<scope>/<scope_id>. The scope replay keeps agent_broadcast_retention_days (default 7).',
@@ -146,13 +128,9 @@ export function makeAgentBroadcastHandler(client) {
 }
 export function makeAgentNotifyHandler(client) {
     return async (args, extra) => {
-        // ORB-1742 - stamp the sender session automatically.
         const senderRef = mcpInstanceToken(args.senderRef, extra);
         const res = await client.post('/v1/agent/notify', { ...args, senderRef });
         return {
-            // ORB-1727 - the message is durable now: it reaches the recipient's
-            // inbox even when they are offline (delivery via the pending-mail
-            // pointer on their next tool call).
             content: [{ type: 'text', text: `notified ${args.targetEmail} (message ${res.messageId} - delivered live if connected, waits in their inbox otherwise)` }],
             structuredContent: { ok: true, messageId: res.messageId },
         };

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

@@ -115,8 +115,6 @@ describe('orboto_agent_notify', () => {
         });
         expect(result.content[0].text).toContain('notified bob@example.com');
         expect(result.structuredContent).toMatchObject({ ok: true });
-        // ORB-1742 - the sender session's ref is stamped automatically (per-
-        // process fallback here, since no MCP sessionId rides along).
         expect(capturedBody[0].senderRef).toMatch(/^mcp-/);
     });
     it('ORB-1742: senderRef prefers the per-connection MCP session id, and an explicit ref wins outright', async () => {

package/dist/tools/agent-instructions.js

@@ -6,11 +6,7 @@
  */
 import { z } from 'zod';
 import { sizeBlockResult } from './shared.js';
-// ORB-1819 - the writing contract, verbatim in every write-tool
-// description so the writing agent sees it at the moment of writing.
 const RULE_WRITING_CONTRACT = ' Rule: title = one imperative sentence; body <= 400 chars, Rule / Why / How, no long examples, nothing another block says.';
-// ORB-1700 - a LIST answers "what exists"; the body belongs to the
-// follow-up read (blockId input below). First line, hard-capped.
 function excerptOf(body) {
     const firstLine = body.split('\n', 1)[0] ?? '';
     return firstLine.length > 200 ? `${firstLine.slice(0, 199)}\u2026` : firstLine;
@@ -42,7 +38,6 @@ function scopeQs(scope, projectId, customerId) {
 export function makeListAgentInstructionsHandler(client) {
     return async (input = {}) => {
         const res = await client.get(`/agent-instructions/blocks?${scopeQs(input.scope ?? 'workspace', input.projectId, input.customerId)}`);
-        // ORB-1700 - full body for ONE explicitly named block, in one call.
         if (input.blockId) {
             const block = res.blocks.find((b) => b.id === input.blockId);
             if (!block) {
@@ -57,17 +52,12 @@ export function makeListAgentInstructionsHandler(client) {
                 structuredContent: { block },
             };
         }
-        // ORB-1700 - list = metadata + excerpt. The assembled 24k rule text is
-        // NOT re-shipped here (it rode along on every management call and cost
-        // 238 Mtok over 3 calls); agents load the rules via orboto_session_start.
         const text = res.blocks.length
             ? res.blocks.map(renderBlock).join('\n')
             : 'No rule blocks configured.';
         return {
             content: [{ type: 'text', text }],
             structuredContent: {
-                // Array order = sortOrder; builtinKey only when it is one; the
-                // descriptive TITLE is the excerpt (bodies via blockId).
                 blocks: res.blocks.map((b) => ({
                     id: b.id,
                     title: b.title,

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

@@ -73,8 +73,6 @@ describe('agent-instruction MCP tools (ORB-1089)', () => {
         expect(calls[0]).toMatchObject({ method: 'DELETE', url: `https://orboto.example.com/agent-instructions/blocks/${BLOCK.id}` });
         expect(res.structuredContent).toMatchObject({ deleted: true });
     });
-    // ORB-1819 - the writing-for-tokens size contract, passed through from
-    // the REST route's warn (200 + sizeWarning) / block (422) responses.
     describe('ORB-1819 size contract', () => {
         it('create surfaces a soft-limit sizeWarning in the success text, not as an error', async () => {
             const oversizeBlock = { ...BLOCK, body: 'x'.repeat(450), sizeWarning: { chars: 450, limit: 400, hint: 'move it to a doc' } };

package/dist/tools/agent-messages.js

@@ -16,7 +16,6 @@ export const agentMessagesToolConfig = {
         all: z.boolean().default(false).describe('true = include already-read messages'),
         limit: z.number().int().min(1).max(200).default(50),
         project: z.string().min(1).max(64).optional().describe('Project key or UUID: scoped messages for this project plus unscoped ones. Ack only messages that are yours.'),
-        // ORB-1742 - self-echo exclusion, on by default for MCP sessions.
         includeOwnSends: z.boolean().default(false).describe('true = also list messages this session sent (hidden by default so a shared identity never wakes itself).'),
         ackIds: z.array(z.string().uuid()).max(200).optional().describe('Message ids to mark as read'),
     }).shape,

package/dist/tools/ai-status.js

@@ -1,19 +1,5 @@
 /**
  * ORB-564 - `orboto_ai_status`.
- *
- * Pre-flight check for agents: is the workspace's AI provider configured?
- * Wraps `GET /ai/status`. Two flags come back - chat features and
- * embeddings - because Anthropic-only deployments have chat fully
- * wired but cannot produce embeddings, and RAG-style features
- * (`ask-docs`, similar-tickets rerank, partial-overlap detection)
- * need both.
- *
- * Today no MCP tool requires AI directly - every `orboto_*` tool is a
- * thin REST wrapper that does its own thing. The dependency lives on
- * the skill side (`orboto ask-docs`) and on chat-only LLM calls the
- * agent host might make. This tool exists so an agent can plan around
- * the workspace shape before calling those skill shortcuts or before
- * suggesting AI-gated features to the operator.
  */
 import { z } from 'zod';
 export const aiStatusToolConfig = {

package/dist/tools/ai-usage.js

@@ -1,15 +1,5 @@
 /**
  * ORB-1321 - `orboto_ai_usage`.
- *
- * Operator diagnostic for AI *consumption*: total calls / tokens in+out /
- * errors over a date range, plus per-user, per-operation, and per-day
- * breakdowns and the AI-Chat slice. Wraps GET /admin/ai/usage.
- *
- * Complements the other two AI diagnostics: `orboto_ai_status` says whether AI
- * is configured; `orboto_embedding_status` covers the embedding pipeline's
- * health; this one answers "how much are we spending / how many calls are
- * erroring". Aggregates only (no per-row error text). admin:ai:read gated
- * (403 for non-admin callers).
  */
 import { z } from 'zod';
 export const aiUsageToolConfig = {

package/dist/tools/analytics.js

@@ -25,8 +25,6 @@ export function makeAnalyticsHandler(client) {
         const project = await resolveProjectByKey(client, input.projectKey);
         let milestoneId;
         if (input.milestone && (input.report === 'burndown' || input.report === 'earned-value' || input.report === 'forecast' || input.report === 'collaboration')) {
-            // ORB-1696 - shared resolver: key (ORB-M3), name or UUID, ambiguous
-            // name -> explicit error. Matches create_ticket/set_milestone/OQL.
             const m = await resolveMilestoneByNameOrId(client, project.id, input.milestone);
             milestoneId = m.id;
         }

package/dist/tools/api-call.js

@@ -22,25 +22,13 @@ export const apiCallToolConfig = {
             .describe('Route path, e.g. "/projects/<uuid>/milestones". No query string.'),
         query: z.record(z.union([z.string(), z.number(), z.boolean(), z.array(z.string())])).optional()
             .describe('Query parameters as an object.'),
-        // ORB-1710 - typed union, NOT z.unknown(): a typeless argument is
-        // serialized as a STRING by real MCP clients (the OCP-540 class),
-        // which used to reach the inner route without a JSON content type
-        // and 415. The union renders a typed anyOf so clients send real
-        // JSON; the handler still parses a string arrival as belt-and-braces.
         body: z.union([z.record(z.unknown()), z.array(z.unknown()), z.string(), z.number(), z.boolean()]).optional()
             .describe('JSON body - a real object/array, not a stringified one.'),
     }).shape,
-    // Dispatches arbitrary methods - never advertise as read-only.
-    // ORB-1669 - the escape hatch can issue DELETE through the proxy: destructive by contract.
     annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
 };
 export function makeApiCallHandler(client) {
     return async (input) => {
-        // ORB-1710 - belt-and-braces for clients that still stringify the
-        // body: a string that parses as JSON is un-stringified here, so the
-        // proxy receives real JSON even against an older API without the
-        // server-side coercion. An unparseable string passes through and
-        // gets the proxy's clear 400.
         let body = input.body;
         if (typeof body === 'string') {
             try {

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

@@ -63,7 +63,7 @@ describe('orboto_api_call', () => {
                 },
             }]);
         const res = await makeApiCallHandler(client)({ method: 'POST', path: '/projects/p1/milestones', body: {} });
-        expect(res.isError).toBeUndefined(); // the tool call succeeded; the API said no
+        expect(res.isError).toBeUndefined();
         const text = res.content[0].text;
         expect(text).toContain('HTTP 403');
         expect(text).toMatch(/missing permission/i);
@@ -77,7 +77,6 @@ describe('orboto_api_call', () => {
             path: '/docs/abc/append-section',
             body: '{"content":"# heading"}',
         });
-        // The proxy must receive real JSON, not a double-encoded string.
         expect(calls[0].body.body).toEqual({ content: '# heading' });
     });
     it('passes an unparseable string body through for the proxy\'s clear 400', async () => {

package/dist/tools/api-search.js

@@ -2,12 +2,7 @@
  * ORB-1518 - `orboto_api_search`: the discovery half of the Code-Mode
  * escape hatch (epic ORB-1517).
  *
- * Wraps the authenticated `GET /system/api-catalog` routes, which search
- * the live OpenAPI spec server-side. Lets an agent find any REST
- * endpoint + its schema on demand instead of needing a named MCP tool
- * per endpoint - the long tail of the API stays reachable even on a
- * curated (small) tool manifest. Execute the endpoint you found with
- * `orboto_api_call` (ORB-1519).
+ * @see ORB-1519
  */
 import { z } from 'zod';
 export const apiSearchToolConfig = {

package/dist/tools/approvals.js

@@ -12,9 +12,6 @@ import { resolveTicketByKey } from './shared.js';
 function fmt(r) {
     return `  ${r.id} → "${r.toStatusName}" [${r.status}] ${r.approveCount}/${r.requiredApprovals} approvals (${r.policyName})${r.canApprove ? ' - you can vote' : ''}`;
 }
-// ---------------------------------------------------------------------------
-// orboto_list_approvals
-// ---------------------------------------------------------------------------
 export const listApprovalsToolConfig = {
     title: 'List a ticket\'s approval / sign-off requests',
     description: 'List the approval / sign-off requests on a ticket (generic change-management gates on status transitions). Shows each request\'s target status, mode, approval progress, and whether YOU can vote on it right now. Use this before `orboto_approval_decide`.',
@@ -33,9 +30,6 @@ export function makeListApprovalsHandler(client) {
         return { content: [{ type: 'text', text }], structuredContent: { ticketKey: ticket.ticketKey, requests: rows } };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_approval_decide
-// ---------------------------------------------------------------------------
 export const approvalDecideToolConfig = {
     title: 'Approve or reject a ticket sign-off request',
     description: 'Cast an approve/reject vote on a pending approval / sign-off request that gates a ticket status transition. You must be an eligible approver (a policy role, a named user, or a RACI role on the ticket) - otherwise the API returns 403. A single reject resolves the request; enough approvals unblock the transition (the requester then re-applies the status move). If the ticket has several pending requests, pass `requestId`.',

package/dist/tools/attach.js

@@ -1,23 +1,5 @@
 /**
  * ORB-799 - attach files to a ticket.
- *
- * Mirrors `orboto.mjs attach <ticket> <path...> [--alt "text"] [--embed]`.
- *
- * MCP-side, the model doesn't have local FS access, so the bytes come
- * over the wire as a base64 `contentBase64` field - same approach as
- * `orboto_ingest_file`. To keep the surface simple, this tool uploads
- * one file per call; the wrapper's multi-file shorthand is unrolled
- * into N tool calls on the agent side.
- *
- * Two modes, controlled by `embed`:
- *
- *   - embed=false (default): upload only, return the markdown image
- *     line + raw URL. The agent typically uses this to compose a
- *     follow-up `orboto_comment` body.
- *   - embed=true: upload, then PATCH the ticket's description to
- *     append the markdown image at the end. Idempotent only up to
- *     duplicate detection (re-running with the same file *does*
- *     append a fresh line; the API doesn't dedupe).
  */
 import { z } from 'zod';
 import { resolveTicketByKey } from './shared.js';
@@ -57,11 +39,6 @@ export function makeAttachToTicketHandler(client) {
     return async ({ ticketKey, filename, contentBase64, altText, embed }) => {
         let arrayBuffer;
         try {
-            // Buffer → fresh ArrayBuffer copy. The Blob ctor's BlobPart type
-            // wants `ArrayBufferView<ArrayBuffer>` and Node @types reject a
-            // raw Buffer / Uint8Array because their backing buffer is the
-            // wider `ArrayBufferLike`. Copying the bytes into a fresh
-            // ArrayBuffer satisfies the constraint without losing data.
             const buf = Buffer.from(contentBase64, 'base64');
             arrayBuffer = new ArrayBuffer(buf.byteLength);
             new Uint8Array(arrayBuffer).set(buf);
@@ -80,8 +57,6 @@ export function makeAttachToTicketHandler(client) {
         const markdown = `![${alt}](${att.downloadUrl})`;
         let embedded = false;
         if (embed === true) {
-            // Read the current description first - the PATCH replaces, not
-            // appends, so we have to construct the new body.
             const current = await client.get(`/projects/${ticket.projectId}/tickets/${ticket.id}`);
             const existing = current.description ?? '';
             const next = existing ? `${existing}\n\n${markdown}` : markdown;

package/dist/tools/backup.js

@@ -9,9 +9,6 @@
  */
 import { z } from 'zod';
 const mb = (n) => `${Math.round((n / 1024 / 1024) * 10) / 10} MB`;
-// ---------------------------------------------------------------------------
-// orboto_create_full_backup
-// ---------------------------------------------------------------------------
 export const createFullBackupToolConfig = {
     title: 'Create + download a full workspace backup',
     description: 'Create an on-demand FULL workspace backup (database + storage) and return the ZIP as a base64 application/zip resource attachment - create, wait and download in one call (the server runs the export as a background run and this tool polls it; large workspaces can take minutes). Rows and file references share one snapshot; missing or incomplete files fail the run, never return a partial ZIP. Requires admin:backup:export. For the scheduled named jobs use orboto_trigger_backup instead.',
@@ -20,10 +17,6 @@ export const createFullBackupToolConfig = {
 };
 export function makeCreateFullBackupHandler(client) {
     return async () => {
-        // ORB-1717 - the export is async server-side (the old synchronous
-        // stream aborted silently under load). Enqueue, poll the run row to a
-        // terminal state, then download the stored artifact - so an aborted
-        // wait never yields a partial ZIP.
         const { runId } = await client.post('/admin/backup/full', {});
         const t0 = Date.now();
         for (;;) {
@@ -47,9 +40,6 @@ export function makeCreateFullBackupHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_list_backups
-// ---------------------------------------------------------------------------
 export const listBackupsToolConfig = {
     title: 'List backup runs',
     description: 'List recent backup runs (id, status, size, time) so you can pick one to download with orboto_download_backup. Requires admin:backup:read.',
@@ -67,9 +57,6 @@ export function makeListBackupsHandler(client) {
         };
     };
 }
-// ---------------------------------------------------------------------------
-// orboto_download_backup
-// ---------------------------------------------------------------------------
 export const downloadBackupToolConfig = {
     title: 'Download a stored backup run',
     description: 'Download a stored backup run\'s ZIP by run id (from orboto_list_backups - e.g. the nightly job\'s run) as a base64 application/zip resource attachment. Requires admin:backup:read.',

package/dist/tools/backup.test.js

@@ -37,7 +37,7 @@ function stubJson(body) {
 describe('orboto_create_full_backup (ORB-1301 / async since ORB-1717)', () => {
     it('enqueues, polls the run to success, then downloads the stored ZIP', async () => {
         vi.useFakeTimers();
-        const zip = new Uint8Array([0x50, 0x4b, 0x03, 0x04]); // PK\x03\x04
+        const zip = new Uint8Array([0x50, 0x4b, 0x03, 0x04]);
         const calls = [];
         let polls = 0;
         vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
@@ -49,7 +49,6 @@ describe('orboto_create_full_backup (ORB-1301 / async since ORB-1717)', () => {
             if (u.includes('/admin/backup/runs/run-1/download')) {
                 return { ok: true, status: 200, statusText: 'OK', headers: new Headers({ 'content-type': 'application/zip' }), arrayBuffer: async () => zip.buffer.slice(0), text: async () => '' };
             }
-            // poll: running twice, then success
             polls += 1;
             return { ok: true, status: 200, statusText: 'OK', headers: new Headers({ 'content-type': 'application/json' }), json: async () => ({ status: polls < 3 ? 'running' : 'success', errorMessage: null }), text: async () => '' };
         });