import type { HumanHandoffAction } from "@agentxm/registry-protocol/unstable/human-handoff"; import * as Schema from "effect/Schema"; import type { SuggestedAction } from "@agentxm/registry-protocol/unstable/suggested-action"; /** * Named exit codes for the CLI. `Success` is the only exit code without an * `AppErrorCode` counterpart; the rest map 1:1 with `AppErrorCode` via * `exitCodeFor`. * * Reserved ranges: * - `0` — success * - `1`–`16` — AXM application errors (this enum) * - `17`–`127` — reserved for future AXM application errors; do not reuse * - `128`+ — POSIX signal convention (e.g., 130 SIGINT, 143 SIGTERM); set * by the runtime's signal handlers, not by `AppError` * * The numeric values diverge from `sysexits.h` deliberately: AXM uses a * flat 1–N scheme so the `code` field in JSON output stays the agent-facing * discriminator rather than the number. * * The descriptions here are the canonical wording. Other surfaces — the * help topic at `apps/cli/help/topics/exit-codes.md`, docs, error * envelopes — should match. A consistency test pins the help topic to * these strings; see `app-error.test.ts`. */ export declare const ExitCode: { /** Success. Also used for help output and cancelled prompts. */ readonly Success: 0; /** Command ran successfully but reported problems requiring attention (e.g., `axm lint` findings, doctor-style checks). Not lint-only — any "ran but found problems" outcome belongs here. Pairs with `AppErrorCode` `issues`. */ readonly Issues: 1; /** Invalid command, flags, or arguments. Fix the invocation. Pairs with `AppErrorCode` `usage`. */ readonly Usage: 2; /** Resource doesn't exist or isn't visible. Pairs with `AppErrorCode` `not_found`. */ readonly NotFound: 3; /** Credentials were rejected, are invalid, or expired. Sign in again. Pairs with `AppErrorCode` `auth`. */ readonly Auth: 4; /** Signed in, but not authorized for this action. Pairs with `AppErrorCode` `forbidden`. */ readonly Forbidden: 5; /** Conflicts with current state (already exists, version mismatch, concurrent update). Reconcile and retry. Pairs with `AppErrorCode` `conflict`. */ readonly Conflict: 6; /** Rate limited. Retry after a backoff. Pairs with `AppErrorCode` `rate_limit`. */ readonly RateLimit: 7; /** Couldn't reach the remote service (DNS, TCP, TLS, timeout). Usually retryable. Pairs with `AppErrorCode` `network`. */ readonly Network: 8; /** Input parsed but failed validation. Correct it and retry. Pairs with `AppErrorCode` `validation`. */ readonly Validation: 9; /** Unexpected internal error. Likely a bug — please report it. Pairs with `AppErrorCode` `internal`. */ readonly Internal: 10; /** Service is responsive but temporarily unable to serve. Pairs with `AppErrorCode` `unavailable`. */ readonly Unavailable: 11; /** Quota, storage, or plan limit exhausted. Pairs with `AppErrorCode` `quota`. */ readonly Quota: 12; /** Authentication or authorization is waiting on a person to complete a required action. Pairs with `AppErrorCode` `auth_required`. */ readonly AuthRequired: 13; /** A pending authentication flow expired. Pairs with `AppErrorCode` `auth_expired`. */ readonly AuthExpired: 14; /** A person denied or cancelled a pending authentication flow. Pairs with `AppErrorCode` `auth_denied`. */ readonly AuthDenied: 15; /** A bounded operation did not complete before its caller-selected deadline. Pairs with `AppErrorCode` `timeout`. */ readonly Timeout: 16; }; export type ExitCode = (typeof ExitCode)[keyof typeof ExitCode]; /** Canonical public meaning of every AXM process exit code. */ export declare const ExitCodeDefinitions: readonly [{ readonly code: 0; readonly meaning: "Success. Also used for help output and cancelled prompts."; }, { readonly code: 1; readonly meaning: "Command ran successfully but reported problems requiring attention (e.g., `axm lint` findings, doctor-style checks). Not lint-only — any \"ran but found problems\" outcome belongs here."; }, { readonly code: 2; readonly meaning: "Invalid invocation, confirmable approval required in non-interactive mode, or a named policy override is required. Fix the invocation or use the reported recovery action."; }, { readonly code: 3; readonly meaning: "Resource doesn't exist or isn't visible."; }, { readonly code: 4; readonly meaning: "Credentials were rejected, are invalid, or expired. Sign in again."; }, { readonly code: 5; readonly meaning: "Signed in, but not authorized for this action."; }, { readonly code: 6; readonly meaning: "Conflicts with current state, including a stale execution candidate (already exists, version mismatch, concurrent update). Reconcile and retry."; }, { readonly code: 7; readonly meaning: "Rate limited. Retry after a backoff."; }, { readonly code: 8; readonly meaning: "Couldn't reach the remote service (DNS, TCP, TLS, timeout). Usually retryable."; }, { readonly code: 9; readonly meaning: "Input parsed but failed validation. Correct it and retry."; }, { readonly code: 10; readonly meaning: "Unexpected internal error. Likely a bug — please report it."; }, { readonly code: 11; readonly meaning: "Service is responsive but temporarily unable to serve."; }, { readonly code: 12; readonly meaning: "Quota, storage, or plan limit exhausted."; }, { readonly code: 13; readonly meaning: "Authentication or authorization is waiting on a person to complete a required action."; }, { readonly code: 14; readonly meaning: "A pending authentication flow expired."; }, { readonly code: 15; readonly meaning: "A person denied or cancelled a pending authentication flow."; }, { readonly code: 16; readonly meaning: "A bounded operation did not complete before its caller-selected deadline."; }, { readonly code: 130; readonly meaning: "Interrupted by SIGINT. Local candidate-wide transactions roll back before AXM exits."; }]; /** `ExitCode` names that carry an `AppErrorCode`. Every exit code except `Success`. */ type ErrorExitName = Exclude; /** * Single source for the snake-case `AppErrorCode` strings (the values emitted * in `--json` output). Keys are `ExitCode` names. * * `satisfies Record` enforces 1:1 with `ExitCode` minus * `Success` — adding an `ExitCode` without an entry here (or removing one) * won't compile. */ declare const AppErrorCodeByExitName: { readonly Issues: "issues"; readonly Usage: "usage"; readonly NotFound: "not_found"; readonly Auth: "auth"; readonly Forbidden: "forbidden"; readonly Conflict: "conflict"; readonly RateLimit: "rate_limit"; readonly Network: "network"; readonly Validation: "validation"; readonly Internal: "internal"; readonly Unavailable: "unavailable"; readonly Quota: "quota"; readonly AuthRequired: "auth_required"; readonly AuthExpired: "auth_expired"; readonly AuthDenied: "auth_denied"; readonly Timeout: "timeout"; }; export type AppErrorCode = (typeof AppErrorCodeByExitName)[ErrorExitName]; export type AppErrorClass = "internal" | "user" | "external"; /** * Tuple of every `AppErrorCode`. Listed via member reads so the tuple type is * preserved for `Schema.Literals` without a cast. */ export declare const AppErrorCodes: readonly ["issues", "usage", "not_found", "auth", "forbidden", "conflict", "rate_limit", "network", "validation", "internal", "unavailable", "quota", "auth_required", "auth_expired", "auth_denied", "timeout"]; export declare const AppErrorCodeSchema: Schema.Literals; export declare const exitCodeFor: (code: AppErrorCode) => ExitCode; export type AppErrorMetadata = { readonly request?: { readonly service: string; readonly method?: string; readonly url: string; }; readonly response?: { readonly status: number; readonly requestId?: string; readonly problemCode?: string; readonly body?: unknown; }; readonly requestPolicy?: { readonly retryable: boolean; readonly attemptCount: number; readonly maxAttempts: number; readonly exhausted: boolean; readonly stoppedBy?: "attempt-limit" | "deadline" | "replay-unsafe"; readonly replaySafety: "safe" | "mutation" | "idempotency-keyed"; }; }; export type AppErrorAction = HumanHandoffAction | { readonly kind: "open-url"; readonly url: string; readonly fallbackUrl?: string; readonly code?: string; readonly expiresAt?: string; readonly resume?: string; }; export declare const WorkspaceLockfileVersionUnsupportedProblemSchema: Schema.Struct<{ readonly code: Schema.Literal<"workspace-lockfile-version-unsupported">; readonly path: Schema.String; readonly observedVersion: Schema.Int; readonly supportedVersion: Schema.Int; readonly direction: Schema.Literals; }>; export declare const AppErrorProblemSchema: Schema.Union; readonly path: Schema.String; readonly observedVersion: Schema.Int; readonly supportedVersion: Schema.Int; readonly direction: Schema.Literals; }>]>; export type AppErrorProblem = typeof AppErrorProblemSchema.Type; /** * One input a failure is about, such as the name a validation rejected. Human * output lists inputs as fields under the reason. They restate what the * detail already names, so the machine envelope does not carry them. */ export interface AppErrorInput { readonly label: string; readonly value: string; } /** CLI-only suggestion metadata is removed before public rendering or serialization. */ export type AppErrorSuggestedAction = SuggestedAction & { readonly commandScope?: "workspace" | "global"; }; export declare const defaultTitleFor: (code: AppErrorCode) => string; export declare const defaultDetailFor: (code: AppErrorCode) => string; /** Baseline suggested next actions for an error category. */ export declare const defaultSuggestionsFor: (code: AppErrorCode) => ReadonlyArray; export declare const errorClassForAppErrorCode: (code: AppErrorCode) => AppErrorClass; /** * Resolve the suggestions to surface for an error: the caller's own * suggestions when present, otherwise the baseline set for the error code. * Used by both human (`renderAppError`) and JSON (`makeJsonErrorEnvelope`) * output so the two surfaces stay consistent. */ export declare const effectiveSuggestionsFor: (error: AppError) => ReadonlyArray; declare const AppError_base: new = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & { readonly _tag: "AppError"; } & Readonly; export declare class AppError extends AppError_base<{ readonly code: AppErrorCode; readonly title: string; readonly detail: string; readonly metadata?: AppErrorMetadata; readonly status?: "pending-human"; readonly retryable?: boolean; readonly blockedOn?: "human"; readonly action?: AppErrorAction; readonly problem?: AppErrorProblem; readonly inputs?: ReadonlyArray; readonly suggestions?: ReadonlyArray; readonly cause: unknown; }> { } export declare const makeAppError: (args: { readonly code: AppErrorCode; readonly title?: string; readonly detail?: string; readonly metadata?: AppErrorMetadata; readonly status?: "pending-human"; readonly retryable?: boolean; readonly blockedOn?: "human"; readonly action?: AppErrorAction; readonly problem?: AppErrorProblem; readonly inputs?: ReadonlyArray; readonly recover?: string; readonly cmd?: string; readonly suggestions?: ReadonlyArray; readonly cause?: unknown; }) => AppError; export {}; //# sourceMappingURL=app-error.d.ts.map