@lotics/cli 0.318.37 → 0.318.38

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -75,6 +75,8 @@ export interface LoticsClientOptions {
75
75
  * instance's key to production (`docs/on_premise.md` section 8). */
76
76
  apiUrl: string;
77
77
  workspaceId?: string;
78
+ /** Stops waiting for any answer after this many milliseconds; absent, a call waits for the server. */
79
+ timeoutMs?: number;
78
80
  }
79
81
  export interface WorkspaceInfo {
80
82
  id: string;
@@ -181,6 +183,31 @@ export declare class LoticsRequestError extends Error {
181
183
  /** What a command's record may say of it: the message only where the envelope marks it the server's own words. */
182
184
  telemetryMessage: string);
183
185
  }
186
+ /**
187
+ * The CLI stopped waiting for a call's answer, so it cannot say whether the
188
+ * call took effect: a write the server was still running commits regardless.
189
+ * Only a call that may write ends this way; a read with no answer is a
190
+ * `NoAnswerError`.
191
+ */
192
+ export declare class OutcomeUnknownError extends Error {
193
+ readonly request_id: string;
194
+ readonly error_code = "outcome_unknown";
195
+ constructor(waited: string, request_id: string, cause?: unknown);
196
+ }
197
+ /**
198
+ * No answer arrived to a call that only reads, so nothing changed. `request_id`
199
+ * is absent for a download from object storage, which is no request of ours.
200
+ */
201
+ export declare class NoAnswerError extends Error {
202
+ readonly request_id: string | undefined;
203
+ constructor(waited: string, request_id: string | undefined, cause?: unknown);
204
+ }
205
+ /**
206
+ * A fetch from an object-storage signed URL: not a request of ours, so it
207
+ * carries no id and is held to `timeoutMs` alone. `read` runs inside the wait,
208
+ * because the clock covers the body too.
209
+ */
210
+ export declare function fetchStorage<T>(url: string, timeoutMs: number | undefined, read: (response: Response) => Promise<T>): Promise<T>;
184
211
  /**
185
212
  * The website: where a person goes when the CLI cannot finish the job. Held
186
213
  * beside the API base and overridable for the same reason — a run against a
@@ -233,6 +260,7 @@ export declare class LoticsClient {
233
260
  private workspaceId;
234
261
  /** The instance this client sends every request to. */
235
262
  readonly baseUrl: string;
263
+ private readonly timeoutMs;
236
264
  constructor(options: LoticsClientOptions);
237
265
  /**
238
266
  * The id is appended to the MESSAGE rather than carried on a field, because
@@ -260,7 +288,17 @@ export declare class LoticsClient {
260
288
  * `app deploy`, `uploadFiles` and every workflow call unfindable.
261
289
  */
262
290
  private buildHeaders;
291
+ /**
292
+ * The one transport for every call to our API. Waits for the server's answer;
293
+ * only the client's `timeoutMs` stops the wait earlier, and a lost connection
294
+ * ends it too. Either way a call that may write could have taken effect, so
295
+ * it gets `OutcomeUnknownError`, never a plain failure; a read gets
296
+ * `NoAnswerError`, because it changed nothing. `read` turns the answer into
297
+ * the result and runs inside the wait.
298
+ */
299
+ private call;
263
300
  private request;
301
+ private requestForm;
264
302
  /** `email` is null for a credential no person signs in as; `account_type` is absent from an older server. */
