nolo-cli 0.1.21 → 0.1.23

package/machineCommands.ts

@@ -4,6 +4,7 @@ import { spawn } from "node:child_process";
 import { mkdirSync, openSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { runLocalAgentTurn, type LocalAgentToolEvent } from "./agent-runtime/localLoop";
 import { DEFAULT_NOLO_SERVER_URL } from "./defaultServer";
 import {
   collectConnectorRunArtifact,
@@ -19,7 +20,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 +31,35 @@ 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[];
+  workspaceRoot?: string;
+  workspaceKind?: string;
+  message?: string;
+  updatedAt?: number;
+};
 
 export type MachineSummary = {
   machineId: string;
@@ -264,8 +291,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 +305,250 @@ 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("execBash")
+    ? "execBash"
+    : 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 +556,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,51 +570,129 @@ 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, {
-        agentKey: String(parsed.payload?.agentKey ?? ""),
-        runtimeContext: parsed.payload?.runtimeContext,
-      }),
-      {
-        model: agentConfig.model || undefined,
-        timeout,
+    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,
-        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,
+      );
+      assertMachineRunAllowed(userInput, effectivePermissionPolicy);
+      baseSha = await readConnectorGitHead(artifactCwd);
+      const provider = String(agentConfig.cliProvider || "copilot");
+      const result = await executeCli(
+        provider,
+        buildConnectorCliPrompt(agentConfig, userInput, {
+          agentKey: String(parsed.payload?.agentKey ?? ""),
+          runtimeContext: parsed.payload?.runtimeContext,
+        }, effectivePermissionPolicy),
+        {
+          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,
+          },
+        }
+      );
+      runContent = result.text;
+      runModel = agentConfig.model ?? 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,
       },
     }));
@@ -385,6 +735,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 +751,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
         ),
       }
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nolo-cli",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "type": "module",
   "description": "Agent-first terminal workspace for Nolo",
   "bin": {
@@ -33,7 +33,8 @@
     "agent-runtime/**/*.ts",
     "database/**/*.ts",
     "connector-experimental/**/*.ts",
-    "ai/**/*.ts"
+    "ai/**/*.ts",
+    "render/**/*.ts"
   ],
   "publishConfig": {
     "access": "public"
@@ -47,6 +48,7 @@
   "dependencies": {
     "date-fns-tz": "^2.0.0",
     "level": "^10.0.0",
+    "js-yaml": "^4.1.0",
     "ulid": "^2.3.0"
   }
 }

package/render/canvas/canvasEditContext.ts

@@ -0,0 +1,127 @@
+import React from "react";
+import type { AgentRuntimeOptions } from "ai/agent/types";
+import type { CanvasEvent } from "./types";
+
+export type CanvasEditSelection = {
+  sourceMessageId?: string;
+  selectedNodeId: string;
+  part: string;
+  path: string[];
+  type: string;
+  props: Record<string, unknown>;
+  style: Record<string, unknown>;
+};
+
+const CANVAS_EDIT_SELECTION_EVENT = "nolo:canvas-edit-selection";
+
+let currentSelection: CanvasEditSelection | null = null;
+let pendingSelection: CanvasEditSelection | null = null;
+const listeners = new Set<(selection: CanvasEditSelection | null) => void>();
+const patchListeners = new Map<string, Set<(events: CanvasEvent[]) => void>>();
+const queuedPatches = new Map<string, CanvasEvent[][]>();
+
+export function publishCanvasEditSelection(
+  selection: CanvasEditSelection | null
+) {
+  currentSelection = selection;
+  listeners.forEach((listener) => listener(selection));
+
+  if (typeof window !== "undefined") {
+    window.dispatchEvent(
+      new CustomEvent(CANVAS_EDIT_SELECTION_EVENT, { detail: selection })
+    );
+  }
+}
+
+export function subscribeCanvasEditSelection(
+  listener: (selection: CanvasEditSelection | null) => void
+) {
+  listeners.add(listener);
+  listener(currentSelection);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function useCanvasEditSelection() {
+  const [selection, setSelection] =
+    React.useState<CanvasEditSelection | null>(currentSelection);
+
+  React.useEffect(
+    () => subscribeCanvasEditSelection(setSelection),
+    []
+  );
+
+  return selection;
+}
+
+export function markPendingCanvasEditSelection(
+  selection: CanvasEditSelection | null
+) {
+  pendingSelection = selection;
+}
+
+export function consumePendingCanvasEditSelection() {
+  const selection = pendingSelection;
+  pendingSelection = null;
+  return selection;
+}
+
+export function publishCanvasMessagePatch(
+  sourceMessageId: string,
+  events: CanvasEvent[]
+) {
+  if (!events.length) return;
+
+  const queued = queuedPatches.get(sourceMessageId) ?? [];
+  queued.push(events);
+  queuedPatches.set(sourceMessageId, queued);
+
+  patchListeners
+    .get(sourceMessageId)
+    ?.forEach((listener) => listener(events));
+}
+
+export function subscribeCanvasMessagePatches(
+  sourceMessageId: string,
+  listener: (events: CanvasEvent[]) => void
+) {
+  const listenersForMessage = patchListeners.get(sourceMessageId) ?? new Set();
+  listenersForMessage.add(listener);
+  patchListeners.set(sourceMessageId, listenersForMessage);
+
+  queuedPatches
+    .get(sourceMessageId)
+    ?.forEach((events) => listener(events));
+
+  return () => {
+    listenersForMessage.delete(listener);
+    if (!listenersForMessage.size) {
+      patchListeners.delete(sourceMessageId);
+    }
+  };
+}
+
+export function buildCanvasNodeEditingTarget(
+  selection: CanvasEditSelection
+): NonNullable<AgentRuntimeOptions["editingTarget"]> {
+  return {
+    kind: "canvas_node",
+    key: selection.selectedNodeId,
+    title: selection.part,
+    summary: [
+      "用户正在编辑 Canvas Tree 画布中的一个已选中节点。",
+      "只输出针对选中节点的 canvas_snapshot updateNode 事件，除非用户明确要求新增内容。",
+      "不要重建整棵树，不要输出 Markdown、解释、React、HTML、CSS 或 JS 源码。",
+    ].join("\n"),
+    metadata: {
+      sourceMessageId: selection.sourceMessageId,
+      selectedNodeId: selection.selectedNodeId,
+      part: selection.part,
+      path: selection.path,
+      type: selection.type,
+      props: selection.props,
+      style: selection.style,
+    },
+  };
+}