@nestr/mcp 0.1.71 → 0.1.73

package/build/tools/index.d.ts

@@ -4,6 +4,7 @@
  */
 import { z } from "zod";
 import { type NestrClient } from "../api/client.js";
+import type { DiagnoseSnapshot } from "../util/diagnose.js";
 type CompletableSource = "inbox" | "daily-plan" | "children" | "projects" | "search";
 export declare function completableResponse(data: unknown, source: CompletableSource, title: string): {
     title: string;
@@ -946,6 +947,7 @@ export declare const schemas: {
     }, {
         topic: string;
     }>;
+    diagnose: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
 };
 export declare const toolDefinitions: ({
     annotations: {
@@ -1027,6 +1029,83 @@ export declare const toolDefinitions: ({
         };
         required: string[];
     };
+} | {
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+    };
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            topic?: undefined;
+            search?: undefined;
+            limit?: undefined;
+            page?: undefined;
+            stripDescription?: undefined;
+            workspaceId?: undefined;
+            title?: undefined;
+            purpose?: undefined;
+            type?: undefined;
+            governance?: undefined;
+            plan?: undefined;
+            apps?: undefined;
+            layout?: undefined;
+            query?: undefined;
+            _listTitle?: undefined;
+            nestId?: undefined;
+            fieldsMetaData?: undefined;
+            hints?: undefined;
+            parentId?: undefined;
+            description?: undefined;
+            labels?: undefined;
+            fields?: undefined;
+            users?: undefined;
+            accountabilities?: undefined;
+            domains?: undefined;
+            data?: undefined;
+            due?: undefined;
+            completed?: undefined;
+            body?: undefined;
+            commentId?: undefined;
+            circleId?: undefined;
+            includeSubCircles?: undefined;
+            userId?: undefined;
+            endDate?: undefined;
+            metricId?: undefined;
+            depth?: undefined;
+            username?: undefined;
+            fullName?: undefined;
+            language?: undefined;
+            labelId?: undefined;
+            from?: undefined;
+            to?: undefined;
+            completedAfter?: undefined;
+            nestIds?: undefined;
+            position?: undefined;
+            relatedNestId?: undefined;
+            color?: undefined;
+            icon?: undefined;
+            fullWorkspaces?: undefined;
+            context?: undefined;
+            skip?: undefined;
+            showRead?: undefined;
+            group?: undefined;
+            feeling?: undefined;
+            needs?: undefined;
+            tensionId?: undefined;
+            order?: undefined;
+            _id?: undefined;
+            partId?: undefined;
+            childId?: undefined;
+            status?: undefined;
+            relation?: undefined;
+            direction?: undefined;
+            targetId?: undefined;
+        };
+        required?: undefined;
+    };
 } | {
     annotations: {
         readOnlyHint: boolean;
@@ -3814,83 +3893,6 @@ export declare const toolDefinitions: ({
         };
         required: string[];
     };
-} | {
-    annotations: {
-        readOnlyHint: boolean;
-        destructiveHint: boolean;
-    };
-    name: string;
-    description: string;
-    inputSchema: {
-        type: "object";
-        properties: {
-            topic?: undefined;
-            search?: undefined;
-            limit?: undefined;
-            page?: undefined;
-            stripDescription?: undefined;
-            workspaceId?: undefined;
-            title?: undefined;
-            purpose?: undefined;
-            type?: undefined;
-            governance?: undefined;
-            plan?: undefined;
-            apps?: undefined;
-            layout?: undefined;
-            query?: undefined;
-            _listTitle?: undefined;
-            nestId?: undefined;
-            fieldsMetaData?: undefined;
-            hints?: undefined;
-            parentId?: undefined;
-            description?: undefined;
-            labels?: undefined;
-            fields?: undefined;
-            users?: undefined;
-            accountabilities?: undefined;
-            domains?: undefined;
-            data?: undefined;
-            due?: undefined;
-            completed?: undefined;
-            body?: undefined;
-            commentId?: undefined;
-            circleId?: undefined;
-            includeSubCircles?: undefined;
-            userId?: undefined;
-            endDate?: undefined;
-            metricId?: undefined;
-            depth?: undefined;
-            username?: undefined;
-            fullName?: undefined;
-            language?: undefined;
-            labelId?: undefined;
-            from?: undefined;
-            to?: undefined;
-            completedAfter?: undefined;
-            nestIds?: undefined;
-            position?: undefined;
-            relatedNestId?: undefined;
-            color?: undefined;
-            icon?: undefined;
-            fullWorkspaces?: undefined;
-            context?: undefined;
-            skip?: undefined;
-            showRead?: undefined;
-            group?: undefined;
-            feeling?: undefined;
-            needs?: undefined;
-            tensionId?: undefined;
-            order?: undefined;
-            _id?: undefined;
-            partId?: undefined;
-            childId?: undefined;
-            status?: undefined;
-            relation?: undefined;
-            direction?: undefined;
-            targetId?: undefined;
-        };
-        required?: undefined;
-    };
 } | {
     annotations: {
         readOnlyHint: boolean;
@@ -5804,6 +5806,14 @@ export type ToolResult = {
 };
 export declare function stripDescriptionFields(data: unknown): unknown;
 export declare function unescapeRichTextFields(args: Record<string, unknown>): Record<string, unknown>;
-export declare function handleToolCall(client: NestrClient, name: string, args: Record<string, unknown>): Promise<ToolResult>;
+/**
+ * Per-tool-call context. Carries session-level info that diagnose-style
+ * tools need but ordinary tools don't. Optional so tests/callers that don't
+ * have a session (CLI, stdio mode) can still call handleToolCall.
+ */
+export interface ToolCallContext {
+    getDiagnose?: () => DiagnoseSnapshot;
+}
+export declare function handleToolCall(client: NestrClient, name: string, args: Record<string, unknown>, context?: ToolCallContext): Promise<ToolResult>;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/build/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAiB,KAAK,WAAW,EAA6C,MAAM,kBAAkB,CAAC;AAS9G,KAAK,iBAAiB,GAAG,OAAO,GAAG,YAAY,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAGrF,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,GACZ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,OAAO,EAAE,CAAA;CAAE,CAWhE;AAeD,wBAAgB,eAAe,CAAC,CAAC,EAC/B,IAAI,EAAE,CAAC,EAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,CAAC,EAAE,CAAA;CAAE,GAAG,CAAC,EAC7D,IAAI,GAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAgB,GAChD,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,CAAA;CAAE,GAAG,CAAC,CA+B3E;AA2CD,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAyCzC;AAaD,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgbnB,CAAC;AAQF,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA0iC3B,CAAC;AAGF,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAGF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAiB7D;AAgBD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgB7F;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,UAAU,CAAC,CAerB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAmC,KAAK,WAAW,EAA6C,MAAM,kBAAkB,CAAC;AAIhI,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAQ5D,KAAK,iBAAiB,GAAG,OAAO,GAAG,YAAY,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAGrF,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,GACZ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,OAAO,EAAE,CAAA;CAAE,CAWhE;AAeD,wBAAgB,eAAe,CAAC,CAAC,EAC/B,IAAI,EAAE,CAAC,EAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,CAAC,EAAE,CAAA;CAAE,GAAG,CAAC,EAC7D,IAAI,GAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAgB,GAChD,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,CAAA;CAAE,GAAG,CAAC,CA+B3E;AA2CD,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAyCzC;AAaD,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkbnB,CAAC;AAQF,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAojC3B,CAAC;AAGF,MAAM,MAAM,UAAU,GAAG;IACvB,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAGF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAiB7D;AAgBD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgB7F;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,MAAM,gBAAgB,CAAC;CACtC;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,UAAU,CAAC,CAerB"}

package/build/tools/index.js

@@ -5,6 +5,8 @@
 import { z } from "zod";
 import { NestrApiError } from "../api/client.js";
 import { appResources } from "../apps/index.js";
+import { getCorrelationId } from "../util/request-context.js";
+import { VERSION } from "../version.js";
 // MCP Apps UI metadata for tools that can render in the completable list app.
 // IMPORTANT: Only use for completable items (tasks, projects, todos, inbox items).
 // Do NOT use for structural nests like roles, circles, metrics, policies, etc.
@@ -509,6 +511,7 @@ export const schemas = {
     help: z.object({
         topic: z.string().describe("Topic key (e.g., 'search', 'labels', 'tensions'). Use 'topics' for the full list."),
     }),
+    diagnose: z.object({}).describe("No arguments — diagnose reads session state from the server."),
 };
 // Tool annotations for MCP - hints for clients on tool behavior
 const readOnly = { annotations: { readOnlyHint: true, destructiveHint: false } };
@@ -518,7 +521,7 @@ const destructive = { annotations: { readOnlyHint: false, destructiveHint: true
 export const toolDefinitions = [
     {
         name: "nestr_help",
-        description: "Get detailed Nestr documentation by topic. Call before unfamiliar operations. Topics: search, labels, nest-model, inbox, daily-plan, notifications, insights, tension-processing, skills, mcp-apps, authentication, and more. Use topic 'topics' for the full list.",
+        description: "Get detailed Nestr documentation by topic. Call before unfamiliar operations. Topics: search, labels, nest-model, inbox, daily-plan, notifications, insights, tension-processing, skills, mcp-apps, authentication, and more. Use topic 'topics' for the full list. Auth: none required.",
         inputSchema: {
             type: "object",
             properties: {
@@ -528,6 +531,15 @@ export const toolDefinitions = [
         },
         ...readOnly,
     },
+    {
+        name: "nestr_diagnose",
+        description: "Server-side auth and session diagnostics. Call this FIRST when any other tool returns an auth error (AUTH_TOKEN_REJECTED_BY_NESTR / AUTH_REFRESH_FAILED / AUTH_SCOPE_INSUFFICIENT / AUTH_PROXY_HEADER_DROPPED). Returns: flow (A=server-managed refresh, B=client-managed refresh, unknown=API key), tokenPresented, tokenFingerprint, lastUpstream401At, lastRefreshAttempt, sessionCorrelationId, serverVersion, mcpClient, mcpClientVersion. Auth: none required — works whether or not the bearer is valid.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+        ...readOnly,
+    },
     {
         name: "nestr_list_workspaces",
         description: "List workspaces. Prefer nestr_get_me with fullWorkspaces:true at session start. Paginated with meta.total.",
@@ -557,7 +569,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_create_workspace",
-        description: "Create a new workspace. OAuth only. See nestr_help('workspace-setup') for guided setup.",
+        description: "Create a new workspace. Auth: OAuth only (user-scoped — workspace API keys cannot create new workspaces). On auth failure call nestr_diagnose. See nestr_help('workspace-setup') for guided setup.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1016,7 +1028,7 @@ export const toolDefinitions = [
     // Inbox tools (require OAuth token - won't work with workspace API keys)
     {
         name: "nestr_list_inbox",
-        description: "List items in the user's personal inbox. Spans all workspaces. OAuth only.",
+        description: "List items in the user's personal inbox. Spans all workspaces. Auth: OAuth only (user-scoped — workspace API keys lack user identity). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1029,7 +1041,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_create_inbox_item",
-        description: "Quick capture: add an item to the inbox for later processing. OAuth only.",
+        description: "Quick capture: add an item to the inbox for later processing. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1042,7 +1054,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_get_inbox_item",
-        description: "Get details of a specific inbox item. Requires OAuth token.",
+        description: "Get details of a specific inbox item. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1055,7 +1067,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_update_inbox_item",
-        description: "Update an inbox item. Set completed:true when processed. Use nestr_update_nest with parentId to move out of inbox. OAuth only.",
+        description: "Update an inbox item. Set completed:true when processed. Use nestr_update_nest with parentId to move out of inbox. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1071,7 +1083,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_reorder_inbox",
-        description: "Reorder inbox items. Provide a subset of IDs — they go to the top in given order, rest unchanged. OAuth only.",
+        description: "Reorder inbox items. Provide a subset of IDs — they go to the top in given order, rest unchanged. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1087,7 +1099,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_reorder_inbox_item",
-        description: "Reorder a single inbox item by positioning it before or after another inbox item. Requires OAuth token.",
+        description: "Reorder a single inbox item by positioning it before or after another inbox item. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1102,7 +1114,7 @@ export const toolDefinitions = [
     // Personal labels (require OAuth token - user's own labels, not workspace labels)
     {
         name: "nestr_list_personal_labels",
-        description: "List the current user's personal labels (not workspace labels). OAuth only.",
+        description: "List the current user's personal labels (not workspace labels). Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {},
@@ -1111,7 +1123,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_create_personal_label",
-        description: "Create a personal label. Can be used across workspaces. OAuth only.",
+        description: "Create a personal label. Can be used across workspaces. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1159,7 +1171,7 @@ export const toolDefinitions = [
     // Daily plan (requires OAuth token)
     {
         name: "nestr_get_daily_plan",
-        description: "Get the user's daily plan — items marked for today. Spans all workspaces. OAuth only.",
+        description: "Get the user's daily plan — items marked for today. Spans all workspaces. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1198,7 +1210,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_add_to_daily_plan",
-        description: "Add one or more items to the daily plan by applying the 'now' label. Requires OAuth token.",
+        description: "Add one or more items to the daily plan by applying the 'now' label. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1214,7 +1226,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_remove_from_daily_plan",
-        description: "Remove one or more items from the daily plan by removing the 'now' label. Requires OAuth token.",
+        description: "Remove one or more items from the daily plan by removing the 'now' label. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1243,7 +1255,7 @@ export const toolDefinitions = [
     // User tension tools (requires OAuth token)
     {
         name: "nestr_list_my_tensions",
-        description: "List tensions created by or assigned to the current user. Check at session start and natural breakpoints. OAuth only.",
+        description: "List tensions created by or assigned to the current user. Check at session start and natural breakpoints. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1254,7 +1266,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_list_tensions_awaiting_consent",
-        description: "List tensions awaiting the current user's consent vote. Check proactively. OAuth only.",
+        description: "List tensions awaiting the current user's consent vote. Check proactively. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1266,7 +1278,7 @@ export const toolDefinitions = [
     // Notification tools (requires OAuth token)
     {
         name: "nestr_list_notifications",
-        description: "List notifications. Use type 'me' for direct (mentions, replies) or 'relevant' for organizational changes. OAuth only.",
+        description: "List notifications. Use type 'me' for direct (mentions, replies) or 'relevant' for organizational changes. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1281,7 +1293,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_mark_notifications_read",
-        description: "Mark all unread in-app notifications as read for the current user. Returns { status, data: { markedCount } }. Requires OAuth token.",
+        description: "Mark all unread in-app notifications as read for the current user. Returns { status, data: { markedCount } }. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {},
@@ -1630,10 +1642,10 @@ export function unescapeRichTextFields(args) {
     }
     return changed ? result : args;
 }
-export async function handleToolCall(client, name, args) {
+export async function handleToolCall(client, name, args, context) {
     const sanitizedArgs = unescapeRichTextFields(args);
     const shouldStripDescription = sanitizedArgs.stripDescription === true;
-    const result = await _handleToolCall(client, name, sanitizedArgs);
+    const result = await _handleToolCall(client, name, sanitizedArgs, context);
     if (shouldStripDescription && !result.isError) {
         try {
             const parsed = JSON.parse(result.content[0].text);
@@ -1645,7 +1657,7 @@ export async function handleToolCall(client, name, args) {
     }
     return result;
 }
-async function _handleToolCall(client, name, args) {
+async function _handleToolCall(client, name, args, context) {
     try {
         switch (name) {
             case "nestr_help": {
@@ -1657,6 +1669,37 @@ async function _handleToolCall(client, name, args) {
                 }
                 return { content: [{ type: "text", text: content }] };
             }
+            case "nestr_diagnose": {
+                schemas.diagnose.parse(args);
+                const snapshot = context?.getDiagnose?.();
+                const correlationId = getCorrelationId();
+                const result = {
+                    serverVersion: VERSION,
+                    correlationId,
+                    // No request context (e.g. stdio mode): we still report the basic facts.
+                    flow: snapshot?.flow ?? "unknown",
+                    tokenPresented: snapshot?.tokenPresented ?? false,
+                    tokenFingerprint: snapshot?.tokenFingerprint ?? "none",
+                    tokenAge: snapshot?.tokenAge ?? null,
+                    lastUpstream401At: snapshot?.lastUpstream401At
+                        ? new Date(snapshot.lastUpstream401At).toISOString()
+                        : null,
+                    lastRefreshAttempt: snapshot?.lastRefreshAttempt
+                        ? {
+                            at: new Date(snapshot.lastRefreshAttempt.at).toISOString(),
+                            success: snapshot.lastRefreshAttempt.success,
+                            error: snapshot.lastRefreshAttempt.error,
+                        }
+                        : null,
+                    sessionCorrelationId: snapshot?.sessionCorrelationId,
+                    authMode: snapshot?.isApiKey ? "api-key" : snapshot?.tokenPresented ? "oauth" : "none",
+                    mcpClient: snapshot?.mcpClient,
+                    mcpClientVersion: snapshot?.mcpClientVersion,
+                    userId: snapshot?.userId,
+                    hint: buildDiagnoseHint(snapshot),
+                };
+                return formatResult(result);
+            }
             case "nestr_list_workspaces": {
                 const parsed = schemas.listWorkspaces.parse(args);
                 const workspaces = await client.listWorkspaces({
@@ -2053,19 +2096,44 @@ async function _handleToolCall(client, name, args) {
                     return formatResult(result);
                 }
                 catch (err) {
-                    // If the error is from the tokenProvider (expired OAuth session),
-                    // surface it instead of silently falling back to workspace mode.
-                    // This prevents get_me from masking expired sessions as "api-key" mode.
-                    if (err instanceof NestrApiError && err.message === "OAuth session expired") {
+                    // 401 means the token itself is invalid — propagate so callers don't
+                    // see a false "success" here while every other tool fails on the
+                    // same auth state. Match by status (any AUTH_* 401 code).
+                    if (err instanceof NestrApiError && err.status === 401) {
                         throw err;
                     }
-                    // getCurrentUser fails for workspace API keys — no user identity
-                    return formatResult({
-                        authMode: "api-key",
-                        user: null,
-                        mode: "workspace",
-                        hint: "Using a workspace API key. No user identity — user-scoped features (inbox, daily plan, personal labels, my tensions) are unavailable. You are managing the workspace directly.",
-                    });
+                    // 403 likely means the token is valid but has no user scope (workspace
+                    // API key calling /users/me). Confirm the token actually works on an
+                    // endpoint that accepts both OAuth and workspace keys before reporting
+                    // "workspace mode" — that way a forbidden coming from anywhere else
+                    // (e.g. an unauthorized token that happens to 403) doesn't get masked.
+                    if (err instanceof NestrApiError && err.code === "AUTH_SCOPE_INSUFFICIENT") {
+                        const workspaceModeResponse = formatResult({
+                            authMode: "api-key",
+                            user: null,
+                            mode: "workspace",
+                            hint: "Using a workspace API key. No user identity — user-scoped features (inbox, daily plan, personal labels, my tensions) are unavailable. You are managing the workspace directly.",
+                        });
+                        try {
+                            await client.listWorkspaces({ limit: 1 });
+                            return workspaceModeResponse;
+                        }
+                        catch (verifyErr) {
+                            // The verification's job is to rule out "this token is bad". An
+                            // explicit auth failure on listWorkspaces does that — propagate.
+                            if (verifyErr instanceof NestrApiError && verifyErr.status === 401) {
+                                throw verifyErr;
+                            }
+                            // Anything else (5xx, network, rate limit) is a transient hiccup
+                            // on a different endpoint, not evidence that the token is bad.
+                            // Don't punish a likely-valid workspace key for a momentary
+                            // server issue — return the workspace-mode response we'd have
+                            // returned if the verification had succeeded.
+                            return workspaceModeResponse;
+                        }
+                    }
+                    // Other errors (expired OAuth session, network, server) — propagate.
+                    throw err;
                 }
             }
             // User tension tools (requires OAuth token)
@@ -2236,7 +2304,9 @@ async function _handleToolCall(client, name, args) {
         }
     }
     catch (error) {
-        // Handle Nestr API errors with structured response
+        // Handle Nestr API errors with structured response. NestrApiError.toToolError
+        // already attaches the correlationId from the active request context, so no
+        // extra wiring is needed here.
         if (error instanceof NestrApiError) {
             return formatError(error.toToolError());
         }
@@ -2248,6 +2318,7 @@ async function _handleToolCall(client, name, args) {
                 message: error.errors.map(e => `${e.path.join(".")}: ${e.message}`).join("; "),
                 retryable: false,
                 hint: "Check the tool parameters match the expected schema.",
+                correlationId: getCorrelationId(),
             });
         }
         // Handle other errors
@@ -2257,9 +2328,28 @@ async function _handleToolCall(client, name, args) {
             code: "UNKNOWN",
             message,
             retryable: false,
+            correlationId: getCorrelationId(),
         });
     }
 }
+function buildDiagnoseHint(snapshot) {
+    if (!snapshot || !snapshot.tokenPresented) {
+        return "No bearer was presented to the server. The MCP client should run the OAuth flow (or pass an X-Nestr-API-Key header) and retry.";
+    }
+    if (snapshot.lastRefreshAttempt && snapshot.lastRefreshAttempt.success === false) {
+        return "Most recent refresh failed. Tell the user to reconnect Nestr.";
+    }
+    if (snapshot.lastUpstream401At) {
+        if (snapshot.flow === "B") {
+            return "Nestr recently rejected the bearer. For Flow B, refresh is the client's responsibility — the MCP client should call /oauth/token with grant_type=refresh_token, then retry. If refresh also fails, tell the user to reconnect Nestr.";
+        }
+        return "Nestr recently rejected the bearer. Tell the user to reconnect Nestr.";
+    }
+    if (snapshot.tokenAge?.exp && snapshot.tokenAge.exp < snapshot.tokenAge.now) {
+        return "Bearer is expired (exp < now). The client should refresh.";
+    }
+    return "Server-side state looks healthy. If a tool is failing, include sessionCorrelationId in the bug report.";
+}
 function formatResult(data) {
     return {
         content: [