@lotics/cli 0.116.0 → 0.123.0

package/dist/src/client.d.ts

@@ -150,6 +150,14 @@ export declare class LoticsClient {
     readonly baseUrl: string;
     constructor(options: LoticsClientOptions);
     private throwResponseError;
+    /**
+     * The backend's `log()` middleware registers `user-agent` and
+     * `x-posthog-session-id` onto the per-request Logger, so they ride EVERY log
+     * line that request emits — the validation 400, the tool error, the timing.
+     * Sending them is therefore the whole of the correlation work: it turns an
+     * anonymous API-key request into "`app workflow set`, from cli 0.117.0, the
+     * fourth command of this session".
+     */
     private buildHeaders;
     private request;
     whoami(): Promise<{
@@ -855,6 +863,10 @@ export declare class LoticsClient {
         outputs?: Record<string, unknown>;
         name?: string;
         description?: string;
+        /** The `body_sha` this push was built on. Makes the write conditional: the
+         *  server refuses it when the live body has moved since, rather than
+         *  letting a stale copy overwrite an edit its author never saw. */
+        expected_body_sha?: string;
     }): Promise<ToolExecuteResult>;
     /**
      * Bind (create or replace) an app query by alias via the `set_app_query` tool
@@ -868,7 +880,9 @@ export declare class LoticsClient {
         ast: unknown;
         params?: Record<string, unknown>;
         description?: string;
-    }): Promise<ToolExecuteResult>;
+    }, 
+    /** The fingerprint this edit was based on — makes the write conditional. */
+    expected_sha?: string): Promise<ToolExecuteResult>;
     /**
      * Bind (create or replace) an app agent by alias via the `set_app_agent` tool
      * — the deploy-free authoring path for `apps.agents`, parallel to
@@ -1036,6 +1050,7 @@ export declare class LoticsClient {
          * (empty array when none declared).
          */
         workflow_aliases?: string[];
+        agent_aliases?: string[];
         query_aliases?: string[];
     }): Promise<{
         version_id: string;

package/dist/src/client.js

@@ -1,6 +1,7 @@
 import { transportErrorMessage } from "@lotics/shared/transport_error";
 import fs from "node:fs";
 import path from "node:path";
+import { getInvocation } from "./invocation.js";
 function findAvailableFilename(dir, filename, reserved) {
     // `reserved` tracks absolute paths claimed by in-flight downloads in the same
     // batch — required for parallel callers because the file may not be on disk
@@ -75,9 +76,21 @@ export class LoticsClient {
         }
         throw new Error(`${response.status}: ${message}`);
     }
+    /**
+     * The backend's `log()` middleware registers `user-agent` and
+     * `x-posthog-session-id` onto the per-request Logger, so they ride EVERY log
+     * line that request emits — the validation 400, the tool error, the timing.
+     * Sending them is therefore the whole of the correlation work: it turns an
+     * anonymous API-key request into "`app workflow set`, from cli 0.117.0, the
+     * fourth command of this session".
+     */
     buildHeaders() {
+        const invocation = getInvocation();
         const headers = {
             "Authorization": `Bearer ${this.apiKey}`,
+            // Unversioned when the SDK is used as a library — there is no CLI process
+            // whose version to name, and a wrong one is worse than none.
+            "user-agent": invocation?.userAgent ?? "lotics-cli",
         };
         if (this.workspaceId) {
             headers["x-workspace-id"] = this.workspaceId;
@@ -85,6 +98,12 @@ export class LoticsClient {
         if (this.viewAsMemberId) {
             headers["x-view-as-member-id"] = this.viewAsMemberId;
         }
+        if (invocation) {
+            headers["x-lotics-cli-command"] = invocation.command;
+            if (invocation.session !== null) {
+                headers["x-posthog-session-id"] = invocation.session;
+            }
+        }
         return headers;
     }
     async request(method, path, body) {
@@ -547,6 +566,7 @@ export class LoticsClient {
             ...(body.outputs ? { outputs: body.outputs } : {}),
             ...(body.name ? { name: body.name } : {}),
             ...(body.description ? { description: body.description } : {}),
+            ...(body.expected_body_sha ? { expected_body_sha: body.expected_body_sha } : {}),
         });
     }
     /**
@@ -557,8 +577,15 @@ export class LoticsClient {
      * deploy validates the manifest. Note: `apps.queries` is manifest-authoritative,
      * so the next `lotics app deploy` overwrites this from the manifest.
      */
-    async setAppQuery(app_id, alias, declaration) {
-        return this.execute("set_app_query", { app_id, alias, declaration });
+    async setAppQuery(app_id, alias, declaration, 
+    /** The fingerprint this edit was based on — makes the write conditional. */
+    expected_sha) {
+        return this.execute("set_app_query", {
+            app_id,
+            alias,
+            declaration,
+            ...(expected_sha ? { expected_sha } : {}),
+        });
     }
     /**
      * Bind (create or replace) an app agent by alias via the `set_app_agent` tool
@@ -723,6 +750,7 @@ export class LoticsClient {
         // server records what the served version calls — the remove_app_workflow
         // guard reads this back. These are the manifest KEYS only, never bindings.
         formData.append("workflow_aliases", JSON.stringify(args.workflow_aliases ?? []));
+        formData.append("agent_aliases", JSON.stringify(args.agent_aliases ?? []));
         formData.append("query_aliases", JSON.stringify(args.query_aliases ?? []));
         const url = `${this.baseUrl}/v1/apps/${encodeURIComponent(args.app_id)}/versions`;
         const response = await fetch(url, {

package/dist/src/invocation.d.ts

@@ -0,0 +1,51 @@
+/** Enabled by an explicit `LOTICS_TELEMETRY=1`. Anything else, including unset, is off. */
+export declare function telemetryEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * 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 declare function commandPath(argv: readonly string[]): string;
+/** `lotics-cli/0.117.0 node/v22.1.0 linux` — enough to correlate a failure with a stale CLI. */
+export declare function userAgent(version: string): string;
+/**
+ * The command + session of the running CLI process, set once by `cli.ts` before
+ * dispatch and read by `LoticsClient.buildHeaders`.
+ *
+ * Process-scoped ambient state, which is a cost — but the alternative is
+ * threading two strings through the ~20 places a client is constructed, and the
+ * facts are genuinely process-wide (there is one command per invocation). It is
+ * write-once at startup and read-only after, so nothing downstream has to track
+ * when it changes.
+ *
+ * Unset is the LIBRARY case: `@lotics/cli` also exports `LoticsClient`, where
+ * `process.argv` belongs to someone else's program and would name a command that
+ * was never run. Absent beats wrong, so the header is simply omitted.
+ */
+type Invocation = {
+    command: string;
+    session: string | null;
+    userAgent: string;
+};
+/**
+ * `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 declare function setInvocation(command: string, session: string | null, version: string): void;
+export declare function getInvocation(): Invocation | null;
+/** Back to the library state (no CLI process). Exists for tests. */
+export declare function resetInvocation(): void;
+export declare function sessionStorePath(): string;
+/**
+ * The current session id, or null when telemetry is off. `now` is injected so the
+ * idle-gap boundary is testable without a clock.
+ */
+export declare function sessionId(now?: number, env?: NodeJS.ProcessEnv): string | null;
+export {};

package/dist/src/invocation.js

@@ -0,0 +1,142 @@
+/**
+ * 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;
+}

package/package.json

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