nolo-cli 0.1.32 → 0.1.33

package/cli/client/agentRun.ts

@@ -1,30 +1,39 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { normalizeAgentRunDialogLineage } from "../../ai/agent/agentRunDialogLineage";
-import type { AgentRuntimeHostAdapter, AgentRuntimeRequestedMode } from "../agentRuntimeLocal";
-import type { EnvLike } from "../cliEnvHelpers";
-import type { OutputLike } from "../cliIoTypes";
-import type { TaskRunPromptContext } from "./taskRunPrompt";
-import { type TaskRunRecorder } from "./agentRunTaskRunRecorder";
-import { buildUserInputContent } from "./agentRunInput";
-import {
-  resolveRequestedRuntimeMode,
-  shouldAttemptAutoLocal,
-  shouldSkipAutoLocalForServerPlatformTools,
-  shouldUseScriptBridge,
-} from "./agentRunRuntimeSelection";
+import { runLocalAgentTurn } from "../agentRuntimeLocal";
+import { LOCAL_AGENT_CONFIG_MISSING_CODE } from "../../agent-runtime/localLoop";
 import {
-  isMissingLocalAgentConfigError,
-  refreshMissingLocalAgentConfig,
-  resolveLocalRuntimeAdapter,
-  runInjectedLocalAgentTurn,
-  runLocalAgentTurnWithAutoRoundExpansion,
-} from "./agentRunLocalExecutor";
-import { runHttpAgentTurn } from "./agentRunServerTransport";
-export { classifyTaskRunReviewStatus } from "./agentRunLocalExecution";
-export { findServerPlatformTools, shouldUseScriptBridge } from "./agentRunRuntimeSelection";
-
-export type RunAgentTurnOptions = {
+  FRONTEND_IMPLEMENTER_AGENT_KEY,
+  NOLO_FULLSTACK_AGENT_KEY,
+  NOLO_PROJECT_MANAGER_AGENT_KEY,
+  NOLO_REVIEW_AGENT_KEY,
+  NOLO_SENIOR_FULLSTACK_AGENT_KEY,
+} from "../agentAliases";
+import type { LocalAgentToolEvent } from "../../agent-runtime/localLoop";
+import type { AgentRuntimeHostAdapter, AgentRuntimeRequestedMode } from "../agentRuntimeLocal";
+import { createCliLocalRuntimeAdapter } from "./localRuntimeAdapter";
+import { createStreamingTextWriter } from "./streamingOutput";
+import { prependTaskRunPrompt, type TaskRunPromptContext } from "./taskRunPrompt";
+
+type EnvLike = Record<string, string | undefined>;
+
+type OutputLike = {
+  write(chunk: string): unknown;
+};
+
+type TaskRunAgentRole = "pm" | "frontend" | "fullstack" | "reviewer" | "codex";
+type TaskRunReviewStatus = "passed" | "needs_changes" | "blocked";
+type TaskRunToolEvidence = {
+  toolsUsed: string[];
+  summary: {
+    callCount: number;
+    resultCount: number;
+    errorCount: number;
+    rounds: number;
+  };
+};
+
+type RunAgentTurnOptions = {
   agentName: string;
   agentKey: string;
   serverUrl: string;
@@ -49,7 +58,14 @@ export type RunAgentTurnOptions = {
   timeoutMs?: number;
   traceTools?: boolean;
   taskRunContext?: TaskRunPromptContext;
-  taskRunRecorder?: TaskRunRecorder<RunAgentTurnOptions>;
+  taskRunRecorder?: (args: {
+    options: RunAgentTurnOptions;
+    status: "running" | "completed" | "failed";
+    dialogId?: string;
+    resultSummary?: string;
+    errorCode?: string;
+    toolEvidence?: TaskRunToolEvidence;
+  }) => Promise<void>;
   scriptPathExists?: (path: string) => boolean;
   fetchImpl?: typeof fetch;
 };
@@ -59,12 +75,446 @@ export type RunAgentTurnResult = {
   dialogId?: string;
   streamInterrupted?: boolean;
 };
+
+type ScriptBridgeDecision = {
+  hasAuthToken: boolean;
+  scriptPathExists: boolean;
+};
+
+const SERVER_PLATFORM_TOOL_NAMES = new Set([
+  "addTableRow",
+  "addTableRows",
+  "deleteTableRow",
+  "deleteTableRows",
+  "queryTableRows",
+  "streamParallelAgents",
+  "taskRun",
+  "updateTableRow",
+  "updateTableRows",
+]);
+
+const KNOWN_SERVER_PLATFORM_AGENT_KEYS = new Set([
+  FRONTEND_IMPLEMENTER_AGENT_KEY,
+  NOLO_FULLSTACK_AGENT_KEY,
+  NOLO_PROJECT_MANAGER_AGENT_KEY,
+  NOLO_REVIEW_AGENT_KEY,
+  NOLO_SENIOR_FULLSTACK_AGENT_KEY,
+]);
+
+const KNOWN_SERVER_PLATFORM_AGENT_ALIASES = new Set([
+  "code-review",
+  "frontend",
+  "frontend-agent",
+  "frontend-implementer",
+  "full-stack",
+  "fullstack",
+  "nolo code review",
+  "nolo frontend",
+  "nolo fullstack",
+  "nolo project manager",
+  "nolo reviewer",
+  "nolo-code-review",
+  "nolo-frontend",
+  "nolo-fullstack",
+  "nolo-pm",
+  "nolo-project-manager",
+  "nolo-reviewer",
+  "pm",
+  "project-manager",
+  "review",
+  "reviewer",
+]);
+
+export function shouldUseScriptBridge(decision: ScriptBridgeDecision) {
+  return !decision.hasAuthToken && decision.scriptPathExists;
+}
+
+export function findServerPlatformTools(toolNames?: string[]) {
+  if (!Array.isArray(toolNames)) return [];
+  return toolNames.filter((toolName) => SERVER_PLATFORM_TOOL_NAMES.has(toolName));
+}
+
+function resolveServerPlatformToolNames(agentConfig: any) {
+  return findServerPlatformTools([
+    ...(Array.isArray(agentConfig?.toolNames) ? agentConfig.toolNames : []),
+    ...(Array.isArray(agentConfig?.runtimeToolPolicy?.agentTools)
+      ? agentConfig.runtimeToolPolicy.agentTools
+      : []),
+  ]);
+}
+
+function normalizeAgentRef(ref?: string) {
+  return ref?.trim().toLowerCase().replace(/\s+/g, " ");
+}
+
+function isKnownServerPlatformAgent(options: RunAgentTurnOptions) {
+  if (KNOWN_SERVER_PLATFORM_AGENT_KEYS.has(options.agentKey)) return true;
+  const normalizedKey = normalizeAgentRef(options.agentKey);
+  return Boolean(normalizedKey && KNOWN_SERVER_PLATFORM_AGENT_ALIASES.has(normalizedKey));
+}
+
+function resolveAuthToken(env: EnvLike) {
+  return env.AUTH_TOKEN || env.AUTH || env.BENCHMARK_AUTH_TOKEN || "";
+}
+
+function shouldShowUsage(env: EnvLike) {
+  return env.NOLO_DEBUG === "1" || env.NOLO_SHOW_USAGE === "1";
+}
+
+function resolveRequestedRuntimeMode(options: RunAgentTurnOptions) {
+  const envMode = options.env.NOLO_RUNTIME_MODE;
+  if (options.runtimeMode) return options.runtimeMode;
+  if (envMode === "local" || envMode === "server" || envMode === "auto") return envMode;
+  return "auto";
+}
+
+function buildDefaultLocalRuntimeAdapter(options: RunAgentTurnOptions) {
+  return createCliLocalRuntimeAdapter({
+    env: options.env,
+    fetchImpl: options.fetchImpl,
+    cwd: options.localRuntimeCwd,
+    output: options.output,
+  });
+}
+
+function resolveLocalRuntimeAdapter(options: RunAgentTurnOptions) {
+  return (
+    options.localRuntimeAdapter ||
+    options.localRuntimeAdapterFactory?.(options.env, { cwd: options.localRuntimeCwd }) ||
+    buildDefaultLocalRuntimeAdapter(options)
+  );
+}
+
+async function shouldSkipAutoLocalForServerPlatformTools(options: RunAgentTurnOptions) {
+  if (isKnownServerPlatformAgent(options)) {
+    options.output.write(
+      `[nolo] auto runtime: skipping local runtime because ${options.agentKey} is a known platform agent. ` +
+        "Use --local explicitly to force local workspace tools.\n"
+    );
+    return true;
+  }
+  const adapter = resolveLocalRuntimeAdapter(options);
+  if (!adapter) return false;
+  let agentConfig;
+  try {
+    agentConfig = await adapter.loadAgentConfig(options.agentKey);
+  } catch {
+    return false;
+  }
+  const serverTools = resolveServerPlatformToolNames(agentConfig);
+  if (serverTools.length === 0) return false;
+  options.output.write(
+    `[nolo] auto runtime: skipping local runtime because ${options.agentKey} declares server platform tools ` +
+      `(${serverTools.join(", ")}). Use --local explicitly to force local workspace tools.\n`
+  );
+  return true;
+}
+
+function buildUserInputContent(message: string, imageUrls: string[] = []) {
+  if (imageUrls.length === 0) return message;
+  return [
+    ...(message.trim() ? [{ type: "text" as const, text: message }] : []),
+    ...imageUrls.map((url) => ({
+      type: "image_url" as const,
+      image_url: { url },
+    })),
+  ];
+}
+
+function shouldTraceLocalTools(options: RunAgentTurnOptions) {
+  return Boolean(options.traceTools || options.env.NOLO_TRACE_TOOLS === "1");
+}
 
-function resolveAuthToken(env: EnvLike) {
-  return env.AUTH_TOKEN || env.AUTH || env.BENCHMARK_AUTH_TOKEN || "";
+function shouldCollectLocalToolEvidence(options: RunAgentTurnOptions) {
+  return Boolean(options.taskRunContext?.rowDbKey);
 }
 
-async function runScriptBridge(options: RunAgentTurnOptions, scriptPath: string) {
+function summarizeLocalToolEvidence(events: LocalAgentToolEvent[]): TaskRunToolEvidence | undefined {
+  if (events.length === 0) return undefined;
+  const toolsUsed = [
+    ...new Set(
+      events
+        .filter((event) => event.type === "tool-call")
+        .map((event) => event.toolName)
+        .filter(Boolean)
+    ),
+  ];
+  const rounds = new Set(events.map((event) => event.round)).size;
+  return {
+    toolsUsed,
+    summary: {
+      callCount: events.filter((event) => event.type === "tool-call").length,
+      resultCount: events.filter((event) => event.type === "tool-result").length,
+      errorCount: events.filter((event) => event.type === "tool-error").length,
+      rounds,
+    },
+  };
+}
+
+const DEFAULT_LOCAL_AGENT_TOOL_ROUND_RETRY_LIMIT = 512;
+
+function parseLocalToolRoundLimitError(error: unknown) {
+  const message = error instanceof Error ? error.message : String(error);
+  const match = message.match(/Local agent exceeded max tool rounds:\s*(\d+)/);
+  if (!match) return null;
+  return Number(match[1]);
+}
+
+function isMissingLocalAgentConfigError(error: unknown, agentRef: string) {
+  return Boolean(
+    error &&
+      typeof error === "object" &&
+      "code" in error &&
+      (error as { code?: string; agentRef?: string }).code === LOCAL_AGENT_CONFIG_MISSING_CODE &&
+      (error as { code?: string; agentRef?: string }).agentRef === agentRef
+  );
+}
+
+function parsePositiveInteger(value: string | undefined) {
+  if (!value) return null;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) return null;
+  return parsed;
+}
+
+function resolveLocalToolRoundRetryLimit(options: RunAgentTurnOptions) {
+  return (
+    parsePositiveInteger(options.env.NOLO_LOCAL_MAX_TOOL_ROUNDS_LIMIT) ??
+    DEFAULT_LOCAL_AGENT_TOOL_ROUND_RETRY_LIMIT
+  );
+}
+
+function nextLocalToolRoundLimit(current: number) {
+  return current <= 0 ? 1 : current * 2;
+}
+
+function formatToolTraceEvent(event: LocalAgentToolEvent) {
+  const round = event.round + 1;
+  if (event.type === "tool-call") {
+    return `[nolo:tool] round ${round} -> ${event.toolName} (${event.toolCallId})\n`;
+  }
+  if (event.type === "tool-error") {
+    return `[nolo:tool] round ${round} !! ${event.toolName}: ${event.message ?? "failed"}\n`;
+  }
+  return `[nolo:tool] round ${round} <- ${event.toolName} (${event.toolCallId})\n`;
+}
+
+function shouldAttemptAutoLocal(options: RunAgentTurnOptions) {
+  if (options.localRuntimeAdapter || options.localRuntimeAdapterFactory) return true;
+  return Boolean(
+    options.env.NOLO_LOCAL_OPENAI_API_KEY ||
+      options.env.OPENAI_API_KEY ||
+      options.env.NOLO_LOCAL_OPENAI_BASE_URL ||
+      options.env.OPENAI_BASE_URL ||
+      options.env.NOLO_LOCAL_AGENT_KEY
+  );
+}
+
+function inferTaskRunAgentRole(agentRef: string): TaskRunAgentRole {
+  const normalized = agentRef.toLowerCase();
+  if (normalized.includes("project-manager") || normalized.includes("manager")) return "pm";
+  if (normalized.includes("frontend")) return "frontend";
+  if (normalized.includes("fullstack")) return "fullstack";
+  if (normalized.includes("review")) return "reviewer";
+  return "codex";
+}
+
+export function classifyTaskRunReviewStatus(summary?: string): TaskRunReviewStatus | undefined {
+  const normalized = summary?.toLowerCase().trim();
+  if (!normalized) return undefined;
+
+  const explicit = normalized.match(/review\s+decision\s*:\s*(passed|needs_changes|blocked)/);
+  if (explicit?.[1]) return explicit[1] as TaskRunReviewStatus;
+
+  if (/\b(blocked|cannot review|unable to review)\b|无法审查|阻塞/.test(normalized)) {
+    return "blocked";
+  }
+  if (
+    /\b(needs changes|request changes|changes requested|not approved)\b|需要修改|需修改|发现问题/.test(
+      normalized
+    )
+  ) {
+    return "needs_changes";
+  }
+  if (/\b(approved|lgtm|no issues|passed)\b|通过|无问题/.test(normalized)) {
+    return "passed";
+  }
+  return undefined;
+}
+
+async function runTaskRunCli(args: {
+  options: RunAgentTurnOptions;
+  cliArgs: string[];
+}) {
+  const scriptPath = join(args.options.scriptDir, "taskRun.ts");
+  const proc = Bun.spawn({
+    cmd: [process.execPath, scriptPath, ...args.cliArgs],
+    stdout: "pipe",
+    stderr: "pipe",
+    env: {
+      ...process.env,
+      ...args.options.env,
+      BASE_URL: args.options.serverUrl,
+    },
+  });
+  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 || stdout || `taskRun.ts exited ${exitCode}`).trim());
+  }
+}
+
+async function defaultTaskRunRecorder(args: {
+  options: RunAgentTurnOptions;
+  status: "running" | "completed" | "failed";
+  dialogId?: string;
+  resultSummary?: string;
+  errorCode?: string;
+  toolEvidence?: TaskRunToolEvidence;
+}) {
+  const context = args.options.taskRunContext;
+  if (!context?.rowDbKey) return;
+  const role = inferTaskRunAgentRole(args.options.agentName || args.options.agentKey);
+  if (role === "reviewer" && args.status !== "running") {
+    await runTaskRunCli({
+      options: args.options,
+      cliArgs: [
+        "request-review",
+        "--row-dbkey",
+        context.rowDbKey,
+        "--base-url",
+        args.options.serverUrl,
+        "--reviewer-agent-key",
+        args.options.agentKey,
+        ...(context.artifactIds?.length ? ["--artifact-ids", context.artifactIds.join(",")] : []),
+        ...(args.dialogId ? ["--dialog-id", args.dialogId] : []),
+      ],
+    });
+  }
+  await runTaskRunCli({
+    options: args.options,
+    cliArgs: [
+      "record-agent-run",
+      "--row-dbkey",
+      context.rowDbKey,
+      "--base-url",
+      args.options.serverUrl,
+      "--agent-key",
+      args.options.agentKey,
+      "--role",
+      role,
+      "--run-status",
+      args.status,
+      ...(context.workItemId ? ["--work-item-id", context.workItemId] : []),
+      ...(args.dialogId ? ["--dialog-id", args.dialogId] : []),
+      ...(args.resultSummary ? ["--result-summary", args.resultSummary.slice(0, 240)] : []),
+      ...(args.errorCode ? ["--error-code", args.errorCode] : []),
+      ...(args.toolEvidence?.toolsUsed?.length
+        ? ["--tools-used", args.toolEvidence.toolsUsed.join(",")]
+        : []),
+      ...(args.toolEvidence?.summary
+        ? ["--tool-trace-summary", JSON.stringify(args.toolEvidence.summary)]
+        : []),
+    ],
+  });
+  if (context.workItemId && args.dialogId) {
+    await runTaskRunCli({
+      options: args.options,
+      cliArgs: [
+        "update-work-item",
+        "--row-dbkey",
+        context.rowDbKey,
+        "--base-url",
+        args.options.serverUrl,
+        "--id",
+        context.workItemId,
+        "--dialog-ids",
+        args.dialogId,
+      ],
+    });
+  }
+  if (role === "reviewer" && args.status !== "running") {
+    const reviewStatus =
+      args.status === "failed" ? "blocked" : classifyTaskRunReviewStatus(args.resultSummary);
+    if (reviewStatus) {
+      await runTaskRunCli({
+        options: args.options,
+        cliArgs: [
+          "review-result",
+          "--row-dbkey",
+          context.rowDbKey,
+          "--base-url",
+          args.options.serverUrl,
+          "--review-status",
+          reviewStatus,
+          "--reviewer-agent-key",
+          args.options.agentKey,
+          ...(context.artifactIds?.length ? ["--artifact-ids", context.artifactIds.join(",")] : []),
+          ...(args.dialogId ? ["--dialog-id", args.dialogId] : []),
+        ],
+      });
+    }
+  }
+}
+
+async function recordTaskRunOutcome(args: {
+  options: RunAgentTurnOptions;
+  status: "running" | "completed" | "failed";
+  dialogId?: string;
+  resultSummary?: string;
+  errorCode?: string;
+  toolEvidence?: TaskRunToolEvidence;
+}) {
+  if (!args.options.taskRunContext?.rowDbKey) return;
+  try {
+    await (args.options.taskRunRecorder ?? defaultTaskRunRecorder)(args);
+  } catch (error) {
+    args.options.output.write(
+      `[nolo] task-run writeback failed: ${error instanceof Error ? error.message : String(error)}\n`
+    );
+  }
+}
+
+function formatUsage(usage: any, dialogId: unknown) {
+  const parts: string[] = [];
+  if (typeof dialogId === "string" && dialogId) parts.push(`dialog=${dialogId}`);
+
+  const input = usage?.input_tokens ?? usage?.prompt_tokens ?? 0;
+  const output = usage?.output_tokens ?? usage?.completion_tokens ?? 0;
+  if (input || output) parts.push(`tokens=${input}+${output}`);
+
+  return parts.length ? `  (${parts.join("  ")})` : "";
+}
+
+function buildTransportErrorHint(serverUrl: string, error: unknown) {
+  const endpoint = `${serverUrl}/api/agent/run`;
+  const reason = error instanceof Error ? error.message : String(error);
+
+  let detail =
+    `[nolo] Could not reach ${endpoint}.\n` +
+    `Reason: ${reason}\n`;
+
+  try {
+    const parsed = new URL(serverUrl);
+    if (parsed.hostname === "127.0.0.1" || parsed.hostname === "localhost") {
+      detail +=
+        "If you meant local dev, start the local API first.\n" +
+        "Otherwise set NOLO_SERVER to a reachable server, or re-run `nolo login --server https://nolo.chat`.\n";
+      return detail;
+    }
+  } catch {
+    // Keep the generic hint below when serverUrl is not a valid absolute URL.
+  }
+
+  detail +=
+    "Check NOLO_SERVER / BASE_URL and make sure the configured server is reachable.\n";
+  return detail;
+}
+
+async function runScriptBridge(options: RunAgentTurnOptions, scriptPath: string) {
   options.output.write(`\n${options.agentName} -> working via local script...\n\n`);
   const proc = Bun.spawn({
     cmd: [
@@ -117,45 +567,391 @@ async function runScriptBridge(options: RunAgentTurnOptions, scriptPath: string)
   }
   return { exitCode };
 }
+
+async function runHttpAgentTurn(options: RunAgentTurnOptions, authToken: string) {
+  options.output.write(`\n${options.agentName} -> working...\n`);
+
+  const fetchImpl = options.fetchImpl ?? fetch;
+  let res: Response;
+  try {
+    res = await fetchImpl(`${options.serverUrl}/api/agent/run`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        agentKey: options.agentKey,
+        userInput: buildUserInputContent(
+          prependTaskRunPrompt(options.message, options.taskRunContext),
+          options.imageUrls
+        ),
+        runtimeContext: {
+          surface: "cli",
+          host: "terminal",
+          runtime: "bun",
+          entrypoint: "nolo-cli",
+          capabilities: ["text-io", "streaming", "slash-commands"],
+          ...(options.taskRunContext
+            ? {
+                taskRun: {
+                  rowDbKey: options.taskRunContext.rowDbKey,
+                  ...(options.taskRunContext.taskRunId
+                    ? { taskRunId: options.taskRunContext.taskRunId }
+                    : {}),
+                  ...(options.taskRunContext.workItemId
+                    ? { workItemId: options.taskRunContext.workItemId }
+                    : {}),
+                  ...(options.taskRunContext.artifactIds?.length
+                    ? { artifactIds: options.taskRunContext.artifactIds }
+                    : {}),
+                },
+              }
+            : {}),
+        },
+        ...(options.continueDialogId
+          ? { continueDialogId: options.continueDialogId }
+          : {}),
+        ...(options.spaceId ? { spaceId: options.spaceId } : {}),
+        ...(options.category ? { category: options.category } : {}),
+        ...(options.inheritedFromDialogKey
+          ? { inheritedFromDialogKey: options.inheritedFromDialogKey }
+          : {}),
+        ...(options.parentDialogId ? { parentDialogId: options.parentDialogId } : {}),
+        ...(options.background ? { background: true } : {}),
+        ...(typeof options.maxToolRounds === "number" ? { maxRounds: options.maxToolRounds } : {}),
+        ...(typeof options.timeoutMs === "number" ? { timeoutMs: options.timeoutMs } : {}),
+        stream: !options.noStream && !options.background,
+      }),
+    });
+  } catch (error) {
+    options.output.write(buildTransportErrorHint(options.serverUrl, error));
+    return { exitCode: 1 };
+  }
+
+  const contentType = res.headers.get("content-type") || "";
+  if (contentType.includes("text/event-stream") && res.body) {
+    const result = await readStreamingAgentRun(options, res);
+    await recordTaskRunOutcome({
+      options,
+      status: result.streamInterrupted
+        ? "running"
+        : result.exitCode === 0
+          ? "completed"
+          : "failed",
+      dialogId: result.dialogId,
+      ...(result.exitCode !== 0 ? { errorCode: "STREAM_FAILED" } : {}),
+    });
+    return result;
+  }
+
+  let data: any = {};
+  try {
+    data = await res.json();
+  } catch {
+    data = {};
+  }
+
+  if (!res.ok) {
+    options.output.write(`[nolo] Agent request failed: HTTP ${res.status}\n`);
+    if (data?.error || data?.message) {
+      options.output.write(`${data.error || data.message}\n`);
+    }
+    await recordTaskRunOutcome({
+      options,
+      status: "failed",
+      errorCode: `HTTP_${res.status}`,
+      resultSummary: String(data?.error || data?.message || "").trim() || undefined,
+    });
+    return { exitCode: 1 };
+  }
+
+  const content = String(data?.content ?? data?.message ?? "").trim();
+  if (content) {
+    options.output.write(`\n${options.agentName} > ${content}\n`);
+  } else {
+    options.output.write(`\n${options.agentName} > (no text response)\n`);
+  }
+
+  const usage = formatUsage(data?.usage, data?.dialogId);
+  if (usage && shouldShowUsage(options.env)) options.output.write(`${usage}\n`);
+  const result = {
+    exitCode: 0,
+    ...(typeof data?.dialogId === "string" && data.dialogId
+      ? { dialogId: data.dialogId }
+      : {}),
+  };
+  await recordTaskRunOutcome({
+    options,
+    status: options.background ? "running" : "completed",
+    dialogId: result.dialogId,
+    ...(!options.background && content ? { resultSummary: content } : {}),
+  });
+  return result;
+}
+
+async function runInjectedLocalAgentTurn(options: RunAgentTurnOptions) {
+  return runLocalAgentTurnWithAutoRoundExpansion(options, { reportFailure: true });
+}
+
+async function refreshMissingLocalAgentConfig(options: RunAgentTurnOptions) {
+  const adapter = resolveLocalRuntimeAdapter(options);
+  if (!adapter) return false;
+  const agentConfig = await adapter.loadAgentConfig(options.agentKey);
+  return Boolean(agentConfig);
+}
+
+async function runLocalAgentTurnWithAutoRoundExpansion(
+  options: RunAgentTurnOptions,
+  settings: { reportFailure: boolean }
+) {
+  const maxRetryLimit = resolveLocalToolRoundRetryLimit(options);
+  let currentMaxToolRounds = options.maxToolRounds;
+  let lastResult: Awaited<ReturnType<typeof runLocalAgentTurnForCli>> | null = null;
+
+  while (true) {
+    const attemptOptions = {
+      ...options,
+      ...(typeof currentMaxToolRounds === "number" ? { maxToolRounds: currentMaxToolRounds } : {}),
+    };
+    const result = await runLocalAgentTurnForCli(attemptOptions, { reportFailure: false });
+    lastResult = result;
+    if (result.exitCode === 0) return result;
+
+    const exhaustedRounds = parseLocalToolRoundLimitError(result.localError);
+    if (exhaustedRounds === null) break;
+
+    const nextMaxToolRounds = nextLocalToolRoundLimit(exhaustedRounds);
+    if (nextMaxToolRounds > maxRetryLimit) break;
+
+    options.output.write(
+      `[nolo] Local agent used all ${exhaustedRounds} tool rounds; retrying with ${nextMaxToolRounds}.\n`
+    );
+    currentMaxToolRounds = nextMaxToolRounds;
+  }
 
+  if (settings.reportFailure && lastResult?.localError) {
+    options.output.write(
+      `[nolo] Local agent run failed: ${
+        lastResult.localError instanceof Error ? lastResult.localError.message : String(lastResult.localError)
+      }\n`
+    );
+    await recordTaskRunOutcome({
+      options,
+      status: "failed",
+      errorCode: "LOCAL_AGENT_FAILED",
+      resultSummary:
+        lastResult.localError instanceof Error ? lastResult.localError.message : String(lastResult.localError),
+      toolEvidence: lastResult.toolEvidence,
+    });
+  }
+  return lastResult ?? { exitCode: 1 };
+}
+
+async function runLocalAgentTurnForCli(
+  options: RunAgentTurnOptions,
+  settings: { reportFailure: boolean }
+) {
+  const adapter = resolveLocalRuntimeAdapter(options);
+  if (!adapter) {
+    options.output.write("[nolo] Local runtime was requested but no local runtime adapter is available.\n");
+    return { exitCode: 1 };
+  }
+
+  options.output.write(`\n${options.agentName} -> working locally...\n`);
+  const toolEvents: LocalAgentToolEvent[] = [];
+  try {
+    const traceLocalTools = shouldTraceLocalTools(options);
+    const collectToolEvidence = shouldCollectLocalToolEvidence(options);
+    const result = await runLocalAgentTurn({
+      adapter,
+      agentRef: options.agentKey,
+      input: buildUserInputContent(
+        prependTaskRunPrompt(options.message, options.taskRunContext),
+        options.imageUrls
+      ),
+      continueDialogId: options.continueDialogId,
+      spaceId: options.spaceId,
+      category: options.category,
+      inheritedFromDialogKey: options.inheritedFromDialogKey,
+      parentDialogId: options.parentDialogId,
+      background: options.background,
+      noStream: options.noStream,
+      maxToolRounds: options.maxToolRounds,
+      ...(traceLocalTools || collectToolEvidence
+        ? {
+            onToolEvent: (event) => {
+              if (collectToolEvidence) toolEvents.push(event);
+              if (traceLocalTools) options.output.write(formatToolTraceEvent(event));
+            },
+          }
+        : {}),
+    });
+    const content = result.content.trim();
+    if (content) {
+      options.output.write(`\n${options.agentName} > ${content}\n`);
+    } else {
+      options.output.write(`\n${options.agentName} > (no text response)\n`);
+    }
+    await recordTaskRunOutcome({
+      options,
+      status: options.background ? "running" : "completed",
+      dialogId: result.dialogId,
+      ...(!options.background && content ? { resultSummary: content } : {}),
+      toolEvidence: summarizeLocalToolEvidence(toolEvents),
+    });
+    return { exitCode: 0, dialogId: result.dialogId };
+  } catch (error) {
+    if (settings.reportFailure) {
+      options.output.write(
+        `[nolo] Local agent run failed: ${
+          error instanceof Error ? error.message : String(error)
+        }\n`
+      );
+    }
+    return { exitCode: 1, localError: error, toolEvidence: summarizeLocalToolEvidence(toolEvents) };
+  }
+}
+
+async function readStreamingAgentRun(
+  options: RunAgentTurnOptions,
+  res: Response,
+): Promise<RunAgentTurnResult> {
+  const reader = res.body?.getReader();
+  if (!reader) {
+    options.output.write("[nolo] Agent stream response did not include a readable body.\n");
+    return { exitCode: 1 };
+  }
+
+  const decoder = new TextDecoder();
+  const writer = createStreamingTextWriter({
+    write: (chunk) => options.output.write(chunk),
+  });
+  let buffer = "";
+  let content = "";
+  let dialogId: string | undefined;
+  let usage: any;
+  let hasPrintedLabel = false;
+
+  const printLabel = () => {
+    if (hasPrintedLabel) return;
+    options.output.write(`\n${options.agentName} > `);
+    hasPrintedLabel = true;
+  };
+
+  const handlePayload = (payload: any) => {
+    if (typeof payload?.dialogId === "string" && payload.dialogId.trim()) {
+      dialogId = payload.dialogId;
+    }
+    if (payload?.error || payload?.type === "error") {
+      throw new Error(String(payload.error || payload.message || "Agent stream failed"));
+    }
+    if (payload?.type === "done") {
+      usage = payload.usage;
+      return;
+    }
+    if (payload?.type === "dialog" || payload?.type === "status") {
+      return;
+    }
+
+    const chunk =
+      payload?.type === "text"
+        ? payload.content
+        : typeof payload?.chunk === "string"
+          ? payload.chunk
+          : "";
+    if (!chunk) return;
+
+    printLabel();
+    content += chunk;
+    writer.push(chunk);
+  };
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const events = buffer.split("\n\n");
+      buffer = events.pop() ?? "";
+
+      for (const event of events) {
+        const dataLines = event
+          .split("\n")
+          .filter((line) => line.startsWith("data:"))
+          .map((line) => line.slice(5).trim())
+          .filter(Boolean);
+        for (const raw of dataLines) {
+          handlePayload(JSON.parse(raw));
+        }
+      }
+    }
+    if (buffer.trim()) {
+      const raw = buffer
+        .split("\n")
+        .find((line) => line.startsWith("data:"))
+        ?.slice(5)
+        .trim();
+      if (raw) handlePayload(JSON.parse(raw));
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (dialogId) {
+      options.output.write(
+        `\n[nolo] Agent stream transport interrupted after dialog ${dialogId} was created: ${message}\n`
+      );
+      options.output.write("[nolo] The agent run may still finish on the server; read the dialog before retrying.\n");
+      return { exitCode: 0, dialogId, streamInterrupted: true };
+    }
+    options.output.write(`\n[nolo] Agent stream failed: ${message}\n`);
+    return { exitCode: 1 };
+  } finally {
+    writer.flushAll();
+  }
+
+  if (!content) {
+    options.output.write(`\n${options.agentName} > (no text response)\n`);
+  } else {
+    options.output.write("\n");
+  }
+
+  const usageText = formatUsage(usage, dialogId);
+  if (usageText && shouldShowUsage(options.env)) options.output.write(`${usageText}\n`);
+  return {
+    exitCode: 0,
+    ...(dialogId ? { dialogId } : {}),
+  };
+}
+
 export async function runAgentTurn(options: RunAgentTurnOptions) {
-  const dialogLineage = normalizeAgentRunDialogLineage(options);
-  const effectiveOptions: RunAgentTurnOptions = {
-    ...options,
-    continueDialogId: dialogLineage.continueDialogId,
-    inheritedFromDialogKey: dialogLineage.inheritedFromDialogKey,
-    parentDialogId: dialogLineage.parentDialogId,
-  };
   const authToken = resolveAuthToken(options.env);
-  const scriptPath = join(effectiveOptions.scriptDir, "chatWithAgent.ts");
+  const scriptPath = join(options.scriptDir, "chatWithAgent.ts");
   const scriptPathExists = (options.scriptPathExists ?? existsSync)(scriptPath);
-  const runtimeMode = resolveRequestedRuntimeMode(effectiveOptions);
+  const runtimeMode = resolveRequestedRuntimeMode(options);
 
   if (runtimeMode === "local") {
-    return runInjectedLocalAgentTurn(effectiveOptions);
+    return runInjectedLocalAgentTurn(options);
   }
 
-  if (runtimeMode === "auto" && shouldAttemptAutoLocal(effectiveOptions)) {
-    const skipLocal = await shouldSkipAutoLocalForServerPlatformTools({
-      ...effectiveOptions,
-      resolveLocalRuntimeAdapter: () => resolveLocalRuntimeAdapter(effectiveOptions),
-    });
+  if (runtimeMode === "auto" && shouldAttemptAutoLocal(options)) {
+    const skipLocal = await shouldSkipAutoLocalForServerPlatformTools(options);
     if (!skipLocal) {
-      const localResult = await runLocalAgentTurnWithAutoRoundExpansion(effectiveOptions, { reportFailure: false });
+      const localResult = await runLocalAgentTurnWithAutoRoundExpansion(options, { reportFailure: false });
       if (localResult.exitCode === 0) {
         return {
           exitCode: localResult.exitCode,
           ...(localResult.dialogId ? { dialogId: localResult.dialogId } : {}),
         };
       }
-      if (isMissingLocalAgentConfigError(localResult.localError, effectiveOptions.agentKey)) {
-        effectiveOptions.output.write(
+      if (isMissingLocalAgentConfigError(localResult.localError, options.agentKey)) {
+        options.output.write(
           `[nolo] Local agent config was missing; refreshing from the configured server and retrying local once.\n`
         );
         try {
-          const refreshed = await refreshMissingLocalAgentConfig(effectiveOptions);
+          const refreshed = await refreshMissingLocalAgentConfig(options);
           if (refreshed) {
-            const retriedLocalResult = await runLocalAgentTurnWithAutoRoundExpansion(effectiveOptions, {
+            const retriedLocalResult = await runLocalAgentTurnWithAutoRoundExpansion(options, {
               reportFailure: false,
             });
             if (retriedLocalResult.exitCode === 0) {
@@ -173,16 +969,16 @@ export async function runAgentTurn(options: RunAgentTurnOptions) {
   }
 
   if (shouldUseScriptBridge({ hasAuthToken: Boolean(authToken), scriptPathExists })) {
-    return runScriptBridge(effectiveOptions, scriptPath);
+    return runScriptBridge(options, scriptPath);
   }
-
-  if (!authToken) {
-    effectiveOptions.output.write(
-      "[nolo] This install needs an auth token before it can talk to agents.\n" +
-        "Set AUTH_TOKEN, or use the repo-local CLI where the dev script bridge is available.\n"
-    );
+
+  if (!authToken) {
+    options.output.write(
+      "[nolo] This install needs an auth token before it can talk to agents.\n" +
+        "Set AUTH_TOKEN, or use the repo-local CLI where the dev script bridge is available.\n"
+    );
     return { exitCode: 1 };
   }
 
-  return runHttpAgentTurn(effectiveOptions, { authToken });
-}
+  return runHttpAgentTurn(options, authToken);
+}