@muhaven/mcp 0.1.2 → 0.1.3

package/dist/index.d.cts

@@ -9,11 +9,14 @@ import { z } from 'zod';
  * (Windows). Each request is a single JSON object; each response is a
  * single JSON object. No request pipelining, no streaming.
  *
- * **Protocol version 0.2.0** — bumped from 0.1.0 in Wave 4 P3 ADR-3
- * to add the `store_jwt` / `get_jwt` / `clear_jwt` triple. The broker
- * is now the single keeper of the device-flow JWT (per ADR-3 D1
- * "polling, not loopback callback") in addition to the session-key
- * private half.
+ * **Protocol version 0.3.0** — additive bump from 0.2.0 in @muhaven/mcp@0.1.3
+ * to add `hello.hasSessionKey` + `hello.effectiveConfig` (so a daemon
+ * booted without `MUHAVEN_BROKER_SESSION_KEY` can serve read paths AND
+ * surface its effective backend/dashboard URLs to `muhaven-broker login
+ * --from-daemon`). The 0.2.0 bump from 0.1.0 (Wave 4 P3 ADR-3) added the
+ * `store_jwt` / `get_jwt` / `clear_jwt` triple — the broker is the single
+ * keeper of the device-flow JWT (per ADR-3 D1 "polling, not loopback
+ * callback") in addition to the session-key private half.
  *
  * Threat-model invariants:
  *  - The broker NEVER reaches out to the network. It only:
@@ -26,7 +29,7 @@ import { z } from 'zod';
  *  - Requests are size-capped (`maxRequestBytes`) — a malformed peer
  *    cannot exhaust broker memory by sending an unbounded JSON blob.
  */
-declare const BROKER_PROTOCOL_VERSION = "0.2.0";
+declare const BROKER_PROTOCOL_VERSION = "0.3.0";
 interface BrokerHelloRequest {
     readonly type: 'hello';
 }
@@ -57,10 +60,40 @@ interface BrokerClearJwtRequest {
 interface BrokerHelloResponse {
     readonly type: 'hello';
     readonly version: string;
-    /** 0x-prefixed checksummed address derived from the session key. */
+    /**
+     * 0x-prefixed checksummed address derived from the session key. When
+     * the daemon was booted without `MUHAVEN_BROKER_SESSION_KEY` (read-only
+     * posture; see `hasSessionKey`), this is the zero address.
+     *
+     * **DO NOT** use address-equality (`sessionKeyAddress !== ZERO_ADDRESS`)
+     * as a proxy for "session key is loaded" — that's a soft signal that
+     * future changes (e.g. allowing custom EOA-bound dev posture) could
+     * break silently. The authoritative aliveness check is `hasSessionKey`.
+     */
     readonly sessionKeyAddress: `0x${string}`;
     /** Whether a JWT is currently in the keystore. Useful for `doctor`. */
     readonly hasJwt: boolean;
+    /**
+     * Whether a session-key private half is loaded into the daemon. False
+     * when the daemon was booted without `MUHAVEN_BROKER_SESSION_KEY` — in
+     * that posture read tools still work (the broker serves JWT verbs), but
+     * any `sign_hash` request returns `session_key_unavailable`. Field added
+     * in protocol 0.3.0; absence implies `true` for back-compat with
+     * 0.2.0 daemons.
+     */
+    readonly hasSessionKey?: boolean;
+    /**
+     * Effective backend + dashboard URLs the daemon resolved from its own
+     * process env at boot. Surfaced so `muhaven-broker login --from-daemon`
+     * can stay in lockstep with the daemon's view rather than re-reading
+     * the CLI's env (which may diverge — e.g. login invoked over ssh inherits
+     * a different shell env than the systemd-launched daemon). Field added
+     * in protocol 0.3.0; absent on older daemons.
+     */
+    readonly effectiveConfig?: {
+        readonly backendBaseUrl: string;
+        readonly dashboardBaseUrl: string;
+    };
 }
 interface BrokerSignHashResponse {
     readonly type: 'sign_hash';
@@ -87,7 +120,7 @@ interface BrokerErrorResponse {
     readonly code: BrokerErrorCode;
     readonly message: string;
 }
-type BrokerErrorCode = 'invalid_request' | 'payload_too_large' | 'unsupported_type' | 'internal' | 'forbidden' | 'keystore_unavailable';
+type BrokerErrorCode = 'invalid_request' | 'payload_too_large' | 'unsupported_type' | 'internal' | 'forbidden' | 'keystore_unavailable' | 'session_key_unavailable';
 type BrokerRequest = BrokerHelloRequest | BrokerSignHashRequest | BrokerStoreJwtRequest | BrokerGetJwtRequest | BrokerClearJwtRequest;
 type BrokerResponse = BrokerHelloResponse | BrokerSignHashResponse | BrokerStoreJwtResponse | BrokerGetJwtResponse | BrokerClearJwtResponse | BrokerErrorResponse;
 /**
@@ -316,6 +349,27 @@ interface AuthRequiredPayload {
     readonly message: string;
     readonly loginCommand: string;
 }
+/**
+ * Sibling to `AUTH_REQUIRED` — used when the broker daemon is reachable
+ * but boots in read-only posture (no `MUHAVEN_BROKER_SESSION_KEY` at
+ * startup). The remediation is NOT `muhaven-broker login` — that mints
+ * a JWT, which is different from minting a session key. The session key
+ * comes from the dashboard's `/agent/policy/transition` ceremony (see
+ * Q1 in the post-§4 queue).
+ *
+ * Surfacing this as a distinct code lets the host LLM disambiguate:
+ *  - `AUTH_REQUIRED` → run a CLI command (deterministic, one-step).
+ *  - `SESSION_KEY_REQUIRED` → open a URL and complete a passkey ceremony
+ *    (operator-mediated, multi-step). The LLM should NOT auto-suggest
+ *    `muhaven-broker login` for this case — that would loop the user
+ *    indefinitely without minting a key.
+ */
+interface SessionKeyRequiredPayload {
+    readonly ok: false;
+    readonly code: 'SESSION_KEY_REQUIRED';
+    readonly message: string;
+    readonly mintUrl: string;
+}
 
 /**
  * Tool handlers — pure functions of `(input, deps)` returning a structured
@@ -343,6 +397,13 @@ interface ToolDeps {
     /** Surface this MCP server is configured for. Always 'mcp' here, but
      *  carried as a dep so the audit tool can filter to the local surface. */
     surface: 'mcp';
+    /**
+     * Dashboard base URL — used to build the mint-URL surfaced in the
+     * `SESSION_KEY_REQUIRED` payload when the broker is in read-only
+     * posture. Optional for back-compat; the payload falls back to the
+     * production default when absent.
+     */
+    dashboardBaseUrl?: string;
 }
 type ToolResult<T> = {
     ok: true;
@@ -351,7 +412,7 @@ type ToolResult<T> = {
     ok: false;
     code: string;
     message: string;
-} | AuthRequiredPayload;
+} | AuthRequiredPayload | SessionKeyRequiredPayload;
 
 /**
  * Static registry binding each tool descriptor to its zod schema and
@@ -393,10 +454,17 @@ declare function selectRegistry(readOnly: boolean): readonly ToolEntry[];
  *    instructs the user to run `muhaven-broker login`.
  */
 
+declare const SERVER_VERSION: string;
 interface BuildServerOptions {
     registry: readonly ToolEntry[];
     backend: BackendClient;
     broker: BrokerClient | undefined;
+    /**
+     * Threaded into `ToolDeps` so the `SESSION_KEY_REQUIRED` payload's
+     * `mintUrl` points at the operator's actual dashboard, not a hardcoded
+     * production URL.
+     */
+    dashboardBaseUrl?: string;
 }
 declare function buildMcpServer(opts: BuildServerOptions): Server;
 /**
@@ -456,12 +524,26 @@ interface McpRuntimeConfig {
 interface BrokerRuntimeConfig {
     /** Endpoint to bind: socket path on POSIX, named pipe name on Windows. */
     endpoint: string;
-    /** 0x-prefixed 32-byte private key. Sensitive — keychain-backed. */
-    sessionKeyHex: `0x${string}`;
+    /**
+     * 0x-prefixed 32-byte private key, OR undefined for read-only posture.
+     * When undefined, the daemon still serves `hello` + the JWT verbs
+     * (so MCP read tools work), but any `sign_hash` request returns
+     * `session_key_unavailable`. Sensitive when present — keychain-backed.
+     */
+    sessionKeyHex: `0x${string}` | undefined;
     /** Maximum payload bytes accepted from the IPC peer. */
     maxRequestBytes: number;
     /** Per-request hard timeout (ms). */
     requestTimeoutMs: number;
+    /**
+     * Effective backend URL the daemon read from its own env at boot. Used
+     * to populate `hello.effectiveConfig` so a `muhaven-broker login
+     * --from-daemon` call uses the same URL as the daemon, even when the
+     * login CLI was launched from a different shell env.
+     */
+    backendBaseUrl: string;
+    /** Effective dashboard URL paired with backendBaseUrl. */
+    dashboardBaseUrl: string;
 }
 /**
  * Compute the default IPC endpoint for the broker. POSIX: a socket file
@@ -587,6 +669,29 @@ interface ISigner {
     readonly address: `0x${string}`;
     signHash(hash: `0x${string}`): Promise<`0x${string}`>;
 }
+/**
+ * Sentinel signer for the read-only daemon posture (no
+ * `MUHAVEN_BROKER_SESSION_KEY` at boot). `address` returns the zero
+ * address; `signHash` throws `MissingSessionKeyError`, which the daemon
+ * maps to a structured `session_key_unavailable` broker error response.
+ *
+ * Closes §3e⁶ F-broker-session-key-required-for-reads — the daemon can
+ * serve `hello` + JWT verbs for read paths without an on-chain signer.
+ */
+declare class MissingSessionKeyError extends Error {
+    constructor();
+}
+declare const ZERO_ADDRESS: "0x0000000000000000000000000000000000000000";
+declare class NullSigner implements ISigner {
+    readonly address: "0x0000000000000000000000000000000000000000";
+    signHash(_hash: `0x${string}`): Promise<`0x${string}`>;
+}
+declare class ViemSigner implements ISigner {
+    private readonly account;
+    constructor(privateKey: `0x${string}`);
+    get address(): `0x${string}`;
+    signHash(hash: `0x${string}`): Promise<`0x${string}`>;
+}
 
 /**
  * Cross-platform JWT keystore for the broker daemon.
@@ -681,13 +786,38 @@ interface BrokerLogEvent {
  * keystore, returns the response object. Easy to unit-test without
  * spawning a socket.
  */
-declare function handleBrokerRequest(req: BrokerRequest, signer: ISigner, keystore: IKeystore, nowSec?: () => number): Promise<BrokerResponse>;
+interface HandleBrokerRequestOptions {
+    /**
+     * Whether the daemon was booted with a session-key private half. Drives
+     * the `hello.hasSessionKey` field + the `session_key_unavailable` error
+     * mapping. Defaults to `true` when omitted (current-runtime back-compat
+     * — older callers that don't know about the read-only posture still
+     * get the pre-0.3.0 behaviour).
+     */
+    hasSessionKey?: boolean;
+    /**
+     * Effective backend + dashboard URLs the daemon resolved from its env
+     * at boot. Surfaced via `hello.effectiveConfig` so the `--from-daemon`
+     * login path can use the daemon's view of these URLs (not the CLI's).
+     */
+    effectiveConfig?: {
+        readonly backendBaseUrl: string;
+        readonly dashboardBaseUrl: string;
+    };
+}
+declare function handleBrokerRequest(req: BrokerRequest, signer: ISigner, keystore: IKeystore, nowSec?: () => number, options?: HandleBrokerRequestOptions): Promise<BrokerResponse>;
 declare class BrokerDaemon {
     private readonly server;
     private readonly signer;
     private readonly log;
     private readonly config;
     private keystore;
+    /**
+     * Whether a session-key private half is actually loaded. `false` =
+     * daemon booted in read-only posture (no `MUHAVEN_BROKER_SESSION_KEY`
+     * at env-load time) and uses a `NullSigner` whose `signHash` throws.
+     */
+    private readonly hasSessionKey;
     constructor(options: BrokerDaemonOptions);
     start(): Promise<string>;
     stop(): Promise<void>;
@@ -695,4 +825,4 @@ declare class BrokerDaemon {
     private runAndRespond;
 }
 
-export { BROKER_PROTOCOL_VERSION, BackendClient, BackendError, type BackendErrorCode, BrokerClient, BrokerClientError, type BrokerClientErrorCode, BrokerDaemon, type BrokerDaemonOptions, type BrokerRequest, type BrokerResponse, type BrokerRuntimeConfig, DeviceFlowAbortedError, DeviceFlowClient, type DeviceFlowEvent, type IKeystore, JwtSource, type KeystoreBackend, KeystoreError, type McpRuntimeConfig, NoJwtAvailableError, type RunMcpStdioCliOptions, TOOL_DESCRIPTORS, type ToolDescriptor, type ToolEntry, type ToolHashEntry, buildMcpServer, buildToolHashTable, defaultBrokerEndpoint, fullToolRegistry, handleBrokerRequest, hashToolDescriptor, loadBrokerConfig, loadMcpConfig, openKeystore, parseBrokerRequest, registryForReadOnly, runMcpStdioCli, selectRegistry, serializeResponse, verifyDescriptorAgainstPin };
+export { BROKER_PROTOCOL_VERSION, BackendClient, BackendError, type BackendErrorCode, BrokerClient, BrokerClientError, type BrokerClientErrorCode, BrokerDaemon, type BrokerDaemonOptions, type BrokerRequest, type BrokerResponse, type BrokerRuntimeConfig, DeviceFlowAbortedError, DeviceFlowClient, type DeviceFlowEvent, type HandleBrokerRequestOptions, type IKeystore, type ISigner, JwtSource, type KeystoreBackend, KeystoreError, type McpRuntimeConfig, MissingSessionKeyError, NoJwtAvailableError, NullSigner, type RunMcpStdioCliOptions, SERVER_VERSION, TOOL_DESCRIPTORS, type ToolDescriptor, type ToolEntry, type ToolHashEntry, ViemSigner, ZERO_ADDRESS, buildMcpServer, buildToolHashTable, defaultBrokerEndpoint, fullToolRegistry, handleBrokerRequest, hashToolDescriptor, loadBrokerConfig, loadMcpConfig, openKeystore, parseBrokerRequest, registryForReadOnly, runMcpStdioCli, selectRegistry, serializeResponse, verifyDescriptorAgainstPin };

package/dist/index.d.ts

@@ -9,11 +9,14 @@ import { z } from 'zod';
  * (Windows). Each request is a single JSON object; each response is a
  * single JSON object. No request pipelining, no streaming.
  *
- * **Protocol version 0.2.0** — bumped from 0.1.0 in Wave 4 P3 ADR-3
- * to add the `store_jwt` / `get_jwt` / `clear_jwt` triple. The broker
- * is now the single keeper of the device-flow JWT (per ADR-3 D1
- * "polling, not loopback callback") in addition to the session-key
- * private half.
+ * **Protocol version 0.3.0** — additive bump from 0.2.0 in @muhaven/mcp@0.1.3
+ * to add `hello.hasSessionKey` + `hello.effectiveConfig` (so a daemon
+ * booted without `MUHAVEN_BROKER_SESSION_KEY` can serve read paths AND
+ * surface its effective backend/dashboard URLs to `muhaven-broker login
+ * --from-daemon`). The 0.2.0 bump from 0.1.0 (Wave 4 P3 ADR-3) added the
+ * `store_jwt` / `get_jwt` / `clear_jwt` triple — the broker is the single
+ * keeper of the device-flow JWT (per ADR-3 D1 "polling, not loopback
+ * callback") in addition to the session-key private half.
  *
  * Threat-model invariants:
  *  - The broker NEVER reaches out to the network. It only:
@@ -26,7 +29,7 @@ import { z } from 'zod';
  *  - Requests are size-capped (`maxRequestBytes`) — a malformed peer
  *    cannot exhaust broker memory by sending an unbounded JSON blob.
  */
-declare const BROKER_PROTOCOL_VERSION = "0.2.0";
+declare const BROKER_PROTOCOL_VERSION = "0.3.0";
 interface BrokerHelloRequest {
     readonly type: 'hello';
 }
@@ -57,10 +60,40 @@ interface BrokerClearJwtRequest {
 interface BrokerHelloResponse {
     readonly type: 'hello';
     readonly version: string;
-    /** 0x-prefixed checksummed address derived from the session key. */
+    /**
+     * 0x-prefixed checksummed address derived from the session key. When
+     * the daemon was booted without `MUHAVEN_BROKER_SESSION_KEY` (read-only
+     * posture; see `hasSessionKey`), this is the zero address.
+     *
+     * **DO NOT** use address-equality (`sessionKeyAddress !== ZERO_ADDRESS`)
+     * as a proxy for "session key is loaded" — that's a soft signal that
+     * future changes (e.g. allowing custom EOA-bound dev posture) could
+     * break silently. The authoritative aliveness check is `hasSessionKey`.
+     */
     readonly sessionKeyAddress: `0x${string}`;
     /** Whether a JWT is currently in the keystore. Useful for `doctor`. */
     readonly hasJwt: boolean;
+    /**
+     * Whether a session-key private half is loaded into the daemon. False
+     * when the daemon was booted without `MUHAVEN_BROKER_SESSION_KEY` — in
+     * that posture read tools still work (the broker serves JWT verbs), but
+     * any `sign_hash` request returns `session_key_unavailable`. Field added
+     * in protocol 0.3.0; absence implies `true` for back-compat with
+     * 0.2.0 daemons.
+     */
+    readonly hasSessionKey?: boolean;
+    /**
+     * Effective backend + dashboard URLs the daemon resolved from its own
+     * process env at boot. Surfaced so `muhaven-broker login --from-daemon`
+     * can stay in lockstep with the daemon's view rather than re-reading
+     * the CLI's env (which may diverge — e.g. login invoked over ssh inherits
+     * a different shell env than the systemd-launched daemon). Field added
+     * in protocol 0.3.0; absent on older daemons.
+     */
+    readonly effectiveConfig?: {
+        readonly backendBaseUrl: string;
+        readonly dashboardBaseUrl: string;
+    };
 }
 interface BrokerSignHashResponse {
     readonly type: 'sign_hash';
@@ -87,7 +120,7 @@ interface BrokerErrorResponse {
     readonly code: BrokerErrorCode;
     readonly message: string;
 }
-type BrokerErrorCode = 'invalid_request' | 'payload_too_large' | 'unsupported_type' | 'internal' | 'forbidden' | 'keystore_unavailable';
+type BrokerErrorCode = 'invalid_request' | 'payload_too_large' | 'unsupported_type' | 'internal' | 'forbidden' | 'keystore_unavailable' | 'session_key_unavailable';
 type BrokerRequest = BrokerHelloRequest | BrokerSignHashRequest | BrokerStoreJwtRequest | BrokerGetJwtRequest | BrokerClearJwtRequest;
 type BrokerResponse = BrokerHelloResponse | BrokerSignHashResponse | BrokerStoreJwtResponse | BrokerGetJwtResponse | BrokerClearJwtResponse | BrokerErrorResponse;
 /**
@@ -316,6 +349,27 @@ interface AuthRequiredPayload {
     readonly message: string;
     readonly loginCommand: string;
 }
+/**
+ * Sibling to `AUTH_REQUIRED` — used when the broker daemon is reachable
+ * but boots in read-only posture (no `MUHAVEN_BROKER_SESSION_KEY` at
+ * startup). The remediation is NOT `muhaven-broker login` — that mints
+ * a JWT, which is different from minting a session key. The session key
+ * comes from the dashboard's `/agent/policy/transition` ceremony (see
+ * Q1 in the post-§4 queue).
+ *
+ * Surfacing this as a distinct code lets the host LLM disambiguate:
+ *  - `AUTH_REQUIRED` → run a CLI command (deterministic, one-step).
+ *  - `SESSION_KEY_REQUIRED` → open a URL and complete a passkey ceremony
+ *    (operator-mediated, multi-step). The LLM should NOT auto-suggest
+ *    `muhaven-broker login` for this case — that would loop the user
+ *    indefinitely without minting a key.
+ */
+interface SessionKeyRequiredPayload {
+    readonly ok: false;
+    readonly code: 'SESSION_KEY_REQUIRED';
+    readonly message: string;
+    readonly mintUrl: string;
+}
 
 /**
  * Tool handlers — pure functions of `(input, deps)` returning a structured
@@ -343,6 +397,13 @@ interface ToolDeps {
     /** Surface this MCP server is configured for. Always 'mcp' here, but
      *  carried as a dep so the audit tool can filter to the local surface. */
     surface: 'mcp';
+    /**
+     * Dashboard base URL — used to build the mint-URL surfaced in the
+     * `SESSION_KEY_REQUIRED` payload when the broker is in read-only
+     * posture. Optional for back-compat; the payload falls back to the
+     * production default when absent.
+     */
+    dashboardBaseUrl?: string;
 }
 type ToolResult<T> = {
     ok: true;
@@ -351,7 +412,7 @@ type ToolResult<T> = {
     ok: false;
     code: string;
     message: string;
-} | AuthRequiredPayload;
+} | AuthRequiredPayload | SessionKeyRequiredPayload;
 
 /**
  * Static registry binding each tool descriptor to its zod schema and
@@ -393,10 +454,17 @@ declare function selectRegistry(readOnly: boolean): readonly ToolEntry[];
  *    instructs the user to run `muhaven-broker login`.
  */
 
+declare const SERVER_VERSION: string;
 interface BuildServerOptions {
     registry: readonly ToolEntry[];
     backend: BackendClient;
     broker: BrokerClient | undefined;
+    /**
+     * Threaded into `ToolDeps` so the `SESSION_KEY_REQUIRED` payload's
+     * `mintUrl` points at the operator's actual dashboard, not a hardcoded
+     * production URL.
+     */
+    dashboardBaseUrl?: string;
 }
 declare function buildMcpServer(opts: BuildServerOptions): Server;
 /**
@@ -456,12 +524,26 @@ interface McpRuntimeConfig {
 interface BrokerRuntimeConfig {
     /** Endpoint to bind: socket path on POSIX, named pipe name on Windows. */
     endpoint: string;
-    /** 0x-prefixed 32-byte private key. Sensitive — keychain-backed. */
-    sessionKeyHex: `0x${string}`;
+    /**
+     * 0x-prefixed 32-byte private key, OR undefined for read-only posture.
+     * When undefined, the daemon still serves `hello` + the JWT verbs
+     * (so MCP read tools work), but any `sign_hash` request returns
+     * `session_key_unavailable`. Sensitive when present — keychain-backed.
+     */
+    sessionKeyHex: `0x${string}` | undefined;
     /** Maximum payload bytes accepted from the IPC peer. */
     maxRequestBytes: number;
     /** Per-request hard timeout (ms). */
     requestTimeoutMs: number;
+    /**
+     * Effective backend URL the daemon read from its own env at boot. Used
+     * to populate `hello.effectiveConfig` so a `muhaven-broker login
+     * --from-daemon` call uses the same URL as the daemon, even when the
+     * login CLI was launched from a different shell env.
+     */
+    backendBaseUrl: string;
+    /** Effective dashboard URL paired with backendBaseUrl. */
+    dashboardBaseUrl: string;
 }
 /**
  * Compute the default IPC endpoint for the broker. POSIX: a socket file
@@ -587,6 +669,29 @@ interface ISigner {
     readonly address: `0x${string}`;
     signHash(hash: `0x${string}`): Promise<`0x${string}`>;
 }
+/**
+ * Sentinel signer for the read-only daemon posture (no
+ * `MUHAVEN_BROKER_SESSION_KEY` at boot). `address` returns the zero
+ * address; `signHash` throws `MissingSessionKeyError`, which the daemon
+ * maps to a structured `session_key_unavailable` broker error response.
+ *
+ * Closes §3e⁶ F-broker-session-key-required-for-reads — the daemon can
+ * serve `hello` + JWT verbs for read paths without an on-chain signer.
+ */
+declare class MissingSessionKeyError extends Error {
+    constructor();
+}
+declare const ZERO_ADDRESS: "0x0000000000000000000000000000000000000000";
+declare class NullSigner implements ISigner {
+    readonly address: "0x0000000000000000000000000000000000000000";
+    signHash(_hash: `0x${string}`): Promise<`0x${string}`>;
+}
+declare class ViemSigner implements ISigner {
+    private readonly account;
+    constructor(privateKey: `0x${string}`);
+    get address(): `0x${string}`;
+    signHash(hash: `0x${string}`): Promise<`0x${string}`>;
+}
 
 /**
  * Cross-platform JWT keystore for the broker daemon.
@@ -681,13 +786,38 @@ interface BrokerLogEvent {
  * keystore, returns the response object. Easy to unit-test without
  * spawning a socket.
  */
-declare function handleBrokerRequest(req: BrokerRequest, signer: ISigner, keystore: IKeystore, nowSec?: () => number): Promise<BrokerResponse>;
+interface HandleBrokerRequestOptions {
+    /**
+     * Whether the daemon was booted with a session-key private half. Drives
+     * the `hello.hasSessionKey` field + the `session_key_unavailable` error
+     * mapping. Defaults to `true` when omitted (current-runtime back-compat
+     * — older callers that don't know about the read-only posture still
+     * get the pre-0.3.0 behaviour).
+     */
+    hasSessionKey?: boolean;
+    /**
+     * Effective backend + dashboard URLs the daemon resolved from its env
+     * at boot. Surfaced via `hello.effectiveConfig` so the `--from-daemon`
+     * login path can use the daemon's view of these URLs (not the CLI's).
+     */
+    effectiveConfig?: {
+        readonly backendBaseUrl: string;
+        readonly dashboardBaseUrl: string;
+    };
+}
+declare function handleBrokerRequest(req: BrokerRequest, signer: ISigner, keystore: IKeystore, nowSec?: () => number, options?: HandleBrokerRequestOptions): Promise<BrokerResponse>;
 declare class BrokerDaemon {
     private readonly server;
     private readonly signer;
     private readonly log;
     private readonly config;
     private keystore;
+    /**
+     * Whether a session-key private half is actually loaded. `false` =
+     * daemon booted in read-only posture (no `MUHAVEN_BROKER_SESSION_KEY`
+     * at env-load time) and uses a `NullSigner` whose `signHash` throws.
+     */
+    private readonly hasSessionKey;
     constructor(options: BrokerDaemonOptions);
     start(): Promise<string>;
     stop(): Promise<void>;
@@ -695,4 +825,4 @@ declare class BrokerDaemon {
     private runAndRespond;
 }
 
-export { BROKER_PROTOCOL_VERSION, BackendClient, BackendError, type BackendErrorCode, BrokerClient, BrokerClientError, type BrokerClientErrorCode, BrokerDaemon, type BrokerDaemonOptions, type BrokerRequest, type BrokerResponse, type BrokerRuntimeConfig, DeviceFlowAbortedError, DeviceFlowClient, type DeviceFlowEvent, type IKeystore, JwtSource, type KeystoreBackend, KeystoreError, type McpRuntimeConfig, NoJwtAvailableError, type RunMcpStdioCliOptions, TOOL_DESCRIPTORS, type ToolDescriptor, type ToolEntry, type ToolHashEntry, buildMcpServer, buildToolHashTable, defaultBrokerEndpoint, fullToolRegistry, handleBrokerRequest, hashToolDescriptor, loadBrokerConfig, loadMcpConfig, openKeystore, parseBrokerRequest, registryForReadOnly, runMcpStdioCli, selectRegistry, serializeResponse, verifyDescriptorAgainstPin };
+export { BROKER_PROTOCOL_VERSION, BackendClient, BackendError, type BackendErrorCode, BrokerClient, BrokerClientError, type BrokerClientErrorCode, BrokerDaemon, type BrokerDaemonOptions, type BrokerRequest, type BrokerResponse, type BrokerRuntimeConfig, DeviceFlowAbortedError, DeviceFlowClient, type DeviceFlowEvent, type HandleBrokerRequestOptions, type IKeystore, type ISigner, JwtSource, type KeystoreBackend, KeystoreError, type McpRuntimeConfig, MissingSessionKeyError, NoJwtAvailableError, NullSigner, type RunMcpStdioCliOptions, SERVER_VERSION, TOOL_DESCRIPTORS, type ToolDescriptor, type ToolEntry, type ToolHashEntry, ViemSigner, ZERO_ADDRESS, buildMcpServer, buildToolHashTable, defaultBrokerEndpoint, fullToolRegistry, handleBrokerRequest, hashToolDescriptor, loadBrokerConfig, loadMcpConfig, openKeystore, parseBrokerRequest, registryForReadOnly, runMcpStdioCli, selectRegistry, serializeResponse, verifyDescriptorAgainstPin };