@orboto/mcp 0.192.0 → 0.194.0

package/dist/with-metrics.js

@@ -33,10 +33,6 @@ function formatApiError(err) {
                                 : 'Request rejected.';
     return `orboto API error ${err.status}. ${hint}\nDetail: ${detail || '(no message)'}`;
 }
-// ORB-1817 - McpLogEntry / redactSecrets / postLogEntry live in
-// mcp-instrument.ts (a leaf module) so input-schema.ts can log validation
-// failures through the same instrument path without an import cycle
-// (this file already imports FROM input-schema.ts).
 /**
  * Wrap a CallToolResult-returning handler so every invocation posts
  * one row to mcp_call_log via /admin/mcp/instrument.
@@ -46,27 +42,10 @@ function formatApiError(err) {
  * Wired centrally in `server.ts` so per-tool files don't need to
  * know about instrumentation.
  */
-export function withMetrics(client, toolName, clientHint, 
-// ORB-1252 - forward the SDK's `extra` (RequestHandlerExtra) so handlers can
-// read the per-connection MCP sessionId (distinct per HTTP client even on a
-// shared server). Backward-compatible: handlers that ignore it are unaffected.
-handler, 
-// ORB-1331 - per-session/-process nudge state. When present, the first
-// tool dispatch that is not `orboto_session_start` gets the one-time
-// reminder prepended to its response. Optional so direct callers/tests
-// that don't care are unaffected.
-nudge) {
+export function withMetrics(client, toolName, clientHint, handler, nudge) {
     return async (args, extra) => {
         const start = Date.now();
-        // ORB-1331 - decide (and advance the flag) once per dispatch, before
-        // the handler runs, so the "first tool call" is the first dispatch
-        // 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` 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.
         if (nudge && shouldGate(nudge, toolName)) {
             const gated = gateResult();
             void postLogEntry(client, {
@@ -80,17 +59,8 @@ nudge) {
         }
         try {
             const handlerResult = await handler(args, extra);
-            // ORB-1697 - the central response budget. Applied HERE, once, so it
-            // covers every registered tool instead of relying on 168 handlers to
-            // each stay small. Over-budget payloads come back truncated with an
-            // explicit `__truncation` block + a handle for the remainder; the
-            // measured sizes go into the call log either way.
             const budgeted = applyResponseBudget(toolName, handlerResult);
             const result = budgeted.result;
-            // Success path - but the handler can also signal a "soft"
-            // failure via { isError: true } in the result. We treat that
-            // as success=false in the log so dashboards reflect actual
-            // user-visible failures.
             const isError = result.isError === true;
             if (nudge)
                 recordSessionStartResult(nudge, toolName, !isError);
@@ -105,11 +75,6 @@ nudge) {
                 responseChars: budgeted.responseChars,
                 truncatedChars: budgeted.truncatedChars,
             });
-            // ORB-1727 - agent-mail piggyback: the client captured the api's
-            // `x-orboto-agent-mail` header on the request this tool just made.
-            // Append a compact pointer while mail is pending - zero bytes when
-            // the inbox is empty, and never on the messages tool itself (the
-            // caller is already fetching).
             const withMail = appendMailNudge(client, toolName, result);
             return wantsNudge ? prependNudge(withMail) : withMail;
         }
@@ -121,20 +86,12 @@ nudge) {
                 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
-            // runtime's opaque "Error occurred during tool execution".
             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 });
-                // Still surface the reminder alongside the actionable error so a
-                // first-call failure doesn't swallow the one-time nudge.
                 const errResult = { isError: true, content: [{ type: 'text', text }] };
                 return wantsNudge ? prependNudge(errResult) : errResult;
             }
