@tryarcanist/cli 0.1.167 → 0.1.168

package/README.md

@@ -53,9 +53,12 @@ Supported environment variables:
 ```bash
 export ARCANIST_TOKEN=arc_...
 export ARCANIST_API_URL=https://api.tryarcanist.com
+export ARCANIST_HTTP_TIMEOUT_MS=30000
 ```
 
 `--token` and `--api-url` are available for one-off invocations. Prefer `ARCANIST_TOKEN` over `--token` for persistent use; CLI flags can appear in shell history and process lists.
+Each HTTP request times out after `ARCANIST_HTTP_TIMEOUT_MS` milliseconds, default `30000`.
+The value must be between `1000` and `600000`; invalid values fail closed instead of falling back silently.
 
 Non-local API URLs must use HTTPS and must not embed credentials.
 
@@ -89,10 +92,18 @@ With `--json`, successful command output is machine-readable and newline-termina
 
 ```json
 {
-  "error": { "code": "auth", "message": "Not logged in.", "hint": "Run `arcanist auth login` or set `ARCANIST_TOKEN`." }
+  "error": {
+    "code": "auth",
+    "message": "Not logged in.",
+    "hint": "Run `arcanist auth login` or set `ARCANIST_TOKEN`.",
+    "data": { "serverCode": "token_revoked" }
+  }
 }
 ```
 
