@cello-protocol/client 0.0.5 → 0.0.6

package/dist/mcp-server.d.ts

@@ -261,10 +261,26 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { CelloClient } from "./types.js";
 import type { CelloNode } from "@cello-protocol/transport";
 import type { KeyProvider } from "@cello-protocol/crypto";
-import type { CheckpointStatusProvider } from "@cello-protocol/interfaces";
+import type { CheckpointStatusProvider, Logger } from "@cello-protocol/interfaces";
 import type { ClientBackup } from "./client-backup.js";
+/**
+ * AC-005 (DX-001): Default demo agent ID — the CELLO demo agent that strangers can connect to.
+ * Overridable via CELLO_DEMO_AGENT_ID env var without a code change.
+ * Must NOT be hardcoded as a string literal in tool implementations.
+ */
+export declare const DEFAULT_DEMO_AGENT_ID = "a2c55e2721f45cfa86cb3417a76e3f7b";
 export declare function createMcpSessionServer(node: CelloNode, client: CelloClient, keyProvider: KeyProvider, opts?: {
     checkpointStatusProvider?: CheckpointStatusProvider;
     clientBackup?: ClientBackup;
+    /** AC-007 (DX-001): Directory HTTP URL for /agent-lookup endpoint. */
+    directoryUrl?: string;
+    /**
+     * AC-009 (DX-001): Promise that resolves when background init (DB open, directory dial,
+     * loadPersistedState) has completed. Tools that require the directory/FROST await this
+     * with a 10s timeout before proceeding.
+     */
+    readyPromise?: Promise<void>;
+    /** Structured logger for observability events (e.g. client.directory.agent_lookup.failed). */
+    logger?: Logger;
 }): McpServer;
 //# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,OAAO,KAAK,EAAE,WAAW,EAA0B,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAC3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAuBvD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,WAAW,EACxB,IAAI,CAAC,EAAE;IAAE,wBAAwB,CAAC,EAAE,wBAAwB,CAAC;IAAC,YAAY,CAAC,EAAE,YAAY,CAAA;CAAE,GAC1F,SAAS,CA+jCX"}
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,OAAO,KAAK,EAAE,WAAW,EAA0B,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AA0BvD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,qCAAqC,CAAC;AAexE,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,SAAS,EACf,MAAM,EAAE,WAAW,EACnB,WAAW,EAAE,WAAW,EACxB,IAAI,CAAC,EAAE;IACL,wBAAwB,CAAC,EAAE,wBAAwB,CAAC;IACpD,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACA,SAAS,CAgyCX"}

package/dist/mcp-server.js

@@ -267,6 +267,26 @@ function jsonText(value) {
     return { content: [{ type: "text", text: JSON.stringify(value) }] };
 }
 const TRANSPORT_NOT_STARTED = jsonText({ error: { reason: "transport_not_started" } });
+/**
+ * AC-004 (DX-001): Structured not_registered error returned when any tool that requires
+ * registration is called before the agent has completed registration.
+ * SI-001: must not include the pre-auth token in any error message.
+ */
+const NOT_REGISTERED_ERROR = jsonText({
+    error: {
+        reason: "not_registered",
+        message: "This agent is not yet registered with the CELLO directory. " +
+            "To register: (1) Get a token from @CelloConnectStagingBot on Telegram, " +
+            "(2) call cello_register({ token: 'CELLO-...' }). " +
+            "Call cello_setup_guidance() for the full 6-step setup guide.",
+    },
+});
+/**
+ * AC-005 (DX-001): Default demo agent ID — the CELLO demo agent that strangers can connect to.
+ * Overridable via CELLO_DEMO_AGENT_ID env var without a code change.
+ * Must NOT be hardcoded as a string literal in tool implementations.
+ */
+export const DEFAULT_DEMO_AGENT_ID = "a2c55e2721f45cfa86cb3417a76e3f7b";
 function toHex(bytes) {
     return Buffer.from(bytes).toString("hex");
 }
