commandmate 0.49.2 → 0.50.0

package/dist/cli/utils/agent-roles.d.ts

@@ -0,0 +1,75 @@
+/**
+ * What `roles`, `instances` and `send` share about roles (Issue #4116): reading a
+ * role or repository the way a person names it, reading a body, and turning the
+ * role API's refusals into an exit code.
+ *
+ * ## Decisions
+ *
+ * - **A role is named by ID or name, and nothing is reserved.** "No role" and
+ *   "follow the defaults" are flags, so a role called `none` is just a role.
+ *   An exact match wins; failing that, a match ignoring case and Unicode form.
+ *   Two answers at the same step is an error listing them, never a pick.
+ * - **`--repo` is, in this order: an ID, a path, a name.** A value containing a `/`
+ *   or starting with `.` is a path; it may be a registered root, or a worktree of
+ *   one (which answers for its root). A bare word is never read as a path, so what
+ *   the current directory holds cannot change which repository a word means.
+ * - **Unknown, unregistered and ambiguous have their own codes**: `unknown_repository`,
+ *   `repository_not_registered` (a real directory with no row) and `ambiguous_repository`.
+ *   A root with no row for a tool is not an error: it reads `stored: inherit`.
+ *
+ * Type imports and {@link isAgentRoleCliTool} only from the shared types: the CLI
+ * does not load the server's role layer.
+ */
+import { type ApiClient } from './api-client';
+import { RoleCliError, roleFailureFromApi, usageError } from './role-failure';
+import { type AgentRoleCliTool, type AgentRoleSummary, type RoleAssignmentInput } from '../../types/agent-roles';
+export { RoleCliError, roleFailureFromApi, usageError };
+export { readRoleBodyOption } from './role-input';
+/**
+ * Run a request that changes a role setting (Issue #4116). The routes write, then build
+ * their answer, so a 500 or a lost answer can follow a write that stayed. Only a 4xx is
+ * known to have changed nothing; anything else says that is not known, how to look, and
+ * with `--json` the same as `saved: "unknown"` and `check`. The code and exit code stay
+ * what the failure itself has.
+ *
+ * @param check - The command that shows what the setting is now
+ * @throws A 4xx as its role failure, or as it came when it is none
+ */
+export declare function roleWrite<T>(check: string, write: () => Promise<T>): Promise<T>;
+/**
+ * End a role command on `error`: the sentence on stderr, and with `--json` the same
+ * thing as an object on stdout, whatever the failure was, so a caller parsing stdout
+ * gets an answer either way. A failure no route classified (a 500, no connection)
+ * keeps the sentence and exit code `handleCommandError` gives it.
+ */
+export declare function reportRoleFailure(error: unknown, json: boolean | undefined): void;
+/**
+ * The role `selector` names. The database keeps names unique ignoring ASCII case
+ * only, so Unicode forms and non-ASCII case can still answer twice, and a name can
+ * equal another role's ID.
+ */
+export declare function pickRole<T extends AgentRoleSummary>(roles: readonly T[], selector: string): T;
+export declare function resolveRole(client: ApiClient, selector: string): Promise<AgentRoleSummary>;
+/** The tool a role command names, or the failure for one outside the role feature. */
+export declare function assertRoleTool(tool: string): AgentRoleCliTool;
+/**
+ * `--role` and `--no-role` share one commander value, where the last one given wins.
+ * Asking for both is a contradiction, so the two are watched as they are parsed.
+ *
+ * @returns Whether both were given. Read after parsing.
+ */
+export declare function watchRoleFlagConflict(command: {
+    on(event: string, listener: () => void): unknown;
+}): () => boolean;
+/** `--role <role>` / `--no-role` as a setting, or undefined when neither was given. */
+export declare function roleAssignmentFromFlag(client: ApiClient, flag: string | false | undefined): Promise<RoleAssignmentInput | undefined>;
+export interface RegisteredRepository {
+    id: string;
+    name: string;
+    path: string;
+    enabled?: boolean;
+}
+export declare function listRepositories(client: ApiClient): Promise<RegisteredRepository[]>;
+/** The registered repository `--repo` names. See the module's decisions for the order. */
+export declare function resolveRepository(client: ApiClient, selector: string): Promise<RegisteredRepository>;
+//# sourceMappingURL=agent-roles.d.ts.map

