sim 2.0.0-preview.17.1 → 2.0.0-preview.21.1

package/README.md

@@ -57,6 +57,11 @@ Each setting resolves independently, first match wins:
 | --- | --- |
 | 1 | Command-line flag (`--endpoint`, `--workspace`, `--output`) |
 | 2 | Environment (`SIM_ENDPOINT`, `SIM_API_KEY`, `SIM_WORKSPACE`, `SIM_OUTPUT`) |
+
+`SIM_TIMEOUT_SECONDS` bounds each request (default `3600`, `0` waits
+indefinitely) and `SIM_DEBUG=1` traces requests to stderr. Node ignores
+`HTTPS_PROXY` unless `NODE_USE_ENV_PROXY=1` is also set, on Node 22.21+ or
+24.5+; the CLI warns when a proxy is configured but will not be used.
 | 3 | `~/.sim/config` / `~/.sim/credentials` for the selected profile |
 | 4 | Built-in default (`https://www.sim.ai`, `table`) |
 

package/dist/index.js

@@ -2539,6 +2539,53 @@ function readPackageVersion() {
 var CLI_VERSION = readPackageVersion();
 var USER_AGENT = `sim-cli/${CLI_VERSION} node/${process.versions.node} (${process.platform}; ${process.arch})`;
 
+// src/http/environment.ts
+var reported = new Set;
+function once(key, message) {
+  if (reported.has(key))
+    return;
+  reported.add(key);
+  process.stderr.write(`warning: ${message}
+`);
+}
+var PROXY_VARIABLES = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"];
+var PROXY_SUPPORT = { 22: 21, 24: 5 };
+var FIRST_SUPPORTED_MAJOR = 24;
+function runtimeCanProxy(version) {
+  const [major, minor] = version.replace(/^v/, "").split(".").map(Number);
+  if (!Number.isFinite(major) || !Number.isFinite(minor))
+    return false;
+  const firstSupportedMinor = PROXY_SUPPORT[major];
+  if (firstSupportedMinor !== undefined)
+    return minor >= firstSupportedMinor;
+  return major > FIRST_SUPPORTED_MAJOR;
+}
+function warnIfProxyIgnored(env2 = process.env, version = process.version) {
+  const variable = PROXY_VARIABLES.find((name) => env2[name]);
+  if (!variable)
+    return;
+  if (env2.NODE_USE_ENV_PROXY && runtimeCanProxy(version))
+    return;
+  once("proxy", runtimeCanProxy(version) ? `${variable} is set but Node only uses it when NODE_USE_ENV_PROXY=1. Re-run with NODE_USE_ENV_PROXY=1 to route through the proxy.` : `${variable} is set but Node ${version} cannot use it. Upgrade to Node 22.21 or 24.5 and set NODE_USE_ENV_PROXY=1 to route through the proxy.`);
+}
+var LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]", "::1", "0.0.0.0"]);
+function isLoopback(hostname) {
+  return LOOPBACK.has(hostname) || hostname.endsWith(".localhost");
+}
+function warnIfKeyOverCleartext(endpoint, hasApiKey) {
+  if (!hasApiKey)
+    return;
+  let url;
+  try {
+    url = new URL(endpoint);
+  } catch {
+    return;
+  }
+  if (url.protocol !== "http:" || isLoopback(url.hostname))
+    return;
+  once("cleartext", `sending your API key to ${url.host} over http. Anything on the path can read it — use https unless this network is trusted.`);
+}
+
 // src/http/client.ts
 class SimApiError extends Error {
   status;
@@ -2623,6 +2670,51 @@ function dropUnionBranchNoise(issues) {
   const kept = issues.filter((issue) => !issues.some((other) => rejectsAKeyThatValidated(issue, other)));
   return kept.length > 0 ? kept : issues;
 }
+var DEFAULT_TIMEOUT_SECONDS = 3600;
+var MAX_TIMEOUT_MS = 2 ** 31 - 1;
+var RAISE_TIMEOUT_HINT = "Raise SIM_TIMEOUT_SECONDS, or set it to 0 to wait indefinitely.";
+function isRequestTimeout(error) {
+  return error instanceof DOMException && error.name === "TimeoutError";
+}
+function resolveTimeoutMs(env2 = process.env) {
+  const raw = env2.SIM_TIMEOUT_SECONDS;
+  if (raw === undefined || raw.trim() === "")
+    return DEFAULT_TIMEOUT_SECONDS * 1000;
+  const seconds = Number(raw);
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    throw new SimApiError(`Invalid SIM_TIMEOUT_SECONDS "${raw}". Use a non-negative number of seconds, or 0 to disable.`, 0);
+  }
+  const ms = seconds === 0 ? 0 : Math.max(1, Math.round(seconds * 1000));
+  if (ms > MAX_TIMEOUT_MS) {
+    throw new SimApiError(`SIM_TIMEOUT_SECONDS "${raw}" is longer than Node can wait (${Math.floor(MAX_TIMEOUT_MS / 1000)}s). Use 0 to wait indefinitely.`, 0);
+  }
+  return ms;
+}
+function combineSignals(caller, timeout) {
+  if (!caller)
+    return timeout;
+  if (!timeout)
+    return caller;
+  if (typeof AbortSignal.any === "function")
+    return AbortSignal.any([caller, timeout]);
+  const controller = new AbortController;
+  for (const signal of [caller, timeout]) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      break;
+    }
+    signal.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+  }
+  return controller.signal;
+}
+function debugEnabled(env2 = process.env) {
+  const raw = env2.SIM_DEBUG;
+  return raw !== undefined && raw !== "" && raw !== "0" && raw.toLowerCase() !== "false";
+}
+function traceRequest(method, url, status, startedAt) {
+  process.stderr.write(`${source_default.dim(`[sim] ${method} ${url} → ${status} ${Math.round(performance.now() - startedAt)}ms`)}
+`);
+}
 function formatApiErrorDetails(details) {
   const issues = [];
   const seen = new Set;
@@ -2706,10 +2798,18 @@ class SimClient {
     const apiKey = this.resolveApiKey(options.auth);
     const url = buildUrl(this.profile.endpoint, path, options.query);
     const hasBody = options.body !== undefined;
+    const method = options.method ?? "GET";
+    warnIfProxyIgnored();
+    warnIfKeyOverCleartext(this.profile.endpoint, Boolean(apiKey));
+    const timeoutMs = resolveTimeoutMs();
+    const timeout = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined;
+    const signal = combineSignals(options.signal, timeout);
+    const trace = debugEnabled();
+    const startedAt = performance.now();
     let response;
     try {
       response = await fetch(url, {
-        method: options.method ?? "GET",
+        method,
         headers: {
           ...apiKey ? { "x-api-key": apiKey } : {},
           accept: "application/json",
@@ -2718,15 +2818,22 @@ class SimClient {
           ...options.headers
         },
         body: hasBody ? JSON.stringify(options.body) : undefined,
-        signal: options.signal,
+        signal,
         redirect: "manual"
       });
     } catch (cause) {
+      if (trace)
+        traceRequest(method, url, "failed", startedAt);
       if (options.signal?.aborted) {
         throw new SimApiError("Request cancelled.", 0);
       }
+      if (timeout?.aborted) {
+        throw new SimApiError(`${url} did not answer within ${timeoutMs / 1000}s. ${RAISE_TIMEOUT_HINT}`, 0);
+      }
       throw new SimApiError(`Could not reach ${this.profile.endpoint}: ${cause.message}`, 0);
     }
+    if (trace)
+      traceRequest(method, url, response.status, startedAt);
     if (REDIRECT_STATUSES.has(response.status))
       throw this.toRedirectError(url, path, response);
     if (!response.ok) {
@@ -2768,16 +2875,16 @@ function redirectEndpoint(endpoint, requestPath, target) {
   return suggested === endpoint.replace(/\/+$/, "") ? null : suggested;
 }
 function pageProgress() {
-  let reported = false;
+  let reported2 = false;
   return {
     advance: (fetched) => {
       if (!process.stderr.isTTY)
         return;
-      reported = true;
+      reported2 = true;
       process.stderr.write(`\r${source_default.dim(`fetched ${fetched}…`)}\x1B[K`);
     },
     finish: () => {
-      if (reported)
+      if (reported2)
         process.stderr.write("\r\x1B[K");
     }
   };
@@ -11064,7 +11171,7 @@ function attachCredentialCommands(program2) {
 }
 
 // src/commands/protocol/files-get.ts
-import { once } from "node:events";
+import { once as once2 } from "node:events";
 import { createWriteStream } from "node:fs";
 import { link, lstat, mkdtemp, readlink, rename, rm } from "node:fs/promises";
 import { dirname as dirname2, join as join2, resolve as resolve2 } from "node:path";
@@ -11079,6 +11186,9 @@ function printProtocolResult(format, result) {
 
 // src/commands/protocol/files-get.ts
 function writeFailure(path, error) {
+  if (isRequestTimeout(error)) {
+    return new SimApiError(`Downloading ${path} timed out. ${RAISE_TIMEOUT_HINT}`, 0);
+  }
   const code = error.code;
   if (code === "EEXIST") {
     return new SimApiError(`${path} already exists. Pass --force to overwrite it, or choose another output path.`, 0);
@@ -11169,7 +11279,7 @@ async function streamToStdout(body, output = process.stdout) {
       if (done)
         return;
       if (!output.write(value))
-        await once(output, "drain");
+        await once2(output, "drain");
     }
   } finally {
     reader.releaseLock();
@@ -11429,6 +11539,278 @@ function attachKnowledgeDocumentUpload(documents) {
   });
 }
 
+// src/commands/protocol/logs-follow.ts
+var DEFAULT_BACKLOG = 10;
+var DEFAULT_INTERVAL_SECONDS = 3;
+var MIN_INTERVAL_SECONDS = 0.1;
+var MAX_BACKOFF_MS = 30000;
+var POLL_PAGE_SIZE = 100;
+var MAX_PAGES_PER_POLL = 10;
+var MAX_REMEMBERED_RUNS = 5000;
+var MAX_CELL_WIDTH2 = 60;
+var WAIT_SLICE_MS = 250;
+var RETRYABLE_CLIENT_STATUSES = new Set([408, 425, 429]);
+var ERASE_LINE = `${String.fromCharCode(27)}[K`;
+function collect(value, previous) {
+  return [...previous, value];
+}
+function at2(row, path) {
+  return path.split(".").reduce((value, key) => value && typeof value === "object" ? value[key] : undefined, row);
+}
+function renderCell2(value, format) {
+  switch (format) {
+    case "timestamp":
+      return timestamp2(value);
+    case "duration":
+      return duration(value);
+    case "bytes":
+      return bytes(value);
+    case "bool":
+      return bool2(value);
+    case "cost":
+      return typeof value === "number" ? `$${value.toFixed(4)}` : text(null);
+    default:
+      return text(typeof value === "object" && value !== null ? JSON.stringify(value) : value);
+  }
+}
+var COLUMNS = (CLI_CONTRACT.listLogs?.columns ?? []).map((spec) => ({
+  header: spec.header,
+  value: (row) => renderCell2(at2(row, spec.path ?? spec.header), spec.format)
+}));
+function oneLine2(value) {
+  return value.replace(/\s*[\r\n\t]+\s*/g, " ");
+}
+function pad2(value, width) {
+  return value + " ".repeat(Math.max(0, width - visibleWidth(value)));
+}
+function clamp2(value, width) {
+  if (visibleWidth(value) <= width || visibleWidth(value) !== value.length)
+    return value;
+  return `${value.slice(0, Math.max(1, width - 1))}…`;
+}
+function createTableWriter() {
+  let widths = null;
+  return (rows) => {
+    const lines = rows.map((row) => COLUMNS.map((column) => oneLine2(column.value(row))));
+    if (!widths) {
+      widths = COLUMNS.map((column, index) => Math.min(MAX_CELL_WIDTH2, Math.max(visibleWidth(column.header), ...lines.map((line) => visibleWidth(line[index])))));
+      const header = widths;
+      console.log(source_default.dim(COLUMNS.map((column, index) => pad2(column.header.toUpperCase(), header[index])).join("  ").trimEnd()));
+    }
+    const locked = widths;
+    for (const line of lines) {
+      console.log(line.map((cell, index) => pad2(clamp2(cell, locked[index]), locked[index])).join("  ").trimEnd());
+    }
+  };
+}
+function createWriter(format) {
+  if (format === "json") {
+    return (rows) => {
+      for (const row of rows)
+        console.log(JSON.stringify(row));
+    };
+  }
+  if (format === "yaml") {
+    return (rows) => {
+      for (const row of rows) {
+        console.log(`---
+${dump(row, { lineWidth: 0, noRefs: true }).trimEnd()}`);
+      }
+    };
+  }
+  if (format === "text") {
+    return (rows) => {
+      if (rows.length > 0)
+        printList("text", rows, COLUMNS);
+    };
+  }
+  return createTableWriter();
+}
+function followStatus() {
+  let reported2 = false;
+  return {
+    note: (message) => {
+      if (!process.stderr.isTTY)
+        return;
+      reported2 = true;
+      process.stderr.write(`\r${source_default.dim(message)}${ERASE_LINE}`);
+    },
+    warn: (message) => {
+      if (reported2) {
+        reported2 = false;
+        process.stderr.write(`\r${ERASE_LINE}`);
+      }
+      process.stderr.write(`warning: ${message}
+`);
+    },
+    clear: () => {
+      if (!reported2)
+        return;
+      reported2 = false;
+      process.stderr.write(`\r${ERASE_LINE}`);
+    }
+  };
+}
+function watchForInterrupt() {
+  let stopped = false;
+  const stop = () => {
+    stopped = true;
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  return {
+    interrupted: () => stopped,
+    dispose: () => {
+      process.off("SIGINT", stop);
+      process.off("SIGTERM", stop);
+    }
+  };
+}
+async function waitFor(ms, interrupted) {
+  let remaining = ms;
+  while (remaining > 0 && !interrupted()) {
+    const step = Math.min(WAIT_SLICE_MS, remaining);
+    await sleep(step);
+    remaining -= step;
+  }
+}
+function isUnprinted(state, row) {
+  if (state.seen.has(row.runId))
+    return false;
+  return state.floor === null || row.startedAt >= state.floor;
+}
+function remember(state, rows) {
+  for (const row of rows)
+    state.seen.set(row.runId, row.startedAt);
+  let excess = state.seen.size - MAX_REMEMBERED_RUNS;
+  if (excess <= 0)
+    return;
+  for (const [runId, startedAt] of state.seen) {
+    if (excess <= 0)
+      break;
+    if (state.floor === null || startedAt > state.floor)
+      state.floor = startedAt;
+    state.seen.delete(runId);
+    excess -= 1;
+  }
+}
+async function collectUnprinted(client, path, query, state, pageSize, maxPages) {
+  const rows = [];
+  let cursor = null;
+  let truncated = false;
+  for (let page = 0;page < maxPages; page += 1) {
+    const response = await client.request(path, {
+      query: { ...query, limit: pageSize, cursor }
+    });
+    const page_rows = response?.data ?? [];
+    const unprinted = page_rows.filter((row) => isUnprinted(state, row));
+    rows.push(...unprinted);
+    cursor = response?.nextCursor ?? null;
+    if (!cursor || page_rows.length === 0 || unprinted.length < page_rows.length)
+      break;
+    if (page === maxPages - 1)
+      truncated = true;
+  }
+  return { rows, truncated };
+}
+function isTransient(error) {
+  if (!(error instanceof SimApiError))
+    return false;
+  if (error.status === 0 || error.status >= 500)
+    return true;
+  return RETRYABLE_CLIENT_STATUSES.has(error.status);
+}
+function nonNegativeInteger(raw, flag) {
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new SimApiError(`${flag} must be a non-negative integer`, 0);
+  }
+  return value;
+}
+function intervalMs(raw) {
+  const seconds = Number(raw);
+  if (!Number.isFinite(seconds) || seconds < MIN_INTERVAL_SECONDS) {
+    throw new SimApiError(`--interval must be at least ${MIN_INTERVAL_SECONDS} seconds`, 0);
+  }
+  return Math.round(seconds * 1000);
+}
+function inSeconds(ms) {
+  return Math.round(ms / 100) / 10;
+}
+function attachLogsFollow(logs) {
+  logs.command("follow").description("Watch runs as they arrive, printing each new run once").option("--workflow <id>", "Only follow runs of this workflow (repeatable)", collect, []).option("--folder <path>", "Only follow runs of workflows in this folder (repeatable)", collect, []).option("--trigger <type>", "Only follow runs with this trigger type (repeatable)", collect, []).addOption(new Option("--level <level>", "Only follow runs at this severity").choices([
+    ...V2_OPERATIONS.listLogs.query.level.values
+  ])).addOption(new Option("--details <level>", "Response detail level; full names each run’s workflow").choices([...V2_OPERATIONS.listLogs.query.details.values]).default("full")).option("-n, --lines <count>", "Recent runs to print before watching", String(DEFAULT_BACKLOG)).option("--interval <seconds>", "Seconds between polls", String(DEFAULT_INTERVAL_SECONDS)).addHelpText("after", `
+Each run prints once, when it is first seen, so its status is the status it had
+at that moment. With --output json every run is a JSON object on its own line
+(JSONL) rather than a member of an array, because a follow never ends and so can
+never close one; --output yaml emits a --- separated document stream. Progress
+and retries go to stderr, leaving stdout a clean stream of rows. Ctrl-C stops the
+follow.
+
+Examples:
+  $ sim logs follow --level error
+  $ sim logs follow --workflow wf_123 -n 0
+  $ sim --output json logs follow | jq -r '.runId'
+`).action(async (options, command) => {
+    const lines = nonNegativeInteger(options.lines, "--lines");
+    const delay = intervalMs(options.interval);
+    const { client, profile } = clientFrom(command);
+    const path = V2_OPERATIONS.listLogs.path;
+    const query = {
+      workspaceId: client.requireWorkspace(),
+      workflowIds: options.workflow?.length ? options.workflow.join(",") : undefined,
+      folderPaths: options.folder?.length ? options.folder.map(encodeFolderPath).join(",") : undefined,
+      triggers: options.trigger?.length ? options.trigger.join(",") : undefined,
+      level: options.level,
+      details: options.details,
+      order: "desc"
+    };
+    const write = createWriter(profile.output);
+    const status = followStatus();
+    const interrupt = watchForInterrupt();
+    const state = { seen: new Map, floor: null };
+    try {
+      const seed = await collectUnprinted(client, path, query, state, Math.max(lines, 1), 1);
+      remember(state, seed.rows);
+      state.floor = seed.rows.at(-1)?.startedAt ?? null;
+      if (seed.truncated && seed.rows.length < lines) {
+        status.warn(`asked for ${lines} earlier runs but a page holds ${seed.rows.length}; following from there — see sim logs list for more`);
+      }
+      write(lines > 0 ? seed.rows.slice(0, lines).reverse() : []);
+      let failures = 0;
+      while (!interrupt.interrupted()) {
+        await waitFor(failures === 0 ? delay : Math.min(delay * 2 ** failures, MAX_BACKOFF_MS), interrupt.interrupted);
+        if (interrupt.interrupted())
+          break;
+        let fresh;
+        try {
+          fresh = await collectUnprinted(client, path, query, state, POLL_PAGE_SIZE, MAX_PAGES_PER_POLL);
+        } catch (error) {
+          if (!isTransient(error))
+            throw error;
+          failures += 1;
+          const next = Math.min(delay * 2 ** failures, MAX_BACKOFF_MS);
+          status.note(`poll failed (${error.message}); retrying in ${inSeconds(next)}s…`);
+          continue;
+        }
+        failures = 0;
+        status.clear();
+        if (fresh.truncated) {
+          status.warn(`more than ${MAX_PAGES_PER_POLL * POLL_PAGE_SIZE} runs arrived at once; older ones were skipped — see sim logs list`);
+        }
+        if (fresh.rows.length === 0)
+          continue;
+        remember(state, fresh.rows);
+        write(fresh.rows.reverse());
+      }
+    } finally {
+      status.clear();
+      interrupt.dispose();
+    }
+  });
+}
+
 // src/runtime/options.ts
 var DEFAULT_LIMIT = 100;
 function describeField(flag, descriptor, name, field) {
@@ -11518,7 +11900,7 @@ function addOperationOptions(command, operation, commandSpec, operationSpec) {
 }
 
 // src/commands/protocol/resource-directory.ts
-var COLUMNS = [
+var COLUMNS2 = [
   { header: "kind", value: (entry) => text(entry.kind) },
   { header: "name", value: (entry) => text(entry.name) },
   {
@@ -11584,7 +11966,7 @@ function attachResourceDirectoryCommands(group, config) {
       listResources(client, config, workspaceId, folderPath, options.search, limit)
     ]);
     const entries = entriesFor(config, folders, resources);
-    printList(profile.output, entries.slice(0, limit), COLUMNS);
+    printList(profile.output, entries.slice(0, limit), COLUMNS2);
   });
   group.command("mkdir").argument("<path>", "Folder path to create; the leading / is optional").allowExcessArguments(false).description(`Create a ${config.kind} directory at a path`).action(async (path, _options, command) => {
     const { client, profile } = clientFrom(command);
@@ -11613,17 +11995,17 @@ function jsonFlag(raw, flagName, kind) {
 }
 async function watchImport(client, workspaceId, job) {
   let current = job;
-  let reported = -1;
+  let reported2 = -1;
   while (!IMPORT_SETTLED.has(current.status)) {
     await sleep2(IMPORT_POLL_MS);
     const next = await client.request(`/api/v2/tables/imports/${encodeURIComponent(current.id)}`, { query: { workspaceId } });
     current = next.data;
-    if (process.stderr.isTTY && current.rowsProcessed !== reported) {
-      reported = current.rowsProcessed;
-      process.stderr.write(`\r${source_default.dim(`${current.status}… ${reported} rows`)}\x1B[K`);
+    if (process.stderr.isTTY && current.rowsProcessed !== reported2) {
+      reported2 = current.rowsProcessed;
+      process.stderr.write(`\r${source_default.dim(`${current.status}… ${reported2} rows`)}\x1B[K`);
     }
   }
-  if (process.stderr.isTTY && reported >= 0)
+  if (process.stderr.isTTY && reported2 >= 0)
     process.stderr.write("\r\x1B[K");
   return current;
 }
@@ -11718,6 +12100,427 @@ function attachTableImport(tables) {
   });
 }
 
+// src/runtime/renamed.ts
+var warned = new Set;
+function warn(kind, from, to) {
+  const key = `${kind}:${from}`;
+  if (warned.has(key))
+    return;
+  warned.add(key);
+  process.stderr.write(`warning: ${kind} "${from}" has been renamed to "${to}". The old name still works.
+`);
+}
+function warnRenamedCommand(from, to) {
+  warn("command", `sim ${from}`, `sim ${to}`);
+}
+function warnRenamedFlag(from, to) {
+  warn("flag", `--${from}`, `--${to}`);
+}
+
+// src/runtime/execute.ts
+function cursorSlot(operationSpec) {
+  if (operationSpec.query && "cursor" in operationSpec.query)
+    return "query";
+  if (operationSpec.body && "cursor" in operationSpec.body)
+    return "body";
+  return null;
+}
+function foldRenamedFlags(operation, commandSpec, flags) {
+  for (const [field, flag] of Object.entries(commandSpec.flags ?? {})) {
+    if (!flag.renamedFrom?.length)
+      continue;
+    const current = flagNameFor(operation, field);
+    for (const previous of flag.renamedFrom) {
+      const supplied = flags[camel(previous)];
+      if (supplied === undefined)
+        continue;
+      if (flags[camel(current)] !== undefined) {
+        throw new SimApiError(`--${previous} is the former name of --${current}; pass one, not both`, 0);
+      }
+      warnRenamedFlag(previous, current);
+      flags[camel(current)] = supplied;
+    }
+  }
+}
+async function executeOperation(operation, commandSpec, operationSpec, invocation) {
+  const host = invocation[invocation.length - 1];
+  const inheritedFlags = host.optsWithGlobals();
+  const flags = {
+    ...inheritedFlags.workspace === undefined ? {} : { workspace: inheritedFlags.workspace },
+    ...inheritedFlags.allWorkspaces === undefined ? {} : { allWorkspaces: inheritedFlags.allWorkspaces },
+    ...invocation[invocation.length - 2]
+  };
+  const pathPositionalCount = operationSpec.pathParams.filter((param) => !commandSpec.pathFlags?.[param] && !isProfileWorkspacePath(commandSpec, param)).length;
+  const positional = invocation.slice(0, pathPositionalCount);
+  const requestFlags = { ...flags };
+  for (const [index, field] of (commandSpec.positionals ?? []).entries()) {
+    requestFlags[camel(flagNameFor(operation, field))] = invocation[pathPositionalCount + index];
+  }
+  foldRenamedFlags(operation, commandSpec, requestFlags);
+  if (commandSpec.confirm && !requestFlags.yes) {
+    throw new SimApiError(`${commandSpec.confirm} Re-run with --yes to confirm.`, 0);
+  }
+  if (commandSpec.allWorkspaces && requestFlags.allWorkspaces && requestFlags.workspace) {
+    throw new SimApiError("--all-workspaces cannot be combined with --workspace", 0);
+  }
+  const { client, profile } = clientFrom(host);
+  const hasWorkspaceField = Boolean(operationSpec.query && PROFILE_INJECTED_FIELD in operationSpec.query || operationSpec.body && PROFILE_INJECTED_FIELD in operationSpec.body);
+  const omitsWorkspace = commandSpec.allWorkspaces && requestFlags.allWorkspaces === true;
+  const request = buildRequest(operation, positional, requestFlags, hasWorkspaceField && !omitsWorkspace ? client.requireWorkspace() : profile.workspaceId);
+  const paging = cursorSlot(operationSpec);
+  if (paging) {
+    const rawLimit = Number.parseInt(String(requestFlags.limit ?? DEFAULT_LIMIT), 10);
+    if (Number.isNaN(rawLimit) || rawLimit < 0) {
+      throw new SimApiError("--limit must be a non-negative number", 0);
+    }
+    const limit = rawLimit === 0 ? Number.POSITIVE_INFINITY : rawLimit;
+    const pageSize = Math.min(Number.isFinite(limit) ? limit : DEFAULT_LIMIT, DEFAULT_LIMIT);
+    const pageLimit = "limit" in (operationSpec[paging] ?? {}) ? { limit: pageSize } : {};
+    const rows = [];
+    const progress = pageProgress();
+    let cursor = null;
+    try {
+      do {
+        const page = await client.request(request.path, {
+          method: operationSpec.method,
+          query: paging === "query" ? { ...request.query, ...pageLimit, cursor } : request.query,
+          body: paging === "body" ? { ...request.body ?? {}, ...pageLimit, ...cursor ? { cursor } : {} } : request.body
+        });
+        rows.push(...page.data);
+        cursor = page.nextCursor;
+        if (cursor && rows.length < limit)
+          progress.advance(rows.length);
+      } while (cursor && rows.length < limit);
+    } finally {
+      progress.finish();
+    }
+    renderPage(profile.output, Number.isFinite(limit) ? rows.slice(0, limit) : rows, commandSpec);
+    return;
+  }
+  const result = await client.request(request.path, {
+    method: operationSpec.method,
+    query: request.query,
+    body: request.body
+  });
+  renderResult(operation, profile.output, result?.data ?? result, commandSpec, {
+    expandedTrace: requestFlags.trace === true
+  });
+}
+
+// src/commands/protocol/workflow-run-follow.ts
+var AGENT_STREAM_PROTOCOL_HEADER = "x-sim-stream-protocol";
+var AGENT_STREAM_PROTOCOL_V1 = "agent-events-v1";
+var DONE_SENTINEL = "[DONE]";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringField(frame, key) {
+  const value = frame[key];
+  return typeof value === "string" ? value : null;
+}
+async function* sseData(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder;
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
+      const lines = buffer.split(`
+`);
+      buffer = done ? "" : lines.pop() ?? "";
+      for (const rawLine of lines) {
+        const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+        if (!line.startsWith("data:"))
+          continue;
+        const payload = line.slice(5).startsWith(" ") ? line.slice(6) : line.slice(5);
+        if (payload.length > 0)
+          yield payload;
+      }
+      if (done)
+        return;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+class Commentary {
+  sink;
+  atLineStart = true;
+  constructor(sink) {
+    this.sink = sink;
+  }
+  inline(text2) {
+    if (text2.length === 0)
+      return;
+    this.sink.write(text2);
+    this.atLineStart = text2.endsWith(`
+`);
+  }
+  line(text2) {
+    this.sink.write(`${this.atLineStart ? "" : `
+`}${text2}
+`);
+    this.atLineStart = true;
+  }
+  endLine() {
+    if (this.atLineStart)
+      return;
+    this.sink.write(`
+`);
+    this.atLineStart = true;
+  }
+}
+function toolNotice(frame) {
+  const name = safeOneLine(stringField(frame, "name") ?? "tool");
+  if (frame.phase === "start")
+    return source_default.dim(`→ ${name}`);
+  const status = stringField(frame, "status");
+  if (status && status !== "success")
+    return source_default.yellow(`✗ ${name} (${safeOneLine(status)})`);
+  return source_default.dim(`✓ ${name}`);
+}
+async function renderRunStream(body, options) {
+  const commentary = new Commentary(options.stderr);
+  let final = null;
+  for await (const payload of sseData(body)) {
+    let frame;
+    try {
+      frame = JSON.parse(payload);
+    } catch {
+      continue;
+    }
+    if (frame === DONE_SENTINEL)
+      break;
+    if (!isRecord(frame))
+      continue;
+    if (frame.event === undefined && typeof frame.chunk === "string") {
+      commentary.inline(sanitize(frame.chunk));
+      continue;
+    }
+    switch (frame.event) {
+      case "chunk_reset":
+        commentary.line(source_default.dim("… retracted; that turn resolved to tool calls"));
+        break;
+      case "thinking":
+        if (options.includeThinking && typeof frame.data === "string") {
+          commentary.inline(source_default.dim(sanitize(frame.data)));
+        }
+        break;
+      case "tool":
+        if (options.includeToolCalls)
+          commentary.line(toolNotice(frame));
+        break;
+      case "stream_error":
+        commentary.line(source_default.yellow(`warning: ${safeOneLine(stringField(frame, "error") ?? "stream read failed")}`));
+        break;
+      case "error":
+        commentary.endLine();
+        throw new SimApiError(safeOneLine(stringField(frame, "error") ?? "The workflow run failed."), 0);
+      case "final":
+        if (isRecord(frame.data))
+          final = frame.data;
+        break;
+      default:
+        break;
+    }
+  }
+  commentary.endLine();
+  if (!final) {
+    throw new SimApiError("The run stream ended before the workflow reported a result. The run may still be in progress — check: sim workflows runs list", 0);
+  }
+  return final;
+}
+async function followRun(workflowId, command) {
+  const flags = command.optsWithGlobals();
+  if (flags.async === true) {
+    throw new SimApiError("--follow streams a run as it happens and --async returns before it starts; pass one, not both", 0);
+  }
+  const includeThinking = flags.includeThinking === true;
+  const includeToolCalls = flags.includeToolCalls === true;
+  const negotiates = includeThinking || includeToolCalls;
+  const { client, profile } = clientFrom(command);
+  const operation = V2_OPERATIONS.executeWorkflow;
+  const request = buildRequest("executeWorkflow", [workflowId], flags, profile.workspaceId);
+  const response = await client.requestRaw(request.path, {
+    method: "POST",
+    query: request.query,
+    body: {
+      ...request.body ?? {},
+      stream: true,
+      ...includeThinking ? { includeThinking: true } : {},
+      ...includeToolCalls ? { includeToolCalls: true } : {}
+    },
+    headers: {
+      accept: "text/event-stream",
+      ...negotiates ? { [AGENT_STREAM_PROTOCOL_HEADER]: AGENT_STREAM_PROTOCOL_V1 } : {}
+    }
+  });
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.toLowerCase().includes("text/event-stream")) {
+    await response.body?.cancel();
+    throw new SimApiError(`${operation.path} answered ${contentType || "an unknown content type"} instead of an event stream. This deployment may predate streaming runs — re-run without --follow.`, response.status);
+  }
+  if (!response.body) {
+    throw new SimApiError("The run stream had no body.", response.status);
+  }
+  const final = await renderRunStream(response.body, {
+    includeThinking,
+    includeToolCalls,
+    stderr: process.stderr
+  });
+  renderResult("executeWorkflow", profile.output, final, CLI_CONTRACT.executeWorkflow ?? {});
+  if (final.success === false) {
+    throw new SimApiError(safeOneLine(typeof final.error === "string" ? final.error : "The workflow run failed."), 0);
+  }
+}
+function followOrDelegate(previous) {
+  return async (workflowId, _options, command) => {
+    const flags = command.optsWithGlobals();
+    if (flags.follow !== true) {
+      if (flags.includeThinking === true || flags.includeToolCalls === true) {
+        throw new SimApiError("--include-thinking and --include-tool-calls describe a stream; add --follow", 0);
+      }
+      if (previous) {
+        await previous(command.processedArgs);
+        return;
+      }
+      await executeOperation("executeWorkflow", CLI_CONTRACT.executeWorkflow ?? {}, V2_OPERATIONS.executeWorkflow, [workflowId, command.opts(), command]);
+      return;
+    }
+    await followRun(workflowId, command);
+  };
+}
+function attachWorkflowRunFollow(workflows) {
+  const run = workflows.commands.find((command) => command.name() === "run");
+  if (!run) {
+    throw new Error("workflows run must be registered before --follow can be attached to it");
+  }
+  const held = run._actionHandler;
+  const previous = typeof held === "function" ? held : null;
+  run.option("--follow", "Stream the run as it happens; progress on stderr, result on stdout. The stream reports only success and output, so the result omits the run id and timings a non-streaming run returns").option("--include-thinking", "Show model reasoning while following (requires --follow)").option("--include-tool-calls", "Show tool calls while following (requires --follow)").action(followOrDelegate(previous));
+}
+
+// src/commands/protocol/workflow-run-wait.ts
+var TERMINAL_STATUSES = new Set(["completed", "failed", "cancelled"]);
+var WAIT_EXIT_CODES = {
+  completed: 0,
+  failed: 1,
+  cancelled: 2,
+  paused: 3,
+  timeout: 4
+};
+var FIRST_POLL_DELAY_MS = 2000;
+var MAX_POLL_DELAY_MS = 15000;
+var POLL_BACKOFF_FACTOR = 2;
+var DEFAULT_WAIT_TIMEOUT_SECONDS = 3600;
+var WAIT_TIMEOUT_FLAG = "--wait-timeout <seconds>";
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function optionalString(value) {
+  return typeof value === "string" && value !== "" ? value : null;
+}
+function readRun(raw) {
+  const run = isRecord2(raw) && isRecord2(raw.data) ? raw.data : raw;
+  if (!isRecord2(run) || typeof run.status !== "string") {
+    throw new SimApiError("Run status response carried no status.", 0);
+  }
+  const paused = isRecord2(run.paused) ? run.paused : null;
+  return {
+    status: run.status,
+    pauseKind: paused ? optionalString(paused.pauseKind) : null,
+    resumeAt: paused ? optionalString(paused.resumeAt) : null,
+    contextId: paused ? optionalString(paused.contextId) : null
+  };
+}
+function classify(snapshot) {
+  if (snapshot.status === "paused")
+    return snapshot.pauseKind === "time" ? null : "paused";
+  if (!TERMINAL_STATUSES.has(snapshot.status))
+    return null;
+  return snapshot.status === "completed" ? "completed" : snapshot.status === "cancelled" ? "cancelled" : "failed";
+}
+function waitProgress() {
+  let reported2 = false;
+  return {
+    advance: (status, elapsedMs) => {
+      if (!process.stderr.isTTY)
+        return;
+      reported2 = true;
+      process.stderr.write(`\r${source_default.dim(`${status} — waiting ${Math.round(elapsedMs / 1000)}s…`)}\x1B[K`);
+    },
+    finish: () => {
+      if (!reported2)
+        return;
+      reported2 = false;
+      process.stderr.write("\r\x1B[K");
+    }
+  };
+}
+function parseWaitTimeout(raw) {
+  const seconds = Number(raw);
+  if (!Number.isFinite(seconds) || seconds < 0) {
+    throw new SimApiError(`Invalid ${WAIT_TIMEOUT_FLAG} "${raw}". Use a non-negative number of seconds, or 0 to wait indefinitely.`, 0);
+  }
+  return seconds;
+}
+function explain(outcome, runId, workflowId, snapshot) {
+  if (outcome === "completed")
+    return null;
+  if (outcome === "failed")
+    return `Run ${runId} failed.`;
+  if (outcome === "cancelled")
+    return `Run ${runId} was cancelled.`;
+  const context = snapshot.contextId ? ` --context ${snapshot.contextId}` : "";
+  return `Run ${runId} is paused waiting for input. Resume it: sim workflows runs resume ${runId} --workflow ${workflowId}${context}`;
+}
+function runSpec() {
+  return CLI_CONTRACT.getWorkflowRun ?? {};
+}
+function attachWorkflowRunWait(runs) {
+  runs.command("wait").argument("<runId>", V2_OPERATIONS.getWorkflowRun.pathParamDocs?.runId).description("Wait for a run to reach a terminal state, then show it").addOption(new Option("--workflow <workflowId>", "Workflow ID (required)").makeOptionMandatory()).addOption(new Option(WAIT_TIMEOUT_FLAG, `Give up after this many seconds, or 0 to wait indefinitely (default: ${DEFAULT_WAIT_TIMEOUT_SECONDS}). Bounds the whole wait; SIM_TIMEOUT_SECONDS bounds one request`)).action(async (runId, options, command) => {
+    const timeoutSeconds = options.waitTimeout === undefined ? DEFAULT_WAIT_TIMEOUT_SECONDS : parseWaitTimeout(options.waitTimeout);
+    const { client, profile } = clientFrom(command);
+    const operation = V2_OPERATIONS.getWorkflowRun;
+    const path = resolvePath(operation.path, { id: options.workflow, runId });
+    const startedAt = Date.now();
+    const deadline = timeoutSeconds === 0 ? Number.POSITIVE_INFINITY : startedAt + timeoutSeconds * 1000;
+    const progress = waitProgress();
+    let delayMs = FIRST_POLL_DELAY_MS;
+    try {
+      while (true) {
+        const raw = await client.request(path, { method: operation.method });
+        const snapshot = readRun(raw);
+        const outcome = classify(snapshot);
+        if (outcome) {
+          progress.finish();
+          renderResult("getWorkflowRun", profile.output, raw, runSpec());
+          const message = explain(outcome, runId, options.workflow, snapshot);
+          if (message)
+            console.error(source_default.red(message));
+          process.exitCode = WAIT_EXIT_CODES[outcome];
+          return;
+        }
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+          progress.finish();
+          renderResult("getWorkflowRun", profile.output, raw, runSpec());
+          console.error(source_default.red(`Timed out after ${timeoutSeconds}s waiting for run ${runId} (status: ${snapshot.status}${snapshot.resumeAt ? `, resuming at ${snapshot.resumeAt}` : ""}). Raise ${WAIT_TIMEOUT_FLAG}, or set it to 0 to wait indefinitely.`));
+          process.exitCode = WAIT_EXIT_CODES.timeout;
+          return;
+        }
+        progress.advance(snapshot.status, Date.now() - startedAt);
+        await sleep(Math.min(delayMs, remainingMs));
+        delayMs = Math.min(delayMs * POLL_BACKOFF_FACTOR, MAX_POLL_DELAY_MS);
+      }
+    } finally {
+      progress.finish();
+    }
+  });
+}
+
 // src/commands/protocol/index.ts
 function group(program2, name) {
   const existing = program2.commands.find((command) => command.name() === name);
@@ -11753,12 +12556,16 @@ function attachProtocolCommands(program2) {
     folders: "listTableFolders",
     createFolder: "createTableFolder"
   });
-  attachResourceDirectoryCommands(group(program2, "workflows"), {
+  const workflows = group(program2, "workflows");
+  attachResourceDirectoryCommands(workflows, {
     kind: "workflow",
     resources: "listWorkflows",
     folders: "listWorkflowFolders",
     createFolder: "createWorkflowFolder"
   });
+  attachWorkflowRunFollow(workflows);
+  attachWorkflowRunWait(group(workflows, "runs"));
+  attachLogsFollow(group(program2, "logs"));
 }
 
 // src/terminal/secret-input.ts
@@ -11882,113 +12689,6 @@ function attachSecretCommands(program2) {
   secrets.command("set").argument("<name>", "Secret name, as referenced in workflows").description("Create or replace a named secret").addOption(new Option("--scope <scope>", "Secret ownership scope").choices([...SECRET_SCOPES]).makeOptionMandatory()).option("--value <value>", "Secret value; visible to shell history when supplied directly").option("--description <description>", "What the secret is for, shown to teammates; workspace scope only. Omit to leave an existing description unchanged").action((name, options, command) => setSecret(name, options, command));
 }
 
-// src/runtime/renamed.ts
-var warned = new Set;
-function warn(kind, from, to) {
-  const key = `${kind}:${from}`;
-  if (warned.has(key))
-    return;
-  warned.add(key);
-  process.stderr.write(`warning: ${kind} "${from}" has been renamed to "${to}". The old name still works.
-`);
-}
-function warnRenamedCommand(from, to) {
-  warn("command", `sim ${from}`, `sim ${to}`);
-}
-function warnRenamedFlag(from, to) {
-  warn("flag", `--${from}`, `--${to}`);
-}
-
-// src/runtime/execute.ts
-function cursorSlot(operationSpec) {
-  if (operationSpec.query && "cursor" in operationSpec.query)
-    return "query";
-  if (operationSpec.body && "cursor" in operationSpec.body)
-    return "body";
-  return null;
-}
-function foldRenamedFlags(operation, commandSpec, flags) {
-  for (const [field, flag] of Object.entries(commandSpec.flags ?? {})) {
-    if (!flag.renamedFrom?.length)
-      continue;
-    const current = flagNameFor(operation, field);
-    for (const previous of flag.renamedFrom) {
-      const supplied = flags[camel(previous)];
-      if (supplied === undefined)
-        continue;
-      if (flags[camel(current)] !== undefined) {
-        throw new SimApiError(`--${previous} is the former name of --${current}; pass one, not both`, 0);
-      }
-      warnRenamedFlag(previous, current);
-      flags[camel(current)] = supplied;
-    }
-  }
-}
-async function executeOperation(operation, commandSpec, operationSpec, invocation) {
-  const host = invocation[invocation.length - 1];
-  const inheritedFlags = host.optsWithGlobals();
-  const flags = {
-    ...inheritedFlags.workspace === undefined ? {} : { workspace: inheritedFlags.workspace },
-    ...inheritedFlags.allWorkspaces === undefined ? {} : { allWorkspaces: inheritedFlags.allWorkspaces },
-    ...invocation[invocation.length - 2]
-  };
-  const pathPositionalCount = operationSpec.pathParams.filter((param) => !commandSpec.pathFlags?.[param] && !isProfileWorkspacePath(commandSpec, param)).length;
-  const positional = invocation.slice(0, pathPositionalCount);
-  const requestFlags = { ...flags };
-  for (const [index, field] of (commandSpec.positionals ?? []).entries()) {
-    requestFlags[camel(flagNameFor(operation, field))] = invocation[pathPositionalCount + index];
-  }
-  foldRenamedFlags(operation, commandSpec, requestFlags);
-  if (commandSpec.confirm && !requestFlags.yes) {
-    throw new SimApiError(`${commandSpec.confirm} Re-run with --yes to confirm.`, 0);
-  }
-  if (commandSpec.allWorkspaces && requestFlags.allWorkspaces && requestFlags.workspace) {
-    throw new SimApiError("--all-workspaces cannot be combined with --workspace", 0);
-  }
-  const { client, profile } = clientFrom(host);
-  const hasWorkspaceField = Boolean(operationSpec.query && PROFILE_INJECTED_FIELD in operationSpec.query || operationSpec.body && PROFILE_INJECTED_FIELD in operationSpec.body);
-  const omitsWorkspace = commandSpec.allWorkspaces && requestFlags.allWorkspaces === true;
-  const request = buildRequest(operation, positional, requestFlags, hasWorkspaceField && !omitsWorkspace ? client.requireWorkspace() : profile.workspaceId);
-  const paging = cursorSlot(operationSpec);
-  if (paging) {
-    const rawLimit = Number.parseInt(String(requestFlags.limit ?? DEFAULT_LIMIT), 10);
-    if (Number.isNaN(rawLimit) || rawLimit < 0) {
-      throw new SimApiError("--limit must be a non-negative number", 0);
-    }
-    const limit = rawLimit === 0 ? Number.POSITIVE_INFINITY : rawLimit;
-    const pageSize = Math.min(Number.isFinite(limit) ? limit : DEFAULT_LIMIT, DEFAULT_LIMIT);
-    const pageLimit = "limit" in (operationSpec[paging] ?? {}) ? { limit: pageSize } : {};
-    const rows = [];
-    const progress = pageProgress();
-    let cursor = null;
-    try {
-      do {
-        const page = await client.request(request.path, {
-          method: operationSpec.method,
-          query: paging === "query" ? { ...request.query, ...pageLimit, cursor } : request.query,
-          body: paging === "body" ? { ...request.body ?? {}, ...pageLimit, ...cursor ? { cursor } : {} } : request.body
-        });
-        rows.push(...page.data);
-        cursor = page.nextCursor;
-        if (cursor && rows.length < limit)
-          progress.advance(rows.length);
-      } while (cursor && rows.length < limit);
-    } finally {
-      progress.finish();
-    }
-    renderPage(profile.output, Number.isFinite(limit) ? rows.slice(0, limit) : rows, commandSpec);
-    return;
-  }
-  const result = await client.request(request.path, {
-    method: operationSpec.method,
-    query: request.query,
-    body: request.body
-  });
-  renderResult(operation, profile.output, result?.data ?? result, commandSpec, {
-    expandedTrace: requestFlags.trace === true
-  });
-}
-
 // src/runtime/build.ts
 var GROUP_ALIASES = {
   "audit-logs": "audit-log",
@@ -12248,6 +12948,10 @@ async function main() {
       console.error(source_default.red(`Error: ${sanitize(error.message)}`));
       process.exit(1);
     }
+    if (isRequestTimeout(error)) {
+      console.error(source_default.red(`Error: the request timed out. ${RAISE_TIMEOUT_HINT}`));
+      process.exit(1);
+    }
     if (error instanceof SimApiError) {
       console.error(source_default.red(`Error: ${sanitize(error.message)}`));
       if (error.code)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sim",
-  "version": "2.0.0-preview.17.1",
+  "version": "2.0.0-preview.21.1",
   "description": "Sim CLI - talk to the Sim API from your terminal",
   "type": "module",
   "bin": {