@@ -280,6 +300,22 @@ function sleep(ms) {
 export function createMcpSessionServer(node, client, keyProvider, opts) {
     const checkpointStatusProvider = opts?.checkpointStatusProvider;
     const clientBackup = opts?.clientBackup;
+    const directoryHttpUrl = opts?.directoryUrl;
+    const logger = opts?.logger;
+    const readyPromise = opts?.readyPromise;
+    /**
+     * AC-009 (DX-001): Await background init with a 10s timeout.
+     * Tools that require the directory/FROST (cello_initiate_session, cello_request_connection)
+     * call this before proceeding. cello_status and cello_setup_guidance do NOT await this.
+     */
+    async function awaitReady() {
+        if (!readyPromise)
+            return;
+        await Promise.race([
+            readyPromise,
+            new Promise((_, reject) => setTimeout(() => reject(new Error("background_init_timeout")), 10_000)),
+        ]);
+    }
     const startedAt = Date.now();
     // FIFO queue of inbound session assignment events.
     // Populated by client.onSessionAssignment callback.
@@ -287,6 +323,16 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
     function transportStarted() {
         return node.listenAddresses().length > 0;
     }
+    /**
+     * AC-004 (DX-001): Returns true if the agent is registered (registration state exists).
+     * Used by all tools that require registration to return NOT_REGISTERED_ERROR if not registered.
+     */
+    function isRegistered() {
+        const regState = typeof client.getRegistrationState === "function"
+            ? client.getRegistrationState()
+            : null;
+        return regState !== null;
+    }
     function directoryReachable() {
         // Check whether the libp2p node currently has an open connection to the directory peer.
         // This is accurate: true means the signaling stream is (or was recently) live;
@@ -320,18 +366,58 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
     // signaling stream, sends session_request, and awaits session_assignment from
     // the directory. The M1 polling stub has been replaced.
     server.registerTool("cello_initiate_session", {
-        description: "Initiate a session with a target agent by their K_local public key. Requires an existing connection (M3+).",
+        description: "Initiate a session with a target agent. Accepts either target_pubkey (64 hex chars) or target_agent_id (32 hex chars). Requires an existing connection (M3+).",
         inputSchema: {
-            target_pubkey: z.string().describe("Target agent K_local pubkey as lowercase hex (64 chars)"),
+            target_pubkey: z.string().optional().describe("Target agent K_local pubkey as lowercase hex (64 chars)"),
+            target_agent_id: z.string().optional().describe("Target agent's agent_id as lowercase hex (32 chars). Resolved to pubkey via directory /agent-lookup."),
             timeout_ms: z.number().int().min(0).optional().describe("Optional timeout in milliseconds"),
         },
-    }, async ({ target_pubkey, timeout_ms }) => {
+    }, async ({ target_pubkey, target_agent_id, timeout_ms }) => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
+        // AC-009 (DX-001): await background init (directory connection, loadPersistedState)
+        try {
+            await awaitReady();
+        }
+        catch { /* proceed — may return directory_unreachable if needed */ }
         if (!transportStarted())
             return TRANSPORT_NOT_STARTED;
-        if (!client.hasConnection(target_pubkey)) {
+        // AC-007b (DX-001): resolve target_agent_id to target_pubkey via /agent-lookup
+        let resolvedTargetPubkey = target_pubkey;
+        if (!resolvedTargetPubkey && target_agent_id) {
+            if (!/^[0-9a-f]{32}$/i.test(target_agent_id)) {
+                return jsonText({ ok: false, reason: "invalid_target_agent_id", agent_id: target_agent_id });
+            }
+            if (!directoryHttpUrl) {
+                return jsonText({ ok: false, reason: "directory_not_configured", agent_id: target_agent_id });
+            }
+            const t0Lookup = Date.now();
+            try {
+                const resp = await fetch(`${directoryHttpUrl}/agent-lookup?agent_id=${target_agent_id}`, { signal: AbortSignal.timeout(10_000) });
+                if (!resp.ok) {
+                    logger?.warn("client.directory.agent_lookup.failed", { agentId: target_agent_id, endpoint: `${directoryHttpUrl}/agent-lookup`, httpStatus: resp.status, reason: "http_error", durationMs: Date.now() - t0Lookup });
+                    return jsonText({ ok: false, reason: "agent_not_found", agent_id: target_agent_id });
+                }
+                const body = await resp.json();
+                if (!body.k_local_pubkey) {
+                    logger?.warn("client.directory.agent_lookup.failed", { agentId: target_agent_id, endpoint: `${directoryHttpUrl}/agent-lookup`, httpStatus: resp.status, reason: "missing_pubkey_in_response", durationMs: Date.now() - t0Lookup });
+                    return jsonText({ ok: false, reason: "agent_not_found", agent_id: target_agent_id });
+                }
+                resolvedTargetPubkey = body.k_local_pubkey;
+            }
+            catch (e) {
+                const reason = e instanceof Error ? e.message : String(e);
+                logger?.warn("client.directory.agent_lookup.failed", { agentId: target_agent_id, endpoint: `${directoryHttpUrl}/agent-lookup`, httpStatus: 0, reason, durationMs: Date.now() - t0Lookup });
+                return jsonText({ ok: false, reason: "agent_not_found", agent_id: target_agent_id });
+            }
+        }
+        if (!resolvedTargetPubkey) {
+            return jsonText({ ok: false, reason: "missing_target", message: "Provide either target_pubkey (64 hex) or target_agent_id (32 hex)." });
+        }
+        if (!client.hasConnection(resolvedTargetPubkey)) {
             return jsonText({ ok: false, reason: "no_connection" });
         }
-        const result = await client.initiateSession(target_pubkey, { timeoutMs: timeout_ms });
+        const result = await client.initiateSession(resolvedTargetPubkey, { timeoutMs: timeout_ms });
         if (result.ok) {
             return jsonText({
                 ok: true,
@@ -351,6 +437,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             timeout_ms: z.number().int().min(0).describe("Maximum wait time in milliseconds"),
         },
     }, async ({ timeout_ms }) => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         if (!transportStarted())
             return TRANSPORT_NOT_STARTED;
         const deadline = Date.now() + timeout_ms;
@@ -382,6 +470,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             content: z.string().describe("UTF-8 message content"),
         },
     }, async ({ session_id, content }) => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         if (!transportStarted())
             return TRANSPORT_NOT_STARTED;
         const contentBytes = new TextEncoder().encode(content);
@@ -419,6 +509,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             timeout_ms: z.number().int().min(0).describe("Maximum wait time in milliseconds"),
         },
     }, async ({ session_id, timeout_ms }) => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         if (!transportStarted())
             return TRANSPORT_NOT_STARTED;
         const msg = await client.receiveSessionMessageAsync(session_id, timeout_ms);
@@ -468,6 +560,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             timeout_ms: z.number().int().min(0).describe("Maximum wait time in milliseconds"),
         },
     }, async ({ timeout_ms }) => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         if (!transportStarted())
             return TRANSPORT_NOT_STARTED;
         const result = await client.receiveMessageAsync(timeout_ms);
