@ogment-ai/cli 0.4.1 → 0.5.0

package/dist/shared/errors.js

@@ -1,112 +1,171 @@
 import { TaggedError } from "better-result";
 import { ERROR_CATEGORY, ERROR_CODE } from "./error-codes.js";
+import { normalizeRecovery } from "./recovery.js";
 const ValidationErrorBase = TaggedError("ValidationError")();
 export class ValidationError extends ValidationErrorBase {
     category = ERROR_CATEGORY.validation;
     code;
+    recovery;
     retryable = false;
-    suggestedCommand;
     constructor(payload) {
         super({
             message: payload.message,
             ...(payload.details === undefined ? {} : { details: payload.details }),
         });
         this.code = payload.code ?? ERROR_CODE.validationInvalidInput;
-        this.suggestedCommand = payload.suggestedCommand;
+        this.recovery = normalizeRecovery(this.code, payload.recovery);
     }
 }
 const AuthErrorBase = TaggedError("AuthError")();
 export class AuthError extends AuthErrorBase {
     category = ERROR_CATEGORY.auth;
     code;
+    recovery;
     retryable;
-    suggestedCommand;
     constructor(payload) {
         super({
             message: payload.message,
             ...(payload.details === undefined ? {} : { details: payload.details }),
         });
         this.code = payload.code ?? ERROR_CODE.authRequired;
+        this.recovery = normalizeRecovery(this.code, payload.recovery);
         this.retryable = payload.retryable ?? this.code === ERROR_CODE.authDeviceExpired;
-        this.suggestedCommand = payload.suggestedCommand;
     }
 }
 const NotFoundErrorBase = TaggedError("NotFoundError")();
 export class NotFoundError extends NotFoundErrorBase {
     category = ERROR_CATEGORY.notFound;
     code;
+    recovery;
     retryable = false;
-    suggestedCommand;
     constructor(payload) {
         super({
             message: payload.message,
             resource: payload.resource,
         });
         this.code = payload.code ?? ERROR_CODE.toolNotFound;
-        this.suggestedCommand = payload.suggestedCommand;
+        this.recovery = normalizeRecovery(this.code, payload.recovery);
     }
 }
 const RemoteRequestErrorBase = TaggedError("RemoteRequestError")();
