nolo-cli 0.1.30 → 0.1.32

package/cli/agentRunCommand.ts

@@ -0,0 +1,190 @@
+import { runAgentTurn, type RunAgentTurnResult } from "./client/agentRun";
+import type { AgentRuntimeHostAdapter } from "./agentRuntimeLocal";
+import { getReadableCliDb, type AgentCommandDeps } from "./agentCommandSupport";
+import {
+  prepareTaskWorktree,
+  ensureWorkspacePackageLinks,
+} from "./client/taskWorktree";
+import {
+  formatLocalRunSummary,
+  inspectLocalRunWorkspace,
+  prepareLocalRunWorkspace,
+  type EnvLike,
+  type OutputLike,
+} from "./agentRunLocalWorkspace";
+import {
+  normalizeCliImageInput,
+  parseAgentRunArgs,
+  readAgentRunInput,
+  prependWorkflowReferencePrompt,
+  resolveWorkflowReference,
+  type ParsedAgentRunArgs,
+  type ResolvedWorkflowReference,
+} from "./agentRunParsing";
+import { resolveAgentRecordFromHybridStore } from "./agentRecordHelpers";
+import {
+  buildCurrentUserPlatformAgentCandidateKeys,
+} from "./agentAliases";
+import { parseUserIdFromAuthToken, resolveAuthToken, resolveServerUrl } from "./cliEnvHelpers";
+
+type AgentRunCommandDeps = AgentCommandDeps & {
+  env?: EnvLike;
+  scriptDir: string;
+  output?: OutputLike;
+  runner?: typeof runAgentTurn;
+  localRuntimeAdapterFactory?: (env: EnvLike, options?: { cwd?: string }) => AgentRuntimeHostAdapter;
+  prepareTaskWorktree?: typeof prepareTaskWorktree;
+  ensureWorkspacePackageLinks?: typeof ensureWorkspacePackageLinks;
+  inspectLocalRunWorkspace?: typeof inspectLocalRunWorkspace;
+  resolveWorkflowReference?: typeof resolveWorkflowReference;
+};
+
+// Compatibility shim for publish/runtime consumers that still import parser helpers from
+// the command module. New code should import these from agentRunParsing directly.
+export {
+  normalizeCliImageInput,
+  parseAgentRunArgs,
+  prependWorkflowReferencePrompt,
+  resolveWorkflowReference,
+};
+
+function shouldPrintLocalRunSummary(args: {
+  parsed: ParsedAgentRunArgs;
+  localRuntimeCwd?: string;
+}) {
+  return Boolean(args.localRuntimeCwd && args.parsed.runtimeMode === "local");
+}
+
+function writeUsage(output: OutputLike) {
+  output.write(
+    "Usage: nolo agent run <agent> <message> [--local|--server|--auto] [--continue <dialogId>] [--cwd <path>] [--max-tool-rounds <n>]\n" +
+      "       nolo agent run --agent <agent> --msg <message> [--image <url-or-path>] [--space <spaceId>] [--category <name>] [--inherit-from-dialog <dialog>] [--task-row-dbkey <key>] [--bg] [--timeout-ms <n>] [--no-stream]\n"
+  );
+}
+
+async function maybeResolveCurrentUserPlatformAgentKey(args: {
+  cliArgs: string[];
+  deps: AgentRunCommandDeps;
+  env: EnvLike;
+  output: OutputLike;
+  parsed: ParsedAgentRunArgs;
+}) {
+  const agentInput = readAgentRunInput(args.cliArgs);
+  if (!agentInput) return args.parsed;
+
+  const authToken = resolveAuthToken(args.cliArgs, args.env);
+  const currentUserId = parseUserIdFromAuthToken(authToken);
+  if (!currentUserId) return args.parsed;
+
+  const candidateKeys = buildCurrentUserPlatformAgentCandidateKeys(agentInput, currentUserId);
+  if (candidateKeys.length === 0 || candidateKeys[0] === args.parsed.agentKey) {
+    return args.parsed;
+  }
+
+  try {
+    const db = args.deps.db ?? await getReadableCliDb(args.output);
+    const resolved = await resolveAgentRecordFromHybridStore({
+      agentInput,
+      cliArgs: args.cliArgs,
+      env: args.env,
+      db,
+      fetchImpl: args.deps.fetchImpl ?? fetch,
+      fallbackFetchImpl: args.deps.fallbackFetchImpl,
+    });
+    return resolved ? { ...args.parsed, agentKey: resolved.agentKey } : args.parsed;
+  } catch {
+    return args.parsed;
+  }
+}
+
+export async function runAgentRunCommand(args: string[], deps: AgentRunCommandDeps) {
+  const env = deps.env ?? process.env;
+  const output = deps.output ?? process.stdout;
+  const parsed = parseAgentRunArgs(args);
+  if (!parsed) {
+    writeUsage(output);
+    return 1;
+  }
+  const resolvedParsed = await maybeResolveCurrentUserPlatformAgentKey({
+    cliArgs: args,
+    deps,
+    env,
+    output,
+    parsed,
+  });
+
+  const runner = deps.runner ?? runAgentTurn;
+  let workflowReference: ResolvedWorkflowReference | undefined;
+  if (resolvedParsed.workflowRef) {
+    try {
+      workflowReference = await (deps.resolveWorkflowReference ?? resolveWorkflowReference)(
+        resolvedParsed.workflowRef
+      );
+    } catch (error) {
+      output.write(`[nolo] ${error instanceof Error ? error.message : String(error)}\n`);
+      return 1;
+    }
+  }
+  const localWorkspace = await prepareLocalRunWorkspace({
+    parsed: resolvedParsed,
+    env,
+    output,
+    ...(deps.prepareTaskWorktree ? { prepareTaskWorktree: deps.prepareTaskWorktree } : {}),
+    ...(deps.ensureWorkspacePackageLinks
+      ? { ensureWorkspacePackageLinks: deps.ensureWorkspacePackageLinks }
+      : {}),
+  });
+  if (!localWorkspace.ok) return localWorkspace.exitCode;
+  const { localRuntimeCwd, runEnv } = localWorkspace;
+  const result: RunAgentTurnResult = await runner({
+    agentName: resolvedParsed.agentKey,
+    agentKey: resolvedParsed.agentKey,
+    serverUrl: resolveServerUrl(args, env),
+    message: prependWorkflowReferencePrompt(resolvedParsed.message, workflowReference),
+    imageUrls: resolvedParsed.imageUrls.map(normalizeCliImageInput),
+    scriptDir: deps.scriptDir,
+    env: runEnv,
+    output,
+    ...(deps.localRuntimeAdapterFactory
+      ? { localRuntimeAdapterFactory: deps.localRuntimeAdapterFactory }
+      : {}),
+    ...(localRuntimeCwd ? { localRuntimeCwd } : {}),
+    ...(resolvedParsed.runtimeMode ? { runtimeMode: resolvedParsed.runtimeMode } : {}),
+    ...(resolvedParsed.continueDialogId ? { continueDialogId: resolvedParsed.continueDialogId } : {}),
+    ...(resolvedParsed.spaceId ? { spaceId: resolvedParsed.spaceId } : {}),
+    ...(resolvedParsed.category ? { category: resolvedParsed.category } : {}),
+    ...(resolvedParsed.inheritedFromDialogKey ? { inheritedFromDialogKey: resolvedParsed.inheritedFromDialogKey } : {}),
+    ...(resolvedParsed.parentDialogId ? { parentDialogId: resolvedParsed.parentDialogId } : {}),
+    background: resolvedParsed.background,
+    noStream: resolvedParsed.noStream,
+    noDefaultTestRoot: resolvedParsed.noDefaultTestRoot,
+    ...(typeof resolvedParsed.maxToolRounds === "number" ? { maxToolRounds: resolvedParsed.maxToolRounds } : {}),
+    ...(typeof resolvedParsed.timeoutMs === "number" ? { timeoutMs: resolvedParsed.timeoutMs } : {}),
+    traceTools: resolvedParsed.traceTools,
+    ...(resolvedParsed.taskRunContext ? { taskRunContext: resolvedParsed.taskRunContext } : {}),
+  });
+
+  if (result.dialogId) {
+    if (resolvedParsed.background) {
+      output.write(`\n[nolo] background dialog ${result.dialogId}\n`);
+      output.write(`[nolo] read: nolo dialog read ${result.dialogId}\n`);
+    } else {
+      output.write(`\n[nolo] dialog ${result.dialogId}\n`);
+    }
+  }
+  if (shouldPrintLocalRunSummary({ parsed: resolvedParsed, localRuntimeCwd })) {
+    try {
+      const inspect = deps.inspectLocalRunWorkspace ?? inspectLocalRunWorkspace;
+      const inspection = await inspect(localRuntimeCwd!);
+      output.write(formatLocalRunSummary({
+        dialogId: result.dialogId,
+        inspection,
+      }));
+    } catch (error) {
+      output.write(
+        `\n[nolo] local run summary unavailable: ${error instanceof Error ? error.message : String(error)}\n`
+      );
+    }
+  }
+  return result.exitCode;
+}