265
303
  /** `credential_origin` describes the CREDENTIAL this call carried, not the
266
304
  * member above: `sign_in` for a terminal somebody signed in from, `api_key`
@@ -350,7 +388,6 @@ export declare class LoticsClient {
350
388
  getTool(name: string): Promise<ToolInfo>;
351
389
  execute(tool: string, args: Record<string, unknown>, options?: {
352
390
  format?: "json" | "text";
353
- timeoutMs?: number;
354
391
  }): Promise<ToolExecuteResult>;
355
392
  /**
356
393
  * Fetch one knowledge doc with its hydrated `content` — the single content-read
@@ -160,6 +160,54 @@ var LoticsRequestError = class extends Error {
160
160
  body;
161
161
  telemetryMessage;
162
162
  };
163
+ var OutcomeUnknownError = class extends Error {
164
+ constructor(waited, request_id, cause) {
165
+ super(
166
+ `No answer from the server ${waited}, so this call cannot say whether it took effect. Read the records before running it again. Request id: ${request_id}.`,
167
+ { cause }
168
+ );
169
+ this.request_id = request_id;
170
+ this.name = "OutcomeUnknownError";
171
+ }
172
+ request_id;
173
+ error_code = "outcome_unknown";
174
+ };
175
+ var NoAnswerError = class extends Error {
176
+ constructor(waited, request_id, cause) {
177
+ super(
178
+ `No answer from ${request_id === void 0 ? "storage" : "the server"} ${waited}. This call only reads, so nothing changed.${request_id === void 0 ? "" : ` Request id: ${request_id}.`}`,
179
+ { cause }
180
+ );
181
+ this.request_id = request_id;
182
+ this.name = "NoAnswerError";
183
+ }
184
+ request_id;
185
+ };
186
+ async function fetchStorage(url, timeoutMs, read) {
187
+ try {
188
+ return await read(await fetch(url, timeoutMs === void 0 ? {} : { signal: AbortSignal.timeout(timeoutMs) }));
189
+ } catch (error) {
190
+ if (error instanceof Error && error.name === "TimeoutError" && timeoutMs !== void 0) {
191
+ throw new NoAnswerError(`within ${timeoutMs / 1e3}s`, void 0, error);
192
+ }
193
+ throw error;
194
+ }
195
+ }
196
+ var NEVER_SENT_CODES = /* @__PURE__ */ new Set([
197
+ "ENOTFOUND",
198
+ "ECONNREFUSED",
199
+ "EAI_AGAIN",
200
+ "UND_ERR_CONNECT_TIMEOUT",
201
+ "CERT_HAS_EXPIRED",
202
+ "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
203
+ "DEPTH_ZERO_SELF_SIGNED_CERT",
204
+ "SELF_SIGNED_CERT_IN_CHAIN",
205
+ "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
206
+ "ERR_TLS_CERT_ALTNAME_INVALID"
207
+ ]);
208
+ function errorCode(cause) {
209
+ return typeof cause === "object" && cause !== null && "code" in cause && typeof cause.code === "string" ? cause.code : void 0;
210
+ }
163
211
  var WEB_APP_URL = process.env.LOTICS_WEB_URL ?? "https://lotics.ai";
164
212
  var PUBLIC_FETCH_TIMEOUT_MS = 1e4;