@@ -518,6 +612,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             session_id: z.string().describe("Session ID as lowercase hex"),
         },
     }, async ({ session_id }) => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         if (!transportStarted())
             return TRANSPORT_NOT_STARTED;
         const result = await client.initiateSessionSeal(session_id);
@@ -603,6 +699,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
         description: "List all known sessions and their current status.",
         inputSchema: {},
     }, async () => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         const records = client.listSessions();
         const sessions = records.map((s) => ({
             session_id: toHex(s.session_id),
@@ -674,6 +772,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             session_id: z.string().describe("Session ID as lowercase hex"),
         },
     }, async ({ session_id }) => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         const record = client.listSessions().find((s) => toHex(s.session_id) === session_id);
         if (!record) {
             return jsonText({ error: { reason: "session_not_found", session_id } });
@@ -748,6 +848,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             leaf_index: z.number().int().min(0).describe("Zero-based index of the target leaf"),
         },
     }, async ({ session_id, leaf_index }) => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         // PERSIST-017: if CheckpointStatusProvider is wired in, check MMR checkpoint status first.
         // Returns the pending/confirmed/error response based on staging table state.
         if (checkpointStatusProvider) {
@@ -822,18 +924,97 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             sealed_root: localRootHex,
         });
     });
+    // ── cello_setup_guidance ──────────────────────────────────────────────────
+    //
+    // AC-005 (DX-001): Returns the full 6-step CELLO setup guide (always shown,
+    // never collapsed) followed by a 'Your current status' section.
+    // Available to unregistered agents — does NOT require registration.
+    server.registerTool("cello_setup_guidance", {
+        description: "Get the full CELLO setup guide and your current status. Always shows all 6 steps. Call this first to understand how to use CELLO.",
+        inputSchema: {},
+    }, async () => {
+        // AC-005 (DX-001): Demo agent ID from env var or constant — NOT hardcoded inline.
+        const demoAgentId = process.env["CELLO_DEMO_AGENT_ID"] ?? DEFAULT_DEMO_AGENT_ID;
+        // Gather current status
+        const regStateRaw = typeof client.getRegistrationState === "function"
+            ? client.getRegistrationState()
+            : null;
+        const registered = regStateRaw !== null;
+        const agentIdStr = registered ? regStateRaw.agent_id : null;
+        const connections = typeof client.listConnections === "function" ? client.listConnections() : [];
+        const sessions = client.listSessions().filter((s) => s.status === "active");
+        const dirReachable = directoryReachable();
+        // Determine current step for the pointer
+        let currentStep = 1;
+        let nextAction = "Call cello_register({ token: '<your token>' }) to register.";
+        if (registered && connections.length === 0) {
+            currentStep = 2;
+            nextAction = `Call cello_request_connection({ target_agent_id: '${demoAgentId}' }) to connect to the demo agent.`;
+        }
+        else if (registered && connections.length > 0 && sessions.length === 0) {
+            currentStep = 3;
+            const firstConn = connections[0];
+            nextAction = `Call cello_initiate_session({ target_agent_id: '${demoAgentId}' }) (or target_pubkey: '${firstConn.counterparty_pubkey}') to start a session.`;
+        }
+        else if (registered && sessions.length > 0) {
+            currentStep = 4;
+            const firstSession = sessions[0];
+            nextAction = `Call cello_send({ session_id: '${toHex(firstSession.session_id)}', content: 'Hello!' }) to send a message.`;
+        }
+        const guide = [
+            "# CELLO Setup Guide",
+            "",
+            "## Step 1: Get your registration token",
+            "Message @CelloConnectStagingBot on Telegram. Say 'register me' and it will send you a one-time token.",
+            "",
+            "## Step 2: Register with the directory",
+            "Call: cello_register({ token: 'CELLO-<your token>' })",
+            "This runs a cryptographic key ceremony (FROST DKG) with the directory. Takes 5-10 seconds.",
+            "",
+            "## Step 3: Connect to another agent",
+            `Call: cello_request_connection({ target_agent_id: '${demoAgentId}' })`,
+            `Or connect to any other agent by their agent_id (32 hex chars) or pubkey (64 hex chars).`,
+            "The demo agent is always online and will accept your connection automatically.",
+            "",
+            "## Step 4: Start a session",
+            `Call: cello_initiate_session({ target_agent_id: '${demoAgentId}' })`,
+            "A session is an encrypted, tamper-evident message channel.",
+            "",
+            "## Step 5: Send and receive messages",
+            "Call: cello_send({ session_id: '<session_id>', content: 'Hello!' })",
+            "Call: cello_receive({ timeout_ms: 10000 }) to receive replies",
+            "",
+            "## Step 6: Close the session and get your permanent record",
+            "Call: cello_close_session({ session_id: '<session_id>' })",
+            "Call: cello_get_sealed_receipt({ session_id: '<session_id>' }) for a cryptographic proof",
+            "",
+            "---",
+            "## Your current status",
+            `Registered: ${registered ? `YES (agent_id: ${agentIdStr})` : "NO"}`,
+            `Connections: ${connections.length}`,
+            `Active sessions: ${sessions.length}`,
+            `Directory reachable: ${dirReachable ? "YES" : "NO"}`,
+            "",
+            `→ You are at Step ${currentStep}. ${nextAction}`,
+        ].join("\n");
+        return { content: [{ type: "text", text: guide }] };
+    });
     // ── cello_register ────────────────────────────────────────────────────────
     //
     // REG-001: DKG registration. Idempotent — second call returns already_registered.
     // SI-001: never emits ML-DSA secret key material.
     server.registerTool("cello_register", {
-        description: "Register this agent with the CELLO directory. Runs the REG-001 DKG ceremony. Idempotent — returns already_registered if already done.",
+        description: "Register this agent with the CELLO directory. Runs the REG-001 DKG ceremony. Idempotent — returns already_registered if already done. Obtain your token from @CelloConnectStagingBot on Telegram.",
         inputSchema: {
-            phone_stub: z.string().describe("Phone stub for identity binding (format: +E.164 or hex stub)"),
-            pre_auth_token: z.string().optional().describe("OPS-AGENT-001: Pre-authorization token issued by POST /internal/pre-authorize. Required in M6+. Use any 'DEV-' prefixed token in CELLO_ENV=local."),
+            // AC-006 (DX-001): phone_stub removed from user-facing schema; token renamed from pre_auth_token.
+            // The client sends phone_stub='' internally (directory accepts empty when token is present).
+            token: z.string().describe("Pre-authorization token from @CelloConnectStagingBot on Telegram. Format: CELLO-<33 base58 chars> (production) or DEV-<...> (local). SI-001: this token must not appear in any log or response."),
         },
-    }, async ({ phone_stub, pre_auth_token }) => {
-        const result = await client.register(phone_stub, pre_auth_token);
+    }, async ({ token }) => {
+        // AC-006 (DX-001): phone_stub is not a user-facing parameter.
+        // Send '' as the wire value — the directory accepts empty phone_stub when pre_auth_token is valid.
+        // SI-001: the token must NOT appear in any log event, error message, or MCP tool response.
+        const result = await client.register("", token);
         if ("error" in result) {
             return jsonText({ error: { reason: result.error } });
         }
@@ -848,21 +1029,64 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
     // ── cello_request_connection ───────────────────────────────────────────────
     //
     // CONNREQ-002: Send Round 1 connection_request to target B.
-    // Blocks up to 5 min (directory default). Returns accepted/rejected/etc.
+    // AC-004 (DX-001): requires registration.
+    // AC-007 (DX-001): accepts target_agent_id (32 hex) in addition to target_pubkey (64 hex).
+    // AC-008 (DX-001): per-stage timeouts (10s dial, 10s send, 90s wait).
     server.registerTool("cello_request_connection", {
-        description: "Send a connection request to a target agent. Blocks until the target responds (up to 5 minutes).",
+        description: "Send a connection request to a target agent. Accepts either target_pubkey (64 hex chars) or target_agent_id (32 hex chars — looks up pubkey from directory). Blocks until the target responds or timeouts per stage.",
         inputSchema: {
-            target_pubkey: z.string().describe("Target agent's own_pubkey (Ed25519 identity key) as lowercase hex (64 chars). This is the value from cello_status().own_pubkey on the target agent — NOT their primary_pubkey."),
+            target_pubkey: z.string().optional().describe("Target agent's K_local pubkey as lowercase hex (64 chars). Use this if you know the raw pubkey."),
+            target_agent_id: z.string().optional().describe("Target agent's agent_id as lowercase hex (32 chars). The directory resolves this to a pubkey automatically."),
             include_endorsements: z.boolean().optional().describe("Include endorsements in the connection package"),
             include_attestations: z.boolean().optional().describe("Include attestations in the connection package"),
         },
-    }, async ({ target_pubkey }) => {
+    }, async ({ target_pubkey, target_agent_id }) => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
+        // AC-009 (DX-001): await background init before attempting connection
+        try {
+            await awaitReady();
+        }
+        catch { /* proceed — per-stage timeouts handle directory_unreachable */ }
         const extendedClient = client;
+        // AC-007 (DX-001): resolve target_agent_id to target_pubkey via /agent-lookup
+        // This runs BEFORE the cello_request_connection function check so that agent_id
+        // and missing_target errors are returned with clear messages in all cases.
+        let resolvedTargetPubkey = target_pubkey;
+        if (!resolvedTargetPubkey && target_agent_id) {
+            if (!/^[0-9a-f]{32}$/i.test(target_agent_id)) {
+                return jsonText({ error: { reason: "invalid_target_agent_id", message: "target_agent_id must be exactly 32 lowercase hex chars" } });
+            }
+            if (!directoryHttpUrl) {
+                return jsonText({ error: { reason: "directory_not_configured", message: "Cannot resolve agent_id: directory URL is not configured." } });
+            }
+            const t0Lookup = Date.now();
+            try {
+                const resp = await fetch(`${directoryHttpUrl}/agent-lookup?agent_id=${target_agent_id}`, { signal: AbortSignal.timeout(10_000) });
+                if (!resp.ok) {
+                    logger?.warn("client.directory.agent_lookup.failed", { agentId: target_agent_id, endpoint: `${directoryHttpUrl}/agent-lookup`, httpStatus: resp.status, reason: "http_error", durationMs: Date.now() - t0Lookup });
+                    return jsonText({ error: { reason: "agent_not_found", agent_id: target_agent_id } });
+                }
+                const body = await resp.json();
+                if (!body.k_local_pubkey) {
+                    logger?.warn("client.directory.agent_lookup.failed", { agentId: target_agent_id, endpoint: `${directoryHttpUrl}/agent-lookup`, httpStatus: resp.status, reason: "missing_pubkey_in_response", durationMs: Date.now() - t0Lookup });
+                    return jsonText({ error: { reason: "agent_not_found", agent_id: target_agent_id } });
+                }
+                resolvedTargetPubkey = body.k_local_pubkey;
+            }
+            catch (e) {
+                const reason = e instanceof Error ? e.message : String(e);
+                logger?.warn("client.directory.agent_lookup.failed", { agentId: target_agent_id, endpoint: `${directoryHttpUrl}/agent-lookup`, httpStatus: 0, reason, durationMs: Date.now() - t0Lookup });
+                return jsonText({ error: { reason: "agent_not_found", agent_id: target_agent_id } });
+            }
+        }
+        if (!resolvedTargetPubkey) {
+            return jsonText({ error: { reason: "missing_target", message: "Provide either target_pubkey (64 hex) or target_agent_id (32 hex)." } });
+        }
         if (typeof extendedClient.cello_request_connection !== "function") {
-            return jsonText({ error: { reason: "not_registered" } });
+            return jsonText({ error: { reason: "not_implemented" } });
         }
         // Build a real ConnectionPackage (pseudonym binding) from registration state.
-        // Falls back to an empty package if the agent is not yet registered.
         let packageCbor = new Uint8Array(0);
         const regState = typeof extendedClient.getRegistrationState === "function"
             ? extendedClient.getRegistrationState()
@@ -890,8 +1114,12 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             }
         }
         const result = await extendedClient.cello_request_connection({
-            target_pubkey,
+            target_pubkey: resolvedTargetPubkey,
             package_cbor: packageCbor,
+            // AC-008 (DX-001): per-stage timeouts
+            dialTimeoutMs: 10_000,
+            sendTimeoutMs: 10_000,
+            waitTimeoutMs: 90_000,
         });
         if (result.result === "established") {
             return jsonText({ result: "accepted", connection_id: result.connection_id });
@@ -910,7 +1138,16 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             });
         }
         if (result.result === "timeout") {
-            return jsonText({ result: "timeout" });
+            // AC-008: stage-specific error messages
+            const stage = result.stage;
+            if (stage === "dial") {
+                return jsonText({ error: { reason: "directory_unreachable_timeout", message: "Could not reach directory. Check your network connection." } });
+            }
+            if (stage === "send") {
+                return jsonText({ error: { reason: "request_delivery_timeout", message: "Connection request not delivered to directory." } });
+            }
+            // Default: target response timeout
+            return jsonText({ error: { reason: "target_response_timeout", message: "Target agent did not respond within 90s. The agent may be offline. Try again with cello_request_connection." } });
         }
         return jsonText({ error: { reason: result.reason } });
     });