package/cli/agentRunLocalWorkspace.ts

@@ -0,0 +1,182 @@
+import { formatPreparedTaskWorktree, prepareTaskWorktree, ensureWorkspacePackageLinks } from "./client/taskWorktree";
+import type { PreparedTaskWorktree } from "./client/taskWorktree";
+
+export type EnvLike = Record<string, string | undefined>;
+
+export type OutputLike = {
+  write(chunk: string): unknown;
+};
+
+export type LocalRunWorkspaceInspection = {
+  cwd: string;
+  clean: boolean;
+  status: string;
+  commit?: {
+    hash: string;
+    subject: string;
+  };
+};
+
+export type LocalWorkspaceRunArgs = {
+  agentKey: string;
+  runtimeMode?: "local" | "server" | "auto";
+  allowShell: boolean;
+  useTaskWorktree: boolean;
+  cwd?: string;
+};
+
+type InspectLocalRunWorkspaceDeps = {
+  runGitForLocalSummary?: typeof runGitForLocalSummary;
+};
+
+type PrepareLocalRunWorkspaceDeps = {
+  parsed: LocalWorkspaceRunArgs;
+  env: EnvLike;
+  output: OutputLike;
+  prepareTaskWorktree?: typeof prepareTaskWorktree;
+  ensureWorkspacePackageLinks?: typeof ensureWorkspacePackageLinks;
+};
+
+export async function runGitForLocalSummary(args: {
+  cwd: string;
+  gitArgs: string[];
+}) {
+  const proc = Bun.spawn(["git", ...args.gitArgs], {
+    cwd: args.cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (exitCode !== 0) {
+    throw new Error((stderr || stdout || `git ${args.gitArgs.join(" ")} failed`).trim());
+  }
+  return stdout.trim();
+}
+
+export async function inspectLocalRunWorkspace(
+  cwd: string,
+  deps: InspectLocalRunWorkspaceDeps = {}
+): Promise<LocalRunWorkspaceInspection> {
+  const runGit = deps.runGitForLocalSummary ?? runGitForLocalSummary;
+  const status = await runGit({
+    cwd,
+    gitArgs: ["status", "--short"],
+  });
+  const rawCommit = await runGit({
+    cwd,
+    gitArgs: ["log", "-1", "--format=%h%x00%s"],
+  }).catch(() => "");
+  const [hash, subject] = rawCommit.split("\0");
+  return {
+    cwd,
+    clean: status.trim() === "",
+    status,
+    ...(hash ? { commit: { hash, subject: subject ?? "" } } : {}),
+  };
+}
+
+export function formatLocalRunSummary(args: {
+  dialogId?: string;
+  inspection: LocalRunWorkspaceInspection;
+}) {
+  return [
+    "",
+    "[nolo] local run summary",
+    `workspace: ${args.inspection.cwd}`,
+    ...(args.dialogId ? [`dialog: ${args.dialogId}`] : []),
+    ...(args.inspection.commit
+      ? [`commit: ${args.inspection.commit.hash} ${args.inspection.commit.subject}`]
+      : []),
+    `dirty: ${args.inspection.clean ? "clean" : "dirty"}`,
+    ...(!args.inspection.clean && args.inspection.status.trim()
+      ? [`status:\n${args.inspection.status.trim()}`]
+      : []),
+    "",
+  ].join("\n");
+}
+
+function shouldPrepareTaskWorktree(parsed: LocalWorkspaceRunArgs) {
+  return !parsed.cwd && (parsed.useTaskWorktree || parsed.allowShell);
+}
+
+function buildTaskWorktreeEnv(args: {
+  env: EnvLike;
+  worktreePath?: string;
+  allowShell: boolean;
+}) {
+  return {
+    ...args.env,
+    ...(args.allowShell ? { NOLO_LOCAL_SHELL_MODE: "worktree" } : {}),
+    ...(args.worktreePath ? { NOLO_LOCAL_WORKTREE: args.worktreePath } : {}),
+  };
+}
+
+function shouldBindLocalWorkspace(args: {
+  parsed: LocalWorkspaceRunArgs;
+  localRuntimeCwd?: string;
+}) {
+  return Boolean(
+    args.localRuntimeCwd &&
+      (args.parsed.runtimeMode === "local" || args.parsed.allowShell || args.parsed.useTaskWorktree)
+  );
+}
+
+export async function prepareLocalRunWorkspace(
+  args: PrepareLocalRunWorkspaceDeps
+): Promise<
+  | {
+      ok: true;
+      localRuntimeCwd?: string;
+      runEnv: EnvLike;
+    }
+  | {
+      ok: false;
+      exitCode: 1;
+    }
+> {
+  let localRuntimeCwd = args.parsed.cwd;
+  if (shouldPrepareTaskWorktree(args.parsed)) {
+    try {
+      const preparedWorktree: PreparedTaskWorktree = await (args.prepareTaskWorktree ?? prepareTaskWorktree)({
+        agentKey: args.parsed.agentKey,
+        env: args.env,
+      });
+      localRuntimeCwd = preparedWorktree.path;
+      args.output.write(formatPreparedTaskWorktree(preparedWorktree));
+    } catch (error) {
+      args.output.write(
+        "[nolo] Could not prepare a local task worktree.\n" +
+          "Run from inside a git repository, or set NOLO_LOCAL_WORKTREE to an existing isolated checkout.\n" +
+          `Reason: ${error instanceof Error ? error.message : String(error)}\n`
+      );
+      return { ok: false, exitCode: 1 };
+    }
+  }
+  if (shouldBindLocalWorkspace({ parsed: args.parsed, localRuntimeCwd })) {
+    try {
+      await (args.ensureWorkspacePackageLinks ?? ensureWorkspacePackageLinks)(localRuntimeCwd!);
+    } catch (error) {
+      args.output.write(
+        "[nolo] Dependency preflight failed for local task worktree.\n" +
+          "The worktree may have node_modules entries that point outside the task checkout, or paths that cannot be repaired safely.\n" +
+          `Reason: ${error instanceof Error ? error.message : String(error)}\n`
+      );
+      return { ok: false, exitCode: 1 };
+    }
+  }
+  return {
+    ok: true,
+    ...(localRuntimeCwd ? { localRuntimeCwd } : {}),
+    runEnv: shouldBindLocalWorkspace({ parsed: args.parsed, localRuntimeCwd })
+      ? buildTaskWorktreeEnv({
+          env: args.env,
+          worktreePath: localRuntimeCwd,
+          allowShell: args.parsed.allowShell,
+        })
+      : args.env,
+  };
+}

package/cli/agentRunParsing.ts

@@ -0,0 +1,298 @@
+import { existsSync, readFileSync } from "node:fs";
+import { extname, resolve } from "node:path";
+
+import {
+  buildAgentRunDialogLineageFields,
+  normalizeAgentRunDialogLineage,
+} from "../ai/agent/agentRunDialogLineage";
+import { parseSkillDocProtocol, type WorkflowReferenceConfig } from "../ai/skills/skillDocProtocol";
+
+import { resolveCliAgentKeyInput } from "./agentAliases";
+import type { AgentRuntimeRequestedMode } from "./agentRuntimeLocal";
+import type { TaskRunPromptContext } from "./client/taskRunPrompt";
+
+type ParseAgentRunArgsOptions = {
+  readTextFile?: (path: string) => string;
+};
+
+export type ParsedAgentRunArgs = {
+  agentKey: string;
+  message: string;
+  imageUrls: string[];
+  allowShell: boolean;
+  runtimeMode?: AgentRuntimeRequestedMode;
+  continueDialogId?: string;
+  spaceId?: string;
+  category?: string;
+  inheritedFromDialogKey?: string;
+  parentDialogId?: string;
+  background: boolean;
+  noStream: boolean;
+  noDefaultTestRoot: boolean;
+  cwd?: string;
+  maxToolRounds?: number;
+  timeoutMs?: number;
+  traceTools: boolean;
+  useTaskWorktree: boolean;
+  taskRunContext?: TaskRunPromptContext;
+  workflowRef?: string;
+};
+
+export type ResolvedWorkflowReference = {
+  ref: string;
+  content: string;
+  config?: Partial<WorkflowReferenceConfig>;
+};
+
+const DEFAULT_TEST_ROOT_DIALOG_ID = "01KN6V3MVEQA4Q1PNKVM2W7YY8";
+const DEFAULT_TEST_ROOT_DIALOG_KEY = `dialog-b2e06f801f-${DEFAULT_TEST_ROOT_DIALOG_ID}`;
+const DEFAULT_TEST_DIALOG_CATEGORY_ID = "test-dialogs";
+
+function readFlagValue(args: string[], flag: string) {
+  const index = args.indexOf(flag);
+  if (index < 0) return undefined;
+  return args[index + 1];
+}
+
+export function readAgentRunInput(args: string[]) {
+  const rawInput = readFlagValue(args, "--agent") ?? positionalArgs(args)[0];
+  const trimmed = rawInput?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function readRepeatedFlagValues(args: string[], flag: string) {
+  const values: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === flag && args[index + 1]) {
+      values.push(args[index + 1]);
+      index += 1;
+    }
+  }
+  return values;
+}
+
+function runtimeModeFromArgs(args: string[]): AgentRuntimeRequestedMode | undefined {
+  if (args.includes("--local")) return "local";
+  if (args.includes("--server")) return "server";
+  if (args.includes("--auto")) return "auto";
+  return undefined;
+}
+
+function parseNonNegativeInteger(value: string | undefined) {
+  if (!value) return undefined;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0) return undefined;
+  return Math.floor(parsed);
+}
+
+function parsePositiveInteger(value: string | undefined) {
+  if (!value) return undefined;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return undefined;
+  return Math.floor(parsed);
+}
+
+function positionalArgs(args: string[]) {
+  const values: string[] = [];
+  const valuelessFlags = new Set([
+    "--local",
+    "--server",
+    "--auto",
+    "--dangerously-allow-shell",
+    "--worktree-task",
+    "--trace-tools",
+    "--bg",
+    "--no-stream",
+    "--debug",
+    "--no-default-test-root",
+  ]);
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (valuelessFlags.has(arg)) continue;
+    if (arg.startsWith("--")) {
+      index += 1;
+      continue;
+    }
+    values.push(arg);
+  }
+  return values;
+}
+
+function parseDialogReference(rawInput: string) {
+  const normalized = rawInput.trim();
+  if (normalized.startsWith("dialog-")) {
+    const parts = normalized.split("-");
+    return {
+      dialogKey: normalized,
+      dialogId: parts.at(-1) ?? normalized,
+    };
+  }
+  const dialogMatch = normalized.match(/dialog-([a-zA-Z0-9]+)-([a-zA-Z0-9]+)/);
+  if (dialogMatch) {
+    return {
+      dialogKey: `dialog-${dialogMatch[1]}-${dialogMatch[2]}`,
+      dialogId: dialogMatch[2],
+    };
+  }
+  return {
+    dialogId: normalized,
+  };
+}
+
+function workflowRefToCandidatePath(cwd: string, ref: string) {
+  const normalized = ref.trim();
+  if (!normalized) return "";
+  if (normalized.endsWith(".md") || normalized.includes("/") || normalized.includes("\\")) {
+    const directPath = resolve(cwd, normalized);
+    if (existsSync(directPath)) return directPath;
+  }
+  const fileName = normalized.replace(/[^a-zA-Z0-9\u4e00-\u9fa5]+/g, "-").replace(/^-+|-+$/g, "");
+  return resolve(cwd, "docs", "workflows", `${fileName}.md`);
+}
+
+function mimeTypeForPath(path: string) {
+  switch (extname(path).toLowerCase()) {
+    case ".jpg":
+    case ".jpeg":
+      return "image/jpeg";
+    case ".webp":
+      return "image/webp";
+    case ".gif":
+      return "image/gif";
+    default:
+      return "image/png";
+  }
+}
+
+export function parseAgentRunArgs(
+  args: string[],
+  options: ParseAgentRunArgsOptions = {}
+): ParsedAgentRunArgs | null {
+  const agentKey = readFlagValue(args, "--agent") ?? positionalArgs(args)[0];
+  const explicitMsg = readFlagValue(args, "--msg");
+  const msgFile = readFlagValue(args, "--msg-file");
+  const fileMessage = msgFile
+    ? (options.readTextFile ?? ((path: string) => readFileSync(path, "utf8")))(msgFile)
+    : undefined;
+  const rawMessage = explicitMsg ?? fileMessage ?? positionalArgs(args).slice(1).join(" ");
+  if (!agentKey || !rawMessage.trim()) return null;
+  const message = rawMessage.trim();
+  const runtimeMode = runtimeModeFromArgs(args);
+  const rawContinueDialogId = readFlagValue(args, "--continue") ?? readFlagValue(args, "--dialog");
+  const continueDialogId = normalizeAgentRunDialogLineage({
+    continueDialogId: rawContinueDialogId,
+  }).continueDialogId;
+  const spaceId = readFlagValue(args, "--space");
+  const category = readFlagValue(args, "--category");
+  const inheritedFromDialog = readFlagValue(args, "--inherit-from-dialog");
+  const noDefaultTestRoot = args.includes("--no-default-test-root");
+  const cwd = readFlagValue(args, "--cwd");
+  const maxToolRounds = parseNonNegativeInteger(
+    readFlagValue(args, "--max-tool-rounds") ?? readFlagValue(args, "--rounds")
+  );
+  const timeoutMs = parsePositiveInteger(readFlagValue(args, "--timeout-ms"));
+  const inheritedRef = inheritedFromDialog
+    ? parseDialogReference(inheritedFromDialog)
+    : !continueDialogId && !noDefaultTestRoot
+      ? {
+          dialogKey: DEFAULT_TEST_ROOT_DIALOG_KEY,
+          dialogId: DEFAULT_TEST_ROOT_DIALOG_ID,
+        }
+      : undefined;
+  const imageUrls = [
+    ...readRepeatedFlagValues(args, "--image"),
+    ...readRepeatedFlagValues(args, "--image-url"),
+  ];
+  const useTaskWorktree = args.includes("--worktree-task");
+  const workflowRef = readFlagValue(args, "--workflow");
+  const taskRowDbKey = readFlagValue(args, "--task-row-dbkey");
+  const artifactIds = readFlagValue(args, "--artifact-ids")
+    ?.split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+  return {
+    agentKey: resolveCliAgentKeyInput(agentKey),
+    message,
+    imageUrls,
+    allowShell: args.includes("--dangerously-allow-shell"),
+    traceTools: args.includes("--trace-tools"),
+    useTaskWorktree,
+    ...(workflowRef ? { workflowRef } : {}),
+    ...(taskRowDbKey
+      ? {
+          taskRunContext: {
+            rowDbKey: taskRowDbKey,
+            ...(readFlagValue(args, "--task-run-id") ? { taskRunId: readFlagValue(args, "--task-run-id") } : {}),
+            ...(readFlagValue(args, "--work-item-id") ? { workItemId: readFlagValue(args, "--work-item-id") } : {}),
+            ...(artifactIds?.length ? { artifactIds } : {}),
+          },
+        }
+      : {}),
+    ...(runtimeMode ? { runtimeMode } : useTaskWorktree ? { runtimeMode: "local" as const } : {}),
+    background: args.includes("--bg"),
+    noStream: args.includes("--no-stream"),
+    noDefaultTestRoot,
+    ...buildAgentRunDialogLineageFields({
+      continueDialogId,
+      inheritedFromDialogKey: inheritedRef?.dialogKey,
+      parentDialogId: inheritedRef?.dialogId,
+    }),
+    ...(!continueDialogId && spaceId ? { spaceId } : {}),
+    ...(category
+      ? { category }
+      : !continueDialogId && !noDefaultTestRoot
+        ? { category: DEFAULT_TEST_DIALOG_CATEGORY_ID }
+        : {}),
+    ...(cwd ? { cwd } : {}),
+    ...(typeof maxToolRounds === "number" ? { maxToolRounds } : {}),
+    ...(typeof timeoutMs === "number" ? { timeoutMs } : {}),
+  };
+}
+
+export async function resolveWorkflowReference(ref: string, cwd = process.cwd()): Promise<ResolvedWorkflowReference> {
+  const path = workflowRefToCandidatePath(cwd, ref);
+  if (!path || !existsSync(path)) {
+    throw new Error(`Workflow reference not found: ${ref}`);
+  }
+  const markdown = readFileSync(path, "utf8");
+  const parsed = parseSkillDocProtocol(markdown);
+  return {
+    ref,
+    content: parsed.content,
+    ...(parsed.meta?.workflowConfig ? { config: parsed.meta.workflowConfig } : {}),
+  };
+}
+
+export function prependWorkflowReferencePrompt(message: string, workflow?: ResolvedWorkflowReference): string {
+  if (!workflow) return message;
+  const config = workflow.config;
+  return [
+    "AI-native workflow reference:",
+    "- This reference is guidance for the agent, not a central workflow engine.",
+    `- ref: ${workflow.ref}`,
+    ...(config?.id ? [`- id: ${config.id}`] : []),
+    ...(config?.name ? [`- name: ${config.name}`] : []),
+    ...(config?.defaultAgent ? [`- suggested defaultAgent: ${config.defaultAgent}`] : []),
+    ...(config?.inputs?.length ? [`- inputs: ${config.inputs.join(", ")}`] : []),
+    ...(config?.recommendedTools?.length ? [`- recommendedTools: ${config.recommendedTools.join(", ")}`] : []),
+    ...(config?.requiredTools?.length ? [`- requiredTools: ${config.requiredTools.join(", ")}`] : []),
+    ...(config?.requiredOutputs?.length ? [`- requiredOutputs: ${config.requiredOutputs.join(", ")}`] : []),
+    ...(config?.gates?.length ? [`- gates: ${config.gates.join(", ")}`] : []),
+    ...(config?.contextStrategy ? [`- contextStrategy: ${config.contextStrategy}`] : []),
+    ...(config?.failureProtocol ? [`- failureProtocol: ${config.failureProtocol}`] : []),
+    "",
+    "Reference body:",
+    workflow.content,
+    "",
+    "User task:",
+    message,
+  ].join("\n");
+}
+
+export function normalizeCliImageInput(input: string) {
+  if (/^(https?:|data:|file:)/i.test(input)) return input;
+  const absolutePath = resolve(input);
+  if (!existsSync(absolutePath)) return input;
+  const base64 = readFileSync(absolutePath).toString("base64");
+  return `data:${mimeTypeForPath(absolutePath)};base64,${base64}`;
+}