+`error.data` is omitted when there is no structured recovery data.
+Stable fields are `serverCode` for server-provided error codes and `sessionId`/`sessionUrl` when `sessions create` created the session but failed to enqueue the prompt.
+
 Exit codes:
 
 ```text

package/dist/index.js

@@ -24,6 +24,7 @@ var CliError = class extends Error {
   exitCode;
   hint;
   requestId;
+  data;
   constructor(code, message, options = {}) {
     super(message);
     this.name = "CliError";
@@ -31,17 +32,20 @@ var CliError = class extends Error {
     this.exitCode = options.exitCode ?? exitCodeForErrorCode(code);
     this.hint = options.hint;
     this.requestId = options.requestId;
+    this.data = options.data;
   }
 };
 var ApiError = class extends CliError {
   status;
   body;
-  constructor(status, body, requestId) {
+  constructor(status, body, requestId, resourceNoun) {
     const code = codeForHttpStatus(status);
-    super(code, messageForApiError(status, body), {
+    const parsed = parseApiErrorBody(body);
+    super(code, messageForApiError(status, body, parsed), {
       exitCode: exitCodeForHttpStatus(status),
-      hint: hintForHttpStatus(status),
-      requestId
+      hint: hintForHttpStatus(status, resourceNoun),
+      requestId,
+      data: parsed?.serverCode ? { serverCode: parsed.serverCode } : void 0
     });
     this.name = "ApiError";
     this.status = status;
@@ -73,9 +77,9 @@ function codeForHttpStatus(status) {
 function exitCodeForHttpStatus(status) {
   return exitCodeForErrorCode(codeForHttpStatus(status));
 }
-function messageForApiError(status, body) {
-  const parsed = parseApiErrorBody(body);
-  if (parsed) return parsed;
+function messageForApiError(status, body, parsed = parseApiErrorBody(body)) {
+  if (parsed?.message) return parsed.message;
+  if (parsed?.serverCode) return parsed.serverCode;
   return body ? `API error ${status}: ${body}` : `API error ${status}`;
 }
 function parseApiErrorBody(body) {
@@ -83,14 +87,36 @@ function parseApiErrorBody(body) {
     const parsed = JSON.parse(body);
     if (!parsed || typeof parsed !== "object") return null;
     const error = parsed.error;
-    return typeof error === "string" && error.length > 0 ? error : null;
+    if (typeof error === "string" && error.length > 0) {
+      const message2 = parsed.message;
+      const code = parsed.code;
+      return {
+        serverCode: typeof code === "string" && code ? code : error,
+        ...typeof message2 === "string" && message2 ? { message: message2 } : { message: error }
+      };
+    }
+    if (error && typeof error === "object") {
+      const code = error.code;
+      const message2 = error.message;
+      return {
+        ...typeof message2 === "string" && message2 ? { message: message2 } : {},
+        ...typeof code === "string" && code ? { serverCode: code } : {}
+      };
+    }
+    const message = parsed.message;
+    return typeof message === "string" && message.length > 0 ? { message } : null;
   } catch {
     return null;
   }
 }
-function hintForHttpStatus(status) {
+function hintForHttpStatus(status, resourceNoun) {
   if (status === 401 || status === 403) return "Run `arcanist auth login` or set `ARCANIST_TOKEN`.";
-  if (status === 404) return "List sessions with `arcanist sessions list`.";
+  if (status === 404) {
+    if (resourceNoun === "token") return "List tokens with `arcanist tokens list`.";
+    if (resourceNoun === "sandbox") return "Check sandbox state with `arcanist sandbox status`.";
+    if (resourceNoun === "repo") return "Check accessible repositories with `arcanist repos list`.";
+    return "List sessions with `arcanist sessions list`.";
+  }
   if (status === 409) return "Check the current resource state and retry the command when it is ready.";
   if (status >= 500) return "Retry later or check the control-plane logs.";
   return void 0;
@@ -106,7 +132,8 @@ function formatJsonError(err) {
       code: err.code,
       message: err.message,
       ...err.hint ? { hint: err.hint } : {},
-      ...err.requestId ? { requestId: err.requestId } : {}
+      ...err.requestId ? { requestId: err.requestId } : {},
+      ...err.data ? { data: err.data } : {}
     }
   });
 }
@@ -115,33 +142,72 @@ function formatJsonError(err) {
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
 var CLI_USER_AGENT = `arcanist-cli/${version}`;
-async function apiRequest(config, path, init) {
-  let res;
+var DEFAULT_HTTP_TIMEOUT_MS = 3e4;
+var MIN_HTTP_TIMEOUT_MS = 1e3;
+var MAX_HTTP_TIMEOUT_MS = 6e5;
+var HTTP_TIMEOUT_ENV = "ARCANIST_HTTP_TIMEOUT_MS";
+function parseHttpTimeoutMs(env = process.env) {
+  const raw = env[HTTP_TIMEOUT_ENV];
+  if (!raw) return DEFAULT_HTTP_TIMEOUT_MS;
+  if (!/^\d+$/.test(raw)) {
+    throw new CliError("user", `${HTTP_TIMEOUT_ENV} must be a positive integer between 1000 and 600000.`);
+  }
+  const value = Number(raw);
+  if (value < MIN_HTTP_TIMEOUT_MS || value > MAX_HTTP_TIMEOUT_MS) {
+    throw new CliError("user", `${HTTP_TIMEOUT_ENV} must be between 1000 and 600000 milliseconds.`);
+  }
+  return value;
+}
+function isAbortError(err) {
+  return err instanceof DOMException && err.name === "AbortError";
+}
+function timeoutError(timeoutMs) {
+  return new CliError("server", `Network timeout after ${timeoutMs}ms.`, {
+    hint: `Increase ${HTTP_TIMEOUT_ENV} for slow links, or check the API connection.`
+  });
+}
+async function apiRequest(config, path, init, read) {
+  const timeoutMs = parseHttpTimeoutMs();
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
   try {
     const headers = new Headers(init?.headers);
     headers.set("Content-Type", "application/json");
     headers.set("User-Agent", CLI_USER_AGENT);
     headers.set("Authorization", `Bearer ${config.token}`);
-    res = await fetch(`${normalizeBaseUrl(config.apiUrl)}${path}`, {
+    const res = await fetch(`${normalizeBaseUrl(config.apiUrl)}${path}`, {
       ...init,
-      headers
+      headers,
+      signal: controller.signal
     });
+    if (!res.ok) {
+      const body = await res.text().catch((err) => {
+        if (isAbortError(err)) throw timeoutError(timeoutMs);
+        return "";
+      });
+      throw new ApiError(res.status, body, res.headers.get("x-request-id") ?? void 0, resourceNounForPath(path));
+    }
+    return await read(res);
   } catch (err) {
+    if (err instanceof CliError) throw err;
+    if (isAbortError(err)) throw timeoutError(timeoutMs);
     throw new CliError("server", `Network error: ${stringifyError(err)}`);
+  } finally {
+    clearTimeout(timeout);
   }
-  if (!res.ok) {
-    const body = await res.text().catch(() => "");
-    throw new ApiError(res.status, body, res.headers.get("x-request-id") ?? void 0);
-  }
-  return res;
+}
+function resourceNounForPath(path) {
+  if (path.startsWith("/api/cli-tokens")) return "token";
+  if (path.startsWith("/api/repos")) return "repo";
+  if (path.startsWith("/api/sandbox")) return "sandbox";
+  if (path.startsWith("/api/sessions")) return "session";
+  return void 0;
 }
 async function apiFetch(config, path, init) {
-  const res = await apiRequest(config, path, init);
-  return res.json();
+  return apiRequest(config, path, init, (res) => res.json());
 }
 async function apiFetchText(config, path, init) {
-  const res = await apiRequest(config, path, init);
-  return res.text();
+  return apiRequest(config, path, init, (res) => res.text());
 }
 async function resolveBusinessId(config, options) {
   if (options.business && options.business.trim()) return options.business.trim();
@@ -1126,8 +1192,9 @@ function isTerminalPhase(phase, _sessionKind) {
 }
 
 // src/constants/watch.ts
-var MIN_WATCH_POLL_INTERVAL_MS = 1;
+var MIN_WATCH_POLL_INTERVAL_MS = 250;
 var DEFAULT_WATCH_POLL_INTERVAL_MS = 1e3;
+var MAX_WATCH_POLL_INTERVAL_MS = 6e4;
 var WATCH_REPLAY_PAGE_SIZE = 200;
 function isWatchTerminal(phase) {
   return isTerminalPhase(phase);
@@ -2702,7 +2769,14 @@ function parsePollInterval(raw) {
   if (!/^\d+$/.test(raw)) {
     throw new CliError("user", "Polling interval must be a non-negative integer.");
   }
-  return Number(raw);
+  const value = Number(raw);
+  if (value < MIN_WATCH_POLL_INTERVAL_MS || value > MAX_WATCH_POLL_INTERVAL_MS) {
+    throw new CliError(
+      "user",
+      `Polling interval must be between ${MIN_WATCH_POLL_INTERVAL_MS} and ${MAX_WATCH_POLL_INTERVAL_MS} milliseconds.`
+    );
+  }
+  return value;
 }
 function parseNonNegativeInteger(raw, name, defaultValue) {
   if (!raw) return defaultValue;
@@ -2762,7 +2836,6 @@ async function watchCommand(sessionId, options, command) {
   const runtime = getRuntimeOptions(command, options);
   const config = requireConfig(runtime);
   const pollIntervalMs = parsePollInterval(options.pollInterval);
-  const effectivePollIntervalMs = Math.max(pollIntervalMs, MIN_WATCH_POLL_INTERVAL_MS);
   const initialAfterSequence = parseNonNegativeInteger(options.afterSequence, "--after-sequence", 0);
   const pageSize = parseNonNegativeInteger(options.limit, "--limit", WATCH_REPLAY_PAGE_SIZE);
   if (pageSize === 0) {
@@ -2845,7 +2918,7 @@ async function watchCommand(sessionId, options, command) {
         }
         break;
       }
-      await sleep(effectivePollIntervalMs);
+      await sleep(pollIntervalMs);
     }
   } finally {
     if (textOpen) process.stdout.write("\n");
@@ -3020,7 +3093,12 @@ async function createCommand(repoUrl, promptArg, options, command) {
       {
         exitCode: err instanceof CliError ? err.exitCode : void 0,
         hint: `Retry with: arcanist sessions send ${sessionId} --prompt-stdin`,
-        requestId: err instanceof CliError ? err.requestId : void 0
+        requestId: err instanceof CliError ? err.requestId : void 0,
+        data: {
+          ...err instanceof CliError && err.data ? err.data : {},
+          sessionId,
+          ...sessionData.sessionUrl ? { sessionUrl: sessionData.sessionUrl } : {}
+        }
       }
     );
   }
@@ -3232,16 +3310,16 @@ async function loginCommand(options, command) {
     console.log(`Logged in. API: ${apiUrl}`);
   }
   try {
-    const res = await fetch(`${apiUrl}/api/cli-tokens`, {
-      headers: { Authorization: `Bearer ${token}`, "User-Agent": CLI_USER_AGENT }
-    });
-    if (res.ok && !runtime.json && !runtime.quiet) {
-      console.log("Token verified.");
-    } else if (res.status === 401 && !runtime.json && !runtime.quiet) {
-      console.warn("Warning: Token could not be verified (401). It may be invalid or expired.");
+    await apiFetch({ apiUrl, token }, "/api/cli-tokens");
+    if (!runtime.json && !runtime.quiet) console.log("Token verified.");
+  } catch (err) {
+    if (!runtime.json && !runtime.quiet) {
+      if (err instanceof ApiError && (err.status === 401 || err.status === 403)) {
+        console.warn("Warning: Token could not be verified (401). It may be invalid or expired.");
+      } else {
+        console.warn("Warning: Could not reach API to verify token.");
+      }
     }
-  } catch {
-    if (!runtime.json && !runtime.quiet) console.warn("Warning: Could not reach API to verify token.");
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryarcanist/cli",
-  "version": "0.1.167",
+  "version": "0.1.168",
   "description": "CLI for Arcanist — create and manage coding agent sessions",
   "type": "module",
   "bin": {