-            // Anything else is unexpected (a bug, not an API rejection) - log
-            // and re-throw so it surfaces loudly rather than being swallowed.
             void postLogEntry(client, {
                 toolName,
                 durationMs,
@@ -163,52 +120,23 @@ nudge) {
 export function appendMailNudge(client, toolName, result) {
     if (!client.pendingAgentMail || toolName === 'orboto_messages')
         return result;
-    // ORB-1733: the nudge lives ONLY in a text content block. Never touch
-    // structuredContent - the SDK validates it against the tool's declared
-    // outputSchema, and an injected extra key fails validation and errors
-    // the entire tool call for as long as mail sits unread.
     const line = `You have ${client.pendingAgentMail} unread agent message(s) - fetch them with orboto_messages.`;
     return {
         ...result,
         content: [...result.content, { type: 'text', text: line }],
     };
 }
-export function registerWithMetrics(server, client, clientHint, 
-// ORB-1331 - shared per-session/-process nudge state. Every tool
-// registered through this closure reads/advances the same flag, so the
-// one-time session-start reminder fires on whichever tool is called
-// first (unless it is `orboto_session_start`).
-nudge) {
+export function registerWithMetrics(server, client, clientHint, nudge) {
     return (toolName, config, handler) => {
-        // ORB-1692 - every raw-shape input becomes strict + alias-resolving.
-        // Central here so a new tool cannot ship permissive; empty/absent
-        // shapes stay untouched (they carry no fields to guard).
         let cfg = config?.inputSchema && isRawShape(config.inputSchema)
-            // ORB-1817 - `client` + `clientHint` let a validation failure log
-            // through the same instrument path as a handler error (Part C):
-            // the SDK validates BEFORE this handler wrapper ever runs, so this
-            // is the only place that sees the failure.
             ? { ...config, inputSchema: buildStrictInputSchema(toolName, config.inputSchema, client, clientHint) }
             : config;
-        // ORB-1738 - every declared output shape ADVERTISES the response
-        // budget's optional __truncation marker. The SDK emits
-        // additionalProperties:false for output schemas, and strict clients
-        // validate structuredContent against that - an over-budget response
-        // carrying the (undeclared) marker was rejected wholesale
-        // (list_projects failed on EVERY call). Same central place as the
-        // input fix so no tool can ship an outputSchema that fights the
-        // budget layer.
         if (cfg?.outputSchema && isRawShape(cfg.outputSchema)) {
             cfg = {
                 ...cfg,
-                // ORB-1805 - the ADVERTISED (compact, open) form; the exact
-                // shape stays TruncationBlockSchema for runtime assertions.
                 outputSchema: { ...cfg.outputSchema, __truncation: TruncationBlockAdvertisedSchema.optional() },
             };
         }
-        // ORB-1741 - manifest diet: the wire manifest carries a one-sentence
-        // summary; the full guidance is captured for orboto_help. Central
-        // here so a new tool cannot ship a manifest essay by accident.
         if (typeof cfg?.description === 'string' && cfg.description.length > 0) {
             captureToolDoc(toolName, cfg.description);
             cfg = { ...cfg, description: summarizeToolDescription(toolName, cfg.description) };

package/dist/with-metrics.test.js

@@ -37,7 +37,6 @@ describe('withMetrics', () => {
         }));
         const result = await wrapped({});
         expect(result.content[0]).toEqual({ type: 'text', text: 'ok' });
-        // Wait one microtask so the fire-and-forget POST resolves.
         await new Promise((r) => setImmediate(r));
         expect(calls).toHaveLength(1);
         expect(calls[0].url).toContain('/admin/mcp/instrument');
@@ -57,8 +56,6 @@ describe('withMetrics', () => {
         expect(body.success).toBe(false);
         expect(body.errorMessage).toBe('kaboom');
     });
-    // ORB-1174 - an OrbotoApiError becomes a structured, actionable isError
-    // result (not the runtime's opaque generic) so the agent can self-correct.
     it('maps OrbotoApiError to a distinct, actionable isError result per status', async () => {
         captureFetch();
         const run = async (status, body) => {
@@ -72,14 +69,13 @@ describe('withMetrics', () => {
         const unauth = await run(401, '{"error":"Invalid API key"}');
         expect(unauth).toContain('401');
         expect(unauth).toMatch(/re-?authenticate/i);
-        expect(unauth).toContain('Invalid API key'); // the API's own message
+        expect(unauth).toContain('Invalid API key');
         const notFound = await run(404, '{"error":"Ticket not found"}');
         expect(notFound).toContain('404');
         expect(notFound).toMatch(/not found/i);
         const server = await run(503, 'upstream down');
         expect(server).toContain('503');
         expect(server).toMatch(/retry/i);
-        // distinct messages, not the same opaque blob
         expect(unauth).not.toBe(notFound);
         expect(notFound).not.toBe(server);
     });
@@ -107,10 +103,6 @@ describe('withMetrics', () => {
         expect(body.clientHint).toBe('cursor');
     });
     it('does not block when the instrument POST fails - handler still resolves', async () => {
-        // First call (the handler-as-fetch?) returns ok; but our handler
-        // doesn't fetch; the only fetch the wrapper makes is to /instrument.
-        // Mock that one to fail - caller must still get the original
-        // result back.
         vi.spyOn(globalThis, 'fetch').mockImplementation(async () => ({
             ok: false, status: 500, statusText: 'Server Error',
             json: async () => ({ error: 'kaboom' }),
@@ -122,8 +114,6 @@ describe('withMetrics', () => {
         const result = await wrapped({});
         expect(result.content[0]).toEqual({ type: 'text', text: 'survives' });
     });
-    // ORB-1180 - admin-panel visibility: the failure log carries the
-    // structured HTTP status, and any secret-shaped text is redacted.
     it('logs the structured statusCode on an OrbotoApiError', async () => {
         const calls = captureFetch();
         const wrapped = withMetrics(client, 'orboto_x', undefined, async () => {
@@ -136,10 +126,6 @@ describe('withMetrics', () => {
         expect(body.statusCode).toBe(403);
         expect(body.errorMessage).toContain('403');
     });
-    // ORB-1331 - the shared nudge state threads through the wrapper: the
-    // first non-session_start dispatch carries the one-time reminder,
-    // later dispatches are clean, and a session_start-first flow never
-    // sees it. structuredContent is left intact.
     it('prepends the session-start nudge on the first non-session_start dispatch, once', async () => {
         captureFetch();
         const nudge = createNudgeState();
@@ -151,9 +137,9 @@ describe('withMetrics', () => {
         const first = await list({});
         expect(first.content[0].text).toBe(SESSION_START_NUDGE);
         expect(first.content[1].text).toBe('ok');
-        expect(first.structuredContent).toEqual({ a: 1 }); // untouched
+        expect(first.structuredContent).toEqual({ a: 1 });
         const second = await list({});
-        expect(second.content[0].text).toBe('ok'); // clean
+        expect(second.content[0].text).toBe('ok');
     });
     it('does not nudge when the first dispatch IS orboto_session_start', async () => {
         captureFetch();
@@ -162,9 +148,9 @@ describe('withMetrics', () => {
         const start = withMetrics(client, 'orboto_session_start', undefined, handler, nudge);
         const list = withMetrics(client, 'orboto_list_projects', undefined, handler, nudge);
         const first = await start({});
-        expect(first.content[0].text).toBe('rules'); // no nudge
+        expect(first.content[0].text).toBe('rules');
         const second = await list({});
-        expect(second.content[0].text).toBe('rules'); // still clean
+        expect(second.content[0].text).toBe('rules');
     });
     it('surfaces the nudge alongside an OrbotoApiError on a first-call failure', async () => {
         captureFetch();
@@ -177,18 +163,13 @@ describe('withMetrics', () => {
         expect(res.content[0].text).toBe(SESSION_START_NUDGE);
         expect(res.content[1].text).toContain('403');
     });
-    // ORB-1471 - the HARD session-start gate. When the workspace requires it,
-    // the wrapper REFUSES a non-session-start tool without running its handler,
-    // returns the instructive gate message, and logs the refusal. A
-    // session_start call unlocks the session; after that everything runs.
     it('gates a non-session-start tool until session_start runs, without invoking the handler', async () => {
         const calls = captureFetch();
-        const nudge = createNudgeState(true); // gate ON
+        const nudge = createNudgeState(true);
         const listHandler = vi.fn(async () => ({ content: [{ type: 'text', text: 'projects' }] }));
         const startHandler = vi.fn(async () => ({ content: [{ type: 'text', text: 'rules' }] }));
         const list = withMetrics(client, 'orboto_list_projects', undefined, listHandler, nudge);
         const start = withMetrics(client, 'orboto_session_start', undefined, startHandler, nudge);
-        // First call is refused - handler never runs.
         const refused = await list({});
         expect(refused.isError).toBe(true);
         expect(refused.content[0].text).toBe(SESSION_START_GATE_MESSAGE);
@@ -196,22 +177,19 @@ describe('withMetrics', () => {
         await new Promise((r) => setImmediate(r));
         const gateLog = calls.find((c) => c.body?.errorMessage?.includes('session-start gate'));
         expect(gateLog).toBeDefined();
-        // Running session_start unlocks the session.
         const rules = await start({});
         expect(rules.content[0].text).toBe('rules');
         expect(startHandler).toHaveBeenCalledTimes(1);
-        // Now the previously-gated tool runs normally.
         const ok = await list({});
         expect(ok.content[0].text).toBe('projects');
         expect(listHandler).toHaveBeenCalledTimes(1);
     });
     it('does not gate anything when the gate is disabled (default)', async () => {
         captureFetch();
-        const nudge = createNudgeState(); // gate OFF
+        const nudge = createNudgeState();
         const handler = vi.fn(async () => ({ content: [{ type: 'text', text: 'ok' }] }));
         const list = withMetrics(client, 'orboto_list_projects', undefined, handler, nudge);
         const res = await list({});
-        // Still nudged (soft), but NOT refused - the handler ran.
         expect(res.content[1].text).toBe('ok');
         expect(handler).toHaveBeenCalledTimes(1);
     });

package/package.json

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