@@ -925,6 +1162,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             include_attestations: z.boolean().optional().describe("Include attestations in the updated package"),
         },
     }, async ({ connection_request_id }) => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         const extendedClient = client;
         if (typeof extendedClient.cello_respond_to_disclosure_request !== "function") {
             return jsonText({ error: { reason: "no_pending_disclosure_request" } });
@@ -982,6 +1221,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             timeout_ms: z.number().int().min(0).optional().describe("Maximum wait time in ms. Default: 30000"),
         },
     }, async ({ timeout_ms }) => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         const result = await client.awaitConnectionRequest(timeout_ms ?? 30_000);
         if (result.type === "timeout") {
             return jsonText({ type: "timeout" });
@@ -1003,6 +1244,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             connection_request_id: z.string().describe("Connection request ID from cello_await_connection_request"),
         },
     }, async ({ connection_request_id }) => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         const result = await client.acceptConnection(connection_request_id);
         if ("error" in result) {
             return jsonText({ error: result.error });
@@ -1019,6 +1262,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             reason: z.string().optional().describe("Optional rejection reason"),
         },
     }, async ({ connection_request_id, reason }) => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         const result = await client.rejectConnection(connection_request_id, reason);
         if ("error" in result) {
             return jsonText({ error: result.error });
@@ -1036,6 +1281,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             requested_items: z.array(z.record(z.string(), z.unknown())).describe("List of disclosure items to request"),
         },
     }, async ({ connection_request_id, requested_items }) => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         const result = await client.requestMoreDisclosure(connection_request_id, requested_items);
         if ("error" in result) {
             return jsonText({ error: result.error });
@@ -1049,6 +1296,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
         description: "List all active connections for this agent.",
         inputSchema: {},
     }, async () => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         const records = client.listConnections();
         const connections = records.map((c) => ({
             connection_id: c.connection_id,
@@ -1073,6 +1322,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             })).optional().describe("Signal requirements (optional)"),
         },
     }, async ({ mode, review_mode, requirements }) => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         const policy = {
             mode,
             review_mode,
@@ -1096,6 +1347,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
         description: "Return the current connection policy configuration.",
         inputSchema: {},
     }, async () => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         const getFn = client.getPolicy;
         const policy = typeof getFn === "function"
             ? getFn.call(client)
@@ -1116,6 +1369,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             "Returns ok:true on success. Returns ok:false with reason if backup fails or is not configured.",
         inputSchema: {},
     }, async () => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         if (!clientBackup) {
             return jsonText({ ok: false, reason: "not_configured" });
         }
@@ -1138,6 +1393,8 @@ export function createMcpSessionServer(node, client, keyProvider, opts) {
             "Returns ok:true on success. Returns ok:false with reason if restore fails or is not configured.",
         inputSchema: {},
     }, async () => {
+        if (!isRegistered())
+            return NOT_REGISTERED_ERROR;
         if (!clientBackup) {
             return jsonText({ ok: false, reason: "not_configured" });
         }