driggsby 0.1.7 → 0.1.9

package/dist/broker/installation.js

@@ -4,6 +4,7 @@ import { generateDpopKeyMaterial } from "../auth/dpop.js";
 import { readJsonFile, removeFileIfPresent, writeJsonFile } from "../lib/json-file.js";
 import { generateLocalAuthToken } from "./authentication.js";
 import { inspectRemoteSessionReadiness } from "./remote-session.js";
+import { buildNotConnectedReadiness } from "./remote-session.js";
 import { clearBrokerRemoteSession, readBrokerRemoteSession, } from "./session.js";
 const LOCAL_AUTH_TOKEN_ACCOUNT_SUFFIX = "local-auth-token";
 const PRIVATE_KEY_ACCOUNT_SUFFIX = "dpop-private-jwk";
@@ -57,34 +58,40 @@ export async function inspectBrokerReadiness(runtimePaths, secretStore) {
 export async function buildBrokerStatus(runtimePaths, secretStore, brokerRunning) {
     const readiness = await inspectBrokerReadiness(runtimePaths, secretStore);
     const remoteReadiness = readiness.brokerId === undefined
-        ? {
-            connected: false,
-            ready: false,
-        }
+        ? buildNotConnectedReadiness()
         : await inspectRemoteSessionReadiness({
             brokerId: readiness.brokerId,
+            refreshIfNeeded: true,
             runtimePaths,
             secretStore,
         });
     const status = {
         installed: readiness.installed && readiness.privateKeyPresent,
         brokerRunning,
+        ...(remoteReadiness.nextStepCommand === undefined
+            ? {}
+            : { nextStepCommand: remoteReadiness.nextStepCommand }),
+        remoteAccessDetail: remoteReadiness.detail,
+        remoteAccessState: remoteReadiness.state,
         remoteMcpReady: remoteReadiness.ready,
         socketPath: runtimePaths.socketPath,
+        ...(readiness.brokerId === undefined ? {} : { brokerId: readiness.brokerId }),
+        ...(readiness.dpopThumbprint === undefined
+            ? {}
+            : { dpopThumbprint: readiness.dpopThumbprint }),
+        ...(remoteReadiness.session === undefined
+            ? {}
+            : { remoteSession: remoteReadiness.session }),
     };
-    if (readiness.brokerId !== undefined) {
-        Object.assign(status, { brokerId: readiness.brokerId });
-    }
-    if (readiness.dpopThumbprint !== undefined) {
-        Object.assign(status, { dpopThumbprint: readiness.dpopThumbprint });
-    }
-    if (remoteReadiness.session !== undefined) {
-        Object.assign(status, {
-            remoteSession: remoteReadiness.session,
-        });
-    }
     return status;
 }
+export async function resolveBrokerStatusForDisplay(runtimePaths, secretStore, liveStatus) {
+    const brokerRunning = liveStatus !== null;
+    if (hasActionableRemoteStatus(liveStatus)) {
+        return liveStatus;
+    }
+    return await buildBrokerStatus(runtimePaths, secretStore, brokerRunning);
+}
 export async function clearBrokerInstallation(runtimePaths, secretStore) {
     const metadata = await readBrokerMetadata(runtimePaths);
     if (metadata !== null) {
@@ -140,3 +147,8 @@ async function removeEmptyDirectory(directoryPath) {
         }
     }
 }
+function hasActionableRemoteStatus(status) {
+    return (status !== null &&
+        typeof status.remoteAccessDetail === "string" &&
+        typeof status.remoteAccessState === "string");
+}

package/dist/broker/remote-session.js

@@ -2,10 +2,12 @@ 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 { retryOperation } from "../lib/retry.js";
+import { buildReauthenticationRequiredMessage, DRIGGSBY_LOGIN_COMMAND, DRIGGSBY_STATUS_COMMAND, 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;
+const STATUS_REFRESH_RETRY_DELAYS_MS = [0, 250, 500];
 export class BrokerRemoteSessionManager {
     brokerId;
     fetchImpl;
@@ -39,16 +41,32 @@ export async function ensureFreshRemoteSession(options) {
 export async function inspectRemoteSessionReadiness(options) {
     const session = await readBrokerRemoteSession(options.secretStore, options.brokerId);
     if (session === null) {
+        return buildNotConnectedReadiness();
+    }
+    if (options.refreshIfNeeded && sessionNeedsRefresh(session)) {
+        try {
+            const refreshedSession = await retryOperation(async () => await ensureFreshRemoteSession(options), {
+                delaysMs: STATUS_REFRESH_RETRY_DELAYS_MS,
+                shouldRetry: shouldRetryStatusRefresh,
+            });
+            return buildReadyReadiness(refreshedSession);
+        }
+        catch (error) {
+            return buildFailedRefreshReadiness(error, session);
+        }
+    }
+    if (sessionNeedsRefresh(session)) {
         return {
-            connected: false,
+            connected: true,
+            detail: "The saved remote session needs a token refresh before remote MCP forwarding can run.",
+            nextStepCommand: DRIGGSBY_STATUS_COMMAND,
             ready: false,
+            reauthenticationRequired: false,
+            session: summarizeBrokerRemoteSession(session),
+            state: "temporarily_unavailable",
         };
     }
-    return {
-        connected: true,
-        ready: !sessionNeedsRefresh(session),
-        session: summarizeBrokerRemoteSession(session),
-    };
+    return buildReadyReadiness(session);
 }
 export function sessionNeedsRefresh(session, nowMs = Date.now()) {
     const expiresAtMs = Date.parse(session.accessTokenExpiresAt);
@@ -108,3 +126,48 @@ function throwRefreshSessionError(error) {
     }
     throw new Error("Driggsby could not refresh the local broker session right now. Wait a moment and try again.");
 }
+function shouldRetryStatusRefresh(error) {
+    return !errorMessageIncludesReauthenticationCommand(error);
+}
+function buildFailedRefreshReadiness(error, session) {
+    if (errorMessageIncludesReauthenticationCommand(error)) {
+        return {
+            connected: true,
+            detail: "The saved remote session is no longer authorized. Remote MCP forwarding will stay blocked until Driggsby signs in again.",
+            nextStepCommand: DRIGGSBY_LOGIN_COMMAND,
+            ready: false,
+            reauthenticationRequired: true,
+            session: summarizeBrokerRemoteSession(session),
+            state: "reauth_required",
+        };
+    }
+    return {
+        connected: true,
+        detail: "Driggsby could not refresh remote MCP access right now. Remote MCP forwarding is blocked until the refresh succeeds.",
+        nextStepCommand: DRIGGSBY_STATUS_COMMAND,
+        ready: false,
+        reauthenticationRequired: false,
+        session: summarizeBrokerRemoteSession(session),
+        state: "temporarily_unavailable",
+    };
+}
+export function buildNotConnectedReadiness() {
+    return {
+        connected: false,
+        detail: "Driggsby does not have a saved remote session yet.",
+        nextStepCommand: DRIGGSBY_LOGIN_COMMAND,
+        ready: false,
+        reauthenticationRequired: false,
+        state: "not_connected",
+    };
+}
+function buildReadyReadiness(session) {
+    return {
+        connected: true,
+        detail: "Remote MCP forwarding is ready to use.",
+        ready: true,
+        reauthenticationRequired: false,
+        session: summarizeBrokerRemoteSession(session),
+        state: "ready",
+    };
+}

package/dist/cli/commands/status.js

@@ -1,5 +1,5 @@
 import { getBrokerStatus } from "../../broker/client.js";
-import { buildBrokerStatus } from "../../broker/installation.js";
+import { resolveBrokerStatusForDisplay } from "../../broker/installation.js";
 import { KeyringSecretStore } from "../../broker/secret-store.js";
 import { formatStatusText } from "../format.js";
 export async function runStatusCommand(runtimePaths) {
@@ -8,7 +8,6 @@ export async function runStatusCommand(runtimePaths) {
         runtimePaths,
         secretStore,
     });
-    const status = liveStatus ??
-        (await buildBrokerStatus(runtimePaths, secretStore, false));
+    const status = await resolveBrokerStatusForDisplay(runtimePaths, secretStore, liveStatus);
     process.stdout.write(formatStatusText(status));
 }

package/dist/cli/format.js

@@ -1,23 +1,84 @@
+import { DRIGGSBY_LOGIN_COMMAND, DRIGGSBY_STATUS_COMMAND, } from "../lib/user-guidance.js";
 export function formatStatusText(status) {
+    const remoteAccessState = resolveRemoteAccessState(status);
+    const remoteAccessDetail = resolveRemoteAccessDetail(status, remoteAccessState);
+    const nextStepCommand = resolveNextStepCommand(status, remoteAccessState);
     const lines = [
         "Local Driggsby broker",
-        `installed: ${status.installed ? "yes" : "no"}`,
-        `running: ${status.brokerRunning ? "yes" : "no"}`,
-        `connected: ${status.remoteSession ? "yes" : "no"}`,
-        `remote mcp ready: ${status.remoteMcpReady ? "yes" : "no"}`,
-        `socket: ${status.socketPath}`,
+        `remote MCP forwarding: ${status.remoteMcpReady ? "ready" : "not ready"}`,
+        `remote access state: ${formatRemoteAccessState(remoteAccessState)}`,
+        `what this means: ${remoteAccessDetail}`,
     ];
-    if (status.brokerId) {
-        lines.push(`broker id: ${status.brokerId}`);
+    if (!status.installed) {
+        lines.push("local broker setup: incomplete");
     }
-    if (status.dpopThumbprint) {
-        lines.push(`dpop thumbprint: ${status.dpopThumbprint}`);
+    if (!status.brokerRunning) {
+        lines.push("local broker service: not running");
+    }
+    if (nextStepCommand) {
+        lines.push(`next step: run \`${nextStepCommand}\``);
     }
     if (status.remoteSession) {
-        lines.push(`server: ${status.remoteSession.issuer}`);
-        lines.push(`resource: ${status.remoteSession.resource}`);
-        lines.push(`scope: ${status.remoteSession.scope}`);
-        lines.push(`access token expires: ${status.remoteSession.accessTokenExpiresAt}`);
+        lines.push(`saved access token expires at: ${status.remoteSession.accessTokenExpiresAt}`);
     }
     return `${lines.join("\n")}\n`;
 }
+function formatRemoteAccessState(remoteAccessState) {
+    switch (remoteAccessState) {
+        case "ready":
+            return "authenticated";
+        case "not_connected":
+            return "not connected";
+        case "reauth_required":
+            return "re-authentication required";
+        case "temporarily_unavailable":
+            return "temporarily unavailable";
+    }
+    return remoteAccessState;
+}
+function resolveRemoteAccessState(status) {
+    const runtimeStatus = status;
+    return runtimeStatus.remoteAccessState ?? inferLegacyRemoteAccessState(status);
+}
+function resolveRemoteAccessDetail(status, remoteAccessState) {
+    const runtimeStatus = status;
+    return runtimeStatus.remoteAccessDetail ??
+        inferLegacyRemoteAccessDetail(status, remoteAccessState);
+}
+function resolveNextStepCommand(status, remoteAccessState) {
+    const runtimeStatus = status;
+    return runtimeStatus.nextStepCommand ??
+        inferLegacyNextStepCommand(remoteAccessState);
+}
+function inferLegacyRemoteAccessState(status) {
+    if (status.remoteMcpReady) {
+        return "ready";
+    }
+    if (status.remoteSession) {
+        return "temporarily_unavailable";
+    }
+    return "not_connected";
+}
+function inferLegacyRemoteAccessDetail(status, remoteAccessState) {
+    if (remoteAccessState === "ready") {
+        return "Remote MCP forwarding is ready to use.";
+    }
+    if (remoteAccessState === "not_connected") {
+        return "Driggsby does not have a saved remote session yet.";
+    }
+    if (status.remoteSession) {
+        return "Remote MCP forwarding is not ready yet. Driggsby may still need to refresh the saved remote session before forwarding can run.";
+    }
+    return "Remote MCP forwarding is not ready to use yet.";
+}
+function inferLegacyNextStepCommand(remoteAccessState) {
+    switch (remoteAccessState) {
+        case "ready":
+            return undefined;
+        case "not_connected":
+        case "reauth_required":
+            return DRIGGSBY_LOGIN_COMMAND;
+        case "temporarily_unavailable":
+            return DRIGGSBY_STATUS_COMMAND;
+    }
+}

package/dist/shim/server.js

@@ -3,11 +3,11 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { ensureBrokerRunning } from "../broker/launch.js";
 import { callBrokerTool, getBrokerStatus, listBrokerTools, } from "../broker/client.js";
-import { buildBrokerStatus } from "../broker/installation.js";
+import { resolveBrokerStatusForDisplay } 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";
+import { formatStatusText, } from "../cli/format.js";
 import { LifecycleAwareStdioServerTransport } from "./stdio-transport.js";
 const LOCAL_STATUS_TOOL = {
     description: "Report readiness and connectivity for the shared local Driggsby broker.",
@@ -59,8 +59,8 @@ export function createLocalShimServer(runtimePaths, secretStore) {
     return server;
 }
 async function buildLocalStatusToolResult(runtimePaths, secretStore) {
-    const status = (await getBrokerStatus({ runtimePaths, secretStore })) ??
-        (await buildBrokerStatus(runtimePaths, secretStore, false));
+    const liveStatus = await getBrokerStatus({ runtimePaths, secretStore });
+    const status = await resolveBrokerStatusForDisplay(runtimePaths, secretStore, liveStatus);
     return {
         content: [
             {

package/dist/shim/stdio-transport.js

@@ -3,20 +3,29 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 export class LifecycleAwareStdioServerTransport {
     delegate;
     stdin;
+    parentPollIntervalMs;
+    parentProcess;
+    startingParentPid;
     closingPromise = null;
+    parentPollHandle = null;
     started = false;
     onclose;
     onerror;
     onmessage;
     handleInputClosed = () => {
-        void this.close().catch((error) => {
-            this.onerror?.(error instanceof Error
-                ? error
-                : new Error("The Driggsby MCP transport could not close cleanly."));
-        });
+        this.closeForLifecycleEnd("input stream closed");
     };
-    constructor(stdin = process.stdin, stdout = process.stdout) {
+    handleParentProcessChanged = () => {
+        if (this.parentProcess.ppid === this.startingParentPid) {
+            return;
+        }
+        this.closeForLifecycleEnd("parent process exited");
+    };
+    constructor(stdin = process.stdin, stdout = process.stdout, options = {}) {
         this.stdin = stdin;
+        this.parentPollIntervalMs = options.parentPollIntervalMs ?? 1_000;
+        this.parentProcess = options.parentProcess ?? process;
+        this.startingParentPid = this.parentProcess.ppid;
         this.delegate = new StdioServerTransport(stdin, stdout);
         this.delegate.onclose = () => {
             this.onclose?.();
@@ -35,11 +44,13 @@ export class LifecycleAwareStdioServerTransport {
         this.started = true;
         this.stdin.once("close", this.handleInputClosed);
         this.stdin.once("end", this.handleInputClosed);
+        this.startParentWatchdog();
         try {
             await this.delegate.start();
         }
         catch (error) {
             this.removeInputListeners();
+            this.stopParentWatchdog();
             this.started = false;
             throw error;
         }
@@ -55,6 +66,7 @@ export class LifecycleAwareStdioServerTransport {
             }
             this.started = false;
             this.removeInputListeners();
+            this.stopParentWatchdog();
             await this.delegate.close();
         })();
         try {
@@ -67,8 +79,28 @@ export class LifecycleAwareStdioServerTransport {
     async send(message) {
         await this.delegate.send(message);
     }
+    closeForLifecycleEnd(reason) {
+        void this.close().catch((error) => {
+            this.onerror?.(error instanceof Error
+                ? error
+                : new Error(`The Driggsby MCP transport could not close cleanly after ${reason}.`));
+        });
+    }
     removeInputListeners() {
         this.stdin.off("close", this.handleInputClosed);
         this.stdin.off("end", this.handleInputClosed);
     }
+    startParentWatchdog() {
+        this.parentPollHandle = setInterval(() => {
+            this.handleParentProcessChanged();
+        }, this.parentPollIntervalMs);
+        this.parentPollHandle.unref();
+    }
+    stopParentWatchdog() {
+        if (this.parentPollHandle === null) {
+            return;
+        }
+        clearInterval(this.parentPollHandle);
+        this.parentPollHandle = null;
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driggsby",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Local MCP broker and CLI for connecting AI clients to Driggsby",
   "license": "UNLICENSED",
   "type": "module",