@lotics/cli 0.92.0 → 0.93.0

package/README.md

@@ -217,6 +217,14 @@ lotics app workflow set issueInvoice        # push the edited src/workflows/issu
 # authoritative, so the next `app deploy` re-syncs it — keep the manifest current.
 lotics app query set openInvoices           # push package.json#lotics.queries.openInvoices
 
+# Run a bound app agent end-to-end (no deployed UI needed — app row + declaration
+# + member auth). Streams progress to stderr; reports the SETTLED run (structured
+# output / final text) to stdout; exits 0 only when the run completed.
+lotics app agent run app_abc recognize '{"image_file_id":"fil_..."}'
+cat input.json | lotics app agent run app_abc recognize        # inputs via stdin/@file
+lotics app agent run app_abc recognize --json                  # full run summary to stdout
+lotics app agent run app_abc recognize --session cli-123 '{}'  # continue an existing thread
+
 # Dev-link @lotics/ui to packages/ui/src for live HMR (Vite alias; deploy bundles it)
 lotics ui link card                        # monorepo: packages/ui/src found automatically
 lotics ui link card --ui-src /abs/monorepo/packages/ui/src   # external app (e.g. ~/lotics_apps)

package/dist/src/cli.js

@@ -30224,6 +30224,18 @@ var LoticsClient = class {
     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`
+   * header). Transcript excluded; structured `output`/`input` included. Mirrors
+   * GET /v1/apps/{app_id}/agent-runs.
+   */
+  async listAgentRuns(app_id, session_id) {
+    return this.request(
+      "GET",
+      `/v1/apps/${encodeURIComponent(app_id)}/agent-runs?session_id=${encodeURIComponent(session_id)}`
+    );
+  }
   /**
    * Mint a presigned URL for uploading a file into an app. Mirrors
    * POST /v1/apps/{app_id}/files/upload-url.
@@ -30555,6 +30567,16 @@ function upsertProfile(orgId, fields) {
     latest_version: config2.latest_version
   });
 }
+function clearProfileWorkspace(orgId) {
+  const config2 = loadGlobalConfig();
+  const existing = config2?.profiles?.[orgId];
+  if (!existing) return;
+  const { workspace_id: _dropped, ...rest } = existing;
+  saveGlobalConfig({
+    ...config2,
+    profiles: { ...config2.profiles, [orgId]: { ...rest } }
+  });
+}
 function removeProfile(orgId) {
   const config2 = loadGlobalConfig();
   if (!config2?.profiles?.[orgId]) return;
@@ -30653,6 +30675,7 @@ var VERSION = pkg.version;
 import fs4 from "node:fs";
 import path5 from "node:path";
 import { spawn as spawn2 } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 
 // src/starter_template.ts
@@ -33660,6 +33683,96 @@ async function appExecuteWorkflow(client, args) {
   }
   if (status === "error" || cleanupFailed) process.exit(1);
 }
+async function streamAgentTextDeltas(body, onText) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let accumulated = "";
+  try {
+    for (; ; ) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const frames = buffer.split("\n\n");
+      buffer = frames.pop() ?? "";
+      for (const frame of frames) {
+        for (const line of frame.split("\n")) {
+          if (!line.startsWith("data:")) continue;
+          const payload = line.slice(5).trim();
+          if (!payload || payload === "[DONE]") continue;
+          let chunk;
+          try {
+            chunk = JSON.parse(payload);
+          } catch {
+            continue;
+          }
+          if (chunk.type === "text-delta" && chunk.delta) {
+            accumulated += chunk.delta;
+            onText(chunk.delta);
+          }
+        }
+      }
+    }
+  } catch {
+  } finally {
+    reader.releaseLock();
+  }
+  return accumulated;
+}
+var AGENT_RUN_POLL = {
+  intervalMs: 1e3,
+  settleTimeoutMs: 21 * 60 * 1e3,
+  existenceTimeoutMs: 5e3
+};
+var sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+async function fetchSettledAgentRun(client, appId, sessionId, runId, timing) {
+  const settleDeadline = Date.now() + timing.settleTimeoutMs;
+  const existenceDeadline = Date.now() + timing.existenceTimeoutMs;
+  for (; ; ) {
+    const { runs } = await client.listAgentRuns(appId, sessionId);
+    const target = runId ? runs.find((r) => r.id === runId) : runs[runs.length - 1];
+    if (target) {
+      if (target.status !== "running" || Date.now() >= settleDeadline) return target;
+    } else if (Date.now() >= existenceDeadline) {
+      return void 0;
+    }
+    await sleep(timing.intervalMs);
+  }
+}
+async function appAgentRun(client, args, timing = AGENT_RUN_POLL) {
+  const sessionId = args.sessionId ?? `cli-${randomUUID()}`;
+  const continuing = args.sessionId !== void 0;
+  const res = await client.appAgentRunStream(args.app_id, args.alias, {
+    session_id: sessionId,
+    input: args.input
+  });
+  const runId = res.headers.get("x-app-agent-run-id") ?? void 0;
+  if (res.body) {
+    await streamAgentTextDeltas(res.body, (piece) => process.stderr.write(piece));
+  }
+  const run = await fetchSettledAgentRun(client, args.app_id, sessionId, runId, timing);
+  if (!run) {
+    console.error(`
+Could not find the settled run for session ${sessionId} on ${args.app_id}.`);
+    console.error("The run may still be in progress \u2014 re-check with `lotics run` against the app's agent-runs.");
+    process.exit(1);
+  }
+  if (args.json) {
+    console.log(JSON.stringify(run, null, 2));
+  } else if (run.output !== null && typeof run.output === "object") {
+    console.log(JSON.stringify(run.output, null, 2));
+  } else if (typeof run.output === "string") {
+    console.log(run.output);
+  }
+  console.error(
+    `
+Agent "${args.alias}" run ${run.id} \u2192 ${run.status}${run.error_message ? `: ${run.error_message}` : ""}`
+  );
+  console.error(
+    continuing ? `Session: ${sessionId}` : `Session: ${sessionId}  (fresh \u2014 pass --session ${sessionId} to continue this thread)`
+  );
+  if (run.status !== "completed") process.exit(1);
+}
 async function appWorkflowSet(client, args) {
   const projectDir = process.cwd();
   const meta3 = readAppMeta(projectDir);
@@ -33891,6 +34004,7 @@ function parseArgs(argv) {
     content: void 0,
     timezone: void 0,
     message: void 0,
+    session: void 0,
     local: false,
     all: false,
     yes: false,
@@ -33952,6 +34066,9 @@ function parseArgs(argv) {
       case "--message":
         flags.message = argv[++i2];
         break;
+      case "--session":
+        flags.session = argv[++i2];
+        break;
       case "--local":
         flags.local = true;
         break;
@@ -34022,6 +34139,36 @@ async function ingestJsonArgs(opts) {
   }
 }
 
+// src/org_commands.ts
+function printWorkspaceList(workspaces, currentId) {
+  for (const ws of workspaces) {
+    const marker = ws.id === currentId ? " (current)" : "";
+    console.error(`  ${ws.id}  ${ws.name}  ${ws.timezone}  ${ws.default_currency}${marker}`);
+  }
+}
+async function validateOrgWorkspacePin(client, orgId, profile) {
+  const pinned = profile.workspace_id;
+  if (!pinned) return;
+  let workspaces;
+  try {
+    workspaces = await client.listWorkspaces();
+  } catch (error51) {
+    const message = error51 instanceof Error ? error51.message : String(error51);
+    console.error(`Could not validate the pinned workspace (${message}) \u2014 keeping ${pinned}.`);
+    return;
+  }
+  if (workspaces.some((w) => w.id === pinned)) return;
+  clearProfileWorkspace(orgId);
+  console.error(`Pinned workspace ${pinned} is no longer in ${profile.org_name} \u2014 cleared the stale pin.`);
+  if (workspaces.length === 0) {
+    console.error("This organization has no workspaces yet.");
+    return;
+  }
+  console.error("Select one with:\n");
+  console.error("  lotics workspace select <id>\n");
+  printWorkspaceList(workspaces);
+}
+
 // src/xlsx.ts
 import fs6 from "node:fs";
 
@@ -67999,7 +68146,7 @@ import { readFileSync as readFileSync2, writeFileSync, existsSync, mkdtempSync,
 import { tmpdir as tmpdir2 } from "node:os";
 import { join, dirname, resolve, extname, basename } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { setTimeout as sleep } from "node:timers/promises";
+import { setTimeout as sleep2 } from "node:timers/promises";
 var HERE = dirname(fileURLToPath2(import.meta.url));
 function fail2(msg) {
   console.error(msg);
@@ -68125,7 +68272,7 @@ async function runPreviewCommand(filePath, flags) {
         const p = parseInt(readFileSync2(portFile, "utf8").split("\n")[0], 10);
         if (p) cdpPort = p;
       }
-      if (!cdpPort) await sleep(100);
+      if (!cdpPort) await sleep2(100);
     }
     if (!cdpPort) throw new Error("Chrome did not expose a debugging port (launch failed?).");
     let target;
@@ -68135,7 +68282,7 @@ async function runPreviewCommand(filePath, flags) {
         target = list.find((t) => t.type === "page");
       } catch {
       }
-      if (!target?.webSocketDebuggerUrl) await sleep(100);
+      if (!target?.webSocketDebuggerUrl) await sleep2(100);
     }
     if (!target?.webSocketDebuggerUrl) throw new Error("No Chrome page target available.");
     const cdp = await cdpConnect(target.webSocketDebuggerUrl);
@@ -68157,7 +68304,7 @@ async function runPreviewCommand(filePath, flags) {
         if (v.warnings?.length) warnings.push(...v.warnings);
         break;
       }
-      await sleep(75);
+      await sleep2(75);
     }
     if (!done) throw new Error("Render timed out (page never signaled completion).");
     if (err2) throw new Error(`Render engine error: ${err2}`);
@@ -68260,6 +68407,10 @@ COMMANDS
   lotics app query set <alias>         Push package.json#lotics.queries.<alias> to
                                        apps.queries via set_app_query (no deploy;
                                        re-synced by the next deploy from the manifest)
+  lotics app agent run <app_id> <alias> '<json>'  Run a bound app agent end-to-end
+                                       (inputs: inline JSON, @file, or stdin; streams
+                                        progress to stderr, reports the settled run;
+                                        --session <id> continues a thread; --json)
   lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address
   lotics app rename "<new name>"       Rename the app's display name (launcher title)
   lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
@@ -68495,12 +68646,6 @@ var SOURCE_LABELS = {
   local_pointer: "local .lotics/config.json (pin)",
   global_profile: "global active profile"
 };
-function printWorkspaceList(workspaces, currentId) {
-  for (const ws of workspaces) {
-    const marker = ws.id === currentId ? " (current)" : "";
-    console.error(`  ${ws.id}  ${ws.name}  ${ws.timezone}  ${ws.default_currency}${marker}`);
-  }
-}
 async function resolveWorkspace(client, ctx) {
   if (ctx.workspaceId) {
     client.setWorkspaceId(ctx.workspaceId);
@@ -68715,6 +68860,7 @@ async function main() {
           console.error("Note: a local pin (.lotics/config.json) overrides the global default in this directory. Use --local to change the pin here.");
         }
       }
+      await validateOrgWorkspacePin(new LoticsClient({ apiKey: profile.api_key }), orgId, profile);
       return;
     }
     if (subcommand && subcommand !== "list") {
@@ -68764,6 +68910,7 @@ async function main() {
     console.error("  lotics app workflow pull                  Rewrite src/workflows/*.ts from the server");
     console.error("  lotics app workflow check [alias]         Typecheck src/workflows bodies locally");
     console.error("  lotics app query set <alias>              Push lotics.queries.<alias> to apps.queries (no deploy)");
+    console.error("  lotics app agent run <app_id> <alias> '<json>'  Run a bound app agent (streams progress, reports the settled run)");
     console.error("  lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address");
     console.error(`  lotics app rename "<new name>"        Rename the app's display name (launcher title)`);
     console.error("  lotics app dev [path]                Run the app locally with HMR + RPC forwarding");
@@ -69022,6 +69169,42 @@ Available workspaces:`);
       }
       workflowUsage();
     }
+    if (subcommand === "agent") {
+      const action = toolArgs;
+      const agentUsage = () => {
+        console.error("Usage: lotics app agent run <app_id> <alias> ['<json>'|@inputs.json|stdin] [--session <id>] [--json]");
+        console.error("       cat inputs.json | lotics app agent run <app_id> <alias>   (read inputs from stdin)");
+        console.error("Streams the run's progress to stderr; reports the settled run (structured output / text) to stdout.");
+        console.error("--session <id> continues an existing thread; omitted mints a fresh session per run.");
+        process.exit(1);
+      };
+      if (action === "run") {
+        const appId = restArgs[0];
+        const alias = restArgs[1];
+        if (!appId || !alias) {
+          agentUsage();
+        }
+        const ingested = await ingestJsonArgs({
+          rawArg: restArgs[2],
+          stdinIsTTY: process.stdin.isTTY ?? false,
+          readFile: (p) => fs9.readFileSync(p, "utf-8"),
+          readStdin
+        });
+        if (ingested.kind === "error") {
+          console.error(ingested.message);
+          process.exit(1);
+        }
+        await appAgentRun(client, {
+          app_id: appId,
+          alias,
+          input: ingested.args,
+          sessionId: flags.session,
+          json: flags.json
+        });
+        return;
+      }
+      agentUsage();
+    }
     if (subcommand === "query") {
       const action = toolArgs;
       if (action === "set") {

package/dist/src/client.d.ts

@@ -50,6 +50,31 @@ export interface ToolExecuteResult {
     model_output?: string;
     error?: string;
 }
+/**
+ * A settled (or in-flight) app-agent run, the transcript-excluded projection
+ * `GET /v1/apps/{app_id}/agent-runs` returns. `output` is the STRUCTURED result
+ * for a typed agent (an object) or the final text for a free-text agent (a
+ * string); `status` is `running` until the run settles to `completed` / `error`
+ * / `aborted`. The authoritative record `lotics app agent run` reports from
+ * (never the stream).
+ */
+export interface AppAgentRunSummary {
+    id: string;
+    app_id: string;
+    agent_alias: string;
+    session_id: string;
+    status: string;
+    input: Record<string, unknown> | null;
+    output: string | Record<string, unknown> | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    } | null;
+    error_message: string | null;
+    triggered_by_member_id: string | null;
+    started_at: string;
+    completed_at: string | null;
+}
 export interface ToolInfo {
     name: string;
     description: string;
@@ -874,6 +899,15 @@ export declare class LoticsClient {
         session_id: string;
         input: 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`
+     * header). Transcript excluded; structured `output`/`input` included. Mirrors
+     * GET /v1/apps/{app_id}/agent-runs.
+     */
+    listAgentRuns(app_id: string, session_id: string): Promise<{
+        runs: AppAgentRunSummary[];
+    }>;
     /**
      * Mint a presigned URL for uploading a file into an app. Mirrors
      * POST /v1/apps/{app_id}/files/upload-url.

package/dist/src/client.js

@@ -629,6 +629,15 @@ export class LoticsClient {
             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`
+     * header). Transcript excluded; structured `output`/`input` included. Mirrors
+     * GET /v1/apps/{app_id}/agent-runs.
+     */
+    async listAgentRuns(app_id, session_id) {
+        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/agent-runs?session_id=${encodeURIComponent(session_id)}`);
+    }
     /**
      * Mint a presigned URL for uploading a file into an app. Mirrors
      * POST /v1/apps/{app_id}/files/upload-url.

package/package.json

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