package/dist/cli/utils/agent-roles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-roles.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/agent-roles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAEnF,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE9E,OAAO,EAGL,KAAK,gBAAgB,EAErB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACzB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAelD;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAkBrF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAiBjF;AAqBD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,gBAAgB,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,CAY7F;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAGhG;AAED,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAO7D;AAMD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE;IAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,OAAO,CAAA;CAAE,GAAG,MAAM,OAAO,CAUlH;AAED,uFAAuF;AACvF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,GAC/B,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC,CAK1C;AAMD,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAoBD,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAGzF;AAqBD,0FAA0F;AAC1F,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA8B1G"}

package/dist/cli/utils/agent-roles.js

@@ -0,0 +1,238 @@
+"use strict";
+/**
+ * What `roles`, `instances` and `send` share about roles (Issue #4116): reading a
+ * role or repository the way a person names it, reading a body, and turning the
+ * role API's refusals into an exit code.
+ *
+ * ## Decisions
+ *
+ * - **A role is named by ID or name, and nothing is reserved.** "No role" and
+ *   "follow the defaults" are flags, so a role called `none` is just a role.
+ *   An exact match wins; failing that, a match ignoring case and Unicode form.
+ *   Two answers at the same step is an error listing them, never a pick.
+ * - **`--repo` is, in this order: an ID, a path, a name.** A value containing a `/`
+ *   or starting with `.` is a path; it may be a registered root, or a worktree of
+ *   one (which answers for its root). A bare word is never read as a path, so what
+ *   the current directory holds cannot change which repository a word means.
+ * - **Unknown, unregistered and ambiguous have their own codes**: `unknown_repository`,
+ *   `repository_not_registered` (a real directory with no row) and `ambiguous_repository`.
+ *   A root with no row for a tool is not an error: it reads `stored: inherit`.
+ *
+ * Type imports and {@link isAgentRoleCliTool} only from the shared types: the CLI
+ * does not load the server's role layer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRoleBodyOption = exports.usageError = exports.roleFailureFromApi = exports.RoleCliError = void 0;
+exports.roleWrite = roleWrite;
+exports.reportRoleFailure = reportRoleFailure;
+exports.pickRole = pickRole;
+exports.resolveRole = resolveRole;
+exports.assertRoleTool = assertRoleTool;
+exports.watchRoleFlagConflict = watchRoleFlagConflict;
+exports.roleAssignmentFromFlag = roleAssignmentFromFlag;
+exports.listRepositories = listRepositories;
+exports.resolveRepository = resolveRepository;
+const types_1 = require("../types");
+const api_client_1 = require("./api-client");
+const command_helpers_1 = require("./command-helpers");
+const role_failure_1 = require("./role-failure");
+Object.defineProperty(exports, "RoleCliError", { enumerable: true, get: function () { return role_failure_1.RoleCliError; } });
+Object.defineProperty(exports, "roleFailureFromApi", { enumerable: true, get: function () { return role_failure_1.roleFailureFromApi; } });
+Object.defineProperty(exports, "usageError", { enumerable: true, get: function () { return role_failure_1.usageError; } });
+const role_input_1 = require("./role-input");
+const agent_roles_1 = require("../../types/agent-roles");
+var role_input_2 = require("./role-input");
+Object.defineProperty(exports, "readRoleBodyOption", { enumerable: true, get: function () { return role_input_2.readRoleBodyOption; } });
+/** The `--json` code of a failure no role route classified. Its exit code stays its own. */
+function unclassifiedFailureCode(error) {
+    if (!(error instanceof api_client_1.ApiError))
+        return 'unexpected_error';
+    const { payload } = error;
+    if (payload?.success === false && typeof payload.error === 'string')
+        return payload.error;
+    if (typeof payload?.code === 'string')
+        return payload.code;
+    return error.statusCode === undefined ? 'no_response' : 'request_failed';
+}
+function printJsonFailure(code, message, details = {}) {
+    console.log(JSON.stringify({ success: false, error: code, message, ...details }, null, 2));
+}
+/**
+ * Run a request that changes a role setting (Issue #4116). The routes write, then build
+ * their answer, so a 500 or a lost answer can follow a write that stayed. Only a 4xx is
+ * known to have changed nothing; anything else says that is not known, how to look, and
+ * with `--json` the same as `saved: "unknown"` and `check`. The code and exit code stay
+ * what the failure itself has.
+ *
+ * @param check - The command that shows what the setting is now
+ * @throws A 4xx as its role failure, or as it came when it is none
+ */
+async function roleWrite(check, write) {
+    try {
+        return await write();
+    }
+    catch (error) {
+        (0, api_client_1.rethrowIfDeadlineExceeded)(error);
+        if (error instanceof api_client_1.ApiError && error.statusCode !== undefined && error.statusCode < 500) {
+            throw (0, role_failure_1.roleFailureFromApi)(error) ?? error;
+        }
+        const known = error instanceof api_client_1.ApiError ? error : undefined;
+        throw new role_failure_1.RoleCliError(unclassifiedFailureCode(error), `${error instanceof Error ? error.message : String(error)} Whether the change was saved is not known. Check it with: ${check}`, known?.exitCode ?? types_1.ExitCode.UNEXPECTED_ERROR, { saved: 'unknown', check }, known?.statusCode, known?.payload);
+    }
+}
+/**
+ * End a role command on `error`: the sentence on stderr, and with `--json` the same
+ * thing as an object on stdout, whatever the failure was, so a caller parsing stdout
+ * gets an answer either way. A failure no route classified (a 500, no connection)
+ * keeps the sentence and exit code `handleCommandError` gives it.
+ */
+function reportRoleFailure(error, json) {
+    const failure = error instanceof role_failure_1.RoleCliError ? error : (0, role_failure_1.roleFailureFromApi)(error);
+    if (failure) {
+        if (json)
+            printJsonFailure(failure.code, failure.message, failure.details);
+        console.error(`Error: ${failure.message}`);
+        process.exit(failure.exitCode);
+        return;
+    }
+    if (error instanceof api_client_1.ApiError && error.statusCode === 404 && !error.payload) {
+        const message = 'the server has no such route. It may be older than this CLI: commandmate stop && commandmate start';
+        if (json)
+            printJsonFailure('role_api_unavailable', message);
+        console.error(`Error: ${message}`);
+        process.exit(types_1.ExitCode.UNEXPECTED_ERROR);
+        return;
+    }
+    if (json)
+        printJsonFailure(unclassifiedFailureCode(error), error instanceof Error ? error.message : String(error));
+    (0, command_helpers_1.handleCommandError)(error);
+}
+/** The role's ID and name, the way a candidate is listed. */
+function describeRole(role) {
+    return `${role.id}  ${role.name}`;
+}
+function foldName(value) {
+    return value.trim().normalize('NFC').toLowerCase();
+}
+function ambiguousRole(selector, matches) {
+    return new role_failure_1.RoleCliError('ambiguous_role', `'${selector}' could mean ${matches.length} roles. Name one by its ID (an ID that is also another role's name: rename that role):\n`
+        + matches.map((role) => `  - ${describeRole(role)}`).join('\n'), types_1.ExitCode.CONFIG_ERROR, { candidates: matches.map(({ id, name }) => ({ id, name })) });
+}
+/**
+ * The role `selector` names. The database keeps names unique ignoring ASCII case
+ * only, so Unicode forms and non-ASCII case can still answer twice, and a name can
+ * equal another role's ID.
+ */
+function pickRole(roles, selector) {
+    const exact = roles.filter((role) => role.id === selector || role.name === selector);
+    if (exact.length === 1)
+        return exact[0];
+    if (exact.length > 1)
+        throw ambiguousRole(selector, exact);
+    const folded = roles.filter((role) => foldName(role.name) === foldName(selector));
+    if (folded.length === 1)
+        return folded[0];
+    if (folded.length > 1)
+        throw ambiguousRole(selector, folded);
+    throw new role_failure_1.RoleCliError('unknown_role', `No role is called '${selector}'. List them with: commandmate roles list`, types_1.ExitCode.CONFIG_ERROR);
+}
+async function resolveRole(client, selector) {
+    const { roles } = await client.get('/api/roles');
+    return pickRole(roles, selector);
+}
+/** The tool a role command names, or the failure for one outside the role feature. */
+function assertRoleTool(tool) {
+    if ((0, agent_roles_1.isAgentRoleCliTool)(tool))
+        return tool;
+    throw new role_failure_1.RoleCliError('tool_not_supported', `Roles do not apply to '${tool}'. They apply to: ${agent_roles_1.AGENT_ROLE_CLI_TOOLS.join(', ')}`, types_1.ExitCode.CONFIG_ERROR);
+}
+// ---------------------------------------------------------------------------
+// Flags
+// ---------------------------------------------------------------------------
+/**
+ * `--role` and `--no-role` share one commander value, where the last one given wins.
+ * Asking for both is a contradiction, so the two are watched as they are parsed.
+ *
+ * @returns Whether both were given. Read after parsing.
+ */
+function watchRoleFlagConflict(command) {
+    let role = false;
+    let noRole = false;
+    command.on('option:role', () => {
+        role = true;
+    });
+    command.on('option:no-role', () => {
+        noRole = true;
+    });
+    return () => role && noRole;
+}
+/** `--role <role>` / `--no-role` as a setting, or undefined when neither was given. */
+async function roleAssignmentFromFlag(client, flag) {
+    if (flag === undefined)
+        return undefined;
+    if (flag === false)
+        return { state: 'none' };
+    const role = await resolveRole(client, flag);
+    return { state: 'role', roleId: role.id };
+}
+function isPathShaped(selector) {
+    return selector.includes('/') || selector.startsWith('.');
+}
+function describeRepository(repository) {
+    return `${repository.id}  ${repository.name}  ${repository.path}`;
+}
+function ambiguousRepository(selector, matches) {
+    return new role_failure_1.RoleCliError('ambiguous_repository', `'${selector}' could mean ${matches.length} repositories. Name one by its ID:\n`
+        + matches.map((repository) => `  - ${describeRepository(repository)}`).join('\n'), types_1.ExitCode.CONFIG_ERROR, { candidates: matches.map(({ id, name, path: repositoryPath }) => ({ id, name, path: repositoryPath })) });
+}
+async function listRepositories(client) {
+    const { repositories } = await client.get('/api/repositories');
+    return repositories;
+}
+/**
+ * The root a path-shaped `--repo` names: a registered root, or the root of the
+ * registered worktree at that path, which is what "this repository" is from inside one.
+ */
+async function repositoryAtPath(client, repositories, selector) {
+    const wanted = (0, role_input_1.canonicalPath)(selector);
+    const roots = repositories.filter((repository) => (0, role_input_1.canonicalPath)(repository.path) === wanted);
+    if (roots.length > 0)
+        return roots;
+    const { worktrees } = await client.get('/api/worktrees');
+    const worktree = (worktrees ?? []).find((row) => typeof row.path === 'string' && (0, role_input_1.canonicalPath)(row.path) === wanted);
+    if (typeof worktree?.repositoryPath !== 'string')
+        return [];
+    const root = (0, role_input_1.canonicalPath)(worktree.repositoryPath);
+    return repositories.filter((repository) => (0, role_input_1.canonicalPath)(repository.path) === root);
+}
+/** The registered repository `--repo` names. See the module's decisions for the order. */
+async function resolveRepository(client, selector) {
+    const repositories = await listRepositories(client);
+    const byId = repositories.filter((repository) => repository.id === selector);
+    if (byId.length === 1)
+        return byId[0];
+    if (isPathShaped(selector)) {
+        const matches = await repositoryAtPath(client, repositories, selector);
+        if (matches.length === 1)
+            return matches[0];
+        if (matches.length > 1)
+            throw ambiguousRepository(selector, matches);
+        if ((0, role_input_1.isDirectory)(selector)) {
+            throw new role_failure_1.RoleCliError('repository_not_registered', `${selector} is a directory, but neither a registered repository nor a worktree of one. `
+                + 'See what is registered with: commandmate roles defaults', types_1.ExitCode.CONFIG_ERROR);
+        }
+    }
+    else {
+        const exact = repositories.filter((repository) => repository.name === selector);
+        if (exact.length === 1)
+            return exact[0];
+        if (exact.length > 1)
+            throw ambiguousRepository(selector, exact);
+        const folded = repositories.filter((repository) => foldName(repository.name) === foldName(selector));
+        if (folded.length === 1)
+            return folded[0];
+        if (folded.length > 1)
+            throw ambiguousRepository(selector, folded);
+    }
+    throw new role_failure_1.RoleCliError('unknown_repository', `No repository matches '${selector}'. See what is registered with: commandmate roles defaults`, types_1.ExitCode.CONFIG_ERROR);
+}

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

