@lotics/cli 0.48.0 → 0.50.0

package/README.md

@@ -102,7 +102,10 @@ lotics tools query_records      # show full description + input schema
 lotics run query_tables '{}'
 lotics run query_records '{"table_id":"tbl_...","field_keys":["name"]}'
 
-# Pipe args via stdin
+# Large args (a knowledge-doc `content`, a bulk update) exceed the OS arg limit —
+# read them from a file or stdin instead of an inline arg:
+lotics run create_knowledge @args.json
+cat args.json | lotics run create_knowledge
 echo '{"table_id":"tbl_..."}' | lotics run query_records
 
 # Upload files (multiple files and directories supported)

package/dist/app_commands.d.ts

@@ -26,6 +26,22 @@ export type AppQueryDeclaration = {
     ast: unknown;
     params?: Record<string, unknown>;
 };
+/**
+ * Manifest declaration for one streaming agent:
+ *   `"alias": { instructions, tool_names, model_id, inputs?, outputs? }`
+ *
+ * A read-only reflection of the live App row (`apps.agents`, owned by
+ * `set_app_agent`), refreshed by `lotics app pull` and used only to codegen
+ * `useAgentRun` typings. `inputs`/`outputs` drive the typed call site; the rest
+ * is carried for fidelity.
+ */
+export type AppAgentDeclaration = {
+    instructions?: string;
+    tool_names?: string[];
+    model_id?: string;
+    inputs?: Record<string, unknown>;
+    outputs?: Record<string, unknown>;
+};
 /**
  * Stamp the post-extraction manifest with server-authoritative meta. Called
  * by `appPull` after the source archive lands on disk.
@@ -45,6 +61,7 @@ export declare function stampPulledManifest(projectDir: string, args: {
     version_number: number;
     workflows: Record<string, AppWorkflowDeclaration>;
     queries: Record<string, AppQueryDeclaration>;
+    agents: Record<string, AppAgentDeclaration>;
 }): void;
 /**
  * `lotics app create <name> [path]`

package/dist/app_commands.js

@@ -18,6 +18,7 @@ import { tmpdir } from "node:os";
 import { buildStarterTemplate } from "./starter_template.js";
 import { startDevServer, openBrowser } from "./dev/server.js";
 import { generateAppWorkflowsDts } from "./generate_app_workflows_dts.js";
+import { generateAppAgentsDts } from "./generate_app_agents_dts.js";
 import { generateAppQueriesDts } from "./generate_app_queries_dts.js";
 /**
  * Resolve the latest published version of a package from the npm registry.
@@ -92,6 +93,7 @@ function readAppMeta(projectDir) {
         version_number: pkg.lotics.version_number ?? null,
         workflows: pkg.lotics.workflows ?? {},
         queries: pkg.lotics.queries ?? {},
+        agents: pkg.lotics.agents ?? {},
         capabilities: pkg.lotics.capabilities,
     };
 }
@@ -113,6 +115,7 @@ function writeAppDts(projectDir, manifest) {
     fs.mkdirSync(dotLotics, { recursive: true });
     fs.writeFileSync(path.join(dotLotics, "app_workflows.d.ts"), generateAppWorkflowsDts(manifest.workflows));
     fs.writeFileSync(path.join(dotLotics, "app_queries.d.ts"), generateAppQueriesDts(manifest.queries));
+    fs.writeFileSync(path.join(dotLotics, "app_agents.d.ts"), generateAppAgentsDts(manifest.agents));
 }
 /**
  * Stamp the post-extraction manifest with server-authoritative meta. Called
@@ -134,8 +137,9 @@ export function stampPulledManifest(projectDir, args) {
         version_number: args.version_number,
         workflows: args.workflows,
         queries: args.queries,
+        agents: args.agents,
     });
-    writeAppDts(projectDir, { workflows: args.workflows, queries: args.queries });
+    writeAppDts(projectDir, { workflows: args.workflows, queries: args.queries, agents: args.agents });
 }
 async function downloadToFile(url, destPath) {
     const response = await fetch(url);
@@ -281,6 +285,7 @@ export async function appPull(client, args) {
         version_number: version.version,
         workflows: app.workflows ?? {},
         queries: app.queries ?? {},
+        agents: app.agents ?? {},
     });
     console.error(`Installing npm dependencies...`);
     await runNpm(["install"], targetPath);
@@ -355,7 +360,7 @@ export async function appDeploy(client, args) {
     // Regenerate AppWorkflows typing before the build picks up source. Keeps
     // .lotics/app_workflows.d.ts in sync with the manifest's workflows map
     // every time the developer ships.
-    writeAppDts(projectDir, { workflows: meta.workflows, queries: meta.queries });
+    writeAppDts(projectDir, { workflows: meta.workflows, queries: meta.queries, agents: meta.agents });
     // Build locally so the server doesn't need a build sandbox in v1.
     console.error("Building...");
     await runNpm(["run", "build"], projectDir);
@@ -469,7 +474,7 @@ export async function appDev(client, args) {
     // Regenerate AppWorkflows typing before Vite spins up so the dev typecheck
     // sees the current shape. Doesn't watch for manifest changes mid-session —
     // re-running `lotics app dev` after editing the manifest is the loop.
-    writeAppDts(projectDir, { workflows: meta.workflows, queries: meta.queries });
+    writeAppDts(projectDir, { workflows: meta.workflows, queries: meta.queries, agents: meta.agents });
     // Sanity: confirm the app exists in the workspace the CLI is auth'd into.
     // Surfaces a clear error if the project's app_id has been deleted or the
     // CLI is pointed at the wrong workspace.

package/dist/app_commands.test.js

@@ -57,6 +57,7 @@ describe("stampPulledManifest", () => {
                 renamed: { workflow_id: "wfl_renamed_on_server" },
             },
             queries: {},
+            agents: {},
         });
         const stamped = readStampedManifest();
         expect(stamped.app_id).toBe("app_live");
@@ -82,6 +83,7 @@ describe("stampPulledManifest", () => {
             version_number: 2,
             workflows: {},
             queries: {},
+            agents: {},
         });
         const stamped = readStampedManifest();
         expect(stamped.workflows).toEqual({});
@@ -97,6 +99,7 @@ describe("stampPulledManifest", () => {
                 only_live: { workflow_id: "wfl_only_live" },
             },
             queries: {},
+            agents: {},
         });
         const dtsPath = path.join(workDir, ".lotics", "app_workflows.d.ts");
         expect(fs.existsSync(dtsPath)).toBe(true);

package/dist/cli.js

@@ -54,6 +54,8 @@ COMMANDS
   lotics tools                         List all available tools
   lotics tools <name>                  Show tool description and input schema
   lotics run <tool> '<json>'           Execute a tool
+  lotics run <tool> @args.json         Read JSON args from a file (large payloads)
+  cat args.json | lotics run <tool>    Read JSON args from stdin (large payloads)
   lotics upload <file|dir...>          Upload files (directories expand to their immediate files)
   lotics download <file_id>            Download a file by ID
   lotics download record <record_id> <field_key>
@@ -533,7 +535,9 @@ async function main() {
         process.exit(1);
     }
     if (command === "run" && !subcommand) {
-        console.error('Usage: lotics run <tool> \'<json_args>\'');
+        console.error("Usage: lotics run <tool> '<json_args>'\n" +
+            "       lotics run <tool> @args.json   (read args from a file — for large payloads)\n" +
+            "       cat args.json | lotics run <tool>   (read args from stdin)");
         console.error('Run "lotics tools" to see available tools.');
         process.exit(1);
     }
@@ -779,7 +783,23 @@ async function main() {
     if (command === "run") {
         const toolName = subcommand;
         let rawArgs = toolArgs;
-        if (!rawArgs && !process.stdin.isTTY) {
+        if (rawArgs && rawArgs.startsWith("@")) {
+            // `@<path>` — read the JSON args from a local file. JSON args always
+            // start with `{`, so a leading `@` is unambiguous. This (and piped
+            // stdin below) carries payloads too large for an inline arg, which the
+            // OS caps (ARG_MAX) — e.g. a knowledge doc's `content` or a bulk update.
+            // Reads only a file the caller explicitly named; no new trust boundary.
+            const argsPath = rawArgs.slice(1);
+            try {
+                rawArgs = fs.readFileSync(argsPath, "utf-8");
+            }
+            catch (err) {
+                console.error(`Cannot read args file "${argsPath}": ${err instanceof Error ? err.message : String(err)}`);
+                process.exit(1);
+            }
+        }
+        else if (!rawArgs && !process.stdin.isTTY) {
+            // Piped/redirected stdin — `… | lotics run <tool>` or `< file.json`.
             rawArgs = await readStdin();
         }
         let args = {};

package/dist/client.d.ts

@@ -130,6 +130,19 @@ export declare class LoticsClient {
             ast: unknown;
             params?: Record<string, unknown>;
         }> | null;
+        /**
+         * Live alias → agent declaration map from `apps.agents`. Source of truth for
+         * `lotics app pull` — supersedes the source archive so `set_app_agent`
+         * authoring survives the pull. Null/undefined on apps with no declared
+         * agents. Drives `useAgentRun` typing.
+         */
+        agents?: Record<string, {
+            instructions?: string;
+            tool_names?: string[];
+            model_id?: string;
+            inputs?: Record<string, unknown>;
+            outputs?: Record<string, unknown>;
+        }> | null;
     }>;
     createApp(body: {
         name: string;

package/dist/generate_app_agents_dts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Codegen: emit `.lotics/app_agents.d.ts` from the app's manifest.
+ *
+ * Mirrors `generate_app_workflows_dts` — agents reuse the exact same typed
+ * input/output vocabulary, so the `inputsToType` / `objectFieldsToType` mappers
+ * are shared. The augmentation adds a typed entry to `AppAgents` for every alias
+ * declared in `package.json#lotics.agents`:
+ *
+ *   - No declared `inputs` → `alias: Record<string, unknown>` (untyped payload)
+ *   - Declared `inputs`    → `alias: { …declared shape… }`
+ *   - Declared `outputs`   → an `AppAgentResults[alias]` entry → typed `output`
+ *
+ * Pure function. Same inputs → same output. Idempotent.
+ */
+import type { AppAgentDeclaration } from "./app_commands.js";
+export declare function generateAppAgentsDts(agents: Record<string, AppAgentDeclaration> | undefined): string;

package/dist/generate_app_agents_dts.js

@@ -0,0 +1,62 @@
+/**
+ * Codegen: emit `.lotics/app_agents.d.ts` from the app's manifest.
+ *
+ * Mirrors `generate_app_workflows_dts` — agents reuse the exact same typed
+ * input/output vocabulary, so the `inputsToType` / `objectFieldsToType` mappers
+ * are shared. The augmentation adds a typed entry to `AppAgents` for every alias
+ * declared in `package.json#lotics.agents`:
+ *
+ *   - No declared `inputs` → `alias: Record<string, unknown>` (untyped payload)
+ *   - Declared `inputs`    → `alias: { …declared shape… }`
+ *   - Declared `outputs`   → an `AppAgentResults[alias]` entry → typed `output`
+ *
+ * Pure function. Same inputs → same output. Idempotent.
+ */
+import { inputsToType, objectFieldsToType, isValidIdentifier } from "./generate_app_workflows_dts.js";
+const HEADER = `// Auto-generated by 'lotics app pull/dev/deploy'.
+// DO NOT EDIT — regenerated from package.json#lotics.agents.
+//
+// This file gives \`useAgentRun("alias")\` typed input + output at call sites by
+// augmenting the @lotics/app-sdk \`AppAgents\` / \`AppAgentResults\` interfaces.
+
+import "@lotics/app-sdk";
+`;
+export function generateAppAgentsDts(agents) {
+    const entries = Object.entries(agents ?? {});
+    if (entries.length === 0) {
+        return `${HEADER}
+// No agents declared in package.json#lotics.agents.
+// Add an entry to enable typed useAgentRun<"alias"> at call sites.
+declare module "@lotics/app-sdk" {
+  interface AppAgents {}
+}
+`;
+    }
+    // Sort alphabetically for deterministic output across regenerations.
+    entries.sort(([a], [b]) => a.localeCompare(b));
+    const inputLines = [];
+    const resultLines = [];
+    for (const [alias, declaration] of entries) {
+        const valueType = declaration.inputs
+            ? inputsToType(declaration.inputs)
+            : "Record<string, unknown>";
+        const aliasKey = isValidIdentifier(alias) ? alias : JSON.stringify(alias);
+        inputLines.push(`    ${aliasKey}: ${valueType};`);
+        if (declaration.outputs) {
+            resultLines.push(`    ${aliasKey}: ${objectFieldsToType(declaration.outputs)};`);
+        }
+    }
+    const resultsBlock = resultLines.length > 0
+        ? `
+  interface AppAgentResults {
+${resultLines.join("\n")}
+  }`
+        : "";
+    return `${HEADER}
+declare module "@lotics/app-sdk" {
+  interface AppAgents {
+${inputLines.join("\n")}
+  }${resultsBlock}
+}
+`;
+}

package/dist/generate_app_agents_dts.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/generate_app_agents_dts.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { generateAppAgentsDts } from "./generate_app_agents_dts.js";
+describe("generateAppAgentsDts", () => {
+    it("emits an empty AppAgents interface when no agents are declared", () => {
+        const out = generateAppAgentsDts(undefined);
+        expect(out).toContain("interface AppAgents {}");
+        expect(out).not.toContain("interface AppAgentResults");
+    });
+    it("types the input payload from declared inputs", () => {
+        const out = generateAppAgentsDts({
+            recognize: { inputs: { photo: { type: "file" }, prompt: { type: "text", required: false } } },
+        });
+        expect(out).toContain("recognize: {");
+        expect(out).toContain("photo: string;");
+        expect(out).toContain("prompt?: string;");
+    });
+    it("leaves an inputs-less agent as an untyped payload", () => {
+        const out = generateAppAgentsDts({ summarize: {} });
+        expect(out).toContain("summarize: Record<string, unknown>;");
+    });
+    it("emits AppAgentResults from declared outputs, including nested objects", () => {
+        const out = generateAppAgentsDts({
+            recognize: {
+                inputs: { photo: { type: "file" } },
+                outputs: {
+                    style: { type: "text" },
+                    dimensions: {
+                        type: "object",
+                        fields: { width_mm: { type: "number" }, height_mm: { type: "number" } },
+                    },
+                    confidence: { type: "number" },
+                },
+            },
+        });
+        expect(out).toContain("interface AppAgentResults {");
+        expect(out).toContain("style: string");
+        expect(out).toContain("width_mm: number");
+        expect(out).toContain("confidence: number");
+    });
+    it("is deterministic and sorts aliases", () => {
+        const a = generateAppAgentsDts({ zebra: {}, alpha: {} });
+        expect(a.indexOf("alpha:")).toBeLessThan(a.indexOf("zebra:"));
+        expect(generateAppAgentsDts({ zebra: {}, alpha: {} })).toBe(a);
+    });
+});

package/dist/src/cli.js

@@ -31358,8 +31358,52 @@ function isValidIdentifier(name) {
   return IDENTIFIER_REGEX.test(name);
 }
 
-// src/generate_app_queries_dts.ts
+// src/generate_app_agents_dts.ts
 var HEADER2 = `// Auto-generated by 'lotics app pull/dev/deploy'.
+// DO NOT EDIT \u2014 regenerated from package.json#lotics.agents.
+//
+// This file gives \`useAgentRun("alias")\` typed input + output at call sites by
+// augmenting the @lotics/app-sdk \`AppAgents\` / \`AppAgentResults\` interfaces.
+
+import "@lotics/app-sdk";
+`;
+function generateAppAgentsDts(agents) {
+  const entries = Object.entries(agents ?? {});
+  if (entries.length === 0) {
+    return `${HEADER2}
+// No agents declared in package.json#lotics.agents.
+// Add an entry to enable typed useAgentRun<"alias"> at call sites.
+declare module "@lotics/app-sdk" {
+  interface AppAgents {}
+}
+`;
+  }
+  entries.sort(([a], [b]) => a.localeCompare(b));
+  const inputLines = [];
+  const resultLines = [];
+  for (const [alias, declaration] of entries) {
+    const valueType = declaration.inputs ? inputsToType(declaration.inputs) : "Record<string, unknown>";
+    const aliasKey = isValidIdentifier(alias) ? alias : JSON.stringify(alias);
+    inputLines.push(`    ${aliasKey}: ${valueType};`);
+    if (declaration.outputs) {
+      resultLines.push(`    ${aliasKey}: ${objectFieldsToType(declaration.outputs)};`);
+    }
+  }
+  const resultsBlock = resultLines.length > 0 ? `
+  interface AppAgentResults {
+${resultLines.join("\n")}
+  }` : "";
+  return `${HEADER2}
+declare module "@lotics/app-sdk" {
+  interface AppAgents {
+${inputLines.join("\n")}
+  }${resultsBlock}
+}
+`;
+}
+
+// src/generate_app_queries_dts.ts
+var HEADER3 = `// Auto-generated by 'lotics app pull/dev/deploy'.
 // DO NOT EDIT \u2014 regenerated from package.json#lotics.queries.
 //
 // This file gives \`useQuery("alias", params)\` typed params at call sites by
@@ -31370,7 +31414,7 @@ import "@lotics/app-sdk";
 function generateAppQueriesDts(queries) {
   const entries = Object.entries(queries ?? {});
   if (entries.length === 0) {
-    return `${HEADER2}
+    return `${HEADER3}
 // No queries declared in package.json#lotics.queries.
 // Add an entry to enable typed useQuery("alias", params) at call sites.
 declare module "@lotics/app-sdk" {
@@ -31385,7 +31429,7 @@ declare module "@lotics/app-sdk" {
     const aliasKey = isValidIdentifier(alias) ? alias : JSON.stringify(alias);
     lines.push(`    ${aliasKey}: ${valueType};`);
   }
-  return `${HEADER2}
+  return `${HEADER3}
 declare module "@lotics/app-sdk" {
   interface AppQueries {
 ${lines.join("\n")}
@@ -31453,6 +31497,7 @@ function readAppMeta(projectDir) {
     version_number: pkg2.lotics.version_number ?? null,
     workflows: pkg2.lotics.workflows ?? {},
     queries: pkg2.lotics.queries ?? {},
+    agents: pkg2.lotics.agents ?? {},
     capabilities: pkg2.lotics.capabilities
   };
 }
@@ -31473,6 +31518,10 @@ function writeAppDts(projectDir, manifest) {
     path4.join(dotLotics, "app_queries.d.ts"),
     generateAppQueriesDts(manifest.queries)
   );
+  fs3.writeFileSync(
+    path4.join(dotLotics, "app_agents.d.ts"),
+    generateAppAgentsDts(manifest.agents)
+  );
 }
 function stampPulledManifest(projectDir, args) {
   writeAppMeta(projectDir, {
@@ -31481,9 +31530,10 @@ function stampPulledManifest(projectDir, args) {
     current_version_id: args.current_version_id,
     version_number: args.version_number,
     workflows: args.workflows,
-    queries: args.queries
+    queries: args.queries,
+    agents: args.agents
   });
-  writeAppDts(projectDir, { workflows: args.workflows, queries: args.queries });
+  writeAppDts(projectDir, { workflows: args.workflows, queries: args.queries, agents: args.agents });
 }
 async function downloadToFile(url, destPath) {
   const response = await fetch(url);
@@ -31572,7 +31622,8 @@ async function appPull(client, args) {
     current_version_id: app.current_version_id,
     version_number: version.version,
     workflows: app.workflows ?? {},
-    queries: app.queries ?? {}
+    queries: app.queries ?? {},
+    agents: app.agents ?? {}
   });
   console.error(`Installing npm dependencies...`);
   await runNpm(["install"], targetPath);
@@ -31619,7 +31670,7 @@ async function appDeploy(client, args) {
   Add to package.json#lotics.capabilities:  ${block}`
     );
   }
