driggsby 0.1.3 → 0.1.5

package/README.md

@@ -1,21 +1,12 @@
 # driggsby
 
-`driggsby` installs the local Driggsby CLI and MCP broker.
-
-It gives local AI clients a single shared path into Driggsby:
-
-```text
-Codex / Claude Code / other local MCP client
-        |
-        v
-  driggsby mcp-server
-        |
-        v
-  shared local broker
-        |
-        v
-  remote Driggsby MCP
-```
+`driggsby` is the local CLI for connecting AI clients to Driggsby over MCP.
+
+## What You Get
+
+- browser-based sign-in to Driggsby
+- a local MCP server for tools like Codex and Claude Code
+- access to supported Driggsby tools from your AI client
 
 ## Install
 
@@ -25,37 +16,42 @@ npm install -g driggsby
 
 Node `20+` is required.
 
-## Commands
+If you prefer not to install globally, you can also use `npx -y driggsby ...`.
+
+## Quick Start
+
+1. Sign in:
 
-```text
+```bash
 driggsby login
-driggsby status
-driggsby mcp-server
-driggsby logout
-driggsby broker-daemon
 ```
 
-Typical local setup:
+2. Add Driggsby as an MCP server in your client:
 
 ```bash
-driggsby login
 codex mcp add driggsby -- driggsby mcp-server
 ```
 
-You can also use `npx -y driggsby ...` if you do not want a global install.
+3. Check broker status any time:
 
-## What It Does
+```bash
+driggsby status
+```
 
-- opens a browser-based Driggsby sign-in flow
-- keeps one local broker session on the machine
-- exposes a local stdio MCP server for local AI clients
-- forwards supported Driggsby MCP tools through the broker
+## Commands
+
+```bash
+driggsby login
+driggsby status
+driggsby mcp-server
+driggsby logout
+driggsby broker-daemon
+```
 
-## Security
+## Learn More
 
-- publishes from GitHub Actions using npm trusted publishing and OIDC
-- does not require a long-lived npm publish token for releases
-- keeps local broker session material in the platform secret store
+- Product and source: https://github.com/thegoodsoftwareco/driggsby
+- Issues: https://github.com/thegoodsoftwareco/driggsby/issues
 
 ## License
 

package/dist/auth/login.js

@@ -6,6 +6,7 @@ import { fetchAuthorizationServerMetadata, fetchProtectedResourceMetadata, } fro
 import { createDpopProof } from "./dpop.js";
 import { startLoopbackAuthListener } from "./loopback.js";
 import { buildAuthorizationUrl, createOAuthState, exchangeAuthorizationCode, registerBrokerClient, } from "./oauth.js";
+import { buildReauthenticationRequiredMessage } from "../lib/user-guidance.js";
 import { generatePkcePair } from "./pkce.js";
 import { assertBrokerRemoteUrl } from "./url-security.js";
 export async function loginBroker(runtimePaths, dependencies) {
@@ -114,7 +115,7 @@ function validateRemoteMetadata(authorizationServerMetadata, protectedResourceMe
 async function tokenEndpointDpopProof(runtimePaths, secretStore, brokerId, tokenEndpoint) {
     const dpopKeyPair = await readBrokerDpopKeyPair(runtimePaths, secretStore, brokerId);
     if (dpopKeyPair === null) {
-        throw new Error("The local broker DPoP key is missing. Run `npx -y driggsby login` again.");
+        throw new Error(buildReauthenticationRequiredMessage("The local broker DPoP key is missing"));
     }
     return await createDpopProof({
         httpMethod: "POST",

package/dist/auth/oauth.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { z } from "zod";
+import { buildReauthenticationRequiredMessage } from "../lib/user-guidance.js";
 const registrationResponseSchema = z.object({
     client_id: z.string().min(1),
     scope: z.string().min(1),
@@ -87,7 +88,11 @@ export async function refreshAccessToken(options, fetchImpl = fetch) {
         method: "POST",
     });
     if (!response.ok) {
-        throw new Error("Driggsby could not refresh the broker session with the remote service.");
+        const errorBody = await readErrorBody(response);
+        if (isAuthenticationFailure(response.status, errorBody)) {
+            throw new Error(buildReauthenticationRequiredMessage("Authentication has expired or the saved broker session is no longer valid"));
+        }
+        throw new Error("Driggsby could not refresh the broker session with the remote service. Wait a moment and try again.");
     }
     const refreshedTokens = parseTokenExchangeResult(await response.json(), false);
     return {
@@ -95,6 +100,24 @@ export async function refreshAccessToken(options, fetchImpl = fetch) {
         refreshToken: refreshedTokens.refreshToken || options.refreshToken,
     };
 }
+async function readErrorBody(response) {
+    try {
+        return (await response.text()).toLowerCase();
+    }
+    catch {
+        return "";
+    }
+}
+function isAuthenticationFailure(status, errorBody) {
+    return (status === 401 ||
+        status === 403 ||
+        (status === 400 &&
+            (errorBody.includes("invalid_grant") ||
+                errorBody.includes("invalid_token") ||
+                errorBody.includes("expired") ||
+                errorBody.includes("revoked") ||
+                errorBody.includes("unauthorized_client"))));
+}
 export function createOAuthState() {
     return randomUUID();
 }

package/dist/broker/daemon.js

@@ -3,6 +3,7 @@ import { BrokerRemoteSessionManager } from "./remote-session.js";
 import { callRemoteTool, listRemoteTools } from "./remote-mcp.js";
 import { KeyringSecretStore } from "./secret-store.js";
 import { LocalBrokerServer } from "./server.js";
+import { buildReauthenticationRequiredMessage } from "../lib/user-guidance.js";
 export async function runBrokerDaemon(runtimePaths) {
     const secretStore = new KeyringSecretStore();
     const metadata = await ensureBrokerInstallation(runtimePaths, secretStore);
@@ -44,21 +45,21 @@ export async function runBrokerDaemon(runtimePaths) {
 async function readRequiredLocalAuthToken(secretStore, brokerId) {
     const localAuthToken = await readBrokerLocalAuthToken(secretStore, brokerId);
     if (localAuthToken === null) {
-        throw new Error("The local broker auth state is incomplete. Run `npx -y driggsby login` again.");
+        throw new Error(buildReauthenticationRequiredMessage("The local broker auth state is incomplete"));
     }
     return localAuthToken;
 }
 async function readRequiredPrivateJwk(secretStore, brokerId) {
     const privateJwkRaw = await readBrokerPrivateJwk(secretStore, brokerId);
     if (privateJwkRaw === null) {
-        throw new Error("The local broker signing key is missing. Run `npx -y driggsby login` again.");
+        throw new Error(buildReauthenticationRequiredMessage("The local broker signing key is missing"));
     }
     return JSON.parse(privateJwkRaw);
 }
 async function readRequiredDpopKeyPair(runtimePaths, secretStore, brokerId) {
     const dpopKeyPair = await readBrokerDpopKeyPair(runtimePaths, secretStore, brokerId);
     if (dpopKeyPair === null) {
-        throw new Error("The local broker DPoP key is missing. Run `npx -y driggsby login` again.");
+        throw new Error(buildReauthenticationRequiredMessage("The local broker DPoP key is missing"));
     }
     return dpopKeyPair;
 }

package/dist/broker/launch.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { setTimeout as sleep } from "node:timers/promises";
+import { buildBrokerInvestigationMessage } from "../lib/user-guidance.js";
 import { getBrokerStatus, pingBroker } from "./client.js";
 export async function ensureBrokerRunning(options) {
     if ((await pingBroker({
@@ -11,7 +12,7 @@ export async function ensureBrokerRunning(options) {
     spawnBrokerDaemon(options.entrypointPath);
     const started = await waitForBroker(options.runtimePaths, options.secretStore, 4_000);
     if (!started) {
-        throw new Error("The local Driggsby broker did not start cleanly. Try `npx -y driggsby login` again.");
+        throw new Error(buildBrokerInvestigationMessage("The local Driggsby broker did not start cleanly"));
     }
 }
 export async function waitForBroker(runtimePaths, secretStore, timeoutMs) {

package/dist/broker/remote-mcp.js

@@ -3,6 +3,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { CallToolResultSchema, ListToolsResultSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { createDpopProof } from "../auth/dpop.js";
 import { assertBrokerRemoteUrl } from "../auth/url-security.js";
+import { buildReauthenticationRequiredMessage } from "../lib/user-guidance.js";
 const BROKER_CLIENT_INFO = {
     name: "driggsby-local-broker",
     version: "0.1.0",
@@ -94,13 +95,20 @@ function createDpopAuthenticatedFetch(session, dpopKeyPair) {
             publicJwk: dpopKeyPair.publicJwk,
             targetUrl: resolveRequestUrl(input),
         }));
-        return await fetch(input, {
+        return await ensureAuthenticatedRemoteResponse(fetch(input, {
             ...init,
             headers,
             method: httpMethod,
-        });
+        }));
     };
 }
+async function ensureAuthenticatedRemoteResponse(responsePromise) {
+    const response = await responsePromise;
+    if (response.status === 401 || response.status === 403) {
+        throw new Error(buildReauthenticationRequiredMessage("Authentication has expired or the saved broker session is no longer authorized for Driggsby"));
+    }
+    return response;
+}
 function resolveRequestMethod(input, init) {
     if (init?.method !== undefined) {
         return init.method;

package/dist/broker/remote-session.js

@@ -2,6 +2,7 @@ import { fetchAuthorizationServerMetadata, } from "../auth/discovery.js";
 import { createDpopProof } from "../auth/dpop.js";
 import { refreshAccessToken } from "../auth/oauth.js";
 import { assertBrokerRemoteUrl } from "../auth/url-security.js";
+import { buildReauthenticationRequiredMessage, errorMessageIncludesReauthenticationCommand } from "../lib/user-guidance.js";
 import { readBrokerDpopKeyPair } from "./installation.js";
 import { readBrokerRemoteSession, summarizeBrokerRemoteSession, writeBrokerRemoteSession, } from "./session.js";
 const ACCESS_TOKEN_REFRESH_SKEW_MS = 60_000;
@@ -20,7 +21,7 @@ export class BrokerRemoteSessionManager {
     async ensureFreshSession() {
         const session = await readBrokerRemoteSession(this.secretStore, this.brokerId);
         if (session === null) {
-            throw new Error("The local Driggsby broker is not connected. Run `npx -y driggsby login` again.");
+            throw new Error(buildReauthenticationRequiredMessage("The local Driggsby broker is not connected"));
         }
         if (!sessionNeedsRefresh(session)) {
             return session;
@@ -63,7 +64,7 @@ async function refreshRemoteSession(runtimePaths, secretStore, brokerId, session
         authorizationServerMetadata = await fetchAuthorizationServerMetadata(session.issuer, fetchImpl);
     }
     catch {
-        throw new Error("Driggsby could not refresh the local broker session right now. Try again in a moment.");
+        throw new Error("Driggsby could not refresh the local broker session right now because it could not reach the authorization server. Wait a moment and try again.");
     }
     let refreshedTokens;
     try {
@@ -75,8 +76,8 @@ async function refreshRemoteSession(runtimePaths, secretStore, brokerId, session
             resource: session.resource,
         }, fetchImpl);
     }
-    catch {
-        throw new Error("The local Driggsby broker session expired. Run `npx -y driggsby login` again.");
+    catch (error) {
+        throwRefreshSessionError(error);
     }
     const refreshedSession = {
         ...session,
@@ -92,7 +93,7 @@ async function refreshRemoteSession(runtimePaths, secretStore, brokerId, session
 async function refreshTokenDpopProof(runtimePaths, secretStore, brokerId, tokenEndpoint) {
     const dpopKeyPair = await readBrokerDpopKeyPair(runtimePaths, secretStore, brokerId);
     if (dpopKeyPair === null) {
-        throw new Error("The local Driggsby broker key is missing. Run `npx -y driggsby login` again.");
+        throw new Error(buildReauthenticationRequiredMessage("The local Driggsby broker key is missing"));
     }
     return await createDpopProof({
         httpMethod: "POST",
@@ -101,3 +102,9 @@ async function refreshTokenDpopProof(runtimePaths, secretStore, brokerId, tokenE
         targetUrl: tokenEndpoint,
     });
 }
+function throwRefreshSessionError(error) {
+    if (errorMessageIncludesReauthenticationCommand(error)) {
+        throw error;
+    }
+    throw new Error("Driggsby could not refresh the local broker session right now. Wait a moment and try again.");
+}

package/dist/lib/retry.js

@@ -0,0 +1,22 @@
+import { setTimeout as sleep } from "node:timers/promises";
+export async function retryOperation(operation, options) {
+    let lastError;
+    const totalAttempts = options.delaysMs.length;
+    for (const [index, delayMs] of options.delaysMs.entries()) {
+        if (delayMs > 0) {
+            await sleep(delayMs);
+        }
+        try {
+            return await operation(index + 1, totalAttempts);
+        }
+        catch (error) {
+            lastError = error;
+            if (index === totalAttempts - 1 || !options.shouldRetry(error)) {
+                throw error;
+            }
+        }
+    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error("The retry operation did not complete successfully.");
+}

package/dist/lib/user-guidance.js

@@ -0,0 +1,19 @@
+export const DRIGGSBY_LOGIN_COMMAND = "npx driggsby@latest login";
+export const DRIGGSBY_STATUS_COMMAND = "npx driggsby@latest status";
+export function buildReauthenticationRequiredMessage(reason) {
+    return `${ensureTrailingPeriod(reason)} Please re-authenticate by running \`${DRIGGSBY_LOGIN_COMMAND}\`.`;
+}
+export function buildBrokerInvestigationMessage(reason) {
+    return `${ensureTrailingPeriod(reason)} Investigate broker readiness by running \`${DRIGGSBY_STATUS_COMMAND}\`. If authentication expired, re-authenticate with \`${DRIGGSBY_LOGIN_COMMAND}\`.`;
+}
+export function errorMessageIncludesReauthenticationCommand(error) {
+    return (error instanceof Error &&
+        error.message.includes(DRIGGSBY_LOGIN_COMMAND));
+}
+export function formatRetryWindow(delaysMs) {
+    const totalDelayMs = delaysMs.reduce((sum, delay) => sum + delay, 0);
+    return `${(totalDelayMs / 1_000).toFixed(1)} seconds`;
+}
+function ensureTrailingPeriod(value) {
+    return /[.!?]$/.test(value) ? value : `${value}.`;
+}