-const resolveRemoteErrorCode = (payload) => {
+const parseHttpCode = (code) => {
+    if (!code.startsWith("HTTP_")) {
+        return undefined;
+    }
+    const parsed = Number.parseInt(code.slice("HTTP_".length), 10);
+    if (!Number.isFinite(parsed)) {
+        return undefined;
+    }
+    return parsed;
+};
+const resolveRemoteErrorCode = (payload, diagnostics) => {
     if (payload.code !== undefined) {
         return payload.code;
     }
-    if (payload.status === 429) {
-        return ERROR_CODE.remoteRateLimited;
+    if (typeof diagnostics.httpStatus === "number") {
+        return `HTTP_${diagnostics.httpStatus}`;
     }
-    if (payload.status !== undefined && payload.status >= 500) {
-        return ERROR_CODE.remoteUnavailable;
+    if (typeof diagnostics.mcpCode === "number") {
+        return `MCP_${diagnostics.mcpCode}`;
     }
     return ERROR_CODE.transportRequestFailed;
 };
+const resolveRemoteDiagnostics = (payload) => {
+    const source = payload.source ?? payload.diagnostics?.source ?? "network";
+    return {
+        httpStatus: payload.httpStatus ?? payload.status ?? payload.diagnostics?.httpStatus,
+        mcpCode: payload.mcpCode ?? payload.diagnostics?.mcpCode,
+        mcpData: payload.mcpData ?? payload.diagnostics?.mcpData,
+        operation: payload.operation ?? payload.diagnostics?.operation,
+        raw: payload.raw ?? payload.diagnostics?.raw,
+        source,
+    };
+};
+const resolveRetryableRemoteError = (diagnostics, code) => {
+    const httpStatus = diagnostics.httpStatus ?? parseHttpCode(code);
+    if (typeof httpStatus === "number") {
+        return httpStatus === 429 || httpStatus >= 500;
+    }
+    if (typeof diagnostics.mcpCode === "number") {
+        return diagnostics.mcpCode === -32_001;
+    }
+    return diagnostics.source === "network";
+};
+const resolveRemoteCategory = (code, diagnostics) => {
+    const httpStatus = diagnostics.httpStatus ?? parseHttpCode(code);
+    if (code === ERROR_CODE.remoteRateLimited || httpStatus === 429) {
+        return ERROR_CATEGORY.rateLimit;
+    }
+    return ERROR_CATEGORY.remote;
+};
 export class RemoteRequestError extends RemoteRequestErrorBase {
     category;
     code;
+    diagnostics;
+    httpStatus;
+    recovery;
     retryable;
-    suggestedCommand;
     constructor(payload) {
+        const diagnostics = resolveRemoteDiagnostics(payload);
+        const code = resolveRemoteErrorCode(payload, diagnostics);
+        const status = diagnostics.httpStatus;
         super({
             message: payload.message,
             ...(payload.body === undefined ? {} : { body: payload.body }),
-            ...(payload.status === undefined ? {} : { status: payload.status }),
+            ...(status === undefined ? {} : { status }),
+            source: diagnostics.source,
+            ...(diagnostics.mcpCode === undefined ? {} : { mcpCode: diagnostics.mcpCode }),
+            ...(diagnostics.mcpData === undefined ? {} : { mcpData: diagnostics.mcpData }),
+            ...(diagnostics.operation === undefined ? {} : { operation: diagnostics.operation }),
+            ...(diagnostics.raw === undefined ? {} : { raw: diagnostics.raw }),
         });
-        this.code = resolveRemoteErrorCode(payload);
-        this.category =
-            this.code === ERROR_CODE.remoteRateLimited ? ERROR_CATEGORY.rateLimit : ERROR_CATEGORY.remote;
-        const status = payload.status;
-        this.retryable = status === undefined || status === 429 || status >= 500;
-        this.suggestedCommand = payload.suggestedCommand;
+        this.code = code;
+        this.category = resolveRemoteCategory(code, diagnostics);
+        this.diagnostics = diagnostics;
+        this.httpStatus = diagnostics.httpStatus;
+        this.recovery = normalizeRecovery(this.code, payload.recovery);
+        this.retryable = payload.retryable ?? resolveRetryableRemoteError(diagnostics, code);
     }
 }
 const ContractMismatchErrorBase = TaggedError("ContractMismatchError")();
 export class ContractMismatchError extends ContractMismatchErrorBase {
     category = ERROR_CATEGORY.contractMismatch;
     code;
+    recovery;
     retryable = false;
-    suggestedCommand;
     constructor(payload) {
         super({
             message: payload.message,
             ...(payload.details === undefined ? {} : { details: payload.details }),
         });
         this.code = payload.code ?? ERROR_CODE.contractVersionUnsupported;
-        this.suggestedCommand = payload.suggestedCommand;
+        this.recovery = normalizeRecovery(this.code, payload.recovery);
     }
 }
 const UnexpectedErrorBase = TaggedError("UnexpectedError")();
 export class UnexpectedError extends UnexpectedErrorBase {
     category = ERROR_CATEGORY.internal;
     code;
+    recovery;
     retryable = false;
-    suggestedCommand = undefined;
     constructor(payload) {
         super({
             message: payload.message,
             ...(payload.cause === undefined ? {} : { cause: payload.cause }),
         });
         this.code = payload.code ?? ERROR_CODE.internalUnexpected;
+        this.recovery = normalizeRecovery(this.code, payload.recovery);
     }
 }
+const withIfDefined = (base, key, value) => {
+    if (value === undefined) {
+        return base;
+    }
+    return {
+        ...base,
+        [key]: value,
+    };
+};
 const hasDetails = (error) => {
     return error._tag === "AuthError" || error._tag === "ValidationError";
 };
@@ -114,16 +173,58 @@ export const appErrorMeta = (error) => {
     return {
         category: error.category,
         code: error.code,
+        recovery: error.recovery,
         retryable: error.retryable,
-        suggestedCommand: error.suggestedCommand,
     };
 };
+export const appErrorDiagnostics = (error) => {
+    if (error._tag === "RemoteRequestError") {
+        let diagnostics = {
+            source: error.source,
+        };
+        diagnostics = withIfDefined(diagnostics, "httpStatus", error.httpStatus);
+        diagnostics = withIfDefined(diagnostics, "mcpCode", error.mcpCode);
+        diagnostics = withIfDefined(diagnostics, "mcpData", error.mcpData);
+        diagnostics = withIfDefined(diagnostics, "operation", error.operation);
+        diagnostics = withIfDefined(diagnostics, "raw", error.raw);
+        diagnostics = withIfDefined(diagnostics, "body", error.body);
+        return diagnostics;
+    }
+    if (error._tag === "NotFoundError") {
+        return {
+            resource: error.resource,
+        };
+    }
+    if (error._tag === "UnexpectedError") {
+        if (error.cause === undefined) {
+            return {};
+        }
+        return {
+            cause: error.cause,
+        };
+    }
+    if (hasDetails(error) && typeof error.details === "string" && error.details.length > 0) {
+        return {
+            details: error.details,
+        };
+    }
+    return {};
+};
+export const appErrorTitle = (error) => {
+    if (error._tag === "UnexpectedError") {
+        return "Unexpected CLI error";
+    }
+    if (error._tag === "ContractMismatchError") {
+        return "Contract version unsupported";
+    }
+    return error.message;
+};
 export const formatAppError = (error) => {
     if (error._tag === "NotFoundError") {
         return `${error.message} (${error.resource})`;
     }
-    if (error._tag === "RemoteRequestError" && typeof error.status === "number") {
-        return `${error.message} (status ${error.status})`;
+    if (error._tag === "RemoteRequestError" && typeof error.httpStatus === "number") {
+        return `${error.message} (status ${error.httpStatus})`;
     }
     if (hasDetails(error) && typeof error.details === "string" && error.details.length > 0) {
         return `${error.message}: ${error.details}`;

package/dist/shared/guards.d.ts

@@ -3,8 +3,9 @@ import type { ZodTypeAny } from "zod";
 import { z } from "zod";
 import { ERROR_CODE } from "./error-codes.js";
 import { ValidationError } from "./errors.js";
+import type { RecoveryOverride } from "./recovery.js";
 export declare const parseWithSchema: <TSchema extends ZodTypeAny>(schema: TSchema, payload: unknown, context: string, options?: {
     code?: typeof ERROR_CODE.toolInputSchemaViolation | typeof ERROR_CODE.validationInvalidInput;
-    suggestedCommand?: string;
+    recovery?: RecoveryOverride;
 }) => ResultType<z.infer<TSchema>, ValidationError>;
 //# sourceMappingURL=guards.d.ts.map

package/dist/shared/guards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/shared/guards.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAoB9C,eAAO,MAAM,eAAe,GAAI,OAAO,SAAS,UAAU,EACxD,QAAQ,OAAO,EACf,SAAS,OAAO,EAChB,SAAS,MAAM,EACf,UAAS;IACP,IAAI,CAAC,EAAE,OAAO,UAAU,CAAC,wBAAwB,GAAG,OAAO,UAAU,CAAC,sBAAsB,CAAC;IAC7F,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACtB,KACL,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,eAAe,CAiB9C,CAAC"}
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/shared/guards.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAoBtD,eAAO,MAAM,eAAe,GAAI,OAAO,SAAS,UAAU,EACxD,QAAQ,OAAO,EACf,SAAS,OAAO,EAChB,SAAS,MAAM,EACf,UAAS;IACP,IAAI,CAAC,EAAE,OAAO,UAAU,CAAC,wBAAwB,GAAG,OAAO,UAAU,CAAC,sBAAsB,CAAC;IAC7F,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CACxB,KACL,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,eAAe,CAe9C,CAAC"}

package/dist/shared/guards.js

@@ -22,9 +22,7 @@ export const parseWithSchema = (schema, payload, context, options = {}) => {
             details: formatIssues(parsed.error.issues),
             message: `Invalid ${context}`,
             ...(options.code === undefined ? {} : { code: options.code }),
-            ...(options.suggestedCommand === undefined
-                ? {}
-                : { suggestedCommand: options.suggestedCommand }),
+            ...(options.recovery === undefined ? {} : { recovery: options.recovery }),
         }));
     }
     return Result.ok(parsed.data);

package/dist/shared/recovery.d.ts

@@ -0,0 +1,5 @@
+import { type ErrorCode } from "./error-codes.js";
+import type { CliNextAction } from "./types.js";
+export type RecoveryOverride = Partial<CliNextAction>;
+export declare const normalizeRecovery: (code: ErrorCode, override?: RecoveryOverride) => CliNextAction | undefined;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/shared/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../src/shared/recovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,SAAS,EAAwB,MAAM,kBAAkB,CAAC;AACpF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;AA0HtD,eAAO,MAAM,iBAAiB,GAC5B,MAAM,SAAS,EACf,WAAW,gBAAgB,KAC1B,aAAa,GAAG,SAkBlB,CAAC"}

package/dist/shared/recovery.js

@@ -0,0 +1,123 @@
+import { ERROR_CODE } from "./error-codes.js";
+const defaultRecoveryByCode = {
+    [ERROR_CODE.authDeviceExpired]: {
+        command: "ogment auth login",
+        reason: "Device code expired; restart login to continue.",
+        title: "Restart login",
+        when: "immediate",
+    },
+    [ERROR_CODE.authDevicePending]: {
+        command: "ogment auth status",
+        reason: "Authorization is pending; check whether credentials are now available.",
+        title: "Check auth status",
+        when: "immediate",
+    },
+    [ERROR_CODE.authInvalidCredentials]: {
+        command: "ogment auth logout",
+        reason: "Credentials are invalid; clear local state before re-authenticating.",
+        title: "Reset auth state",
+        when: "immediate",
+    },
+    [ERROR_CODE.authRequired]: {
+        command: "ogment auth login",
+        reason: "Authentication is required before catalog or invoke commands can run.",
+        title: "Authenticate",
+        when: "immediate",
+    },
+    [ERROR_CODE.contractVersionUnsupported]: {
+        command: "ogment --version",
+        reason: "Contract mismatch detected; verify CLI version and upgrade before retrying.",
+        title: "Inspect CLI version",
+        when: "immediate",
+    },
+    [ERROR_CODE.internalUnexpected]: {
+        command: "ogment status",
+        reason: "Unexpected failure detected; run diagnostics before retrying the workflow.",
+        title: "Inspect diagnostics",
+        when: "immediate",
+    },
+    [ERROR_CODE.remoteRateLimited]: {
+        command: "ogment status",
+        reason: "Remote rate limit detected; check diagnostics before retrying.",
+        title: "Inspect diagnostics",
+        when: "immediate",
+    },
+    [ERROR_CODE.remoteUnavailable]: {
+        command: "ogment status",
+        reason: "Remote service is unavailable; check connectivity and endpoint health.",
+        title: "Inspect diagnostics",
+        when: "immediate",
+    },
+    [ERROR_CODE.toolInputSchemaViolation]: {
+        command: "ogment catalog",
+        reason: "Tool contract did not validate; inspect available servers and tool metadata.",
+        title: "Inspect catalog",
+        when: "immediate",
+    },
+    [ERROR_CODE.toolNotFound]: {
+        command: "ogment catalog",
+        reason: "Requested tool could not be found; rediscover servers and tools.",
+        title: "Rediscover tools",
+        when: "immediate",
+    },
+    [ERROR_CODE.transportRequestFailed]: {
+        command: "ogment status",
+        reason: "Transport request failed; inspect connectivity diagnostics.",
+        title: "Inspect diagnostics",
+        when: "immediate",
+    },
+    [ERROR_CODE.validationInvalidInput]: {
+        command: "ogment --help",
+        reason: "Input validation failed; inspect canonical command syntax.",
+        title: "Show command help",
+        when: "immediate",
+    },
+};
+const dynamicRecoveryForCode = (code) => {
+    if (code.startsWith("HTTP_")) {
+        return {
+            command: "ogment status",
+            reason: `HTTP error ${code} detected; inspect diagnostics and remote connectivity.`,
+            title: "Inspect diagnostics",
+            when: "immediate",
+        };
+    }
+    if (code.startsWith("MCP_")) {
+        return {
+            command: "ogment status",
+            reason: `MCP error ${code} detected; inspect diagnostics and remote server state.`,
+            title: "Inspect diagnostics",
+            when: "immediate",
+        };
+    }
+    return undefined;
+};
+const hasPlaceholderTokens = (command) => {
+    return command.includes("<") || command.includes(">");
+};
+const sanitizedCommand = (command) => {
+    if (typeof command !== "string") {
+        return undefined;
+    }
+    if (hasPlaceholderTokens(command)) {
+        return undefined;
+    }
+    return command;
+};
+export const normalizeRecovery = (code, override) => {
+    const fallback = defaultRecoveryByCode[code] ?? dynamicRecoveryForCode(code);
+    if (fallback === undefined) {
+        return undefined;
+    }
+    const overrideCommand = sanitizedCommand(override?.command);
+    const command = overrideCommand ?? fallback.command;
+    const usesCustomCommand = overrideCommand !== undefined && overrideCommand !== fallback.command;
+    return {
+        command,
+        id: override?.id ?? `recover_${code.toLowerCase()}`,
+        reason: override?.reason ??
+            (usesCustomCommand ? `Suggested recovery for error ${code}.` : fallback.reason),
+        title: override?.title ?? (usesCustomCommand ? "Run suggested command" : fallback.title),
+        when: override?.when ?? fallback.when,
+    };
+};

package/dist/shared/schema-example.d.ts

@@ -1,2 +1,3 @@
+export declare const EXAMPLE_PLACEHOLDER = " ... ";
 export declare const buildJsonSchemaExample: (schema: Record<string, unknown>) => unknown;
 //# sourceMappingURL=schema-example.d.ts.map

package/dist/shared/schema-example.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-example.d.ts","sourceRoot":"","sources":["../../src/shared/schema-example.ts"],"names":[],"mappings":"AAyJA,eAAO,MAAM,sBAAsB,GAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,OAExE,CAAC"}
+{"version":3,"file":"schema-example.d.ts","sourceRoot":"","sources":["../../src/shared/schema-example.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,mBAAmB,UAAU,CAAC;AA8H3C,eAAO,MAAM,sBAAsB,GAAI,QAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,OAExE,CAAC"}

package/dist/shared/schema-example.js

@@ -1,4 +1,5 @@
 const MAX_EXAMPLE_DEPTH = 6;
+export const EXAMPLE_PLACEHOLDER = " ... ";
 const isRecord = (value) => {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 };
@@ -31,38 +32,25 @@ const deriveType = (schema) => {
     }
     return undefined;
 };
-const baseScalarExample = (typeName, schema) => {
+const baseScalarExample = (typeName) => {
     switch (typeName) {
         case "string": {
-            const format = schema["format"];
-            if (format === "email") {
-                return "agent@example.com";
-            }
-            if (format === "uri" || format === "url") {
-                return "https://example.com";
-            }
-            if (format === "date-time") {
-                return "2026-01-01T00:00:00Z";
-            }
-            if (format === "uuid") {
-                return "00000000-0000-0000-0000-000000000000";
-            }
-            return "string";
+            return EXAMPLE_PLACEHOLDER;
         }
         case "integer": {
-            return 0;
+            return EXAMPLE_PLACEHOLDER;
         }
         case "number": {
-            return 0;
+            return EXAMPLE_PLACEHOLDER;
         }
         case "boolean": {
-            return false;
+            return EXAMPLE_PLACEHOLDER;
         }
         case "null": {
-            return null;
+            return EXAMPLE_PLACEHOLDER;
         }
         default: {
-            return {};
+            return EXAMPLE_PLACEHOLDER;
         }
     }
 };
@@ -73,20 +61,6 @@ const buildExample = (value, depth) => {
     if (depth > MAX_EXAMPLE_DEPTH) {
         return {};
     }
-    if (value["default"] !== undefined) {
-        return value["default"];
-    }
-    if (value["const"] !== undefined) {
-        return value["const"];
-    }
-    const enumValue = firstKnown(value["enum"]);
-    if (enumValue !== undefined) {
-        return enumValue;
-    }
-    const examplesValue = firstKnown(value["examples"]);
-    if (examplesValue !== undefined) {
-        return examplesValue;
-    }
     const oneOfCandidate = firstKnown(value["oneOf"]);
     if (oneOfCandidate !== undefined) {
         return buildExample(oneOfCandidate, depth + 1);
@@ -116,12 +90,15 @@ const buildExample = (value, depth) => {
         return result;
     }
     if (typeName === "array") {
+        if (value["items"] === undefined) {
+            return [EXAMPLE_PLACEHOLDER];
+        }
         return [buildExample(value["items"], depth + 1)];
     }
     if (typeName === undefined) {
-        return {};
+        return depth === 0 ? {} : EXAMPLE_PLACEHOLDER;
     }
-    return baseScalarExample(typeName, value);
+    return baseScalarExample(typeName);
 };
 export const buildJsonSchemaExample = (schema) => {
     return buildExample(schema, 0);

package/dist/shared/types.d.ts

@@ -30,9 +30,20 @@ export interface ToolCallResult {
     structuredContent: unknown;
     isError: boolean;
 }
+export type RemoteErrorSource = "http" | "mcp_jsonrpc" | "mcp_transport_http" | "network" | "unknown";
+export interface RemoteErrorDiagnostics {
+    httpStatus?: number | undefined;
+    mcpCode?: number | undefined;
+    mcpData?: unknown;
+    operation?: string | undefined;
+    raw?: unknown;
+    source: RemoteErrorSource;
+}
+export type LoginOutcome = "already_authenticated" | "authenticated";
 export interface LoginSuccess {
     agentName: string;
-    alreadyLoggedIn: boolean;
+    loggedIn: true;
+    outcome: LoginOutcome;
 }
 export interface LogoutSuccess {
     revoked: boolean;
@@ -70,6 +81,12 @@ export interface InfoPingCheck {
 }
 export type InfoAccountStatus = "auth_error" | "remote_error" | "skipped" | "success" | "unexpected_error" | "validation_error";
 export interface InfoAccountCheck {
+    errorCode: string | null;
+    errorHttpStatus: number | null;
+    errorMcpCode: number | null;
+    errorRaw: unknown;
+    errorRetryable: boolean | null;
+    errorSource: string | null;
     errorType: string | null;
     latencyMs: number | null;
     message: string | null;
@@ -99,17 +116,15 @@ export interface InfoPayload {
     runtime: InfoRuntimeDetails;
     summary: InfoSummary;
 }
-export declare const CLI_CONTRACT_VERSION: "0.4";
-export type CliContractVersion = typeof CLI_CONTRACT_VERSION;
 export interface CliPaginationMeta {
     nextCursor: string | null;
 }
 export interface CliMeta {
     command: string;
-    entity: Record<string, unknown> | null;
-    pagination: CliPaginationMeta | null;
-    requestId: string;
-    timestamp: string;
+    entity?: Record<string, unknown> | null;
+    pagination?: CliPaginationMeta;
+    requestId?: string;
+    timestamp?: string;
 }
 export interface CliNextAction {
     command: string;
@@ -118,19 +133,32 @@ export interface CliNextAction {
     title: string;
     when: string | null;
 }
-export interface CliErrorPayload {
+export interface CliRuntimeErrorPayload {
     category: string;
     code: string;
     detail: string;
     diagnostics: Record<string, unknown>;
-    docsUrl: string | null;
-    retryAfterMs: number | null;
+    related_codes?: string[];
     retryable: boolean;
-    suggestedCommand: string | null;
     title: string;
 }
+export type CliParseErrorKind = "missing_argument" | "missing_option_value" | "missing_subcommand" | "invalid_argument" | "conflicting_option" | "excess_arguments" | "unknown_command" | "unknown_option" | "other";
+export interface CliParseErrorDiagnostics {
+    kind: CliParseErrorKind;
+    parserCode?: string;
+    helpText?: string | null;
+    scope: string | null;
+}
+export interface CliParseErrorPayload {
+    category: "parse";
+    code: "CLI_PARSE_ERROR";
+    detail: string;
+    diagnostics: CliParseErrorDiagnostics;
+    retryable: false;
+    title: string;
+}
+export type CliErrorPayload = CliParseErrorPayload | CliRuntimeErrorPayload;
 export interface CliSuccessEnvelope<TData> {
-    version: CliContractVersion;
     data: TData;
     error: null;
     meta: CliMeta;
@@ -138,7 +166,6 @@ export interface CliSuccessEnvelope<TData> {
     ok: true;
 }
 export interface CliErrorEnvelope {
-    version: CliContractVersion;
     data: null;
     error: CliErrorPayload;
     meta: CliMeta;
@@ -160,11 +187,23 @@ export interface CatalogServerSummary {
     version: string | null;
 }
 export interface CatalogSummarySuccess {
+    failures: CatalogServerFailure[];
     servers: CatalogServerSummary[];
 }
+export interface CatalogServerFailure {
+    error: {
+        code: string;
+        diagnostics: Record<string, unknown>;
+        detail: string;
+        related_codes?: string[];
+        retryable: boolean;
+        title: string;
+    };
+    orgSlug: string;
+    serverId: string;
+}
 export interface CatalogToolSummary {
     description: string | null;
-    inputSchemaRef: string | null;
     name: string;
 }
 export interface CatalogToolsSuccess {