@lotics/cli 0.93.0 → 0.94.0

package/dist/src/cli.js

@@ -29586,6 +29586,7 @@ var require_lib3 = __commonJS({
 import dns from "node:dns";
 import net2 from "node:net";
 import fs9 from "node:fs";
+import os2 from "node:os";
 import path7 from "node:path";
 import readline from "node:readline";
 
@@ -30198,11 +30199,18 @@ var LoticsClient = class {
    * `async function __workflow(): …` wrapper the server compiles inside, so the
    * local typecheck mirrors the set-time verdict. Mirrors
    * POST /v1/apps/{app_id}/workflows/{alias}/dts.
+   *
+   * `declaration` (the manifest's `{ inputs?, outputs? }`) is posted as the body
+   * `{ declaration }` ONLY when the alias isn't `set` on the server yet — the
+   * server then synthesizes the dts from the declared schemas instead of 400ing
+   * "no workflow alias". A registered alias needs no declaration (the server's
+   * own bound contract wins), so the field is omitted in that case.
    */
-  async getAppWorkflowDts(app_id, alias) {
+  async getAppWorkflowDts(app_id, alias, declaration) {
     return this.request(
       "POST",
-      `/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/dts`
+      `/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/dts`,
+      declaration ? { declaration } : void 0
     );
   }
   /**
@@ -30224,6 +30232,25 @@ var LoticsClient = class {
     if (!res.ok) await this.throwResponseError(res);
     return res;
   }
+  /**
+   * Continue a PARKED (`awaiting_input`) agent run with the user's answer to its
+   * pending `ask_user_choice` — returns the RAW streamed continuation `Response`,
+   * exactly like `appAgentRunStream`. Mirrors
+   * POST /v1/apps/{app_id}/agent-runs/{run_id}/continue.
+   */
+  async appAgentRunContinueStream(app_id, run_id, body, signal) {
+    const res = await fetch(
+      `${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/agent-runs/${encodeURIComponent(run_id)}/continue`,
+      {
+        method: "POST",
+        headers: { ...this.buildHeaders(), "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal
+      }
+    );
+    if (!res.ok) await this.throwResponseError(res);
+    return res;
+  }
   /**
    * A session's app-agent run history, oldest-first (the run just started is the
    * last, and its exact id is on the stream response's `x-app-agent-run-id`
@@ -31801,14 +31828,14 @@ function buildWrapperPage(args) {
       // protocol expects (stream-chunk* -> stream-end). Mirrors the production
       // host in frontend/features/app_ui/app_iframe_host.tsx.
       const streamingRuns = {};
-      async function handleAgentRun(id, payload) {
+      async function handleAgentRun(id, op, payload) {
         const controller = new AbortController();
         streamingRuns[id] = controller;
         try {
           const res = await fetch("/_agent_run", {
             method: "POST",
             headers: { "content-type": "application/json" },
-            body: JSON.stringify({ app_id: APP_ID, op: "agentRun", payload: payload }),
+            body: JSON.stringify({ app_id: APP_ID, op: op, payload: payload }),
             signal: controller.signal,
           });
           if (!res.ok || !res.body) {
@@ -31816,6 +31843,9 @@ function buildWrapperPage(args) {
             try { detail = JSON.parse(detail).message || detail; } catch (_) {}
             throw new Error(detail || ("HTTP " + res.status));
           }
+          // Forward the run id (poll-recovery / cancel / continue key on it).
+          const runId = res.headers.get("x-app-agent-run-id");
+          if (runId) iframe.contentWindow.postMessage({ id: id, type: "run-id", runId: runId }, VITE_ORIGIN);
           const reader = res.body.getReader();
           const decoder = new TextDecoder();
           for (;;) {
@@ -31849,7 +31879,7 @@ function buildWrapperPage(args) {
         }
         if (typeof msg.op !== "string") return;
         // Streaming agent run \u2014 many messages back, not a single result.
-        if (msg.op === "agentRun") { handleAgentRun(msg.id, msg.payload); return; }
+        if (msg.op === "agentRun" || msg.op === "agentRunContinue") { handleAgentRun(msg.id, msg.op, msg.payload); return; }
         const startedAt = performance.now();
         try {
           const data = msg.op === "upload"
@@ -32088,18 +32118,37 @@ async function startDevServer(args) {
       });
       try {
         const body = await readJson(req);
-        const p = body.payload ?? {};
-        if (typeof p.alias !== "string" || typeof p.session_id !== "string") {
-          throw new Error("agentRun payload must include `alias` and `session_id`");
-        }
-        const upstream = await args.client.appAgentRunStream(
-          body.app_id,
-          p.alias,
-          { session_id: p.session_id, input: p.input ?? {} },
-          ac.signal
-        );
+        let upstream;
+        if (body.op === "agentRunContinue") {
+          const p = body.payload ?? {};
+          if (typeof p.run_id !== "string" || typeof p.tool_call_id !== "string" || typeof p.output !== "object" || p.output === null) {
+            throw new Error("agentRunContinue payload must include `run_id`, `tool_call_id`, and `output`");
+          }
+          upstream = await args.client.appAgentRunContinueStream(
+            body.app_id,
+            p.run_id,
+            { tool_call_id: p.tool_call_id, output: p.output },
+            ac.signal
+          );
+        } else {
+          const p = body.payload ?? {};
+          if (typeof p.alias !== "string" || typeof p.session_id !== "string") {
+            throw new Error("agentRun payload must include `alias` and `session_id`");
+          }
+          upstream = await args.client.appAgentRunStream(
+            body.app_id,
+            p.alias,
+            { session_id: p.session_id, input: p.input ?? {} },
+            ac.signal
+          );
+        }
         if (!upstream.body) throw new Error("agent run returned no stream body");
-        res.writeHead(200, { "Content-Type": "text/event-stream", "Cache-Control": "no-cache, no-transform" });
+        const runId = upstream.headers.get("x-app-agent-run-id");
+        res.writeHead(200, {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache, no-transform",
+          ...runId ? { "x-app-agent-run-id": runId } : {}
+        });
         const reader = upstream.body.getReader();
         for (; ; ) {
           const { value, done } = await reader.read();
@@ -32955,6 +33004,12 @@ var LOTICS_INCLUDE_GLOB = ".lotics/**/*";
 var STALE_LOTICS_INCLUDES = /* @__PURE__ */ new Set([".lotics", "./.lotics", ".lotics/"]);
 var FALLBACK_ENVELOPE_PREFIX = "async function __workflow(): Promise<__WorkflowReturn | void> {\n";
 var FALLBACK_ENVELOPE_SUFFIX = "\n}";
+function toWorkflowDtsDeclaration(d) {
+  return { inputs: d.inputs, outputs: d.outputs };
+}
+function isUnknownWorkflowAliasError(err2) {
+  return err2 instanceof Error && /^400:/.test(err2.message) && /has no workflow alias/i.test(err2.message);
+}
 function workflowFileHeader(alias) {
   const refPath = path5.join("..", "..", WORKFLOW_GLOBALS_DIR, `${alias}.globals.d.ts`).split(path5.sep).join("/");
   return `/// <reference path="${refPath}" />
@@ -33015,9 +33070,9 @@ function stripWorkflowHeader(content) {
   }
   return lines.slice(start + 1).join("\n").replace(/\s+$/, "");
 }
-async function writeWorkflowFiles(client, projectDir, app_id, aliases) {
+async function writeWorkflowFiles(client, projectDir, app_id, workflows) {
   const written = [];
-  for (const alias of aliases) {
+  for (const [alias, declaration] of Object.entries(workflows)) {
     const res = await client.getAppWorkflow(app_id, alias);
     const source = res.error || res.result === null || typeof res.result !== "object" ? null : res.result.source;
     if (typeof source !== "string" || source.trim() === "") {
@@ -33026,15 +33081,26 @@ async function writeWorkflowFiles(client, projectDir, app_id, aliases) {
       );
       continue;
     }
-    const envelope = await fetchWorkflowGlobals(client, projectDir, app_id, alias);
+    const envelope = await fetchWorkflowGlobals(
+      client,
+      projectDir,
+      app_id,
+      alias,
+      toWorkflowDtsDeclaration(declaration)
+    );
     writeWorkflowFile(projectDir, alias, source, envelope);
     written.push(alias);
   }
   return written;
 }
-async function fetchWorkflowGlobals(client, projectDir, app_id, alias) {
+async function fetchWorkflowGlobals(client, projectDir, app_id, alias, declaration) {
   try {
-    const { dts, envelope_prefix, envelope_suffix } = await client.getAppWorkflowDts(app_id, alias);
+    const { dts, envelope_prefix, envelope_suffix } = await fetchWorkflowDts(
+      client,
+      app_id,
+      alias,
+      declaration
+    );
     writeWorkflowGlobals(projectDir, alias, dts);
     return { prefix: envelope_prefix, suffix: envelope_suffix };
   } catch (err2) {
@@ -33044,6 +33110,16 @@ async function fetchWorkflowGlobals(client, projectDir, app_id, alias) {
     return { prefix: FALLBACK_ENVELOPE_PREFIX, suffix: FALLBACK_ENVELOPE_SUFFIX };
   }
 }
+async function fetchWorkflowDts(client, app_id, alias, declaration) {
+  try {
+    return await client.getAppWorkflowDts(app_id, alias);
+  } catch (err2) {
+    if (declaration && isUnknownWorkflowAliasError(err2)) {
+      return client.getAppWorkflowDts(app_id, alias, declaration);
+    }
+    throw err2;
+  }
+}
 function runTar(args, cwd) {
   return new Promise((resolve2, reject2) => {
     const proc = spawn2("tar", args, { cwd, stdio: ["ignore", "ignore", "pipe"] });
@@ -33090,10 +33166,37 @@ function readAppMeta(projectDir) {
     capabilities: pkg2.lotics.capabilities
   };
 }
+var APP_META_KEYS = Object.keys({
+  app_id: true,
+  workspace_id: true,
+  current_version_id: true,
+  version_number: true,
+  workflows: true,
+  queries: true,
+  agents: true,
+  capabilities: true
+});
 function writeAppMeta(projectDir, meta3) {
   const pkgPath2 = path5.join(projectDir, "package.json");
   const pkg2 = JSON.parse(fs4.readFileSync(pkgPath2, "utf-8"));
-  pkg2.lotics = meta3;
+  const existing = pkg2.lotics && typeof pkg2.lotics === "object" ? pkg2.lotics : {};
+  const preserved = {};
+  for (const [key, value] of Object.entries(existing)) {
+    if (!APP_META_KEYS.includes(key)) preserved[key] = value;
+  }
+  pkg2.lotics = { ...meta3, ...preserved };
+  fs4.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
+}
+function writeWorkflowOutputs(projectDir, alias, outputs) {
+  const pkgPath2 = path5.join(projectDir, "package.json");
+  const pkg2 = JSON.parse(fs4.readFileSync(pkgPath2, "utf-8"));
+  const declaration = pkg2.lotics?.workflows?.[alias];
+  if (!declaration) {
+    throw new Error(
+      `package.json#lotics.workflows.${alias} disappeared before the derived-outputs write-back.`
+    );
+  }
+  declaration.outputs = outputs;
   fs4.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
 }
 function ensureAppTsconfig(projectDir) {
@@ -33228,19 +33331,29 @@ async function appCodegen(args) {
       `\u26A0 Could not regenerate .lotics/app_fields.ts (${err2 instanceof Error ? err2.message : String(err2)}). Kept the existing file.`
     );
   }
-  await refreshWorkflowGlobals(args.client, projectDir, meta3.app_id, Object.keys(meta3.workflows ?? {}));
+  await refreshWorkflowGlobals(args.client, projectDir, meta3.app_id, meta3.workflows ?? {});
 }
-async function refreshWorkflowGlobals(client, projectDir, app_id, aliases) {
-  for (const alias of aliases) {
-    const file2 = workflowFilePath(projectDir, alias);
-    if (!fs4.existsSync(file2)) continue;
-    const body = stripWorkflowHeader(fs4.readFileSync(file2, "utf-8"));
-    if (body.trim() === "") continue;
-    const envelope = await fetchWorkflowGlobals(client, projectDir, app_id, alias);
-    writeWorkflowFile(projectDir, alias, body, envelope);
-    console.error(`Refreshed ${path5.relative(projectDir, file2)} + its workflow types`);
+async function refreshWorkflowGlobals(client, projectDir, app_id, workflows) {
+  for (const [alias, declaration] of Object.entries(workflows)) {
+    const refreshed = await refreshWorkflowTypes(
+      client,
+      projectDir,
+      app_id,
+      alias,
+      toWorkflowDtsDeclaration(declaration)
+    );
+    if (refreshed) console.error(`Refreshed workflow types for ${alias}`);
   }
 }
+async function refreshWorkflowTypes(client, projectDir, app_id, alias, declaration) {
+  const file2 = workflowFilePath(projectDir, alias);
+  if (!fs4.existsSync(file2)) return false;
+  const body = stripWorkflowHeader(fs4.readFileSync(file2, "utf-8"));
+  if (body.trim() === "") return false;
+  const envelope = await fetchWorkflowGlobals(client, projectDir, app_id, alias, declaration);
+  writeWorkflowFile(projectDir, alias, body, envelope);
+  return true;
+}
 function stampPulledManifest(projectDir, args) {
   writeAppMeta(projectDir, {
     app_id: args.app_id,
@@ -33403,9 +33516,9 @@ async function appPull(client, args) {
     queries: app.queries ?? {},
     agents: app.agents ?? {}
   });
-  const aliases = Object.keys(app.workflows ?? {});
-  if (aliases.length > 0) {
-    const written = await writeWorkflowFiles(client, targetPath, app.id, aliases);
+  const workflows = app.workflows ?? {};
+  if (Object.keys(workflows).length > 0) {
+    const written = await writeWorkflowFiles(client, targetPath, app.id, workflows);
     if (written.length > 0) {
       console.error(
         `Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/ (${written.join(", ")})`
@@ -33807,8 +33920,19 @@ async function appWorkflowSet(client, args) {
   const result = res.result ?? {};
   const workflowId = typeof result.workflow_id === "string" ? result.workflow_id : "(unknown)";
   console.error(`Set workflow "${args.alias}" \u2192 ${workflowId}`);
-  if (result.outputs && typeof result.outputs === "object") {
-    console.error(`  result.data schema: ${JSON.stringify(result.outputs)}`);
+  const derivedOutputs = result.outputs !== null && typeof result.outputs === "object" && !Array.isArray(result.outputs) ? result.outputs : null;
+  if (!declaration.outputs && derivedOutputs && Object.keys(derivedOutputs).length > 0) {
+    writeWorkflowOutputs(projectDir, args.alias, derivedOutputs);
+    console.error(
+      `  Wrote the derived result.data schema into package.json#lotics.workflows.${args.alias}.outputs.`
+    );
+    const refreshed = await refreshWorkflowTypes(client, projectDir, meta3.app_id, args.alias, {
+      inputs: declaration.inputs,
+      outputs: derivedOutputs
+    });
+    if (refreshed) console.error(`  Refreshed workflow types for ${args.alias}.`);
+  } else if (derivedOutputs) {
+    console.error(`  result.data schema: ${JSON.stringify(derivedOutputs)}`);
   }
 }
 async function appQuerySet(client, args) {
@@ -33834,12 +33958,12 @@ async function appWorkflowPull(client) {
   const projectDir = process.cwd();
   const meta3 = readAppMeta(projectDir);
   const app = await client.getApp(meta3.app_id);
-  const aliases = Object.keys(app.workflows ?? {});
-  if (aliases.length === 0) {
+  const workflows = app.workflows ?? {};
+  if (Object.keys(workflows).length === 0) {
     console.error(`App ${meta3.app_id} has no bound workflows.`);
     return;
   }
-  const written = await writeWorkflowFiles(client, projectDir, meta3.app_id, aliases);
+  const written = await writeWorkflowFiles(client, projectDir, meta3.app_id, workflows);
   console.error(
     `Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/` + (written.length > 0 ? ` (${written.join(", ")})` : "")
   );
@@ -47318,13 +47442,50 @@ function unmergeCellsCommand(workbook, sheetIndex, mergeRef) {
     }
   };
 }
+function isInertCell(cell) {
+  return (cell.value === null || cell.value === "") && cell.formula === void 0 && cell.styleIndex === 0 && (cell.originalXfIndex === void 0 || cell.originalXfIndex === 0) && (cell.numFmtCode === "General" || cell.numFmtCode === "") && cell.richText === void 0 && cell.error === void 0 && cell.content.type === "plain" && cell.content.text === "";
+}
+function clampInertCells(sheet) {
+  let minRow = Infinity;
+  let maxRow = 0;
+  let minCol = Infinity;
+  let maxCol = 0;
+  let hasMeaningful = false;
+  for (const [ref, cell] of sheet.cells) {
+    if (isInertCell(cell)) continue;
+    const rc = refToRowColSafe(ref);
+    if (!rc) continue;
+    hasMeaningful = true;
+    if (rc.row < minRow) minRow = rc.row;
+    if (rc.row > maxRow) maxRow = rc.row;
+    if (rc.col < minCol) minCol = rc.col;
+    if (rc.col > maxCol) maxCol = rc.col;
+  }
+  const pruned = /* @__PURE__ */ new Map();
+  for (const [ref, cell] of sheet.cells) {
+    if (!isInertCell(cell)) continue;
+    if (!hasMeaningful) {
+      pruned.set(ref, cell);
+      continue;
+    }
+    const rc = refToRowColSafe(ref);
+    if (!rc) continue;
+    if (rc.row < minRow || rc.row > maxRow || rc.col < minCol || rc.col > maxCol) {
+      pruned.set(ref, cell);
+    }
+  }
+  for (const ref of pruned.keys()) sheet.cells.delete(ref);
+  return pruned;
+}
 function insertRowsCommand(workbook, sheetIndex, at, count) {
   const sheet = workbook.sheets[sheetIndex];
   let mergeSnapshot = [];
+  let inertSnapshot = /* @__PURE__ */ new Map();
   return {
     description: `Insert ${count} row${count > 1 ? "s" : ""} at ${at}`,
     execute() {
       mergeSnapshot = [...sheet.mergedCells];
+      inertSnapshot = clampInertCells(sheet);
       const toMove = [];
       for (const [ref] of sheet.cells) {
         const rc = refToRowColSafe(ref);
@@ -47368,6 +47529,7 @@ function insertRowsCommand(workbook, sheetIndex, at, count) {
         sheet.rowHeights.set(r - count, h);
       }
       for (let r = at; r < at + count; r++) sheet.rowHeights.delete(r);
+      for (const [ref, cell] of inertSnapshot) sheet.cells.set(ref, cell);
       workbook.emit({ type: "rows_deleted", sheet: sheetIndex, at, count });
     }
   };
@@ -47382,10 +47544,12 @@ function deleteRowsCommand(workbook, sheetIndex, at, count) {
     }
   }
   let mergeSnapshot = [];
+  let inertSnapshot = /* @__PURE__ */ new Map();
   return {
     description: `Delete ${count} row${count > 1 ? "s" : ""} at ${at}`,
     execute() {
       mergeSnapshot = [...sheet.mergedCells];
+      inertSnapshot = clampInertCells(sheet);
       for (const ref of snapshot.keys()) sheet.cells.delete(ref);
       const toMove = [];
       for (const [ref] of sheet.cells) {
@@ -47418,6 +47582,7 @@ function deleteRowsCommand(workbook, sheetIndex, at, count) {
       for (const [ref, snap] of snapshot) {
         sheet.set(ref, snap.value, sheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
       }
+      for (const [ref, cell] of inertSnapshot) sheet.cells.set(ref, cell);
       workbook.emit({ type: "rows_inserted", sheet: sheetIndex, at, count });
     }
   };
@@ -47425,10 +47590,12 @@ function deleteRowsCommand(workbook, sheetIndex, at, count) {
 function insertColsCommand(workbook, sheetIndex, at, count) {
   const sheet = workbook.sheets[sheetIndex];
   let mergeSnapshot = [];
+  let inertSnapshot = /* @__PURE__ */ new Map();
   return {
     description: `Insert ${count} column${count > 1 ? "s" : ""} at ${at}`,
     execute() {
       mergeSnapshot = [...sheet.mergedCells];
+      inertSnapshot = clampInertCells(sheet);
       const toMove = [];
       for (const [ref] of sheet.cells) {
         const rc = refToRowColSafe(ref);
@@ -47472,6 +47639,7 @@ function insertColsCommand(workbook, sheetIndex, at, count) {
         sheet.colWidths.set(c - count, w);
       }
       for (let c = at; c < at + count; c++) sheet.colWidths.delete(c);
+      for (const [ref, cell] of inertSnapshot) sheet.cells.set(ref, cell);
       workbook.emit({ type: "cols_deleted", sheet: sheetIndex, at, count });
     }
   };
@@ -47486,10 +47654,12 @@ function deleteColsCommand(workbook, sheetIndex, at, count) {
     }
   }
   let mergeSnapshot = [];
+  let inertSnapshot = /* @__PURE__ */ new Map();
   return {
     description: `Delete ${count} column${count > 1 ? "s" : ""} at ${at}`,
     execute() {
       mergeSnapshot = [...sheet.mergedCells];
+      inertSnapshot = clampInertCells(sheet);
       for (const ref of snapshot.keys()) sheet.cells.delete(ref);
       const toMove = [];
       for (const [ref] of sheet.cells) {
@@ -47522,6 +47692,7 @@ function deleteColsCommand(workbook, sheetIndex, at, count) {
       for (const [ref, snap] of snapshot) {
         sheet.set(ref, snap.value, sheet.styles?.get(snap.styleIndex), snap.numFmtCode, snap.formula);
       }
+      for (const [ref, cell] of inertSnapshot) sheet.cells.set(ref, cell);
       workbook.emit({ type: "cols_inserted", sheet: sheetIndex, at, count });
     }
   };
@@ -47744,26 +47915,37 @@ function lazyEngine(workbook) {
     }
   };
 }
-function readToJson(filePath) {
+function readToJson(filePath, filter2) {
   const buffer = fs6.readFileSync(filePath);
   const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
   const parsed = parseExcelBuffer(arrayBuffer);
+  let sheets = parsed.sheets;
+  if (filter2?.sheet !== void 0) {
+    const match = sheets.filter((s) => s.name === filter2.sheet);
+    if (match.length === 0) {
+      const names = parsed.sheets.map((s) => `"${s.name}"`).join(", ");
+      fail(`Sheet not found: "${filter2.sheet}". Available: ${names}`);
+    }
+    sheets = match;
+  }
   return {
     activeSheetIndex: parsed.activeSheetIndex,
-    sheets: parsed.sheets.map((s) => ({
+    sheets: sheets.map((s) => ({
       name: s.name,
       totalRowCount: s.totalRowCount,
       truncated: s.truncated,
-      cells: cellsFromParsedRows(s.rows),
+      cells: cellsFromParsedRows(s.rows, filter2?.range),
       merges: s.mergedCells.map((m) => `${rowColToRef(m.startRow, m.startCol)}:${rowColToRef(m.endRow, m.endCol)}`),
       freeze: s.freezePane ? { row: s.freezePane.frozenRows, col: s.freezePane.frozenCols } : void 0
     }))
   };
 }
-function cellsFromParsedRows(rows) {
+function cellsFromParsedRows(rows, range) {
   const out = {};
   for (const row of rows) {
+    if (range && (row.index < range.startRow || row.index > range.endRow)) continue;
     for (const cell of row.cells) {
+      if (range && (cell.column < range.startCol || cell.column > range.endCol)) continue;
       const ref = rowColToRef(row.index, cell.column);
       const value = cell.typedValue ?? cell.value;
       const entry = { value };
@@ -47835,9 +48017,34 @@ function valueToInput(value) {
   if (value === null || value === void 0) return "";
   return String(value);
 }
-function xlsxRead(filePath) {
-  if (!filePath) fail("Usage: lotics xlsx read <file>");
-  const data = readToJson(filePath);
+function readOptionFlag(rest, name) {
+  const i2 = rest.indexOf(name);
+  if (i2 < 0) return void 0;
+  const val = rest[i2 + 1];
+  if (val === void 0 || val.startsWith("--")) fail(`Missing value for ${name}`);
+  return val;
+}
+function splitOptionalSheetRef(spec) {
+  const idx = spec.indexOf("!");
+  if (idx < 0) return { sheet: void 0, ref: spec };
+  return { sheet: spec.slice(0, idx), ref: spec.slice(idx + 1) };
+}
+function xlsxRead(filePath, rest) {
+  if (!filePath) fail("Usage: lotics xlsx read <file> [--sheet <name>] [--range <sheet>!<A1:G60>]");
+  const rangeArg = readOptionFlag(rest, "--range");
+  const sheetArg = readOptionFlag(rest, "--sheet");
+  let filter2;
+  if (rangeArg !== void 0) {
+    const { sheet, ref } = splitOptionalSheetRef(rangeArg);
+    const targetSheet = sheet ?? sheetArg;
+    if (targetSheet === void 0) {
+      fail("--range without a <sheet>! prefix requires --sheet <name>");
+    }
+    filter2 = { sheet: targetSheet, range: parseRange2(ref) };
+  } else if (sheetArg !== void 0) {
+    filter2 = { sheet: sheetArg };
+  }
+  const data = readToJson(filePath, filter2);
   console.log(JSON.stringify(data, null, 2));
 }
 function xlsxWrite(filePath, json2) {
@@ -48074,7 +48281,10 @@ function printXlsxHelp() {
   console.error(`Lotics xlsx commands \u2014 manipulate .xlsx files in place.
 Uses Lotics' own xlsx engine; round-trips faithfully with the Lotics editor and templates.
 
-  lotics xlsx read <file>                          Dump file as JSON (sheets, cells, merges, freeze)
+  lotics xlsx read <file> [--sheet <name>] [--range <sheet>!<A1:G60>]
+                                                   Dump file as JSON (sheets, cells, merges, freeze).
+                                                   --sheet limits to one sheet; --range to a cell window
+                                                   (its <sheet>! prefix is optional when --sheet is given)
   lotics xlsx write <file> '<json>'                Create .xlsx from {"sheets":[{"name","cells":{"A1":...}}]}
   lotics xlsx set-cell <file> <sheet>!<ref> '<v>'  Set cell value (prefix '=' for formula)
   lotics xlsx clear-range <file> <sheet>!<range>   Clear all cells in a range
@@ -48096,7 +48306,7 @@ Edit ops mutate the file atomically (temp file + rename).`);
 async function runXlsxCommand(subcommand, toolArgs, restArgs) {
   switch (subcommand) {
     case "read":
-      return xlsxRead(toolArgs);
+      return xlsxRead(toolArgs, restArgs);
     case "write":
       return xlsxWrite(toolArgs, restArgs[0]);
     case "set-cell":
@@ -68204,8 +68414,14 @@ async function cdpConnect(wsUrl) {
   });
   return { send, close: () => ws.close() };
 }
+function isStoredFileId(target) {
+  return /^fil_[A-Za-z0-9]+$/.test(target);
+}
+function defaultPreviewOutputPath(filename, cwd) {
+  return join(cwd, basename(filename, extname(filename)) + ".png");
+}
 async function runPreviewCommand(filePath, flags) {
-  if (!filePath) fail2("Usage: lotics preview <file.docx|.xlsx> [--out <file.png>]");
+  if (!filePath) fail2("Usage: lotics preview <file.docx|.xlsx | fil_id> [-o <file.png>]");
   const abs = resolve(filePath);
   if (!existsSync(abs)) fail2(`File not found: ${abs}`);
   const ext = extname(abs).toLowerCase();
@@ -68438,8 +68654,10 @@ COMMANDS
   lotics file download <file_id>       Download a file by ID (alias: lotics download)
   lotics file download record <record_id> <field_key>
                                        Download all files on a record file field
-  lotics file preview <file> [-o png]  Render a .docx/.xlsx to a PNG (frontend engines;
-                                       needs a Chrome/Chromium on the machine)
+  lotics file preview <file|fil_id> [-o png]
+                                       Render a .docx/.xlsx to a PNG \u2014 a local path OR a
+                                       stored file id (downloaded first). Frontend engines;
+                                       needs a Chrome/Chromium on the machine
 
 FLAGS
   --json             Full JSON output (default is human-readable text)
@@ -68799,6 +69017,18 @@ async function main() {
     return;
   }
   if (command === "preview") {
+    if (subcommand && isStoredFileId(subcommand)) {
+      const { client: client2 } = requireClient(flags);
+      const tmpDir = fs9.mkdtempSync(path7.join(os2.tmpdir(), "lotics-preview-"));
+      try {
+        const { path: localPath, filename } = await client2.downloadFileById(subcommand, tmpDir);
+        const output = flags.output ?? defaultPreviewOutputPath(filename, process.cwd());
+        await runPreviewCommand(localPath, { output });
+      } finally {
+        fs9.rmSync(tmpDir, { recursive: true, force: true });
+      }
+      return;
+    }
     await runPreviewCommand(subcommand, flags);
     return;
   }

package/dist/src/client.d.ts

@@ -883,8 +883,17 @@ export declare class LoticsClient {
      * `async function __workflow(): …` wrapper the server compiles inside, so the
      * local typecheck mirrors the set-time verdict. Mirrors
      * POST /v1/apps/{app_id}/workflows/{alias}/dts.
+     *
+     * `declaration` (the manifest's `{ inputs?, outputs? }`) is posted as the body
+     * `{ declaration }` ONLY when the alias isn't `set` on the server yet — the
+     * server then synthesizes the dts from the declared schemas instead of 400ing
+     * "no workflow alias". A registered alias needs no declaration (the server's
+     * own bound contract wins), so the field is omitted in that case.
      */
-    getAppWorkflowDts(app_id: string, alias: string): Promise<{
+    getAppWorkflowDts(app_id: string, alias: string, declaration?: {
+        inputs?: Record<string, unknown>;
+        outputs?: Record<string, unknown>;
+    }): Promise<{
         dts: string;
         envelope_prefix: string;
         envelope_suffix: string;
@@ -899,6 +908,16 @@ export declare class LoticsClient {
         session_id: string;
         input: Record<string, unknown>;
     }, signal?: AbortSignal): Promise<Response>;
+    /**
+     * Continue a PARKED (`awaiting_input`) agent run with the user's answer to its
+     * pending `ask_user_choice` — returns the RAW streamed continuation `Response`,
+     * exactly like `appAgentRunStream`. Mirrors
+     * POST /v1/apps/{app_id}/agent-runs/{run_id}/continue.
+     */
+    appAgentRunContinueStream(app_id: string, run_id: string, body: {
+        tool_call_id: string;
+        output: Record<string, unknown>;
+    }, signal?: AbortSignal): Promise<Response>;
     /**
      * A session's app-agent run history, oldest-first (the run just started is the
      * last, and its exact id is on the stream response's `x-app-agent-run-id`

package/dist/src/client.js

@@ -608,9 +608,15 @@ export class LoticsClient {
      * `async function __workflow(): …` wrapper the server compiles inside, so the
      * local typecheck mirrors the set-time verdict. Mirrors
      * POST /v1/apps/{app_id}/workflows/{alias}/dts.
+     *
+     * `declaration` (the manifest's `{ inputs?, outputs? }`) is posted as the body
+     * `{ declaration }` ONLY when the alias isn't `set` on the server yet — the
+     * server then synthesizes the dts from the declared schemas instead of 400ing
+     * "no workflow alias". A registered alias needs no declaration (the server's
+     * own bound contract wins), so the field is omitted in that case.
      */
-    async getAppWorkflowDts(app_id, alias) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/dts`);
+    async getAppWorkflowDts(app_id, alias, declaration) {
+        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/dts`, declaration ? { declaration } : undefined);
     }
     /**
      * Open a streaming agent run and return the RAW streamed `Response` (the
@@ -629,6 +635,23 @@ export class LoticsClient {
             await this.throwResponseError(res);
         return res;
     }
+    /**
+     * Continue a PARKED (`awaiting_input`) agent run with the user's answer to its
+     * pending `ask_user_choice` — returns the RAW streamed continuation `Response`,
+     * exactly like `appAgentRunStream`. Mirrors
+     * POST /v1/apps/{app_id}/agent-runs/{run_id}/continue.
+     */
+    async appAgentRunContinueStream(app_id, run_id, body, signal) {
+        const res = await fetch(`${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/agent-runs/${encodeURIComponent(run_id)}/continue`, {
+            method: "POST",
+            headers: { ...this.buildHeaders(), "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+            signal,
+        });
+        if (!res.ok)
+            await this.throwResponseError(res);
+        return res;
+    }
     /**
      * A session's app-agent run history, oldest-first (the run just started is the
      * last, and its exact id is on the stream response's `x-app-agent-run-id`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.93.0",
+  "version": "0.94.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {