nolo-cli 0.1.19 → 0.1.21

package/agentRuntimeCommands.ts

@@ -7,8 +7,14 @@ import {
   buildMachinePermissionPromptBlock,
   resolveMachineRunPermissionPolicy,
 } from "./ai/agent/machineRunPermissions";
-import { resolveConnectorWebSocketTarget } from "./connectorWebSocketTarget";
-import { DEFAULT_NOLO_SERVER_URL } from "./defaultServer";
+import { resolveConnectorWebSocketTarget } from "./connectorWebSocketTarget";
+import { DEFAULT_NOLO_SERVER_URL } from "./defaultServer";
+import { resolveCliAgentKeyInput } from "./agentAliases";
+import {
+  collectConnectorRunArtifact,
+  readConnectorGitHead,
+  resolveConnectorRunCwd,
+} from "./connectorRunArtifact";
 
 type EnvLike = Record<string, string | undefined>;
 type OutputLike = { write(chunk: string): unknown };
@@ -21,7 +27,7 @@ type SmokeWebSocketOptions = {
 type LocalCliExecutor = (
   provider: string,
   prompt: string,
-  options: { model?: string; yolo?: boolean }
+  options: { model?: string; timeout?: number; cwd?: string; yolo?: boolean }
 ) => Promise<{ text: string; raw?: string; elapsed?: number }>;
 type LocalRuntimeProbeResult = {
   ok: boolean;
@@ -32,9 +38,10 @@ type LocalRuntimeProbeResult = {
 };
 
 type AgentRuntimeCommandDeps = {
-  env?: EnvLike;
-  output?: OutputLike;
-  fetchImpl?: typeof fetch;
+  env?: EnvLike;
+  output?: OutputLike;
+  fetchImpl?: typeof fetch;
+  fallbackFetchImpl?: typeof fetch;
   machineInfo?: () => MachineHeartbeat;
   connectWebSocket?: (url: string, options: SmokeWebSocketOptions) => Promise<void>;
   executeCli?: LocalCliExecutor;
@@ -118,7 +125,11 @@ function readOption(args: string[], flag: string) {
   return index >= 0 ? args[index + 1] : undefined;
 }
 
-async function defaultExecuteCli(provider: string, prompt: string, options: { model?: string; yolo?: boolean }) {
+async function defaultExecuteCli(
+  provider: string,
+  prompt: string,
+  options: { model?: string; timeout?: number; cwd?: string; yolo?: boolean }
+) {
   const { executeCli } = await import("./ai/agent/cliExecutor");
   return executeCli(provider as any, prompt, options);
 }
@@ -127,16 +138,23 @@ function detectLaunchableMachineInfo() {
   return detectMachineInfo({ probeLaunchable: true });
 }
 
-function buildConnectorCliPrompt(agentConfig: any, userInput: string) {
+function buildConnectorCliPrompt(agentConfig: any, userInput: string) {
   const policy = resolveMachineRunPermissionPolicy(agentConfig);
   return [
     typeof agentConfig?.prompt === "string" ? agentConfig.prompt.trim() : "",
     buildMachinePermissionPromptBlock(policy),
     `--- User task ---\n${userInput}`,
-  ].filter(Boolean).join("\n\n");
-}
-
-function requiredCapabilityForAgent(agent: any) {
+  ].filter(Boolean).join("\n\n");
+}
+
+function normalizeConnectorRunTimeoutMs(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return undefined;
+  }
+  return Math.floor(value);
+}
+
+function requiredCapabilityForAgent(agent: any) {
   if (agent?.apiSource !== "cli") return "";
   const cliProvider = String(agent?.cliProvider || "").trim();
   const capabilityByProvider: Record<string, string> = {
@@ -146,10 +164,26 @@ function requiredCapabilityForAgent(agent: any) {
     gemini: "gemini-cli",
     kimi: "kimi-cli",
   };
-  return capabilityByProvider[cliProvider] ?? "";
-}
+  return capabilityByProvider[cliProvider] ?? "";
+}
+
+function classifyAgentRuntime(agent: any) {
+  if (agent?.apiSource === "cli") return "cli-machine";
+  if (agent?.apiSource === "platform" || agent?.useServerProxy) return "platform-local-loop";
+  if (agent?.apiSource === "local") return "local-provider-loop";
+  return "unknown";
+}
+
+function shouldRuntimeDoctorPass(args: {
+  runtimeClass: string;
+  requiredCapability: string;
+  hasCapability: boolean;
+}) {
+  if (args.runtimeClass !== "cli-machine") return args.runtimeClass !== "unknown";
+  return Boolean(args.requiredCapability && args.hasCapability);
+}
 
-function assertSmokeCompatible(agent: any, machine: MachineHeartbeat) {
+function assertSmokeCompatible(agent: any, machine: MachineHeartbeat) {
   if (agent?.apiSource !== "cli") {
     throw new Error(`Agent ${agent?.name ?? agent?.dbKey ?? "unknown"} is not a CLI agent.`);
   }
@@ -164,26 +198,52 @@ function assertSmokeCompatible(agent: any, machine: MachineHeartbeat) {
     throw new Error(
       `Agent ${agent?.name ?? agent?.dbKey ?? "unknown"} requires ${requiredCapability}; current machine capabilities: ${currentCapabilities}.`
     );
-  }
-}
-
-async function defaultConnectWebSocket(url: string, options: SmokeWebSocketOptions) {
+  }
+}
+
+const CONNECTOR_WS_KEEPALIVE_MS = 25_000;
+
+function buildConnectorKeepaliveMessage() {
+  return JSON.stringify({ type: "connector.keepalive", sentAt: Date.now() });
+}
+
+async function defaultConnectWebSocket(url: string, options: SmokeWebSocketOptions) {
   const WebSocketCtor = globalThis.WebSocket;
   if (!WebSocketCtor) {
     throw new Error("WebSocket is not available in this runtime");
-  }
-  await new Promise<void>((resolve, reject) => {
-    const ws = new WebSocketCtor(url, { headers: options.headers } as any);
-    ws.addEventListener("open", () => {
-      Promise.resolve(options.onOpen())
-        .then(() => ws.close())
-        .catch((error) => {
-          ws.close();
-          reject(error);
-        });
-    }, { once: true });
-    ws.addEventListener("error", () => reject(new Error("connector websocket failed")));
-    ws.addEventListener("close", () => resolve(), { once: true });
+  }
+  await new Promise<void>((resolve, reject) => {
+    const ws = new WebSocketCtor(url, { headers: options.headers } as any);
+    let keepalive: ReturnType<typeof setInterval> | null = null;
+    const clearKeepalive = () => {
+      if (keepalive) {
+        clearInterval(keepalive);
+        keepalive = null;
+      }
+    };
+    ws.addEventListener("open", () => {
+      keepalive = setInterval(() => {
+        try {
+          ws.send(buildConnectorKeepaliveMessage());
+        } catch {
+          clearKeepalive();
+        }
+      }, CONNECTOR_WS_KEEPALIVE_MS);
+      Promise.resolve(options.onOpen())
+        .then(() => ws.close())
+        .catch((error) => {
+          ws.close();
+          reject(error);
+        });
+    }, { once: true });
+    ws.addEventListener("error", () => {
+      clearKeepalive();
+      reject(new Error("connector websocket failed"));
+    });
+    ws.addEventListener("close", () => {
+      clearKeepalive();
+      resolve();
+    }, { once: true });
     ws.addEventListener("message", (event) => {
       const startIndex = options.sentMessages.length;
       Promise.resolve(options.onMessage(String(event.data))).then(() => {
@@ -212,27 +272,38 @@ async function handleSmokeConnectorMessage(
     if (agentConfig.apiSource !== "cli") {
       throw new Error("Connector can only execute CLI agents. Set the agent apiSource to cli and choose a cliProvider.");
     }
-    const provider = String(agentConfig.cliProvider || "copilot");
-    const policy = resolveMachineRunPermissionPolicy(agentConfig);
-    const userInput = String(parsed.payload?.userInput ?? "");
-    assertMachineRunAllowed(userInput, policy);
-    const result = await executeCli(
-      provider,
-      buildConnectorCliPrompt(agentConfig, userInput),
-      {
-        model: agentConfig.model || undefined,
-        yolo: true,
-      }
-    );
-    send(JSON.stringify({
-      type: "agent.run.result",
-      requestId: parsed.requestId,
+    const provider = String(agentConfig.cliProvider || "copilot");
+    const policy = resolveMachineRunPermissionPolicy(agentConfig);
+    const userInput = String(parsed.payload?.userInput ?? "");
+    const timeout = normalizeConnectorRunTimeoutMs(parsed.payload?.timeoutMs);
+    assertMachineRunAllowed(userInput, policy);
+    const cwd = resolveConnectorRunCwd({ env: process.env, policy });
+    const baseSha = await readConnectorGitHead(cwd);
+    const result = await executeCli(
+      provider,
+      buildConnectorCliPrompt(agentConfig, userInput),
+      {
+        model: agentConfig.model || undefined,
+        timeout,
+        cwd,
+        yolo: true,
+      }
+    );
+    const artifacts = await collectConnectorRunArtifact({
+      cwd,
+      baseSha,
+      exitStatus: "completed",
+    });
+    send(JSON.stringify({
+      type: "agent.run.result",
+      requestId: parsed.requestId,
       result: {
-        content: result.text,
-        model: agentConfig.model ?? provider,
-        trace: [{ role: "assistant", content: result.text }],
-      },
-    }));
+        content: result.text,
+        model: agentConfig.model ?? provider,
+        trace: [{ role: "assistant", content: result.text }],
+        artifacts,
+      },
+    }));
   } catch (error) {
     send(JSON.stringify({
       type: "agent.run.result",
@@ -242,54 +313,114 @@ async function handleSmokeConnectorMessage(
   }
 }
 
-async function readAgentRecord(args: {
-  agentKey: string;
-  authToken: string;
-  fetchImpl: typeof fetch;
-  serverUrl: string;
-}) {
-  const res = await args.fetchImpl(
-    `${args.serverUrl}/api/v1/db/read/${encodeURIComponent(args.agentKey)}`,
-    {
-      method: "GET",
-      headers: { Authorization: `Bearer ${args.authToken}` },
-    }
-  );
-  const data = await res.json().catch(() => ({}));
-  if (!res.ok) {
-    throw new Error(`read failed: HTTP ${res.status} ${JSON.stringify(data)}`);
-  }
+async function readAgentRecord(args: {
+  agentKey: string;
+  authToken: string;
+  fallbackFetchImpl?: typeof fetch;
+  fetchImpl: typeof fetch;
+  serverUrl: string;
+}) {
+  const res = await fetchWithTransportFallback(
+    `${args.serverUrl}/api/v1/db/read/${encodeURIComponent(args.agentKey)}`,
+    {
+      method: "GET",
+      headers: { Authorization: `Bearer ${args.authToken}` },
+    },
+    args
+  );
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(`read failed: HTTP ${res.status} ${JSON.stringify(data)}`);
+  }
   return data?.data ?? data;
 }
 
-async function writeAgentRecord(args: {
-  agentKey: string;
-  authToken: string;
-  fetchImpl: typeof fetch;
-  serverUrl: string;
-  userId: string;
-  record: Record<string, any>;
-}) {
-  const res = await args.fetchImpl(`${args.serverUrl}/api/v1/db/write/`, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${args.authToken}`,
-      "Content-Type": "application/json",
-    },
+async function writeAgentRecord(args: {
+  agentKey: string;
+  authToken: string;
+  fallbackFetchImpl?: typeof fetch;
+  fetchImpl: typeof fetch;
+  serverUrl: string;
+  userId: string;
+  record: Record<string, any>;
+}) {
+  const res = await fetchWithTransportFallback(`${args.serverUrl}/api/v1/db/write/`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${args.authToken}`,
+      "Content-Type": "application/json",
+    },
     body: JSON.stringify({
       customKey: args.agentKey,
       userId: args.userId,
       data: {
         ...args.record,
-        dbKey: args.agentKey,
-      },
-    }),
-  });
-  const data = await res.json().catch(() => ({}));
-  if (!res.ok) {
-    throw new Error(`write failed: HTTP ${res.status} ${JSON.stringify(data)}`);
-  }
-}
+        dbKey: args.agentKey,
+      },
+    }),
+  }, args);
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    throw new Error(`write failed: HTTP ${res.status} ${JSON.stringify(data)}`);
+  }
+}
+
+function shouldUseCurlTransportFallback(error: unknown) {
+  const message = error instanceof Error ? error.message : String(error);
+  return /Unable to connect|ConnectionRefused|ECONNREFUSED|Failed to connect|Was there a typo|timed out|Timeout|handshake|certificate|ECONNRESET|socket|network/i.test(message);
+}
+
+async function curlFetch(url: string, init?: RequestInit): Promise<Response> {
+  const method = init?.method ?? "GET";
+  const headers = new Headers(init?.headers ?? {});
+  const command = ["curl", "-sS", "-L", "-X", method];
+
+  headers.forEach((value, key) => {
+    command.push("-H", `${key}: ${value}`);
+  });
+
+  if (typeof init?.body === "string" && init.body.length > 0) {
+    command.push("--data", init.body);
+  }
+
+  command.push("-w", "\n__NOLO_STATUS__:%{http_code}", url);
+  const proc = Bun.spawn(command, { stdout: "pipe", stderr: "pipe" });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (exitCode !== 0) {
+    throw new Error(stderr.trim() || `curl failed for ${url}`);
+  }
+
+  const marker = "\n__NOLO_STATUS__:";
+  const markerIndex = stdout.lastIndexOf(marker);
+  const body = markerIndex >= 0 ? stdout.slice(0, markerIndex) : stdout;
+  const statusText = markerIndex >= 0 ? stdout.slice(markerIndex + marker.length).trim() : "0";
+  const status = Number(statusText);
+  return new Response(body, {
+    status: Number.isFinite(status) ? status : 0,
+    headers: { "Content-Type": headers.get("Content-Type") ?? "application/json" },
+  });
+}
+
+async function fetchWithTransportFallback(
+  url: string,
+  init: RequestInit,
+  options: { fallbackFetchImpl?: typeof fetch; fetchImpl: typeof fetch }
+): Promise<Response> {
+  try {
+    return await options.fetchImpl(url, init);
+  } catch (error) {
+    if (!shouldUseCurlTransportFallback(error)) throw error;
+    if (options.fallbackFetchImpl) {
+      return options.fallbackFetchImpl(url, init);
+    }
+    if (options.fetchImpl !== fetch) throw error;
+    return curlFetch(url, init);
+  }
+}
 
 async function heartbeatCurrentMachine(args: {
   authToken: string;
@@ -311,10 +442,10 @@ async function heartbeatCurrentMachine(args: {
   }
 }
 
-export async function runAgentBindCurrentCommand(
-  args: string[],
-  deps: AgentRuntimeCommandDeps = {}
-) {
+export async function runAgentBindCurrentCommand(
+  args: string[],
+  deps: AgentRuntimeCommandDeps = {}
+) {
   const env = deps.env ?? process.env;
   const output = deps.output ?? process.stdout;
   const agentKey = args[0]?.trim();
@@ -335,13 +466,14 @@ export async function runAgentBindCurrentCommand(
     return 1;
   }
 
-  const serverUrl = resolveServerUrl(env);
-  const fetchImpl = deps.fetchImpl ?? fetch;
-  const machine = (deps.machineInfo ?? detectLaunchableMachineInfo)();
-
-  try {
-    await heartbeatCurrentMachine({ authToken, fetchImpl, machine, serverUrl });
-    const existing = await readAgentRecord({ agentKey, authToken, fetchImpl, serverUrl });
+  const serverUrl = resolveServerUrl(env);
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const fallbackFetchImpl = deps.fallbackFetchImpl;
+  const machine = (deps.machineInfo ?? detectLaunchableMachineInfo)();
+
+  try {
+    await heartbeatCurrentMachine({ authToken, fetchImpl, machine, serverUrl });
+    const existing = await readAgentRecord({ agentKey, authToken, fallbackFetchImpl, fetchImpl, serverUrl });
     const updated = {
       ...existing,
       runtimeBinding: {
@@ -354,11 +486,12 @@ export async function runAgentBindCurrentCommand(
       updatedAt: Date.now(),
     };
     await writeAgentRecord({
-      agentKey,
-      authToken,
-      fetchImpl,
-      serverUrl,
-      userId,
+      agentKey,
+      authToken,
+      fallbackFetchImpl,
+      fetchImpl,
+      serverUrl,
+      userId,
       record: updated,
     });
   } catch (error) {
@@ -370,21 +503,73 @@ export async function runAgentBindCurrentCommand(
     return 1;
   }
 
-  output.write(`Bound agent ${agentKey} to this machine: ${machine.name} (${machine.machineId})\n`);
-  return 0;
-}
-
-export async function runAgentSmokeCurrentCommand(
-  args: string[],
+  output.write(`Bound agent ${agentKey} to this machine: ${machine.name} (${machine.machineId})\n`);
+  return 0;
+}
+
+export async function runAgentReadCommand(
+  args: string[],
+  deps: AgentRuntimeCommandDeps = {}
+) {
+  const env = deps.env ?? process.env;
+  const output = deps.output ?? process.stdout;
+  const agentInput = args[0]?.trim();
+  if (!agentInput || agentInput === "--help" || agentInput === "-h") {
+    output.write("Usage: nolo agent read <agent>\n");
+    return agentInput ? 0 : 1;
+  }
+
+  const authToken = resolveAuthToken(env);
+  if (!authToken) {
+    output.write("[nolo] agent read requires an auth token. Run `nolo login` or set AUTH_TOKEN.\n");
+    return 1;
+  }
+
+  const agentKey = resolveCliAgentKeyInput(agentInput);
+  const serverUrl = resolveServerUrl(env);
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const fallbackFetchImpl = deps.fallbackFetchImpl;
+
+  try {
+    const agent = await readAgentRecord({ agentKey, authToken, fallbackFetchImpl, fetchImpl, serverUrl });
+    output.write(JSON.stringify({
+      agentKey,
+      baseUrl: serverUrl,
+      name: agent?.name,
+      greeting: agent?.greeting,
+      model: agent?.model,
+      provider: agent?.provider ?? agent?.apiSource ?? null,
+      customProviderUrl: agent?.customProviderUrl ?? null,
+      tools: agent?.tools ?? [],
+      isPublic: agent?.isPublic,
+      authUserId: parseUserIdFromAuthToken(authToken),
+      userId: agent?.userId,
+      record: agent,
+    }, null, 2));
+    output.write("\n");
+    return 0;
+  } catch (error) {
+    output.write(
+      `[nolo] agent read failed: ${
+        error instanceof Error ? error.message : String(error)
+      }\n`
+    );
+    return 1;
+  }
+}
+
+export async function runAgentSmokeCurrentCommand(
+  args: string[],
   deps: AgentRuntimeCommandDeps = {}
 ) {
   const env = deps.env ?? process.env;
   const output = deps.output ?? process.stdout;
-  const agentKey = args[0]?.trim();
-  if (!agentKey || agentKey === "--help" || agentKey === "-h") {
-    output.write("Usage: nolo agent smoke-current <agentKey> --msg \"hello\"\n");
-    return agentKey ? 0 : 1;
-  }
+  const agentInput = args[0]?.trim();
+  if (!agentInput || agentInput === "--help" || agentInput === "-h") {
+    output.write("Usage: nolo agent smoke-current <agent> --msg \"hello\"\n");
+    return agentInput ? 0 : 1;
+  }
+  const agentKey = resolveCliAgentKeyInput(agentInput);
 
   const authToken = resolveAuthToken(env);
   if (!authToken) {
@@ -397,22 +582,24 @@ export async function runAgentSmokeCurrentCommand(
     return 1;
   }
 
-  const userInput = readOption(args, "--msg") ?? "Smoke test from nolo connector.";
-  const serverUrl = resolveServerUrl(env);
-  const fetchImpl = deps.fetchImpl ?? fetch;
-  const machine = (deps.machineInfo ?? detectLaunchableMachineInfo)();
+  const userInput = readOption(args, "--msg") ?? "Smoke test from nolo connector.";
+  const serverUrl = resolveServerUrl(env);
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const fallbackFetchImpl = deps.fallbackFetchImpl;
+  const machine = (deps.machineInfo ?? detectLaunchableMachineInfo)();
   const sentMessages: string[] = [];
 
-  try {
-    await heartbeatCurrentMachine({ authToken, fetchImpl, machine, serverUrl });
-    const existing = await readAgentRecord({ agentKey, authToken, fetchImpl, serverUrl });
+  try {
+    await heartbeatCurrentMachine({ authToken, fetchImpl, machine, serverUrl });
+    const existing = await readAgentRecord({ agentKey, authToken, fallbackFetchImpl, fetchImpl, serverUrl });
     assertSmokeCompatible(existing, machine);
     await writeAgentRecord({
-      agentKey,
-      authToken,
-      fetchImpl,
-      serverUrl,
-      userId,
+      agentKey,
+      authToken,
+      fallbackFetchImpl,
+      fetchImpl,
+      serverUrl,
+      userId,
       record: {
         ...existing,
         runtimeBinding: {
@@ -477,16 +664,17 @@ export async function runAgentSmokeCurrentCommand(
 }
 
 export async function runAgentRuntimeDoctorCommand(
-  args: string[],
-  deps: AgentRuntimeCommandDeps = {}
-) {
+  args: string[],
+  deps: AgentRuntimeCommandDeps = {}
+) {
   const env = deps.env ?? process.env;
   const output = deps.output ?? process.stdout;
-  const agentKey = args[0]?.trim();
-  if (!agentKey || agentKey === "--help" || agentKey === "-h") {
-    output.write("Usage: nolo agent runtime-doctor <agentKey>\n");
-    return agentKey ? 0 : 1;
-  }
+  const agentInput = args[0]?.trim();
+  if (!agentInput || agentInput === "--help" || agentInput === "-h") {
+    output.write("Usage: nolo agent runtime-doctor <agentKey>\n");
+    return agentInput ? 0 : 1;
+  }
+  const agentKey = resolveCliAgentKeyInput(agentInput);
 
   const authToken = resolveAuthToken(env);
   if (!authToken) {
@@ -494,31 +682,33 @@ export async function runAgentRuntimeDoctorCommand(
     return 1;
   }
 
-  const serverUrl = resolveServerUrl(env);
-  const fetchImpl = deps.fetchImpl ?? fetch;
-  const machine = (deps.machineInfo ?? detectLaunchableMachineInfo)();
-
-  try {
-    const agent = await readAgentRecord({ agentKey, authToken, fetchImpl, serverUrl });
-    const requiredCapability = requiredCapabilityForAgent(agent);
-    const isBoundToCurrent = agent?.runtimeBinding?.machineId === machine.machineId;
-    const hasCapability = requiredCapability
-      ? machine.capabilities.includes(requiredCapability)
-      : false;
-    output.write(`Agent runtime doctor: ${agent?.name ?? agentKey}\n`);
-    output.write(`Agent key: ${agentKey}\n`);
-    output.write(`API source: ${agent?.apiSource ?? "unknown"}\n`);
-    output.write(`CLI provider: ${agent?.cliProvider ?? "none"}\n`);
-    output.write(`Required capability: ${requiredCapability || "none"}\n`);
-    output.write(`Current machine: ${machine.name} (${machine.machineId})\n`);
-    output.write(`Current machine capabilities: ${machine.capabilities.length ? machine.capabilities.join(", ") : "none"}\n`);
-    output.write(`Current machine binding: ${isBoundToCurrent ? "yes" : "no"}\n`);
-    output.write(`Current machine has required capability: ${hasCapability ? "yes" : "no"}\n`);
-
-    if (agent?.apiSource !== "cli") return 1;
-    if (!requiredCapability || !hasCapability) return 1;
-    return 0;
-  } catch (error) {
+  const serverUrl = resolveServerUrl(env);
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const fallbackFetchImpl = deps.fallbackFetchImpl;
+  const machine = (deps.machineInfo ?? detectLaunchableMachineInfo)();
+
+  try {
+    const agent = await readAgentRecord({ agentKey, authToken, fallbackFetchImpl, fetchImpl, serverUrl });
+    const requiredCapability = requiredCapabilityForAgent(agent);
+    const runtimeClass = classifyAgentRuntime(agent);
+    const isBoundToCurrent = agent?.runtimeBinding?.machineId === machine.machineId;
+    const hasCapability = requiredCapability
+      ? machine.capabilities.includes(requiredCapability)
+      : false;
+    output.write(`Agent runtime doctor: ${agent?.name ?? agentKey}\n`);
+    if (agentInput !== agentKey) output.write(`Agent input: ${agentInput}\n`);
+    output.write(`Agent key: ${agentKey}\n`);
+    output.write(`Runtime class: ${runtimeClass}\n`);
+    output.write(`API source: ${agent?.apiSource ?? "unknown"}\n`);
+    output.write(`CLI provider: ${agent?.cliProvider ?? "none"}\n`);
+    output.write(`Required capability: ${requiredCapability || "none"}\n`);
+    output.write(`Current machine: ${machine.name} (${machine.machineId})\n`);
+    output.write(`Current machine capabilities: ${machine.capabilities.length ? machine.capabilities.join(", ") : "none"}\n`);
+    output.write(`Current machine binding: ${runtimeClass === "cli-machine" ? (isBoundToCurrent ? "yes" : "no") : "not required"}\n`);
+    output.write(`Current machine has required capability: ${requiredCapability ? (hasCapability ? "yes" : "no") : "not required"}\n`);
+
+    return shouldRuntimeDoctorPass({ runtimeClass, requiredCapability, hasCapability }) ? 0 : 1;
+  } catch (error) {
     output.write(
       `[nolo] agent runtime-doctor failed: ${
         error instanceof Error ? error.message : String(error)