@lotics/cli 0.185.0 → 0.186.0

package/docs/cli_reference.md

@@ -27,7 +27,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | — | **The exit code reports the WORK, not just the call — for the two tools that RUN one.** `run_app_workflow` and `run_app_agent` whose envelope carries a failed `status` (`error`/`failed`/`cancelled`) exit non-zero and print `<tool> → <status>: <message>` to stderr, so `lotics run … && next-step` cannot walk past a refused run. The rule is an allowlist of FAILURE — an unrecognized status exits 0, so a status added later never turns a working script red. A parked run (`awaiting_input`) is not a failure: it is waiting for an answer and the work is still live. Only a TOP-LEVEL `status` counts; one inside the data belongs to the data. Any OTHER tool's `status` — `press_button`'s included — is data, and exits 0. |
 | `lotics run <tool> --print-created` | Report the records the call created, grouped by table, with a paste-ready `delete_records` per table and the mandatory caveat naming what cannot be auto-undone (external integrations, notifications, possible sub-workflows). Works for any tool that returns a `side_effects` block, not workflows alone. |
 | `lotics run <tool> --cleanup` | Implies `--print-created`, then runs those deletes — harvested records **only**, never files / external calls / notifications. **Not a rollback**; a rollback is structurally impossible here. A partial cleanup exits non-zero so a script cannot read it as success. |
-| `lotics upload <file\|dir...>` · `--stdin` · `--base64` · `--url <url>` | Upload files/directories via multipart POST to /v1/files. A directory expands to its immediate files; `--as <name>` renames a single upload. **Three alternative byte sources, for a caller that never had the bytes on disk** — an attachment decoded in memory, a generated document, a signed download link — each mutually exclusive with the others and with a path argument: `--stdin` takes raw bytes on stdin, `--base64` takes base64 on stdin (the shape attachments arrive in), `--url <url>` fetches the URL first. `--stdin`/`--base64` REQUIRE `--as`, because stdin carries no filename and the mime type is derived from it; `--url` falls back to `Content-Disposition` then the URL's last path segment. `--base64` decodes STRICTLY — `Buffer.from(s, "base64")` silently skips invalid characters and truncates on bad padding, so a corrupted pipe would otherwise store a short file that only fails when a human opens it. The `--url` fetch happens in the CLI, not the server: the URL comes from the operator running the command, so routing it through the backend would add an SSRF surface to buy what `curl` already does. |
+| `lotics upload <file\|dir...>` · `--stdin` · `--base64` · `--url <url>` | Upload files/directories. **The transport is chosen by size and is not a flag**: under 8 MiB the file is POSTed to `/v1/files` in one request, and several such files go in the same one; at or above it the CLI takes presigned part URLs and PUTs the bytes straight to object storage, so they never pass through the API. That threshold matches the AWS CLI's own `multipart_threshold`, and the number matters less than there being nothing to choose — one verb, any size, up to the 2 GiB a workspace may store. A large upload reads one part at a time, so memory stays flat regardless of file size, and a failure part-way abandons the parts already sent rather than leaving them billable and invisible. A directory expands to its immediate files; `--as <name>` renames a single upload. **Three alternative byte sources, for a caller that never had the bytes on disk** — an attachment decoded in memory, a generated document, a signed download link — each mutually exclusive with the others and with a path argument: `--stdin` takes raw bytes on stdin, `--base64` takes base64 on stdin (the shape attachments arrive in), `--url <url>` fetches the URL first. `--stdin`/`--base64` REQUIRE `--as`, because stdin carries no filename and the mime type is derived from it; `--url` falls back to `Content-Disposition` then the URL's last path segment. `--base64` decodes STRICTLY — `Buffer.from(s, "base64")` silently skips invalid characters and truncates on bad padding, so a corrupted pipe would otherwise store a short file that only fails when a human opens it. The `--url` fetch happens in the CLI, not the server: the URL comes from the operator running the command, so routing it through the backend would add an SSRF surface to buy what `curl` already does. |
 | `lotics file download <file_id> [-o <dir>]` | (alias `lotics download`) Download a stored file: `GET /v1/files/{id}/signed_url` → fetch the presigned URL, saving under the stored filename (from the response's `Content-Disposition`) into `-o` (a **DIRECTORY** — note this is distinct from `lotics file preview`'s `-o`, which is a FILE path), else cwd. `lotics file download record <record_id> <field_key>` pulls every file on a record's file field. |
 | `lotics knowledge list [--include-hidden]` | `GET /v1/knowledge_docs` — a table of id, name, tags, description (`--json` for the docs). **REST, not the `list_knowledge` tool**: the tool answers what the ASSISTANT may browse, and a hidden doc is out of that corpus by definition, so a tool-backed listing could never show one and the person who hid it would have no way back to it. Hidden docs are left out unless `--include-hidden` asks; those rows are marked `(hidden)`. |
 | `lotics knowledge create --name <n> [--description <d>] [--tags <a,b>] (--from <file.md> \| --content <str>)` | Read the body client-side (a file XOR an inline string — exactly one required), then call `create_knowledge` with `{ name, description, content, tags? }` (description defaults to `""`). `--tags` files the doc as it is made, which is the only moment a corpus reliably gets labelled. Prints the new id to stdout. Large files ride the POST body fine. |

package/package.json

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

package/dist/src/invocation.js

