commandmate 0.49.1 → 0.49.3

package/dist/cli/utils/api-client.d.ts

@@ -7,6 +7,9 @@
  * - handleApiError(): Error classification and user-friendly messages
  * - ApiClient: HTTP get/post with base URL and auth headers
  */
+export { ApiError, FOREIGN_SESSION_ERROR_CODE, foreignSessionMessage, handleApiError, } from './api-client-errors';
+export type { ApiErrorContext, ApiErrorPayload, ApiErrorResult } from './api-client-errors';
+export { DeadlineExceededError, isDeadlineExceeded, rethrowIfDeadlineExceeded, } from './api-client-deadline';
 /** Maximum stop-pattern length [SEC4-06] */
 export declare const MAX_STOP_PATTERN_LENGTH = 500;
 /**
@@ -31,59 +34,6 @@ export declare function isValidInstanceId(id: string): boolean;
 export declare function resolveAuthToken(options?: {
     token?: string;
 }): string | undefined;
-/**
- * Error result from API operations
- */
-export interface ApiErrorResult {
-    message: string;
-    exitCode: number;
-}
-/**
- * What this function knows about the request, beyond its status (Issue #2404).
- *
- * `handleApiError` is a pure classifier over `(status, payload)` and has no way
- * to know which server answered — which is exactly the fact a 404 needs. The
- * caller's `Resource not found. Check the worktree ID.` sent an agent looking
- * for a typo in an id that was correct: the CLI was dialling a *different*
- * CommandMate server than the one that had started its session, and the id it
- * was asking about lived on the other one. Optional so the two callers that
- * classify without a client ({@link ApiClient} aside, `server-capabilities.ts`)
- * keep compiling and keep their wording.
- */
-export interface ApiErrorContext {
-    /** The base URL the failing request was actually sent to. */
-    serverUrl?: string;
-}
-/**
- * The `code` the server sends with the 409 for a tmux session another
- * CommandMate server created (Issue #2865). Spelled out rather than imported:
- * the server's constant lives next to the tmux gateway, which the CLI must not
- * load. `tests/unit/cli/utils/api-client-foreign-session-3334.test.ts` pins the
- * two to the same string.
- */
-export declare const FOREIGN_SESSION_ERROR_CODE = "session_owned_by_other_server";
-/**
- * Issue #3334: what the operator reads for that 409. It has to say three
- * things the status alone does not: the session is another CommandMate
- * server's, this command therefore did nothing to it, and where to go instead.
- */
-export declare function foreignSessionMessage(payload?: ApiErrorPayload): string;
-/**
- * Classify API errors into user-friendly messages and exit codes.
- * [IA3-09] Covers: ECONNREFUSED, 400, 401/403, 404, 429, 500, timeout
- *
- * @param error - Error object or unknown
- * @param status - HTTP status code if available
- * @param payload - Parsed error body, when the response carried one (Issue #1637).
- *   Used for 5xx, and for the foreign-session 409 (Issue #3334): the other 4xx
- *   messages below are already specific, and are pinned by tests as the CLI's
- *   own wording.
- * @param context - Which server answered, when the caller knows (Issue #2404).
- *   Read by the 404 branch only; the other messages do not send anyone looking
- *   in the wrong place.
- * @returns User-friendly error message and exit code
- */
-export declare function handleApiError(error: unknown, status?: number, payload?: ApiErrorPayload, context?: ApiErrorContext): ApiErrorResult;
 /**
  * API Client for CLI HTTP communication.
  * Uses Node.js built-in fetch. Handles auth headers and error mapping.
@@ -91,6 +41,8 @@ export declare function handleApiError(error: unknown, status?: number, payload?
 export declare class ApiClient {
     private baseUrl;
     private token?;
+    /** Epoch ms after which every request of this client fails (Issue #3983). */
+    private deadlineAt?;
     constructor(options?: {
         baseUrl?: string;
         token?: string;
@@ -107,6 +59,34 @@ export declare class ApiClient {
      * command talk to" only helps if it is the one the request went to.
      */
     get serverUrl(): string;
+    /**
+     * This client with every request bounded by `deadlineAt` (Issue #3983).
+     *
+     * `wait` / `ask` / `verify` take `--timeout` as the deadline of the whole
+     * command, but only the poll's own reads were bounded by it: a task-ledger
+     * read, an `--instance` resolution or a capability probe before the poll had
+     * no deadline at all, so a server that stopped answering held the command for
+     * as long as undici's own timeouts (minutes) and then, swallowed into a
+     * degraded path, kept it going. The derived client carries one deadline for
+     * every method (`get` / `post` / `patch` / `rawGet`), and a request it ends
+     * fails with {@link DeadlineExceededError} — exit 124 — which the
+     * degrade-on-failure catches rethrow ({@link isDeadlineExceeded}).
+     *
+     * One request lasts until its body has been read (`json()` / `text()`), the
+     * body of a {@link rawGet} response included: a server that sends headers and
+     * then stalls the body is not an answer.
+     *
+     * @param deadlineAt - Epoch ms; undefined returns this client unchanged
+     * @returns A client sharing this one's server and token
+     */
+    withDeadline(deadlineAt: number | undefined): ApiClient;
+    /** The deadline this client carries, if any (Issue #3983). */
+    get deadline(): number | undefined;
+    /**
+     * The bound of one request: a signal that fires at the deadline (combined
+     * with the caller's own, when it gave one), or null without a deadline.
+     */
+    private startDeadline;
     private getHeaders;
     /**
      * GET without any status handling, for callers that must read the raw response.
@@ -150,62 +130,6 @@ export declare class ApiClient {
      */
     patch<T>(path: string, body?: unknown): Promise<T>;
 }
-/**
- * Machine-readable part of a failed API response (Issue #1237).
- * Every Skill route answers `{ error, code }`; the uninstall routes add `blockers`.
- */
-export interface ApiErrorPayload {
-    code?: string;
-    error?: string;
-    blockers?: Array<{
-        code: string;
-        path: string | null;
-    }>;
-    /** Issue #1544: run already in flight, sent with the verify route's 409. */
-    runningRunId?: number;
-    /**
-     * Issue #1545: every task-contract violation, sent with the tasks route's 400.
-     * Printed in full so a broken contract is fixed in one pass, not one round
-     * trip per mistake.
-     */
-    issues?: string[];
-    /** Issue #2865: sent with the foreign-session 409 (`session_owned_by_other_server`). */
-    sessionName?: string;
-    sessionPath?: string | null;
-    /**
-     * Issue #3957/#3992: sent with the send route's errors after a bound relay
-     * was reserved — `not_sent`: nothing reached the session, it may be sent
-     * again; `unknown`: it may have, look before resending. Mirrors
-     * src/lib/relay/relay-bind.ts RelaySendOutcome (and ChatMessage.sendOutcome).
-     */
-    sendOutcome?: 'sent' | 'not_sent' | 'unknown';
-}
-/**
- * API Error with exit code for CLI process.exit()
- */
-export declare class ApiError extends Error {
-    readonly exitCode: number;
-    readonly statusCode?: number | undefined;
-    /** Typed error body, when the server sent one (Issue #1237). */
-    readonly payload?: ApiErrorPayload | undefined;
-    /**
-     * The error `fetch` threw, when no HTTP response came back (Issue #3756):
-     * the strict `respond` tells "never connected" (nothing can have been sent)
-     * from "the connection broke" by its `cause.code`.
-     */
-    readonly transportError?: unknown | undefined;
-    constructor(message: string, exitCode: number, statusCode?: number | undefined, 
-    /** Typed error body, when the server sent one (Issue #1237). */
-    payload?: ApiErrorPayload | undefined, 
-    /**
-     * The error `fetch` threw, when no HTTP response came back (Issue #3756):
-     * the strict `respond` tells "never connected" (nothing can have been sent)
-     * from "the connection broke" by its `cause.code`.
-     */
-    transportError?: unknown | undefined);
-    /** Stable machine code the server assigned to this failure, if any. */
-    get apiCode(): string | undefined;
-}
 /**
  * Assert that a parsed API response contains the given required top-level fields
  * (Issue #1357).

package/dist/cli/utils/api-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/api-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/api-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,OAAO,EACL,QAAQ,EACR,0BAA0B,EAC1B,qBAAqB,EACrB,cAAc,GACf,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC5F,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAE/B,4CAA4C;AAC5C,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAK3C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAaD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,GAAG,SAAS,CASjF;AAeD;;;GAGG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,KAAK,CAAC,CAAS;IACvB,6EAA6E;IAC7E,OAAO,CAAC,UAAU,CAAC,CAAS;gBAEhB,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IA2B1D;;;;;;;;;;OAUG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAYvD,8DAA8D;IAC9D,IAAI,QAAQ,IAAI,MAAM,GAAG,SAAS,CAEjC;IAED;;;OAGG;IACH,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,UAAU;IAUlB;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;IAwB1F;;;;;;;;OAQG;IACG,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC;IAiCvE;;;OAGG;IACG,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIvD;;;;OAIG;IACG,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;CAGzD;AA4LD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,EACvC,OAAO,EAAE,MAAM,GACd,CAAC,CAiBH;AAOD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CASvF;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CASxE"}