-  writeAppDts(projectDir, { workflows: meta.workflows, queries: meta.queries });
+  writeAppDts(projectDir, { workflows: meta.workflows, queries: meta.queries, agents: meta.agents });
   console.error("Building...");
   await runNpm(["run", "build"], projectDir);
   const distDir = path4.join(projectDir, "dist");
@@ -31710,7 +31761,7 @@ async function warnIfUnbranded(client, appId) {
 async function appDev(client, args) {
   const projectDir = path4.resolve(args.projectDir ?? process.cwd());
   const meta = readAppMeta(projectDir);
-  writeAppDts(projectDir, { workflows: meta.workflows, queries: meta.queries });
+  writeAppDts(projectDir, { workflows: meta.workflows, queries: meta.queries, agents: meta.agents });
   const app = await client.getApp(meta.app_id);
   const handle = await startDevServer({
     projectDir,
@@ -47594,6 +47645,8 @@ COMMANDS
   lotics tools                         List all available tools
   lotics tools <name>                  Show tool description and input schema
   lotics run <tool> '<json>'           Execute a tool
+  lotics run <tool> @args.json         Read JSON args from a file (large payloads)
+  cat args.json | lotics run <tool>    Read JSON args from stdin (large payloads)
   lotics upload <file|dir...>          Upload files (directories expand to their immediate files)
   lotics download <file_id>            Download a file by ID
   lotics download record <record_id> <field_key>
@@ -48038,7 +48091,9 @@ async function main() {
     process.exit(1);
   }
   if (command === "run" && !subcommand) {
-    console.error("Usage: lotics run <tool> '<json_args>'");
+    console.error(
+      "Usage: lotics run <tool> '<json_args>'\n       lotics run <tool> @args.json   (read args from a file \u2014 for large payloads)\n       cat args.json | lotics run <tool>   (read args from stdin)"
+    );
     console.error('Run "lotics tools" to see available tools.');
     process.exit(1);
   }
@@ -48270,7 +48325,17 @@ ${JSON.stringify(info.input_schema, null, 2)}`);
   if (command === "run") {
     const toolName = subcommand;
     let rawArgs = toolArgs;
-    if (!rawArgs && !process.stdin.isTTY) {
+    if (rawArgs && rawArgs.startsWith("@")) {
+      const argsPath = rawArgs.slice(1);
+      try {
+        rawArgs = fs7.readFileSync(argsPath, "utf-8");
+      } catch (err2) {
+        console.error(
+          `Cannot read args file "${argsPath}": ${err2 instanceof Error ? err2.message : String(err2)}`
+        );
+        process.exit(1);
+      }
+    } else if (!rawArgs && !process.stdin.isTTY) {
       rawArgs = await readStdin();
     }
     let args = {};

package/package.json

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