@@ -0,0 +1,28 @@
+/**
+ * The command-deadline error and its predicates (split out of api-client.ts, Issue #4058).
+ * api-client.ts re-exports every exported name here; import from there.
+ */
+import { ApiError } from './api-client-errors';
+/**
+ * A request ended by the deadline of a client from {@link ApiClient.withDeadline}
+ * (Issue #3983).
+ *
+ * An `ApiError` with exit 124 so that the commands' own error handling reports
+ * it as the timeout it is, and a class of its own so that a catch which turns
+ * failures into a degraded result ("verification resolves its own task", "use
+ * the selector as an instance id") can tell it apart and rethrow it — see
+ * {@link isDeadlineExceeded}. Wrapped into another `ApiError`, it travels as
+ * that error's `transportError`.
+ */
+export declare class DeadlineExceededError extends ApiError {
+    constructor(serverUrl?: string);
+}
+/**
+ * Whether `error` is — or wraps — a request ended by a command deadline
+ * (Issue #3983). The catches that degrade on failure ask this first and
+ * rethrow: a deadline is the command's answer, not a reason to carry on.
+ */
+export declare function isDeadlineExceeded(error: unknown): error is ApiError;
+/** Rethrow `error` when it is a command deadline; otherwise return (Issue #3983). */
+export declare function rethrowIfDeadlineExceeded(error: unknown): void;
+//# sourceMappingURL=api-client-deadline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api-client-deadline.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/api-client-deadline.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,QAAQ,EAAiB,MAAM,qBAAqB,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,qBAAa,qBAAsB,SAAQ,QAAQ;gBACrC,SAAS,CAAC,EAAE,MAAM;CAO/B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAIpE;AAED,qFAAqF;AACrF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE9D"}