package/dist/shim/server.js

@@ -6,6 +6,8 @@ import { ensureBrokerRunning } from "../broker/launch.js";
 import { callBrokerTool, getBrokerStatus, listBrokerTools, } from "../broker/client.js";
 import { buildBrokerStatus } from "../broker/installation.js";
 import { KeyringSecretStore } from "../broker/secret-store.js";
+import { retryOperation } from "../lib/retry.js";
+import { buildBrokerInvestigationMessage, errorMessageIncludesReauthenticationCommand, formatRetryWindow, } from "../lib/user-guidance.js";
 import { formatStatusText } from "../cli/format.js";
 const LOCAL_STATUS_TOOL = {
     description: "Report readiness and connectivity for the shared local Driggsby broker.",
@@ -16,6 +18,7 @@ const LOCAL_STATUS_TOOL = {
     },
     name: "get_local_broker_status",
 };
+const BROKER_OPERATION_RETRY_DELAYS_MS = [0, 250, 500, 1_000, 2_000];
 export async function runMcpServerCommand(runtimePaths, entrypointPath) {
     const secretStore = new KeyringSecretStore();
     await ensureBrokerRunning({
@@ -36,7 +39,7 @@ export function createLocalShimServer(runtimePaths, secretStore) {
         },
     });
     server.setRequestHandler(ListToolsRequestSchema, async () => {
-        const remoteTools = await loadRemoteTools(runtimePaths, secretStore);
+        const remoteTools = await loadRemoteToolsOrThrow(runtimePaths, secretStore);
         return {
             tools: [LOCAL_STATUS_TOOL, ...remoteTools],
         };
@@ -45,23 +48,11 @@ export function createLocalShimServer(runtimePaths, secretStore) {
         if (request.params.name === LOCAL_STATUS_TOOL.name) {
             return await buildLocalStatusToolResult(runtimePaths, secretStore);
         }
-        const remoteTools = await listBrokerTools({
-            runtimePaths,
-            secretStore,
-        });
-        if (remoteTools === null) {
-            throw new Error("The local Driggsby broker could not load the remote Driggsby tools right now. Use `get_local_broker_status` for details, then try again.");
-        }
+        const remoteTools = await loadRemoteToolsOrThrow(runtimePaths, secretStore);
         if (!remoteTools.some((tool) => tool.name === request.params.name)) {
             throw new Error("That Driggsby tool is not available in this session anymore. Ask the client to refresh its tool list and try again.");
         }
-        const toolResult = await callBrokerTool({
-            runtimePaths,
-            secretStore,
-        }, request.params.name, asToolArguments(request.params.arguments));
-        if (toolResult === null) {
-            throw new Error("The local Driggsby broker could not reach Driggsby right now. Use `get_local_broker_status` for details, then try again.");
-        }
+        const toolResult = await callBrokerToolOrThrow(runtimePaths, secretStore, request.params.name, asToolArguments(request.params.arguments));
         return toolResult;
     });
     return server;
@@ -89,15 +80,63 @@ function asToolArguments(argumentsValue) {
     }
     return argumentsValue;
 }
-async function loadRemoteTools(runtimePaths, secretStore) {
+async function loadRemoteToolsOrThrow(runtimePaths, secretStore) {
+    try {
+        return await retryOperation(async () => {
+            const remoteTools = await listBrokerTools({
+                runtimePaths,
+                secretStore,
+            });
+            if (remoteTools === null) {
+                throw new Error("The local Driggsby broker is not responding yet.");
+            }
+            return remoteTools;
+        }, {
+            delaysMs: BROKER_OPERATION_RETRY_DELAYS_MS,
+            shouldRetry: shouldRetryBrokerOperation,
+        });
+    }
+    catch (error) {
+        if (errorMessageIncludesReauthenticationCommand(error)) {
+            throw error;
+        }
+        throw new Error(buildBrokerInvestigationMessage(`The local Driggsby broker could not load the Driggsby tool list after ${BROKER_OPERATION_RETRY_DELAYS_MS.length} attempts over ${formatRetryWindow(BROKER_OPERATION_RETRY_DELAYS_MS)}`));
+    }
+}
+async function callBrokerToolOrThrow(runtimePaths, secretStore, toolName, args) {
     try {
-        const remoteTools = await listBrokerTools({
-            runtimePaths,
-            secretStore,
+        return await retryOperation(async () => {
+            const toolResult = await callBrokerTool({
+                runtimePaths,
+                secretStore,
+            }, toolName, args);
+            if (toolResult === null) {
+                throw new Error("The local Driggsby broker is not responding yet.");
+            }
+            return toolResult;
+        }, {
+            delaysMs: BROKER_OPERATION_RETRY_DELAYS_MS,
+            shouldRetry: shouldRetryBrokerOperation,
         });
-        return remoteTools ?? [];
     }
-    catch {
-        return [];
+    catch (error) {
+        if (errorMessageIncludesReauthenticationCommand(error)) {
+            throw error;
+        }
+        if (error instanceof Error && error.message.includes("not available in this session anymore")) {
+            throw error;
+        }
+        throw new Error(buildBrokerInvestigationMessage(`The local Driggsby broker could not run \`${toolName}\` after ${BROKER_OPERATION_RETRY_DELAYS_MS.length} attempts over ${formatRetryWindow(BROKER_OPERATION_RETRY_DELAYS_MS)}`));
+    }
+}
+function shouldRetryBrokerOperation(error) {
+    if (errorMessageIncludesReauthenticationCommand(error)) {
+        return false;
+    }
+    if (!(error instanceof Error)) {
+        return true;
     }
+    const message = error.message.toLowerCase();
+    return (!message.includes("not available in this session anymore") &&
+        !message.includes("invalid tool arguments"));
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "driggsby",
-  "version": "0.1.3",
-  "description": "Local Driggsby MCP broker and CLI",
+  "version": "0.1.5",
+  "description": "Local MCP broker and CLI for connecting AI clients to Driggsby",
   "license": "UNLICENSED",
   "type": "module",
   "repository": {