@lotics/cli 0.313.3 → 0.313.5

package/dist/src/client.d.ts

@@ -118,6 +118,9 @@ export interface ToolExecuteResult {
      *  and the only part of a failure a caller may branch on. Absent when the
      *  failure was not a typed error, and from any server older than it. */
     error_code?: string;
+    /** Whose words `error` is: `system` ours, `customer` a workspace author's (a table check's sentence). Absent from
+     *  a server older than it. */
+    message_source?: "system" | "customer";
     /** A refused input addressed per field: one sentence from a typed alias, a
      *  list from a refusing table check. */
     field_errors?: Record<string, string> | Record<string, string[]>;
@@ -213,7 +216,11 @@ export interface ModelBinding {
 export declare class LoticsRequestError extends Error {
     readonly status: number;
     readonly body: Record<string, unknown>;
-    constructor(message: string, status: number, body: Record<string, unknown>);
+    /** What a command's record may say of it: the message only where the envelope marks it the server's own words. */
+    readonly telemetryMessage: string;
+    constructor(message: string, status: number, body: Record<string, unknown>, 
+    /** What a command's record may say of it: the message only where the envelope marks it the server's own words. */
+    telemetryMessage: string);
 }
 /**
  * The website: where a person goes when the CLI cannot finish the job. Held

package/dist/src/client.js

@@ -58,6 +58,24 @@ async function uploadParts(options) {
   return done.sort((a, b) => a.part_number - b.part_number);
 }
 
+// ../shared/src/transport_error.ts
+function gatewayErrorMessage(status) {
+  if (status === 524) {
+    return "The request took too long to finish (gateway timeout). It may still be running \u2014 check back in a moment, or try again.";
+  }
+  if (status >= 500) {
+    return "The service is temporarily unavailable. Please try again shortly.";
+  }
+  return "The service returned an unexpected response. Please try again.";
+}
+function telemetryErrorMessage(status, parsed) {
+  if (parsed === null || typeof parsed !== "object") return gatewayErrorMessage(status);
+  const code = "code" in parsed && typeof parsed.code === "string" && parsed.code.length > 0 ? parsed.code : null;
+  const system = "message_source" in parsed && parsed.message_source === "system";
+  if (system && "message" in parsed && typeof parsed.message === "string") return parsed.message;
+  return code ?? gatewayErrorMessage(status);
+}
+
 // ../shared/src/cli_capabilities.ts
 var CLI_CAPABILITIES_HEADER = "x-lotics-cli-capabilities";
 var CLI_CAPABILITIES = ["docs-fallback"];
@@ -131,14 +149,16 @@ function getMimeType(filename) {
 var MULTIPART_THRESHOLD_BYTES = 8 * 1024 * 1024;
 var PROXY_BATCH_MAX_BYTES = PROXY_UPLOAD_MAX_BYTES / 2;
 var LoticsRequestError = class extends Error {
-  constructor(message, status, body) {
+  constructor(message, status, body, telemetryMessage) {
     super(message);
     this.status = status;
     this.body = body;
+    this.telemetryMessage = telemetryMessage;
     this.name = "LoticsRequestError";
   }
   status;
   body;
+  telemetryMessage;
 };
 var WEB_APP_URL = process.env.LOTICS_WEB_URL ?? "https://lotics.ai";
 var PUBLIC_FETCH_TIMEOUT_MS = 1e4;
@@ -226,7 +246,12 @@ var LoticsClient = class {
     const trace = requestId === void 0 ? "" : `
 
   Request id: ${requestId} \u2014 quote this to Lotics support.`;
-    throw new LoticsRequestError(`${response.status}: ${message}${hint}${trace}`, response.status, body);
+    throw new LoticsRequestError(
+      `${response.status}: ${message}${hint}${trace}`,
+      response.status,
+      body,
+      `${response.status}: ${telemetryErrorMessage(response.status, body)}${trace}`
+    );
   }
   /**
    * The backend's `log()` middleware registers `user-agent`,

package/docs/building_an_app.md

@@ -192,7 +192,8 @@ on it, the `patch` adopting the decisions among them, and the app's body as the
 leaves it (`draft`). `verdict_unread` says why none was read.
 
 The app's `name`, `icon`, `theme` and `description` are keys of the app in the model, and each apply
-writes them onto the app; one the model leaves out is cleared. `lotics run update_app` changes them on
+writes them onto the app; an `icon` or `description` the model leaves out is cleared, and an app
+stating no `theme` is refused (`app.theme`). `lotics run update_app` changes them on
 the app, and `lotics model pull` reads them back as the app holds them. The
 `description` heads the capability listing the member's chat agent reads on **every** turn, so a
 standing process the app expects that agent to carry out belongs there and nowhere else.

package/package.json

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