package/dist/cli/utils/api-client-deadline.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * The command-deadline error and its predicates (split out of api-client.ts, Issue #4058).
+ * api-client.ts re-exports every exported name here; import from there.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeadlineExceededError = void 0;
+exports.isDeadlineExceeded = isDeadlineExceeded;
+exports.rethrowIfDeadlineExceeded = rethrowIfDeadlineExceeded;
+const types_1 = require("../types");
+const api_client_errors_1 = require("./api-client-errors");
+/**
+ * A request ended by the deadline of a client from {@link ApiClient.withDeadline}
+ * (Issue #3983).
+ *
+ * An `ApiError` with exit 124 so that the commands' own error handling reports
+ * it as the timeout it is, and a class of its own so that a catch which turns
+ * failures into a degraded result ("verification resolves its own task", "use
+ * the selector as an instance id") can tell it apart and rethrow it — see
+ * {@link isDeadlineExceeded}. Wrapped into another `ApiError`, it travels as
+ * that error's `transportError`.
+ */
+class DeadlineExceededError extends api_client_errors_1.ApiError {
+    constructor(serverUrl) {
+        super((0, api_client_errors_1.withServerUrl)('--timeout reached before the server answered', { serverUrl }), types_1.WaitExitCode.TIMEOUT);
+        this.name = 'DeadlineExceededError';
+    }
+}
+exports.DeadlineExceededError = DeadlineExceededError;
+/**
+ * Whether `error` is — or wraps — a request ended by a command deadline
+ * (Issue #3983). The catches that degrade on failure ask this first and
+ * rethrow: a deadline is the command's answer, not a reason to carry on.
+ */
+function isDeadlineExceeded(error) {
+    if (error instanceof DeadlineExceededError)
+        return true;
+    if (error instanceof api_client_errors_1.ApiError && error.transportError instanceof DeadlineExceededError)
+        return true;
+    return error instanceof Error && error.cause instanceof DeadlineExceededError;
+}
+/** Rethrow `error` when it is a command deadline; otherwise return (Issue #3983). */
+function rethrowIfDeadlineExceeded(error) {
+    if (isDeadlineExceeded(error))
+        throw error;
+}

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

@@ -0,0 +1,140 @@
+/**
+ * Error classification for the CLI API client (split out of api-client.ts, Issue #4058).
+ * api-client.ts re-exports every exported name here; import from there.
+ */
+/**
+ * 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;
+}
+/** Append `(server: <url>)` when the caller named one. */
+export declare function withServerUrl(message: string, context?: ApiErrorContext): 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;
+/**
+ * The `code` of the 409 for a roster that moved since it was read (Issue #4132).
+ * Spelled out for the reason {@link FOREIGN_SESSION_ERROR_CODE} is: it comes from a route.
+ */
+export declare const ROSTER_CHANGED_ERROR_CODE = "ROSTER_CHANGED";
+/**
+ * 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. Issue #4149: the roster 409 is told apart by its code too.
+ * @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;
+/**
+ * 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. Issue #4011: also
+     * on a failure of a send with no bound relay that was recorded as its
+     * attempt (`not-sent` → `not_sent`, otherwise `unknown`; no 400). Mirrors
+     * src/lib/relay/relay-bind.ts RelaySendOutcome (and ChatMessage.sendOutcome).
+     */
+    sendOutcome?: 'sent' | 'not_sent' | 'unknown';
+    /**
+     * Issue #4116: the role routes answer `{ success: false, error: <code>, message }`,
+     * so there `error` is the stable code and `message` the sentence.
+     */
+    success?: boolean;
+    message?: string;
+    /** `role_in_use`: what points at the role. */
+    references?: unknown;
+    /** `version_conflict`: the version the role is at now. */
+    currentBodyVersion?: number;
+    /** Issue #4115: a send refused because of its role says whether the setting stayed saved. */
+    roleSettings?: {
+        saved?: boolean;
+        stored?: unknown;
+    };
+    /** Issue #4115: why a launch was refused because of its role. */
+    roleRefusal?: string;
+}
+/**
+ * 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;
+}
+//# sourceMappingURL=api-client-errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api-client-errors.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/api-client-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AA0BD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAEhF;AAED;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,kCAAkC,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAYvE;AAED;;;GAGG;AACH,eAAO,MAAM,yBAAyB,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,OAAO,EACd,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,eAAe,GACxB,cAAc,CAgHhB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACxD,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAC;IAC9C;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,0DAA0D;IAC1D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,6FAA6F;IAC7F,YAAY,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACrD,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,QAAS,SAAQ,KAAK;aAGf,QAAQ,EAAE,MAAM;aAChB,UAAU,CAAC,EAAE,MAAM;IACnC,gEAAgE;aAChD,OAAO,CAAC,EAAE,eAAe;IACzC;;;;OAIG;aACa,cAAc,CAAC,EAAE,OAAO;gBAVxC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,YAAA;IACnC,gEAAgE;IAChD,OAAO,CAAC,EAAE,eAAe,YAAA;IACzC;;;;OAIG;IACa,cAAc,CAAC,EAAE,OAAO,YAAA;IAM1C,uEAAuE;IACvE,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;CACF"}