@@ -1,142 +0,0 @@
-/**
- * What this process was asked to do, and which run of a sitting it belongs to —
- * the two facts that make a server log line attributable to a CLI invocation.
- *
- * Today a CLI request is indistinguishable from any other API-key request: the
- * backend's `log()` middleware registers `user_agent` and `$session_id` onto
- * every log line of a request, and the CLI sent neither. So a 400 in PostHog
- * names an endpoint and nothing about the command that produced it, and nothing
- * links it to the twelve invocations that preceded it — which is the whole
- * question when an agent is stuck in a retry loop.
- *
- * Split by sensitivity, deliberately:
- *   - the VERSION and the COMMAND describe the request that is already being
- *     made (the endpoint mostly implies the verb anyway) and always ride;
- *   - the SESSION id is a cross-request correlator, so it rides only under
- *     `LOTICS_TELEMETRY=1`. Opt-out would be the industry default; this package
- *     publishes to npm and runs on customers' machines, so it is opt-in.
- */
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-/** Enabled by an explicit `LOTICS_TELEMETRY=1`. Anything else, including unset, is off. */
-export function telemetryEnabled(env = process.env) {
-    return env.LOTICS_TELEMETRY === "1";
-}
-/**
- * The verb path of an invocation — `app.workflow.set`, `run.query_records` —
- * from the raw argv positionals.
- *
- * Positionals stop at the first token that is a flag, a JSON blob, an `@file`,
- * or an identifier: the point of the header is to name the COMMAND, and a table
- * id or a record payload past that point is customer data that has no business
- * in a request header. `run` keeps one extra token because the tool name IS the
- * verb there — `run` alone would collapse ~90 distinct operations into one label.
- */
-export function commandPath(argv) {
-    const parts = [];
-    for (const raw of argv) {
-        if (parts.length >= 3)
-            break;
-        if (raw.startsWith("-") || raw.startsWith("@") || raw.startsWith("{"))
-            break;
-        if (raw.includes("/") || raw.includes("."))
-            break;
-        if (!/^[a-z][a-z0-9_-]*$/i.test(raw))
-            break;
-        if (isResourceId(raw))
-            break;
-        parts.push(raw);
-    }
-    return parts.length > 0 ? parts.join(".") : "unknown";
-}
-/**
- * A Lotics resource id (`app_Gw6rs95ZYKQs`, `tbl_1KxO3W08g75o`) as opposed to a
- * snake_case tool name (`query_records`, `grep_knowledge`).
- *
- * Both are `<word>_<word>`, so prefix-and-underscore alone is not the tell — it
- * rejected half the tool registry. The discriminator is the SUFFIX: an id's is a
- * long base62 blob, which always carries an uppercase letter or a digit; a tool
- * name's second word is an English word in lowercase. Requiring both (a short
- * prefix with a long mixed-case suffix, and no second underscore) leaves
- * `set_app_workflow` and `aggregate_records` on the verb side where they belong.
- */
-function isResourceId(token) {
-    const match = /^[a-z]{2,5}_([A-Za-z0-9]{8,})$/.exec(token);
-    return match !== null && /[A-Z0-9]/.test(match[1]);
-}
-/** `lotics-cli/0.117.0 node/v22.1.0 linux` — enough to correlate a failure with a stale CLI. */
-export function userAgent(version) {
-    return `lotics-cli/${version} node/${process.version} ${os.platform()}`;
-}
-let invocation = null;
-/**
- * `version` is passed in rather than imported: `version.ts` resolves
- * `package.json` relative to its own module URL, which only holds from `dist/`,
- * so importing it into `client.ts` would make the library entry unloadable from
- * source. The bin already reads it correctly; the client just relays it.
- */
-export function setInvocation(command, session, version) {
-    invocation = { command, session, userAgent: userAgent(version) };
-}
-export function getInvocation() {
-    return invocation;
-}
-/** Back to the library state (no CLI process). Exists for tests. */
-export function resetInvocation() {
-    invocation = null;
-}
-/**
- * A sitting of the CLI, as one id shared by every invocation in it.
- *
- * Under an agent harness that already has a session concept, adopt it — the ids
- * then line up with the harness's own transcript, which is the difference between
- * "these 40 commands are related" and "these 40 commands ARE that conversation".
- * Otherwise sessionize the way web analytics does: reuse the stored id while
- * invocations keep arriving, mint a new one after an idle gap.
- */
-const IDLE_GAP_MS = 30 * 60 * 1000;
-export function sessionStorePath() {
-    return path.join(os.homedir(), ".lotics", "session.json");
-}
-function readSession(file) {
-    try {
-        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
-        if (typeof parsed !== "object" || parsed === null)
-            return null;
-        const { id, last_seen } = parsed;
-        if (typeof id !== "string" || typeof last_seen !== "number")
-            return null;
-        return { id, last_seen };
-    }
-    catch {
-        // Absent, unreadable, or corrupt — all mean "no session to continue", and a
-        // telemetry id is never worth failing a command over.
-        return null;
-    }
-}
-/**
- * The current session id, or null when telemetry is off. `now` is injected so the
- * idle-gap boundary is testable without a clock.
- */
-export function sessionId(now = Date.now(), env = process.env) {
-    if (!telemetryEnabled(env))
-        return null;
-    const harnessSession = env.CLAUDE_CODE_SESSION_ID;
-    if (harnessSession !== undefined && harnessSession !== "")
-        return harnessSession;
-    const file = sessionStorePath();
-    const stored = readSession(file);
-    const id = stored !== null && now - stored.last_seen < IDLE_GAP_MS
-        ? stored.id
-        : `cli_${now.toString(36)}${Math.random().toString(36).slice(2, 10)}`;
-    try {
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, JSON.stringify({ id, last_seen: now }), { mode: 0o600 });
-    }
-    catch {
-        // A read-only home still gets a usable id for this process; only the
-        // continuity across invocations is lost.
-    }
-    return id;
-}