165
213
  async function startCliLogin(apiUrl, email) {
@@ -212,7 +260,9 @@ var LoticsClient = class {
212
260
  workspaceId;
213
261
  /** The instance this client sends every request to. */
214
262
  baseUrl;
263
+ timeoutMs;
215
264
  constructor(options) {
265
+ this.timeoutMs = options.timeoutMs;
216
266
  this.apiKey = options.apiKey;
217
267
  this.workspaceId = options.workspaceId;
218
268
  this.baseUrl = options.apiUrl;
@@ -229,7 +279,20 @@ var LoticsClient = class {
229
279
  * logs. Every call against the API passes the id its own headers carry.
230
280
  */
231
281
  async throwResponseError(response, requestId) {
232
- const text = await response.text();
282
+ const trace = requestId === void 0 ? "" : `
283
+
284
+ Request id: ${requestId} \u2014 quote this to Lotics support.`;
285
+ let text;
286
+ try {
287
+ text = await response.text();
288
+ } catch (readError) {
289
+ throw new LoticsRequestError(
290
+ `${response.status}: the server refused with HTTP ${response.status} and its error body could not be read (${readError instanceof Error ? readError.message : String(readError)})${trace}`,
291
+ response.status,
292
+ {},
293
+ `${response.status}: ${telemetryErrorMessage(response.status, {})}${trace}`
294
+ );
295
+ }
233
296
  let body = {};
234
297
  try {
235
298
  const json = JSON.parse(text);
@@ -240,9 +303,6 @@ var LoticsClient = class {
240
303
  const message = typeof body.message === "string" ? body.message : unparsedAnswer(text);
241
304
  const hint = typeof body.hint === "string" ? `
242
305
  ${body.hint}` : "";
243
- const trace = requestId === void 0 ? "" : `
244
-
245
- Request id: ${requestId} \u2014 quote this to Lotics support.`;
246
306
  throw new LoticsRequestError(
247
307
  `${response.status}: ${message}${hint}${trace}`,
248
308
  response.status,
@@ -284,17 +344,54 @@ var LoticsClient = class {
284
344
  headers["x-request-id"] = newRequestId();
285
345
  return headers;
286
346
  }
287
- async request(method, path2, body) {
347
+ /**
348
+ * The one transport for every call to our API. Waits for the server's answer;
349
+ * only the client's `timeoutMs` stops the wait earlier, and a lost connection
350
+ * ends it too. Either way a call that may write could have taken effect, so
351
+ * it gets `OutcomeUnknownError`, never a plain failure; a read gets
352
+ * `NoAnswerError`, because it changed nothing. `read` turns the answer into
353
+ * the result and runs inside the wait.
354
+ */
355
+ async call(method, path2, body, read) {
288
356
  const url = `${this.baseUrl}${path2}`;
289
357
  const headers = this.buildHeaders();
358
+ const requestId = headers["x-request-id"];
359
+ const timeoutMs = this.timeoutMs;
360
+ const readOnly = method === "GET" || method === "HEAD";
361
+ const noAnswer = (waited, cause) => readOnly ? new NoAnswerError(waited, requestId, cause) : new OutcomeUnknownError(waited, requestId, cause);
290
362
  const init = { method, headers };
291
- if (body !== void 0) {
363
+ if (timeoutMs !== void 0) init.signal = AbortSignal.timeout(timeoutMs);
364
+ if (body?.kind === "json") {
292
365
  headers["Content-Type"] = "application/json";
293
- init.body = JSON.stringify(body);
366
+ init.body = JSON.stringify(body.value);
367
+ } else if (body?.kind === "form") {
368
+ init.body = body.value;
369
+ }
370
+ try {
371
+ const response = await fetch(url, init);
372
+ if (!response.ok) {
373
+ if (response.status >= 500 && !response.headers.has("x-request-id")) {
374
+ throw noAnswer(`before the gateway in front of it gave up (HTTP ${response.status})`);
375
+ }
376
+ await this.throwResponseError(response, requestId);
377
+ }
378
+ return await read(response);
379
+ } catch (error) {
380
+ if (error instanceof LoticsRequestError || error instanceof OutcomeUnknownError || error instanceof NoAnswerError) throw error;
381
+ if (error instanceof Error && error.name === "TimeoutError" && timeoutMs !== void 0) {
382
+ throw noAnswer(`within ${timeoutMs / 1e3}s`, error);
383
+ }
384
+ if (error instanceof TypeError && error.cause !== void 0 && !NEVER_SENT_CODES.has(errorCode(error.cause))) {
385
+ throw noAnswer("before the connection closed", error.cause);
386
+ }
387
+ throw error;
294
388
  }
295
- const response = await fetch(url, init);
296
- if (!response.ok) await this.throwResponseError(response, headers["x-request-id"]);
297
- return response.json();
389
+ }
390
+ async request(method, path2, body) {
391
+ return this.call(method, path2, body === void 0 ? void 0 : { kind: "json", value: body }, async (response) => await response.json());
392
+ }
393
+ async requestForm(method, path2, form) {
394
+ return this.call(method, path2, { kind: "form", value: form }, async (response) => await response.json());
298
395
  }
299
396
  /** `email` is null for a credential no person signs in as; `account_type` is absent from an older server. */
300
397
  /** `credential_origin` describes the CREDENTIAL this call carried, not the
@@ -353,31 +450,7 @@ var LoticsClient = class {
353
450
  return this.request("GET", `/v1/tools/${encodeURIComponent(name)}`);
354
451
  }
355
452
  async execute(tool, args, options) {
356
- const body = { tool, args, format: options?.format ?? "text" };
357
- if (options?.timeoutMs) {
358
- const controller = new AbortController();
359
- const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
360
- try {
361
- const url = `${this.baseUrl}/v1/tools/execute`;
362
- const headers = { ...this.buildHeaders(), "Content-Type": "application/json" };
363
- const response = await fetch(url, {
364
- method: "POST",
365
- headers,
366
- body: JSON.stringify(body),
367
- signal: controller.signal
368
- });
369
- if (!response.ok) await this.throwResponseError(response, headers["x-request-id"]);
370
- return response.json();
371
- } catch (error) {
372
- if (error instanceof Error && error.name === "AbortError") {
373
- throw new Error(`Tool execution timed out after ${options.timeoutMs}ms`);
374
- }
375
- throw error;
376
- } finally {
377
- clearTimeout(timeout);
378
- }
379
- }
380
- return this.request("POST", "/v1/tools/execute", body);
453
+ return this.request("POST", "/v1/tools/execute", { tool, args, format: options?.format ?? "text" });
381
454
  }
382
455
  // --- Knowledge docs ---
383
456
  /**
@@ -422,9 +495,10 @@ var LoticsClient = class {
422
495
  "GET",
423
496
  `/v1/apps/${encodeURIComponent(appId)}/versions/${encodeURIComponent(versionId)}/source`
424
497
  );
425
- const response = await fetch(url);
426
- if (!response.ok) await this.throwResponseError(response);
427
- return Buffer.from(await response.arrayBuffer());
498
+ return fetchStorage(url, this.timeoutMs, async (response) => {
499
+ if (!response.ok) await this.throwResponseError(response);
500
+ return Buffer.from(await response.arrayBuffer());
501
+ });
428
502
  }
429
503
  /**
430
504
  * Workspace-wide dangling-reference sweep — active app/workflow artifacts
@@ -465,20 +539,13 @@ var LoticsClient = class {
465
539
  );
466
540
  if (args.prev_version_id) formData.append("prev_version_id", args.prev_version_id);
467
541
  if (args.message) formData.append("message", args.message);
468
- const url = `${this.baseUrl}/v1/apps/${encodeURIComponent(args.app_id)}/versions`;
469
- const headers = this.buildHeaders();
470
- const response = await fetch(url, { method: "POST", headers, body: formData });
471
- if (!response.ok) {
472
- await this.throwResponseError(response, headers["x-request-id"]);
473
- }
474
- return response.json();
542
+ return this.requestForm("POST", `/v1/apps/${encodeURIComponent(args.app_id)}/versions`, formData);
475
543
  }
476
544
  async downloadFile(url, outputPath) {
477
- const response = await fetch(url);
478
- if (!response.ok) {
479
- throw new Error(`${response.status}: Failed to download file`);
480
- }
481
- const buffer = Buffer.from(await response.arrayBuffer());
545
+ const buffer = await fetchStorage(url, this.timeoutMs, async (response) => {
546
+ if (!response.ok) throw new Error(`${response.status}: Failed to download file`);
547
+ return Buffer.from(await response.arrayBuffer());
548
+ });
482
549
  const absolutePath = path.resolve(outputPath);
483
550
  await fs.promises.mkdir(path.dirname(absolutePath), { recursive: true });
484
551
  await fs.promises.writeFile(absolutePath, buffer);
@@ -500,20 +567,12 @@ var LoticsClient = class {
500
567
  return this.request("GET", `/v1/files${query ? `?${query}` : ""}`);
501
568
  }
502
569
  async downloadFileById(fileId, destination, options) {
503
- const signedHeaders = this.buildHeaders();
504
- const signedUrlRes = await fetch(
505
- `${this.baseUrl}/v1/files/${encodeURIComponent(fileId)}/signed_url`,
506
- { headers: signedHeaders }
507
- );
508
- if (!signedUrlRes.ok) {
509
- await this.throwResponseError(signedUrlRes, signedHeaders["x-request-id"]);
510
- }
511
- const { url } = await signedUrlRes.json();
512
- const response = await fetch(url);
513
- if (!response.ok) await this.throwResponseError(response);
514
- const disposition = response.headers.get("content-disposition") ?? "";
570
+ const { url } = await this.request("GET", `/v1/files/${encodeURIComponent(fileId)}/signed_url`);
571
+ const { disposition, buffer } = await fetchStorage(url, this.timeoutMs, async (response) => {
572
+ if (!response.ok) await this.throwResponseError(response);
573
+ return { disposition: response.headers.get("content-disposition") ?? "", buffer: Buffer.from(await response.arrayBuffer()) };
574
+ });
515
575
  const originalFilename = parseContentDispositionFilename(disposition) ?? fileId;
516
- const buffer = Buffer.from(await response.arrayBuffer());
517
576
  const { dir, named } = destination === void 0 ? { dir: process.cwd() } : "file" in destination ? {
518
577
  dir: path.dirname(path.resolve(destination.file)),
519
578
  named: path.basename(destination.file)
@@ -562,6 +621,7 @@ var LoticsClient = class {
562
621
  files.push(...result.files);
563
622
  errors.push(...result.errors);
564
623
  } catch (error) {
624
+ if (error instanceof OutcomeUnknownError) throw error;
565
625
  const message = error instanceof Error ? error.message : String(error);
566
626
  errors.push(...sent.map((item) => ({ filename: item.filename, error: message })));
567
627
  }
@@ -583,6 +643,7 @@ var LoticsClient = class {
583
643
  try {
584
644
  files.push(await this.uploadLargeFile(item));
585
645
  } catch (error) {
646
+ if (error instanceof OutcomeUnknownError) throw error;
586
647
  errors.push({
587
648
  filename: item.filename,
588
649
  error: error instanceof Error ? error.message : String(error)
@@ -685,17 +746,16 @@ var LoticsClient = class {
685
746
  const mimeType = item.mimeType ?? getMimeType(item.filename);
686
747
  formData.append("file", new Blob([item.bytes], { type: mimeType }), item.filename);
687
748
  }
688
- const url = `${this.baseUrl}/v1/files`;
689
- const headers = this.buildHeaders();
690
- const response = await fetch(url, { method: "POST", headers, body: formData });
691
- if (!response.ok) await this.throwResponseError(response, headers["x-request-id"]);
692
- return response.json();
749
+ return this.requestForm("POST", "/v1/files", formData);
693
750
  }
694
751
  };
695
752
  export {
696
753
  LoticsClient,
697
754
  LoticsRequestError,
755
+ NoAnswerError,
756
+ OutcomeUnknownError,
698
757
  WEB_APP_URL,
758
+ fetchStorage,
699
759
  findAvailableFilename,
700
760
  pollCliLogin,
701
761
  startCliLogin
@@ -8,6 +8,7 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
8
8
  | `lotics auth signup <email>` | Create account + org + API key, sends magic link email. Refused on a private instance, whose people arrive by invitation; prints that creating the account accepts the Terms and Privacy Policy. Registers the new org as a profile; `--local` pins this directory to it (pointer) instead of setting the global default. |
9
9
  | `lotics auth login <email>` | Sign in an account that already exists, on a machine holding no key. **Two steps, and it does not wait for the person.** The first prints the page to open — `https://lotics.ai/cli_login/<request_id>`, also mailed — and the code that page must show, records the request, and exits 0. They sign in there if asked, check the code and press Confirm. **Then the next command that needs a credential collects the key** before it does its own work, so the second step is just re-running whatever was wanted; a command run before Confirm exits 1 naming the page and the code again, and once the 15 minutes are up it says to ask again. The handful that run WITHOUT a credential — `docs` among them — claim nothing, so one of those run after Confirm still answers as though signed out. `--wait` keeps one command instead, holding the terminal until Confirm; `--local` pins this directory to that org rather than setting the global default, and implies `--wait` (a pin names THIS directory, so only the terminal that stays in it can write one). `--json` prints `organization_id`, `workspace_id` and `organization_name` when it finishes signed in, and `request_id`, `confirm_url`, `code`, `email`, `expires_at` when it is the first step. The request's secret is never printed and the org's key never leaves the store. |
10
10
  | — | **A flag is refused on a verb that does not read it**, naming the verbs that do, before any request or credential: `--check` on `lotics run` would otherwise be parsed and ignored, and the write it was meant to stop would run. `--json`, `--workspace`, `--api-key` and `--timeout` are read by every verb. |
11
+ | — | **Every call a verb makes waits for the server's answer**; `--timeout <ms>` (a whole number of milliseconds from 1 to 2147483647) stops each wait early. The wait ends without an answer when `--timeout` passes or no answer arrives from the server. A read with no answer changed nothing: the command exits non-zero naming the request id. A write with no answer exits non-zero with `error_code: "outcome_unknown"` and the request id under `--json`, because it cannot say whether the call took effect: read before running it again. The one fetch outside this is the download from an object-storage signed URL, which carries no request id and is stopped by `--timeout` alone. Under `--json` every error is one object on stdout: `error`, with `error_code` and `request_id` where the error has them. |
11
12
  | `lotics auth api-key [key]` | `whoami` → **upsert** the key's org as a profile in the global store (never overwrites). The profile records the instance the key was verified against (`LOTICS_API_URL`, default `https://api.lotics.ai`), and every later command for that org goes there. `--local` additionally pins this directory to it (pointer) instead of setting the global default. |
12
13
  | `lotics auth web` | Send a magic link email to access the web app (requires auth) |
13
14
  | `lotics auth whoami` | Print active account name, email, org, resolved workspace, the instance the credential belongs to, which **kind** of credential this machine holds (a sign-in from `auth login`, or an API key — read from the saved profile, and from the server when the profile does not say, which covers `--api-key`/`LOTICS_API_KEY` and a profile saved before the field existed; unknown only when neither can say), and the resolution **source** (flag/env/local/app-manifest/global). `--json` adds `workspace_id`, `api_url`, `credential_kind` + `source`. |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lotics/cli",
3
- "version": "0.318.37",
3
+ "version": "0.318.38",
4
4
  "description": "Lotics SDK and CLI for AI agents",
5
5
  "type": "module",
6
6
  "bin": {