nolo-cli 0.1.30 → 0.1.32

package/cli/cliRuntimeDoctorReport.ts

@@ -0,0 +1,193 @@
+import { resolveAgentRuntimeDecision } from "../agent-runtime/runtimeDecision";
+import type { AgentRuntimeDecision } from "../agent-runtime/types";
+import type { LocalRuntimeProbeResult } from "./agentCommandSupport";
+import type { EnvLike } from "./cliEnvHelpers";
+
+export type CliRuntimeDoctorProbe = {
+  levelDb: {
+    ok: boolean;
+    path: string;
+    error?: string;
+  };
+  agentConfig: {
+    key: string;
+    cacheReady: boolean;
+    found: boolean;
+  };
+  provider: {
+    available: boolean;
+    label: string;
+  };
+  sync: {
+    available: boolean;
+  };
+  serverFallback: {
+    available: boolean;
+    url: string;
+  };
+};
+
+export type CliRuntimeDoctorReport = {
+  decision: AgentRuntimeDecision;
+  levelDb: {
+    status: "ok" | "failed";
+    path: string;
+    error?: string;
+  };
+  agentConfig: {
+    status: "found" | "missing";
+    value: string;
+  };
+  provider: {
+    status: "available" | "missing";
+    label: string;
+  };
+  sync: {
+    status: "available" | "unavailable";
+  };
+  serverFallback: {
+    status: "available" | "unavailable";
+    value: string;
+  };
+};
+
+function readLocalAgentKey(env: EnvLike) {
+  return env.NOLO_LOCAL_AGENT_KEY || env.NOLO_AGENT || "";
+}
+
+function detectLocalProvider(env: EnvLike) {
+  return Boolean(
+    env.OPENAI_API_KEY ||
+      env.ANTHROPIC_API_KEY ||
+      env.GOOGLE_API_KEY ||
+      env.NOLO_LOCAL_OPENAI_BASE_URL ||
+      env.OLLAMA_BASE_URL
+  );
+}
+
+function detectProviderLabel(env: EnvLike) {
+  if (env.NOLO_LOCAL_OPENAI_BASE_URL) {
+    return `openai-compatible endpoint ${env.NOLO_LOCAL_OPENAI_BASE_URL}`;
+  }
+  if (env.OLLAMA_BASE_URL) {
+    return `ollama-compatible endpoint ${env.OLLAMA_BASE_URL}`;
+  }
+  if (env.OPENAI_API_KEY) return "openai via env OPENAI_API_KEY";
+  if (env.ANTHROPIC_API_KEY) return "anthropic via env ANTHROPIC_API_KEY";
+  if (env.GOOGLE_API_KEY) return "google via env GOOGLE_API_KEY";
+  return "missing";
+}
+
+export function buildCliRuntimeDoctorProbe(input: {
+  env: EnvLike;
+  localProbe: LocalRuntimeProbeResult;
+  authToken: string;
+  serverUrl: string;
+}): CliRuntimeDoctorProbe {
+  const agentKey = input.localProbe.agentKey || readLocalAgentKey(input.env);
+  const cacheReady = Boolean(input.env.NOLO_AGENT_CACHE_READY);
+  return {
+    levelDb: {
+      ok: input.localProbe.ok,
+      path: input.localProbe.dbPath,
+      ...(input.localProbe.error ? { error: input.localProbe.error } : {}),
+    },
+    agentConfig: {
+      key: agentKey,
+      cacheReady,
+      found: input.localProbe.ok && input.localProbe.agentFound && (Boolean(agentKey) || cacheReady),
+    },
+    provider: {
+      available: detectLocalProvider(input.env),
+      label: detectProviderLabel(input.env),
+    },
+    sync: {
+      available: Boolean(input.authToken),
+    },
+    serverFallback: {
+      available: Boolean(input.authToken || input.env.NOLO_SERVER || input.env.BASE_URL),
+      url: input.serverUrl,
+    },
+  };
+}
+
+export function buildCliRuntimeDoctorReport(
+  probe: CliRuntimeDoctorProbe
+): CliRuntimeDoctorReport {
+  const missingLocalCapabilities = [
+    ...(probe.levelDb.ok ? [] : ["leveldb"]),
+    ...(probe.agentConfig.found ? [] : ["agent-config"]),
+    ...(probe.provider.available ? [] : ["provider"]),
+  ];
+  const decision = resolveAgentRuntimeDecision({
+    requestedMode: "auto",
+    syncRequested: false,
+    host: "cli",
+    hasLocalAgentConfig: probe.agentConfig.found,
+    hasLocalProvider: probe.provider.available,
+    hasLocalPersistence: true,
+    missingLocalCapabilities,
+    requiresServer: false,
+    serverFallbackAvailable: probe.serverFallback.available,
+  });
+
+  return {
+    decision,
+    levelDb: {
+      status: probe.levelDb.ok ? "ok" : "failed",
+      path: probe.levelDb.path,
+      ...(probe.levelDb.error ? { error: probe.levelDb.error } : {}),
+    },
+    agentConfig: {
+      status: probe.agentConfig.found ? "found" : "missing",
+      value: probe.agentConfig.key || (probe.agentConfig.cacheReady ? "cache ready" : "no local agent key"),
+    },
+    provider: {
+      status: probe.provider.available ? "available" : "missing",
+      label: probe.provider.label,
+    },
+    sync: {
+      status: probe.sync.available ? "available" : "unavailable",
+    },
+    serverFallback: {
+      status: probe.serverFallback.available ? "available" : "unavailable",
+      value: probe.serverFallback.available ? probe.serverFallback.url : "unavailable",
+    },
+  };
+}
+
+export function formatCliRuntimeDoctorReport(
+  report: CliRuntimeDoctorReport
+): string {
+  const lines = [
+    `Runtime: ${report.decision.mode}`,
+    `Reason: ${report.decision.reason}`,
+    `LevelDB: ${report.levelDb.status}`,
+    `DB path: ${report.levelDb.path}`,
+  ];
+  if (report.levelDb.error) {
+    lines.push(`DB error: ${report.levelDb.error}`);
+  }
+  if (report.agentConfig.status === "found") {
+    lines.push(`Agent config: found (${report.agentConfig.value})`);
+  } else if (report.agentConfig.value === "no local agent key") {
+    lines.push("Agent config: missing (no local agent key)");
+  } else {
+    lines.push(`Agent config: missing (${report.agentConfig.value})`);
+  }
+  lines.push(`Provider: ${report.provider.status} (${report.provider.label})`);
+  lines.push("Persistence: LevelDB local store");
+  lines.push(
+    `Sync: ${report.sync.status}${
+      report.sync.status === "available" ? "" : " (not authenticated)"
+    }`
+  );
+  lines.push(`Server fallback: ${report.serverFallback.value}`);
+  if (report.decision.missingLocalCapabilities.length > 0) {
+    lines.push("Missing local capabilities:");
+    for (const capability of report.decision.missingLocalCapabilities) {
+      lines.push(`- ${capability}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}

package/cli/client/agentConfigResolver.ts

@@ -0,0 +1 @@
+export { resolveAgentRuntimeConfigFromRecord } from "../agentRuntimeLocal";

package/cli/client/agentRun.ts

@@ -0,0 +1,188 @@
+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 {
+  isMissingLocalAgentConfigError,
+  refreshMissingLocalAgentConfig,
+  resolveLocalRuntimeAdapter,
+  runInjectedLocalAgentTurn,
+  runLocalAgentTurnWithAutoRoundExpansion,
+} from "./agentRunLocalExecutor";
+import { runHttpAgentTurn } from "./agentRunServerTransport";
+export { classifyTaskRunReviewStatus } from "./agentRunLocalExecution";
+export { findServerPlatformTools, shouldUseScriptBridge } from "./agentRunRuntimeSelection";
+
+export type RunAgentTurnOptions = {
+  agentName: string;
+  agentKey: string;
+  serverUrl: string;
+  message: string;
+  imageUrls?: string[];
+  continueDialogId?: string;
+  spaceId?: string;
+  category?: string;
+  inheritedFromDialogKey?: string;
+  parentDialogId?: string;
+  background?: boolean;
+  noStream?: boolean;
+  noDefaultTestRoot?: boolean;
+  scriptDir: string;
+  env: EnvLike;
+  output: OutputLike;
+  runtimeMode?: AgentRuntimeRequestedMode;
+  localRuntimeAdapter?: AgentRuntimeHostAdapter;
+  localRuntimeAdapterFactory?: (env: EnvLike, options?: { cwd?: string }) => AgentRuntimeHostAdapter;
+  localRuntimeCwd?: string;
+  maxToolRounds?: number;
+  timeoutMs?: number;
+  traceTools?: boolean;
+  taskRunContext?: TaskRunPromptContext;
+  taskRunRecorder?: TaskRunRecorder<RunAgentTurnOptions>;
+  scriptPathExists?: (path: string) => boolean;
+  fetchImpl?: typeof fetch;
+};
+
+export type RunAgentTurnResult = {
+  exitCode: number;
+  dialogId?: string;
+  streamInterrupted?: boolean;
+};
+
+function resolveAuthToken(env: EnvLike) {
+  return env.AUTH_TOKEN || env.AUTH || env.BENCHMARK_AUTH_TOKEN || "";
+}
+
+async function runScriptBridge(options: RunAgentTurnOptions, scriptPath: string) {
+  options.output.write(`\n${options.agentName} -> working via local script...\n\n`);
+  const proc = Bun.spawn({
+    cmd: [
+      process.execPath,
+      scriptPath,
+      "--agent",
+      options.agentKey,
+      "--server",
+      options.serverUrl,
+      "--msg",
+      options.message,
+      ...(options.taskRunContext?.rowDbKey
+        ? ["--task-row-dbkey", options.taskRunContext.rowDbKey]
+        : []),
+      ...(options.taskRunContext?.taskRunId
+        ? ["--task-run-id", options.taskRunContext.taskRunId]
+        : []),
+      ...(options.taskRunContext?.workItemId
+        ? ["--work-item-id", options.taskRunContext.workItemId]
+        : []),
+      ...(options.taskRunContext?.artifactIds?.length
+        ? ["--artifact-ids", options.taskRunContext.artifactIds.join(",")]
+        : []),
+      ...(options.noDefaultTestRoot ? ["--no-default-test-root"] : []),
+      ...(options.continueDialogId
+        ? ["--continue", options.continueDialogId]
+        : []),
+      ...(options.spaceId ? ["--space", options.spaceId] : []),
+      ...(options.category ? ["--category", options.category] : []),
+      ...(options.inheritedFromDialogKey
+        ? ["--inherit-from-dialog", options.inheritedFromDialogKey]
+        : []),
+      ...(options.background ? ["--bg"] : []),
+      ...(typeof options.timeoutMs === "number" ? ["--timeout-ms", String(options.timeoutMs)] : []),
+      ...(options.noStream ? ["--no-stream"] : []),
+    ],
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+    env: {
+      ...process.env,
+      ...options.env,
+      ASSISTANT_LABEL: options.agentName,
+    },
+  });
+
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    options.output.write(`\n[nolo] Agent run exited with code ${exitCode}.\n`);
+  }
+  return { exitCode };
+}
+
+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 scriptPathExists = (options.scriptPathExists ?? existsSync)(scriptPath);
+  const runtimeMode = resolveRequestedRuntimeMode(effectiveOptions);
+
+  if (runtimeMode === "local") {
+    return runInjectedLocalAgentTurn(effectiveOptions);
+  }
+
+  if (runtimeMode === "auto" && shouldAttemptAutoLocal(effectiveOptions)) {
+    const skipLocal = await shouldSkipAutoLocalForServerPlatformTools({
+      ...effectiveOptions,
+      resolveLocalRuntimeAdapter: () => resolveLocalRuntimeAdapter(effectiveOptions),
+    });
+    if (!skipLocal) {
+      const localResult = await runLocalAgentTurnWithAutoRoundExpansion(effectiveOptions, { reportFailure: false });
+      if (localResult.exitCode === 0) {
+        return {
+          exitCode: localResult.exitCode,
+          ...(localResult.dialogId ? { dialogId: localResult.dialogId } : {}),
+        };
+      }
+      if (isMissingLocalAgentConfigError(localResult.localError, effectiveOptions.agentKey)) {
+        effectiveOptions.output.write(
+          `[nolo] Local agent config was missing; refreshing from the configured server and retrying local once.\n`
+        );
+        try {
+          const refreshed = await refreshMissingLocalAgentConfig(effectiveOptions);
+          if (refreshed) {
+            const retriedLocalResult = await runLocalAgentTurnWithAutoRoundExpansion(effectiveOptions, {
+              reportFailure: false,
+            });
+            if (retriedLocalResult.exitCode === 0) {
+              return {
+                exitCode: retriedLocalResult.exitCode,
+                ...(retriedLocalResult.dialogId ? { dialogId: retriedLocalResult.dialogId } : {}),
+              };
+            }
+          }
+        } catch {
+          // Fall through to the existing server runtime fallback below.
+        }
+      }
+    }
+  }
+
+  if (shouldUseScriptBridge({ hasAuthToken: Boolean(authToken), scriptPathExists })) {
+    return runScriptBridge(effectiveOptions, 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"
+    );
+    return { exitCode: 1 };
+  }
+
+  return runHttpAgentTurn(effectiveOptions, { authToken });
+}

package/cli/client/agentRunInput.ts

@@ -0,0 +1,10 @@
+export 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 },
+    })),
+  ];
+}

package/cli/client/agentRunLocalExecution.ts

@@ -0,0 +1,124 @@
+import type { LocalAgentToolEvent } from "../../agent-runtime/localLoop";
+import type { EnvLike } from "../cliEnvHelpers";
+
+type TaskRunReviewStatus = "passed" | "needs_changes" | "blocked";
+
+export type TaskRunToolEvidence = {
+  toolsUsed: string[];
+  summary: {
+    callCount: number;
+    resultCount: number;
+    errorCount: number;
+    rounds: number;
+  };
+};
+
+type TraceLocalToolOptions = {
+  traceTools?: boolean;
+  env: EnvLike;
+};
+
+type CollectLocalToolEvidenceOptions = {
+  taskRunContext?: {
+    rowDbKey?: string;
+  };
+};
+
+type ResolveLocalToolRoundRetryLimitOptions = {
+  env: EnvLike;
+};
+
+const DEFAULT_LOCAL_AGENT_TOOL_ROUND_RETRY_LIMIT = 512;
+
+function parsePositiveInteger(value: string | undefined) {
+  if (!value) return null;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) return null;
+  return parsed;
+}
+
+export function shouldTraceLocalTools(options: TraceLocalToolOptions) {
+  return Boolean(options.traceTools || options.env.NOLO_TRACE_TOOLS === "1");
+}
+
+export function shouldCollectLocalToolEvidence(options: CollectLocalToolEvidenceOptions) {
+  return Boolean(options.taskRunContext?.rowDbKey);
+}
+
+export 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,
+    },
+  };
+}
+
+export 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]);
+}
+
+export function resolveLocalToolRoundRetryLimit(
+  options: ResolveLocalToolRoundRetryLimitOptions
+) {
+  return (
+    parsePositiveInteger(options.env.NOLO_LOCAL_MAX_TOOL_ROUNDS_LIMIT) ??
+    DEFAULT_LOCAL_AGENT_TOOL_ROUND_RETRY_LIMIT
+  );
+}
+
+export function nextLocalToolRoundLimit(current: number) {
+  return current <= 0 ? 1 : current * 2;
+}
+
+export 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`;
+}
+
+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;
+}

package/cli/client/agentRunLocalExecutor.ts

@@ -0,0 +1,179 @@
+import { runLocalAgentTurn, resolveHostRuntimeConfigFromEnv } from "../agentRuntimeLocal";
+import { LOCAL_AGENT_CONFIG_MISSING_CODE } from "../../agent-runtime/localLoop";
+import type { LocalAgentToolEvent } from "../../agent-runtime/localLoop";
+import { buildUserInputContent } from "./agentRunInput";
+import { createCliLocalRuntimeAdapter } from "./localRuntimeAdapter";
+import { prependTaskRunPrompt } from "./taskRunPrompt";
+import { recordTaskRunOutcome } from "./agentRunTaskRunRecorder";
+import {
+  formatToolTraceEvent,
+  nextLocalToolRoundLimit,
+  parseLocalToolRoundLimitError,
+  resolveLocalToolRoundRetryLimit,
+  shouldCollectLocalToolEvidence,
+  shouldTraceLocalTools,
+  summarizeLocalToolEvidence,
+} from "./agentRunLocalExecution";
+import type { RunAgentTurnOptions } from "./agentRun";
+
+export type LocalAgentTurnResult = {
+  exitCode: number;
+  dialogId?: string;
+  localError?: unknown;
+  toolEvidence?: ReturnType<typeof summarizeLocalToolEvidence>;
+};
+
+function buildDefaultLocalRuntimeAdapter(options: RunAgentTurnOptions) {
+  return createCliLocalRuntimeAdapter({
+    env: options.env,
+    hostRuntimeConfig: resolveHostRuntimeConfigFromEnv({
+      env: options.env,
+      surface: "cli-local",
+      workspaceBinding: "explicit-cwd",
+    }),
+    fetchImpl: options.fetchImpl,
+    cwd: options.localRuntimeCwd,
+    output: options.output,
+  });
+}
+
+export function resolveLocalRuntimeAdapter(options: RunAgentTurnOptions) {
+  return (
+    options.localRuntimeAdapter ||
+    options.localRuntimeAdapterFactory?.(options.env, { cwd: options.localRuntimeCwd }) ||
+    buildDefaultLocalRuntimeAdapter(options)
+  );
+}
+
+export 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
+  );
+}
+
+export async function runInjectedLocalAgentTurn(options: RunAgentTurnOptions) {
+  return runLocalAgentTurnWithAutoRoundExpansion(options, { reportFailure: true });
+}
+
+export async function refreshMissingLocalAgentConfig(options: RunAgentTurnOptions) {
+  const adapter = resolveLocalRuntimeAdapter(options);
+  if (!adapter) return false;
+  const agentConfig = await adapter.loadAgentConfig(options.agentKey);
+  return Boolean(agentConfig);
+}
+
+export 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 };
+}
+
+export async function runLocalAgentTurnForCli(
+  options: RunAgentTurnOptions,
+  settings: { reportFailure: boolean }
+): Promise<LocalAgentTurnResult> {
+  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) };
+  }
+}