nolo-cli 0.1.22 → 0.1.26

package/machineCommands.ts

@@ -1,9 +1,11 @@
 import type { MachineHeartbeat } from "./connector-experimental/protocol";
 import { detectMachineInfo } from "./connector-experimental/machineInfo";
+import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
-import { mkdirSync, openSync } from "node:fs";
+import { existsSync, mkdirSync, openSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { runLocalAgentTurn, type LocalAgentToolEvent } from "./agent-runtime/localLoop";
 import { DEFAULT_NOLO_SERVER_URL } from "./defaultServer";
 import {
   collectConnectorRunArtifact,
@@ -19,7 +21,9 @@ import {
   buildMachinePermissionPromptBlock,
   resolveMachineRunPermissionPolicy,
 } from "./ai/agent/machineRunPermissions";
-import { resolveConnectorWebSocketTarget } from "./connectorWebSocketTarget";
+import { resolveConnectorWebSocketTarget } from "./connectorWebSocketTarget";
+import { createCliLocalRuntimeAdapter } from "./client/localRuntimeAdapter";
+import { prepareTaskWorktree } from "./client/taskWorktree";
 
 type EnvLike = Record<string, string | undefined>;
 type OutputLike = { write(chunk: string): unknown };
@@ -28,11 +32,42 @@ type ConnectorWebSocketOptions = {
   onMessage: (message: string) => void | Promise<void>;
   sentMessages: string[];
 };
-type LocalCliExecutor = (
+export type LocalCliExecutor = (
   provider: string,
   prompt: string,
   options: { model?: string; timeout?: number; cwd?: string; yolo?: boolean; env?: EnvLike }
 ) => Promise<{ text: string; raw?: string; elapsed?: number }>;
+
+type ConnectorRuntimePolicy = {
+  runtimeTools?: string[];
+  agentTools?: string[];
+  workspace?: {
+    mode?: string;
+    cwd?: string;
+  };
+  shell?: {
+    enabled?: boolean;
+    mode?: string;
+  };
+};
+
+type ConnectorRunProgress = {
+  eventType?: LocalAgentToolEvent["type"];
+  toolCallCount?: number;
+  toolResultCount?: number;
+  lastToolNames?: string[];
+  provider?: string;
+  promptBytes?: number;
+  promptHash?: string;
+  promptRef?: string;
+  promptPageKey?: string;
+  promptPageHash?: string;
+  requestId?: string;
+  workspaceRoot?: string;
+  workspaceKind?: string;
+  message?: string;
+  updatedAt?: number;
+};
 
 export type MachineSummary = {
   machineId: string;
@@ -55,15 +90,26 @@ type MachineCommandDeps = {
   fetchImpl?: typeof fetch;
   machineInfo?: () => MachineHeartbeat;
   runHeartbeatLoop?: (options: HeartbeatLoopOptions) => Promise<void>;
-  connectWebSocket?: (url: string, options: ConnectorWebSocketOptions) => Promise<void>;
-  executeCli?: LocalCliExecutor;
-  spawnDaemon?: (args: {
+  connectWebSocket?: (url: string, options: ConnectorWebSocketOptions) => Promise<void>;
+  executeCli?: LocalCliExecutor;
+  validateWorkspaceLinks?: (cwd: string) => string[] | Promise<string[]>;
+  spawnDaemon?: (args: {
     cmd: string[];
     cwd: string;
     env: EnvLike;
     logPath: string;
   }) => { pid?: number };
-};
+};
+
+type PackageJson = {
+  name?: string;
+  workspaces?: string[] | { packages?: string[] };
+};
+
+const CONNECTOR_RUNTIME_WORKSPACE_PACKAGES = new Set([
+  "connector-experimental",
+  "ai",
+]);
 
 function resolveServerUrl(env: EnvLike) {
   return (env.NOLO_SERVER || env.BASE_URL || DEFAULT_NOLO_SERVER_URL).replace(/\/+$/, "");
@@ -79,9 +125,113 @@ function writeAuthMissing(output: OutputLike) {
   );
 }
 
-function hasFlag(args: string[], flag: string) {
-  return args.includes(flag);
-}
+function hasFlag(args: string[], flag: string) {
+  return args.includes(flag);
+}
+
+function normalizePath(path: string) {
+  const resolved = resolve(path);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function isInsideOrSame(path: string, parent: string) {
+  const relativePath = relative(parent, path);
+  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+
+function readJsonFile<T>(path: string): T | null {
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as T;
+  } catch {
+    return null;
+  }
+}
+
+function getWorkspacePatterns(packageJson: PackageJson) {
+  if (Array.isArray(packageJson.workspaces)) return packageJson.workspaces;
+  return packageJson.workspaces?.packages ?? [];
+}
+
+function findWorkspaceRoot(startPath: string) {
+  let current = resolve(startPath);
+  while (true) {
+    const packageJsonPath = join(current, "package.json");
+    if (existsSync(packageJsonPath)) {
+      const packageJson = readJsonFile<PackageJson>(packageJsonPath);
+      if (packageJson && getWorkspacePatterns(packageJson).length > 0) {
+        return current;
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function validateConnectorWorkspaceLinks(cwd: string) {
+  const repoRoot = findWorkspaceRoot(cwd);
+  if (!repoRoot) return [];
+
+  const rootPackageJson = readJsonFile<PackageJson>(join(repoRoot, "package.json"));
+  if (!rootPackageJson) return [];
+
+  const normalizedRepoRoot = normalizePath(realpathSync(repoRoot));
+  const errors: string[] = [];
+
+  for (const pattern of getWorkspacePatterns(rootPackageJson)) {
+    if (!pattern.endsWith("/*")) continue;
+    const workspaceParent = join(repoRoot, pattern.slice(0, -2));
+    if (!existsSync(workspaceParent)) continue;
+
+    for (const entry of Array.from(new Bun.Glob("*/package.json").scanSync({ cwd: workspaceParent }))) {
+      const packageDir = join(workspaceParent, dirname(entry));
+      const packageJson = readJsonFile<PackageJson>(join(workspaceParent, entry));
+      if (!packageJson?.name || !CONNECTOR_RUNTIME_WORKSPACE_PACKAGES.has(packageJson.name)) {
+        continue;
+      }
+
+      const linkPath = join(repoRoot, "node_modules", ...packageJson.name.split("/"));
+      if (!existsSync(linkPath)) {
+        errors.push(`${linkPath} is missing. Run bun install in ${repoRoot}.`);
+        continue;
+      }
+
+      const actualPath = normalizePath(realpathSync(linkPath));
+      const expectedPath = normalizePath(realpathSync(packageDir));
+      if (!isInsideOrSame(actualPath, normalizedRepoRoot)) {
+        errors.push(
+          `${linkPath} points outside this checkout: ${actualPath}. Run bun install in ${repoRoot}.`,
+        );
+        continue;
+      }
+      if (actualPath !== expectedPath) {
+        errors.push(
+          `${linkPath} points at ${actualPath}, expected ${expectedPath}. Run bun install in ${repoRoot}.`,
+        );
+      }
+    }
+  }
+
+  return errors;
+}
+
+async function checkConnectorWorkspaceLinks(
+  cwd: string,
+  output: OutputLike,
+  validateWorkspaceLinks: (cwd: string) => string[] | Promise<string[]>,
+) {
+  const errors = await validateWorkspaceLinks(cwd);
+  if (errors.length === 0) return true;
+  output.write(
+    [
+      "[nolo] Connector workspace package links are unsafe.",
+      "The connector would import workspace packages from a different checkout, so machine capabilities and runtime behavior may be stale.",
+      ...errors,
+      "",
+    ].join("\n"),
+  );
+  return false;
+}
 
 function readOption(args: string[], flag: string) {
   for (let i = 0; i < args.length; i++) {
@@ -112,6 +262,90 @@ function resolveDaemonLogPath(env: EnvLike) {
   return env.NOLO_CONNECT_LOG || join(homedir(), ".nolo", "logs", "connector.log");
 }
 
+function byteLength(value: string) {
+  return Buffer.byteLength(value, "utf8");
+}
+
+function shortHash(value: string) {
+  return createHash("sha256").update(value).digest("hex").slice(0, 12);
+}
+
+function resolvePromptInlineMaxBytes(env: EnvLike) {
+  const raw = Number(env.NOLO_CONNECTOR_PROMPT_INLINE_MAX_BYTES);
+  return Number.isFinite(raw) && raw >= 1024 ? raw : 32_000;
+}
+
+function materializeLargeConnectorPrompt(args: {
+  prompt: string;
+  cwd: string;
+  env: EnvLike;
+  requestId: string;
+  runtimePromptPage?: {
+    dbKey?: string;
+    promptHash?: string;
+    contentBytes?: number;
+  } | null;
+}) {
+  const promptBytes = byteLength(args.prompt);
+  const promptHash = shortHash(args.prompt);
+  const maxInlineBytes = resolvePromptInlineMaxBytes(args.env);
+  if (promptBytes <= maxInlineBytes) {
+    return {
+      prompt: args.prompt,
+      promptBytes,
+      promptHash,
+      promptRef: null as string | null,
+    };
+  }
+
+  const promptDir = join(args.cwd, ".nolo", "agent-prompts");
+  mkdirSync(promptDir, { recursive: true });
+  const promptRef = join(promptDir, `${args.requestId}-${promptHash}.md`);
+  writeFileSync(promptRef, args.prompt, "utf8");
+
+  return {
+    prompt: [
+      "A large Nolo runtime prompt has been materialized outside this command argument.",
+      ...(args.runtimePromptPage?.dbKey
+        ? [
+            "Cloud prompt page is the shared audit/context source.",
+            `Cloud prompt page: ${args.runtimePromptPage.dbKey}`,
+            `Read cloud page: bun packages/cli/index.ts doc read ${JSON.stringify(args.runtimePromptPage.dbKey)}`,
+            ...(args.runtimePromptPage.promptHash
+              ? [`Cloud prompt sha256 prefix: ${args.runtimePromptPage.promptHash}`]
+              : []),
+            "",
+          ]
+        : []),
+      "Local prompt file is the execution-machine fallback and should match the cloud page content at run start.",
+      `Prompt file: ${promptRef}`,
+      `Prompt bytes: ${promptBytes}`,
+      `Prompt sha256 prefix: ${promptHash}`,
+      "",
+      "Prefer the cloud prompt page for shared context when readable; use the local prompt file as fallback.",
+      "Local repository edits, diffs, test output, and commits are still authoritative for local execution facts.",
+      "If neither source is readable, stop and report PROMPT_REF_UNREADABLE with both references.",
+    ].join("\n"),
+    promptBytes,
+    promptHash,
+    promptRef,
+  };
+}
+
+function readRuntimePromptPageMeta(parsed: any) {
+  const page = parsed?.payload?.meta?.runtimePromptPage;
+  if (!page || typeof page !== "object") return null;
+  return {
+    dbKey: typeof page.dbKey === "string" ? page.dbKey : undefined,
+    promptHash: typeof page.promptHash === "string" ? page.promptHash : undefined,
+    contentBytes: typeof page.contentBytes === "number" ? page.contentBytes : undefined,
+  };
+}
+
+function logConnectorRun(message: string, fields: Record<string, unknown> = {}) {
+  console.error(`[nolo-connector] ${message} ${JSON.stringify(fields)}`);
+}
+
 function buildDaemonCommand(cliEntrypointPath: string | undefined) {
   return [process.execPath, cliEntrypointPath || import.meta.path, "connect", "--ws"];
 }
@@ -245,6 +479,7 @@ function buildTaskRunBridgePrompt(args: {
     "Run commands from the repository root. The runner already provides server URL and auth in the environment.",
     "Release boundary: after review passes, AI/reviewer/Codex may advance alpha for verification. Do not merge, push, or release main/release unless the human owner explicitly authorizes it in the current task context.",
     "Cost boundary: read taskRun.control from context. Prefer low-cost/free-window models for routine work, and reserve Codex for supervision, quality gates, complex unblocking, and main/release decisions.",
+    "Handoff context: start from read-context, then inspect existing refs such as workItems.dialogIds, workItems.outcome, review.dialogId, activityRefs, agentRuns.dialogId/resultSummary, and artifactRefs. Use dialog read/search for exact evidence; do not infer completion from handoff text alone.",
     `Read context: bun packages/cli/index.ts task-run read-context --row-dbkey ${JSON.stringify(rowDbKey)}`,
     ...(workItemId
       ? [
@@ -264,8 +499,8 @@ function buildTaskRunBridgePrompt(args: {
 function buildConnectorCliPrompt(agentConfig: any, userInput: string, bridgeArgs?: {
   agentKey: string;
   runtimeContext: any;
-}) {
-  const policy = resolveMachineRunPermissionPolicy(agentConfig);
+}, permissionPolicy?: ReturnType<typeof resolveMachineRunPermissionPolicy>) {
+  const policy = permissionPolicy ?? resolveMachineRunPermissionPolicy(agentConfig);
   return [
     typeof agentConfig?.prompt === "string" ? agentConfig.prompt.trim() : "",
     bridgeArgs ? buildTaskRunBridgePrompt({
@@ -278,6 +513,248 @@ function buildConnectorCliPrompt(agentConfig: any, userInput: string, bridgeArgs
   ].filter(Boolean).join("\n\n");
 }
 
+function isRecord(value: unknown): value is Record<string, any> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function runtimePolicyFromConnectorPayload(parsed: any): ConnectorRuntimePolicy | undefined {
+  const fromMeta = parsed?.payload?.meta?.runtimeToolPolicySnapshot;
+  const fromAgent = parsed?.payload?.agentConfig?.runtimeToolPolicy;
+  const policy = isRecord(fromMeta) ? fromMeta : isRecord(fromAgent) ? fromAgent : null;
+  return policy ? policy as ConnectorRuntimePolicy : undefined;
+}
+
+function requestsTaskWorktree(policy?: ConnectorRuntimePolicy) {
+  return policy?.workspace?.mode === "task-worktree" || policy?.workspace?.mode === "lease";
+}
+
+function hasExplicitMachinePermissions(agentConfig: any) {
+  const runtimeBinding = isRecord(agentConfig?.runtimeBinding) ? agentConfig.runtimeBinding : {};
+  return Boolean(
+    isRecord(agentConfig?.machinePermissions) ||
+      isRecord(runtimeBinding.permissions) ||
+      isRecord(runtimeBinding.machinePermissions) ||
+      isRecord(agentConfig?.boundRuntimeMachine?.permissions)
+  );
+}
+
+function runtimeWorkspacePermissionPolicy(
+  runtimePolicy: ConnectorRuntimePolicy | undefined,
+  cwd: string
+): ReturnType<typeof resolveMachineRunPermissionPolicy> | null {
+  if (!requestsTaskWorktree(runtimePolicy)) return null;
+  return {
+    mode: "full_access",
+    allowFilesystemRead: true,
+    allowFilesystemWrite: true,
+    allowShell: runtimePolicy?.shell?.enabled !== false,
+    writableRoots: [cwd],
+  };
+}
+
+function scopePermissionPolicyToRuntimeWorkspace(
+  policy: ReturnType<typeof resolveMachineRunPermissionPolicy>,
+  runtimePolicy: ConnectorRuntimePolicy | undefined,
+  cwd: string
+): ReturnType<typeof resolveMachineRunPermissionPolicy> {
+  if (!requestsTaskWorktree(runtimePolicy)) return policy;
+  return {
+    ...policy,
+    writableRoots: policy.allowFilesystemWrite ? [cwd] : [],
+  };
+}
+
+function mergeToolNames(...values: unknown[]) {
+  const names: string[] = [];
+  for (const value of values) {
+    if (!Array.isArray(value)) continue;
+    for (const item of value) {
+      const name = typeof item === "string"
+        ? item
+        : isRecord(item) && typeof item.name === "string"
+          ? item.name
+          : isRecord(item) && typeof item.function?.name === "string"
+            ? item.function.name
+            : "";
+      if (name && !names.includes(name)) names.push(name);
+    }
+  }
+  return names;
+}
+
+function localRuntimeEnvFromPolicy(runtimeEnv: EnvLike, policy?: ConnectorRuntimePolicy): EnvLike {
+  return {
+    ...runtimeEnv,
+    ...(policy?.shell?.enabled && policy.shell.mode === "worktree"
+      ? { NOLO_LOCAL_SHELL_MODE: "worktree" }
+      : {}),
+    ...(policy?.workspace?.cwd ? { NOLO_LOCAL_WORKTREE: policy.workspace.cwd } : {}),
+  };
+}
+
+function runtimeWorkspaceRootFromTrace(trace: unknown): string | undefined {
+  if (!Array.isArray(trace)) return undefined;
+  for (const message of trace) {
+    if (!isRecord(message)) continue;
+    const metadata = isRecord(message.tool_result_metadata)
+      ? message.tool_result_metadata
+      : null;
+    const workspaceRoot = metadata && typeof metadata.workspaceRoot === "string"
+      ? metadata.workspaceRoot.trim()
+      : "";
+    if (workspaceRoot) return workspaceRoot;
+  }
+  return undefined;
+}
+
+function buildArtifactProgress(args: {
+  artifacts: unknown;
+  runtimePolicy?: ConnectorRuntimePolicy;
+  workspaceRoot: string;
+  workspaceKind?: string;
+}): ConnectorRunProgress | null {
+  if (!isRecord(args.artifacts)) return null;
+  const changedFiles = Array.isArray(args.artifacts.changedFiles)
+    ? args.artifacts.changedFiles
+    : [];
+  const statusShort = typeof args.artifacts.statusShort === "string"
+    ? args.artifacts.statusShort.trim()
+    : "";
+  if (changedFiles.length === 0 && !statusShort) return null;
+  const runtimeTools = Array.isArray(args.runtimePolicy?.runtimeTools)
+    ? args.runtimePolicy.runtimeTools
+    : [];
+  const shellTool = runtimeTools.includes("execShell")
+    ? "execShell"
+    : "workspaceArtifact";
+  return {
+    eventType: "tool-result",
+    toolCallCount: 1,
+    toolResultCount: 1,
+    lastToolNames: [shellTool],
+    workspaceRoot: args.workspaceRoot,
+    ...(args.workspaceKind ? { workspaceKind: args.workspaceKind } : {}),
+    message: statusShort || `${changedFiles.length} changed file(s)`,
+    updatedAt: Date.now(),
+  };
+}
+
+async function runConnectorLocalRuntimeAgent(args: {
+  parsed: any;
+  runtimeEnv: EnvLike;
+  cwd: string;
+  fetchImpl?: typeof fetch;
+  onProgress?: (progress: ConnectorRunProgress) => void;
+}): Promise<Awaited<ReturnType<typeof runLocalAgentTurn>> & { runtimeWorkspaceRoot?: string }> {
+  const agentKey = String(args.parsed.payload?.agentKey ?? "");
+  const payloadAgentConfig = isRecord(args.parsed.payload?.agentConfig)
+    ? args.parsed.payload.agentConfig
+    : {};
+  const policy = runtimePolicyFromConnectorPayload(args.parsed);
+  const agentRecord = {
+    ...payloadAgentConfig,
+    dbKey: agentKey,
+    id: agentKey,
+    key: agentKey,
+    apiSource: payloadAgentConfig.apiSource ?? "platform",
+    provider: payloadAgentConfig.provider ?? payloadAgentConfig.apiSource ?? "openai",
+    toolNames: mergeToolNames(
+      payloadAgentConfig.toolNames,
+      payloadAgentConfig.tools,
+      policy?.agentTools,
+      policy?.runtimeTools,
+    ),
+    ...(policy ? { runtimeToolPolicy: policy } : {}),
+    ...(policy?.workspace?.mode === "task-worktree" || policy?.workspace?.mode === "lease"
+      ? { localWorkspaceMode: "task-worktree" }
+      : {}),
+  };
+  const store = new Map<string, any>([
+    [agentKey, agentRecord],
+    [`agent-${args.runtimeEnv.NOLO_USER_ID || "local"}-${agentKey}`, agentRecord],
+    [`agent-${args.runtimeEnv.NOLO_LOCAL_USER_ID || args.runtimeEnv.NOLO_USER_ID || "local"}-${agentKey}`, agentRecord],
+  ]);
+  const env = localRuntimeEnvFromPolicy(args.runtimeEnv, policy);
+  const wantsTaskWorktree = requestsTaskWorktree(policy);
+  const adapter = createCliLocalRuntimeAdapter({
+    env,
+    cwd: args.cwd,
+    useCwdAsTaskWorkspaceBase: wantsTaskWorktree,
+    ...(wantsTaskWorktree
+      ? {
+          prepareTaskWorktree: (input) => prepareTaskWorktree({
+            ...input,
+            cwd: args.cwd,
+          }),
+        }
+      : {}),
+    fetchImpl: args.fetchImpl ?? fetch,
+    store: {
+      read: async (key) => store.get(key) ?? null,
+      batch: async (ops) => {
+        for (const op of ops) {
+          if (op.type === "put") store.set(op.key, op.value);
+        }
+      },
+      iterator: async function* (options) {
+        const keys = [...store.keys()].sort();
+        for (const key of keys) {
+          if (key < options.gte) continue;
+          if (options.lte && key > options.lte) continue;
+          if (options.lt && key >= options.lt) continue;
+          yield [key, store.get(key)];
+        }
+      },
+    },
+  });
+  let toolCallCount = 0;
+  let toolResultCount = 0;
+  const lastToolNames: string[] = [];
+  let runtimeWorkspaceRoot: string | undefined;
+  let runtimeWorkspaceKind: string | undefined;
+  const noteToolName = (toolName: string) => {
+    if (!toolName) return;
+    const existingIndex = lastToolNames.indexOf(toolName);
+    if (existingIndex >= 0) lastToolNames.splice(existingIndex, 1);
+    lastToolNames.push(toolName);
+    while (lastToolNames.length > 8) lastToolNames.shift();
+  };
+  const result = await runLocalAgentTurn({
+    adapter,
+    agentRef: agentKey,
+    input: String(args.parsed.payload?.userInput ?? ""),
+    continueDialogId: typeof args.parsed.payload?.continueDialogId === "string"
+      ? args.parsed.payload.continueDialogId
+      : undefined,
+    onToolEvent: (event) => {
+      if (event.type === "tool-call") toolCallCount += 1;
+      if (event.type === "tool-result") toolResultCount += 1;
+      noteToolName(event.toolName);
+      const metadata = isRecord(event.metadata) ? event.metadata : {};
+      if (typeof metadata.workspaceRoot === "string" && metadata.workspaceRoot.trim()) {
+        runtimeWorkspaceRoot = metadata.workspaceRoot.trim();
+      }
+      if (typeof metadata.workspaceKind === "string" && metadata.workspaceKind.trim()) {
+        runtimeWorkspaceKind = metadata.workspaceKind.trim();
+      }
+      args.onProgress?.({
+        eventType: event.type,
+        toolCallCount,
+        toolResultCount,
+        lastToolNames: [...lastToolNames],
+        ...(runtimeWorkspaceRoot ? { workspaceRoot: runtimeWorkspaceRoot } : {}),
+        ...(runtimeWorkspaceKind ? { workspaceKind: runtimeWorkspaceKind } : {}),
+        ...(event.message ? { message: event.message } : {}),
+        updatedAt: Date.now(),
+      });
+    },
+  });
+  return {
+    ...result,
+    runtimeWorkspaceRoot: runtimeWorkspaceRootFromTrace(result.trace) ?? runtimeWorkspaceRoot,
+  };
+}
+
 function normalizeConnectorRunTimeoutMs(value: unknown): number | undefined {
   if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
     return undefined;
@@ -285,12 +762,13 @@ function normalizeConnectorRunTimeoutMs(value: unknown): number | undefined {
   return Math.floor(value);
 }
 
-async function handleConnectorRunMessage(
+export async function handleConnectorRunMessage(
   machine: MachineHeartbeat,
   message: string,
   send: (message: string) => void,
   executeCli: LocalCliExecutor,
-  runtimeEnv: EnvLike
+  runtimeEnv: EnvLike,
+  fetchImpl?: typeof fetch
 ) {
   let parsed: any;
   try {
@@ -298,59 +776,193 @@ async function handleConnectorRunMessage(
   } catch {
     return;
   }
-  if (parsed?.type !== "agent.run" || typeof parsed.requestId !== "string") return;
-  const agentConfig = parsed.payload?.agentConfig ?? {};
-  try {
-    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);
+  if (parsed?.type !== "agent.run" || typeof parsed.requestId !== "string") return;
+  const agentConfig = parsed.payload?.agentConfig ?? {};
+  const sendProgress = (progress: ConnectorRunProgress) => {
+    send(JSON.stringify({
+      type: "agent.run.progress",
+      requestId: parsed.requestId,
+      progress,
+    }));
+  };
+  try {
+    const machinePermissionPolicy = resolveMachineRunPermissionPolicy(agentConfig);
+    const runtimePolicy = runtimePolicyFromConnectorPayload(parsed);
     const userInput = String(parsed.payload?.userInput ?? "");
     const timeout = normalizeConnectorRunTimeoutMs(parsed.payload?.timeoutMs);
-    assertMachineRunAllowed(userInput, policy);
-    const cwd = resolveConnectorRunCwd({ env: runtimeEnv, policy });
-    const baseSha = await readConnectorGitHead(cwd);
-    const result = await executeCli(
-      provider,
-      buildConnectorCliPrompt(agentConfig, userInput, {
+    let cwd = resolveConnectorRunCwd({ env: runtimeEnv, policy: machinePermissionPolicy });
+    let runContent = "";
+    let runModel = agentConfig.model;
+    let runTrace: unknown[] = [];
+    let artifactCwd = cwd;
+    let baseSha: string | null = null;
+    if (agentConfig.apiSource === "cli") {
+      if (requestsTaskWorktree(runtimePolicy)) {
+        const prepared = await prepareTaskWorktree({
+          agentKey: String(parsed.payload?.agentKey ?? "agent"),
+          cwd,
+          env: runtimeEnv,
+        });
+        cwd = prepared.path;
+        artifactCwd = prepared.path;
+      }
+      const runtimePermissionPolicy = !hasExplicitMachinePermissions(agentConfig)
+        ? runtimeWorkspacePermissionPolicy(runtimePolicy, cwd)
+        : null;
+      const effectivePermissionPolicy = scopePermissionPolicyToRuntimeWorkspace(
+        runtimePermissionPolicy ?? machinePermissionPolicy,
+        runtimePolicy,
+        cwd,
+      );
+      assertMachineRunAllowed(userInput, effectivePermissionPolicy);
+      baseSha = await readConnectorGitHead(artifactCwd);
+      const provider = String(agentConfig.cliProvider || "copilot");
+      const builtPrompt = buildConnectorCliPrompt(agentConfig, userInput, {
         agentKey: String(parsed.payload?.agentKey ?? ""),
         runtimeContext: parsed.payload?.runtimeContext,
-      }),
-      {
-        model: agentConfig.model || undefined,
-        timeout,
+      }, effectivePermissionPolicy);
+      const materializedPrompt = materializeLargeConnectorPrompt({
+        prompt: builtPrompt,
         cwd,
-        yolo: true,
-        env: {
-          NOLO_SERVER: runtimeEnv.NOLO_SERVER || runtimeEnv.NOLO_SERVER_URL || runtimeEnv.BASE_URL,
-          NOLO_SERVER_URL: runtimeEnv.NOLO_SERVER_URL || runtimeEnv.NOLO_SERVER || runtimeEnv.BASE_URL,
-          BASE_URL: runtimeEnv.BASE_URL || runtimeEnv.NOLO_SERVER || runtimeEnv.NOLO_SERVER_URL,
-          AUTH_TOKEN: runtimeEnv.AUTH_TOKEN || runtimeEnv.AUTH || runtimeEnv.NOLO_MACHINE_API_KEY,
-          NOLO_MACHINE_API_KEY: runtimeEnv.NOLO_MACHINE_API_KEY || runtimeEnv.AUTH_TOKEN || runtimeEnv.AUTH,
+        env: runtimeEnv,
+        requestId: parsed.requestId,
+        runtimePromptPage: readRuntimePromptPageMeta(parsed),
+      });
+      const runtimePromptPage = readRuntimePromptPageMeta(parsed);
+      const startAt = Date.now();
+      const progressBase = {
+        provider,
+        requestId: parsed.requestId,
+        promptBytes: materializedPrompt.promptBytes,
+        promptHash: materializedPrompt.promptHash,
+        ...(materializedPrompt.promptRef ? { promptRef: materializedPrompt.promptRef } : {}),
+        ...(runtimePromptPage?.dbKey ? { promptPageKey: runtimePromptPage.dbKey } : {}),
+        ...(runtimePromptPage?.promptHash ? { promptPageHash: runtimePromptPage.promptHash } : {}),
+        workspaceRoot: artifactCwd,
+        workspaceKind: requestsTaskWorktree(runtimePolicy) ? "task-worktree" : "current",
+      };
+      logConnectorRun("agent.run.cli.start", {
+        requestId: parsed.requestId,
+        agentKey: parsed.payload?.agentKey,
+        provider,
+        cwd,
+        artifactCwd,
+        timeout,
+        promptBytes: materializedPrompt.promptBytes,
+        promptHash: materializedPrompt.promptHash,
+        promptRef: materializedPrompt.promptRef,
+        promptPageKey: runtimePromptPage?.dbKey,
+      });
+      sendProgress({
+        ...progressBase,
+        message: "cli-started",
+        updatedAt: startAt,
+      });
+      const heartbeat = setInterval(() => {
+        sendProgress({
+          ...progressBase,
+          message: "cli-running",
+          updatedAt: Date.now(),
+        });
+      }, 15_000);
+      const result = await executeCli(
+        provider,
+        materializedPrompt.prompt,
+        {
+          model: agentConfig.model || undefined,
+          timeout,
+          cwd,
+          yolo: true,
+          env: {
+            NOLO_SERVER: runtimeEnv.NOLO_SERVER || runtimeEnv.NOLO_SERVER_URL || runtimeEnv.BASE_URL,
+            NOLO_SERVER_URL: runtimeEnv.NOLO_SERVER_URL || runtimeEnv.NOLO_SERVER || runtimeEnv.BASE_URL,
+            BASE_URL: runtimeEnv.BASE_URL || runtimeEnv.NOLO_SERVER || runtimeEnv.NOLO_SERVER_URL,
+            AUTH_TOKEN: runtimeEnv.AUTH_TOKEN || runtimeEnv.AUTH || runtimeEnv.NOLO_MACHINE_API_KEY,
+            NOLO_MACHINE_API_KEY: runtimeEnv.NOLO_MACHINE_API_KEY || runtimeEnv.AUTH_TOKEN || runtimeEnv.AUTH,
+          },
+        }
+      ).finally(() => clearInterval(heartbeat));
+      logConnectorRun("agent.run.cli.result", {
+        requestId: parsed.requestId,
+        provider,
+        elapsed: result.elapsed,
+        outputBytes: byteLength(result.raw ?? result.text ?? ""),
+      });
+      runContent = result.text;
+      runModel = String(agentConfig.model || "").trim() || provider;
+      runTrace = [{ role: "assistant", content: result.text }];
+      const artifacts = await collectConnectorRunArtifact({
+        cwd: artifactCwd,
+        baseSha,
+        exitStatus: "completed",
+      });
+      const artifactProgress = buildArtifactProgress({
+        artifacts,
+        runtimePolicy,
+        workspaceRoot: artifactCwd,
+        workspaceKind: requestsTaskWorktree(runtimePolicy) ? "task-worktree" : "current",
+      });
+      if (artifactProgress && requestsTaskWorktree(runtimePolicy)) sendProgress(artifactProgress);
+      send(JSON.stringify({
+        type: "agent.run.result",
+        requestId: parsed.requestId,
+        result: {
+          content: runContent,
+          model: runModel,
+          trace: runTrace,
+          artifacts,
         },
+      }));
+      return;
+    } else {
+      if (!runtimePolicy) {
+        throw new Error("Connector can only execute non-CLI agents when runtimeToolPolicySnapshot requests a local workspace runtime.");
       }
-    );
+      baseSha = await readConnectorGitHead(cwd);
+      const result = await runConnectorLocalRuntimeAgent({
+        parsed,
+        runtimeEnv,
+        cwd,
+        fetchImpl,
+        onProgress: sendProgress,
+      });
+      runContent = result.content;
+      runModel = result.model;
+      runTrace = result.trace ?? [];
+      artifactCwd = result.runtimeWorkspaceRoot ?? cwd;
+    }
     const artifacts = await collectConnectorRunArtifact({
-      cwd,
+      cwd: artifactCwd,
       baseSha,
       exitStatus: "completed",
     });
+    const artifactProgress = buildArtifactProgress({
+      artifacts,
+      runtimePolicy,
+      workspaceRoot: artifactCwd,
+      workspaceKind: requestsTaskWorktree(runtimePolicy) ? "task-worktree" : "current",
+    });
+    if (artifactProgress && requestsTaskWorktree(runtimePolicy)) sendProgress(artifactProgress);
     send(JSON.stringify({
-      type: "agent.run.result",
-      requestId: parsed.requestId,
-      result: {
-        content: result.text,
-        model: agentConfig.model ?? provider,
-        trace: [{ role: "assistant", content: result.text }],
+      type: "agent.run.result",
+      requestId: parsed.requestId,
+      result: {
+        content: runContent,
+        model: runModel,
+        trace: runTrace,
         artifacts,
       },
     }));
-  } catch (error) {
-    send(JSON.stringify({
-      type: "agent.run.result",
-      requestId: parsed.requestId,
-      error: error instanceof Error ? error.message : String(error),
+  } catch (error) {
+    logConnectorRun("agent.run.error", {
+      requestId: parsed.requestId,
+      agentKey: parsed.payload?.agentKey,
+      error: error instanceof Error ? error.message : String(error),
+    });
+    send(JSON.stringify({
+      type: "agent.run.result",
+      requestId: parsed.requestId,
+      error: error instanceof Error ? error.message : String(error),
     }));
   }
 }
@@ -385,6 +997,10 @@ async function runConnectorWebSocketSession(options: {
       headers: { Authorization: `Bearer ${options.authToken}` },
       fetchImpl: options.fetchImpl,
     });
+    const runtimeServerUrl =
+      options.env.NOLO_CONNECT_RUNTIME_SERVER_URL ||
+      options.env.NOLO_RUNTIME_SERVER_URL ||
+      options.serverUrl;
     const websocketPromise = options.connectWebSocket(
       wsTarget,
       {
@@ -397,12 +1013,13 @@ async function runConnectorWebSocketSession(options: {
           options.executeCli,
           {
             ...options.env,
-            NOLO_SERVER: options.serverUrl,
-            NOLO_SERVER_URL: options.serverUrl,
-            BASE_URL: options.serverUrl,
+            NOLO_SERVER: runtimeServerUrl,
+            NOLO_SERVER_URL: runtimeServerUrl,
+            BASE_URL: runtimeServerUrl,
             AUTH_TOKEN: options.authToken,
             NOLO_MACHINE_API_KEY: options.authToken,
-          }
+          },
+          options.fetchImpl
         ),
       }
     );
@@ -449,10 +1066,11 @@ export async function runMachineConnectCommand(
     return 1;
   }
 
-  const serverUrl = resolveConnectServerUrl(args, env);
-  const fetchImpl = deps.fetchImpl ?? fetch;
-  const machine = (deps.machineInfo ?? detectLaunchableMachineInfo)();
-  const sendHeartbeat = async () => {
+  const serverUrl = resolveConnectServerUrl(args, env);
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const machine = (deps.machineInfo ?? detectLaunchableMachineInfo)();
+  const validateWorkspaceLinks = deps.validateWorkspaceLinks ?? validateConnectorWorkspaceLinks;
+  const sendHeartbeat = async () => {
     const res = await fetchImpl(`${serverUrl}/api/machines/heartbeat`, {
     method: "POST",
     headers: {
@@ -467,8 +1085,11 @@ export async function runMachineConnectCommand(
       throw new Error(`HTTP ${res.status}\n${text}`);
     }
   };
-
+
   if (hasFlag(args, "--daemon") || hasFlag(args, "--background")) {
+    if (!(await checkConnectorWorkspaceLinks(process.cwd(), output, validateWorkspaceLinks))) {
+      return 1;
+    }
     const logPath = resolveDaemonLogPath(env);
     const result = (deps.spawnDaemon ?? defaultSpawnDaemon)({
       cmd: buildDaemonCommand(deps.cliEntrypointPath),
@@ -478,9 +1099,12 @@ export async function runMachineConnectCommand(
     });
     output.write(`Connector daemon started${result.pid ? ` pid=${result.pid}` : ""}. Log: ${logPath}\n`);
     return 0;
-  }
-
+  }
+
   if (hasFlag(args, "--ws")) {
+    if (!(await checkConnectorWorkspaceLinks(process.cwd(), output, validateWorkspaceLinks))) {
+      return 1;
+    }
     const maxAttempts = deps.maxConnectorAttempts ?? Infinity;
     const sleep = deps.sleep ?? defaultSleep;
     const reconnectDelayMs = resolveConnectorReconnectDelayMs(env);