@agentclientprotocol/claude-agent-acp 0.67.0 → 0.69.0

package/dist/file-change-audit.d.ts

@@ -0,0 +1,56 @@
+import { type HookCallback, type McpSdkServerConfigWithInstance } from "@anthropic-ai/claude-agent-sdk";
+export declare const AGENT_FILE_CHANGE_REPORT_CAPABILITY = "agentFileChangeReport";
+export declare const FILE_CHANGE_AUDIT_SERVER_NAME = "claude_agent_acp";
+export declare const FILE_CHANGE_AUDIT_TOOL_NAME = "report_changed_files";
+export declare const FILE_CHANGE_AUDIT_WIRE_TOOL_NAME = "mcp__claude_agent_acp__report_changed_files";
+export declare const AGENT_FILE_CHANGE_REPORT_MAX_BYTES: number;
+export type FileChangeAuditTurnState = {
+    requestId: string;
+    phase: "requested" | "collecting" | "finished";
+};
+export type FileChangeAuditWorkspace = {
+    cwd: string;
+    additionalDirectories: string[];
+};
+export type AgentFileChangeReport = {
+    paths: string[];
+    complete: boolean;
+    uncertainty?: string;
+};
+export type AgentFileChangeReportResult = {
+    version: 1;
+    requestId: string;
+} & ({
+    status: "reported";
+    paths: string[];
+    declaredComplete: boolean;
+    truncated: boolean;
+    uncertainty?: string;
+} | {
+    status: "unavailable";
+    reason: FileChangeReportUnavailableReason;
+});
+export type FileChangeReportUnavailableReason = "cancelled" | "timeout" | "invalidOutput" | "notReported" | "providerError";
+type FileChangeAuditSupportOptions = {
+    cwd: string;
+    additionalDirectories: string[];
+    getActiveState: () => FileChangeAuditTurnState | undefined;
+    publish: (result: AgentFileChangeReportResult) => Promise<void>;
+    logError: (message: string) => void;
+};
+export type FileChangeAuditSupport = {
+    mcpServer: McpSdkServerConfigWithInstance;
+    preToolUseHook: HookCallback;
+    stopHook: HookCallback;
+    finishUnavailable: (state: FileChangeAuditTurnState, reason: FileChangeReportUnavailableReason) => Promise<void>;
+};
+export declare function agentFileChangeReportRequestId(meta: unknown): string | undefined;
+export declare function supportsAgentFileChangeReport(capabilities: unknown): boolean;
+export declare function agentFileChangeReportMeta(result: AgentFileChangeReportResult): Record<string, unknown>;
+export declare function createFileChangeAuditTurnState(requestId: string): FileChangeAuditTurnState;
+export declare function isFileChangeAuditReportPhase(state: FileChangeAuditTurnState | undefined): boolean;
+export declare function isFileChangeAuditTool(toolName: string): boolean;
+export declare function containsFileChangeAuditMarker(text: string): boolean;
+export declare function createFileChangeAuditSupport(options: FileChangeAuditSupportOptions): FileChangeAuditSupport;
+export {};
+//# sourceMappingURL=file-change-audit.d.ts.map

package/dist/file-change-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-change-audit.d.ts","sourceRoot":"","sources":["../src/file-change-audit.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,8BAA8B,EAEpC,MAAM,gCAAgC,CAAC;AAKxC,eAAO,MAAM,mCAAmC,0BAA0B,CAAC;AAC3E,eAAO,MAAM,6BAA6B,qBAAqB,CAAC;AAChE,eAAO,MAAM,2BAA2B,yBAAyB,CAAC;AAClE,eAAO,MAAM,gCAAgC,gDAA0E,CAAC;AAKxH,eAAO,MAAM,kCAAkC,QAAa,CAAC;AAG7D,MAAM,MAAM,wBAAwB,GAAG;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,WAAW,GAAG,YAAY,GAAG,UAAU,CAAC;CAChD,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,qBAAqB,EAAE,MAAM,EAAE,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,OAAO,EAAE,CAAC,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,CACA;IACE,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GACD;IACE,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,iCAAiC,CAAC;CAC3C,CACJ,CAAC;AAEF,MAAM,MAAM,iCAAiC,GAC3C,WAAW,GAAG,SAAS,GAAG,eAAe,GAAG,aAAa,GAAG,eAAe,CAAC;AAQ9E,KAAK,6BAA6B,GAAG;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,cAAc,EAAE,MAAM,wBAAwB,GAAG,SAAS,CAAC;IAC3D,OAAO,EAAE,CAAC,MAAM,EAAE,2BAA2B,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,SAAS,EAAE,8BAA8B,CAAC;IAC1C,cAAc,EAAE,YAAY,CAAC;IAC7B,QAAQ,EAAE,YAAY,CAAC;IACvB,iBAAiB,EAAE,CACjB,KAAK,EAAE,wBAAwB,EAC/B,MAAM,EAAE,iCAAiC,KACtC,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB,CAAC;AAoBF,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAiBhF;AAED,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAW5E;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,2BAA2B,GAClC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CASzB;AAYD,wBAAgB,8BAA8B,CAAC,SAAS,EAAE,MAAM,GAAG,wBAAwB,CAK1F;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,wBAAwB,GAAG,SAAS,GAAG,OAAO,CAEjG;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE/D;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,6BAA6B,GACrC,sBAAsB,CAmJxB"}

package/dist/file-change-audit.js

@@ -0,0 +1,379 @@
+import { createSdkMcpServer, } from "@anthropic-ai/claude-agent-sdk";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { z } from "zod";
+export const AGENT_FILE_CHANGE_REPORT_CAPABILITY = "agentFileChangeReport";
+export const FILE_CHANGE_AUDIT_SERVER_NAME = "claude_agent_acp";
+export const FILE_CHANGE_AUDIT_TOOL_NAME = "report_changed_files";
+export const FILE_CHANGE_AUDIT_WIRE_TOOL_NAME = `mcp__${FILE_CHANGE_AUDIT_SERVER_NAME}__${FILE_CHANGE_AUDIT_TOOL_NAME}`;
+const FILE_CHANGE_AUDIT_MARKER = "claude-agent-acp-file-change-audit";
+const MAX_REPORTED_PATHS = 1024;
+const MAX_REPORTED_PATH_LENGTH = 4096;
+export const AGENT_FILE_CHANGE_REPORT_MAX_BYTES = 256 * 1024;
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+const JETBRAINS_META_KEY = "jetbrains";
+const AIR_META_KEY = "air";
+const AIR_EXTENSION_VERSION = 1;
+const AIR_EXTENSION_CAPABILITIES_KEY = "capabilities";
+const AIR_AGENT_FILE_CHANGE_REPORT_KEY = "agentFileChangeReport";
+const reportInputSchema = {
+    paths: z
+        .array(z.string())
+        .describe("Workspace file paths changed during this turn. Use absolute paths or paths relative to cwd."),
+    complete: z
+        .boolean()
+        .describe("True only when paths contains every workspace file changed during this turn."),
+    uncertainty: z
+        .string()
+        .trim()
+        .min(1)
+        .max(2000)
+        .optional()
+        .describe("Why the report may be incomplete or uncertain."),
+};
+export function agentFileChangeReportRequestId(meta) {
+    const air = airExtension(meta);
+    const request = air?.agentFileChangeReportRequest;
+    if (!request || typeof request !== "object" || Array.isArray(request))
+        return undefined;
+    const requestRecord = request;
+    const requestKeys = Object.keys(requestRecord);
+    if (requestKeys.length !== 2 ||
+        !requestKeys.includes("version") ||
+        !requestKeys.includes("requestId") ||
+        requestRecord.version !== 1)
+        return undefined;
+    const requestId = requestRecord.requestId;
+    return typeof requestId === "string" && REQUEST_ID_PATTERN.test(requestId)
+        ? requestId
+        : undefined;
+}
+export function supportsAgentFileChangeReport(capabilities) {
+    if (!capabilities || typeof capabilities !== "object" || Array.isArray(capabilities)) {
+        return false;
+    }
+    const air = airExtension(capabilities._meta);
+    const advertised = air?.[AIR_EXTENSION_CAPABILITIES_KEY];
+    return (air?.version === AIR_EXTENSION_VERSION &&
+        Array.isArray(advertised) &&
+        advertised.includes(AGENT_FILE_CHANGE_REPORT_CAPABILITY));
+}
+export function agentFileChangeReportMeta(result) {
+    return {
+        [JETBRAINS_META_KEY]: {
+            [AIR_META_KEY]: {
+                version: AIR_EXTENSION_VERSION,
+                [AIR_AGENT_FILE_CHANGE_REPORT_KEY]: result,
+            },
+        },
+    };
+}
+function airExtension(meta) {
+    if (!meta || typeof meta !== "object" || Array.isArray(meta))
+        return undefined;
+    const jetbrains = meta[JETBRAINS_META_KEY];
+    if (!jetbrains || typeof jetbrains !== "object" || Array.isArray(jetbrains))
+        return undefined;
+    const air = jetbrains[AIR_META_KEY];
+    return air && typeof air === "object" && !Array.isArray(air)
+        ? air
+        : undefined;
+}
+export function createFileChangeAuditTurnState(requestId) {
+    return {
+        requestId,
+        phase: "requested",
+    };
+}
+export function isFileChangeAuditReportPhase(state) {
+    return state?.phase === "collecting" || state?.phase === "finished";
+}
+export function isFileChangeAuditTool(toolName) {
+    return toolName === FILE_CHANGE_AUDIT_WIRE_TOOL_NAME;
+}
+export function containsFileChangeAuditMarker(text) {
+    return text.includes(`<${FILE_CHANGE_AUDIT_MARKER}>`);
+}
+export function createFileChangeAuditSupport(options) {
+    const workspace = normalizeWorkspace(options.cwd, options.additionalDirectories);
+    const finishUnavailable = async (state, reason) => {
+        // Claim the terminal outcome before the first await. The report tool, a
+        // Stop hook, cancellation, and stream teardown can race, but only the
+        // winner may publish for this request id. Publication remains fail-open:
+        // an audit transport failure must never hold the user prompt open.
+        if (state.phase === "finished")
+            return;
+        state.phase = "finished";
+        try {
+            await options.publish({
+                version: 1,
+                requestId: state.requestId,
+                status: "unavailable",
+                reason,
+            });
+        }
+        catch (error) {
+            options.logError(`Failed to publish unavailable report ${state.requestId}: ${error}`);
+        }
+    };
+    const tool = {
+        name: FILE_CHANGE_AUDIT_TOOL_NAME,
+        description: "Internal audit tool. Call it only when a stop-hook message explicitly requests the file-change audit.",
+        inputSchema: reportInputSchema,
+        _meta: {
+            "anthropic/alwaysLoad": true,
+            "claude/endTurn": true,
+        },
+        handler: async (report) => {
+            const state = options.getActiveState();
+            if (!state || state.phase !== "collecting") {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: `<${FILE_CHANGE_AUDIT_MARKER}>No file-change audit is active.</${FILE_CHANGE_AUDIT_MARKER}>`,
+                        },
+                    ],
+                };
+            }
+            // Flip before publishing: a client transport failure must not make the
+            // model retry the report and produce duplicates. Delivery is audit-only
+            // and fail-open; the normal turn must still finish.
+            state.phase = "finished";
+            const normalized = normalizeReportedPaths(report.paths, workspace);
+            const result = fitReportedAgentFileChangeReport({
+                version: 1,
+                requestId: state.requestId,
+                status: "reported",
+                paths: normalized.paths,
+                declaredComplete: report.complete && !normalized.truncated,
+                truncated: normalized.truncated,
+                ...(report.uncertainty ? { uncertainty: report.uncertainty } : {}),
+            });
+            try {
+                await options.publish(result);
+            }
+            catch (error) {
+                options.logError(`Failed to publish file-change report ${state.requestId}: ${error}`);
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `<${FILE_CHANGE_AUDIT_MARKER}>File-change audit recorded.</${FILE_CHANGE_AUDIT_MARKER}>`,
+                    },
+                ],
+                structuredContent: result,
+            };
+        },
+    };
+    // canUseTool is not guaranteed to run for tools that the current permission
+    // mode auto-allows (notably bypassPermissions). A PreToolUse hook is the
+    // enforcement boundary that keeps the hidden continuation read-only in every
+    // mode: it can submit the report, but cannot inspect or mutate more files.
+    const preToolUseHook = async (input) => {
+        if (input.hook_event_name !== "PreToolUse")
+            return {};
+        const state = options.getActiveState();
+        const isReportTool = isFileChangeAuditTool(input.tool_name);
+        if (!isReportTool && !isFileChangeAuditReportPhase(state))
+            return {};
+        const allowReport = state?.phase === "collecting" && isReportTool;
+        return {
+            hookSpecificOutput: {
+                hookEventName: "PreToolUse",
+                permissionDecision: allowReport ? "allow" : "deny",
+                ...(!allowReport
+                    ? {
+                        permissionDecisionReason: "Only the internal file-change report is allowed during the audit.",
+                    }
+                    : {}),
+            },
+        };
+    };
+    const stopHook = async (input) => {
+        if (input.hook_event_name !== "Stop")
+            return {};
+        const state = options.getActiveState();
+        if (!state || state.phase === "finished")
+            return {};
+        // A Stop can be only a pause while a background generator is still
+        // running. Keep the request pending so a later final Stop can include its
+        // writes instead of declaring a prematurely complete path set.
+        if (state.phase === "requested" && (input.background_tasks?.length ?? 0) > 0)
+            return {};
+        if (state.phase === "collecting" || input.stop_hook_active) {
+            await finishUnavailable(state, "notReported");
+            return {};
+        }
+        // Set the phase before returning the continuation so every following SDK
+        // message is hidden even if the next stream starts immediately.
+        state.phase = "collecting";
+        return {
+            hookSpecificOutput: {
+                hookEventName: "Stop",
+                additionalContext: `<${FILE_CHANGE_AUDIT_MARKER}>` +
+                    `Before stopping, call ${FILE_CHANGE_AUDIT_WIRE_TOOL_NAME} exactly once. ` +
+                    "Report every workspace file changed during this user turn, including files changed " +
+                    "by commands, generators, version-control operations, and child processes. " +
+                    "Do not call any other tool and do not emit user-facing prose. " +
+                    "Set complete to false and explain uncertainty when you are not sure the list is complete." +
+                    `</${FILE_CHANGE_AUDIT_MARKER}>`,
+            },
+        };
+    };
+    return {
+        mcpServer: createSdkMcpServer({
+            name: FILE_CHANGE_AUDIT_SERVER_NAME,
+            version: "1.0.0",
+            tools: [tool],
+            alwaysLoad: true,
+        }),
+        preToolUseHook,
+        stopHook,
+        finishUnavailable,
+    };
+}
+function normalizeWorkspace(cwd, additionalDirectories) {
+    const normalizedCwd = canonicalizeWorkspaceRoot(path.resolve(cwd));
+    const seen = new Set([pathKey(normalizedCwd)]);
+    const normalizedAdditionalDirectories = [];
+    for (const directory of additionalDirectories) {
+        const normalized = canonicalizeWorkspaceRoot(path.resolve(normalizedCwd, directory));
+        const key = pathKey(normalized);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        normalizedAdditionalDirectories.push(normalized);
+    }
+    return {
+        cwd: normalizedCwd,
+        additionalDirectories: normalizedAdditionalDirectories,
+    };
+}
+function normalizeReportedPaths(reportedPaths, workspace) {
+    const roots = [workspace.cwd, ...workspace.additionalDirectories];
+    const seen = new Set();
+    const result = [];
+    let totalBytes = 0;
+    let truncated = false;
+    for (const reportedPath of reportedPaths) {
+        if (reportedPath.trim().length === 0 ||
+            reportedPath.length > MAX_REPORTED_PATH_LENGTH ||
+            hasControlCharacter(reportedPath)) {
+            truncated = true;
+            continue;
+        }
+        let normalized;
+        try {
+            normalized = canonicalizeReportedPath(path.resolve(workspace.cwd, reportedPath));
+        }
+        catch {
+            truncated = true;
+            continue;
+        }
+        if (normalized.length > MAX_REPORTED_PATH_LENGTH || hasControlCharacter(normalized)) {
+            truncated = true;
+            continue;
+        }
+        if (!roots.some((root) => isWithinRoot(normalized, root))) {
+            truncated = true;
+            continue;
+        }
+        const key = pathKey(normalized);
+        if (roots.some((root) => pathKey(root) === key)) {
+            truncated = true;
+            continue;
+        }
+        if (seen.has(key)) {
+            continue;
+        }
+        const pathBytes = Buffer.byteLength(normalized, "utf8");
+        if (result.length >= MAX_REPORTED_PATHS ||
+            totalBytes + pathBytes > AGENT_FILE_CHANGE_REPORT_MAX_BYTES) {
+            truncated = true;
+            continue;
+        }
+        seen.add(key);
+        result.push(normalized);
+        totalBytes += pathBytes;
+    }
+    return { paths: result, truncated };
+}
+/** Keep the complete serialized report within AIR's wire limit. */
+function fitReportedAgentFileChangeReport(report) {
+    const paths = [...report.paths];
+    let fitted = report;
+    while (Buffer.byteLength(JSON.stringify(fitted), "utf8") > AGENT_FILE_CHANGE_REPORT_MAX_BYTES) {
+        if (paths.length === 0) {
+            // The fixed fields and bounded uncertainty are far below the cap. Keep
+            // this loud if the wire contract changes without updating this helper.
+            throw new Error("Agent file-change report exceeds the wire limit without paths");
+        }
+        paths.pop();
+        fitted = {
+            ...report,
+            paths: [...paths],
+            declaredComplete: false,
+            truncated: true,
+        };
+    }
+    return fitted;
+}
+function isWithinRoot(candidate, root) {
+    const relative = path.relative(root, candidate);
+    return !path.isAbsolute(relative) && !relative.startsWith(`..${path.sep}`) && relative !== "..";
+}
+/**
+ * Resolve filesystem aliases in a workspace root, including macOS' /tmp ->
+ * /private/tmp alias. For a root that does not exist yet, resolve its nearest
+ * existing ancestor and retain the missing suffix.
+ */
+function canonicalizeWorkspaceRoot(value) {
+    return canonicalizeFromExistingAncestor(value);
+}
+/**
+ * Canonicalize the parent but not the leaf itself. A changed path may be
+ * deleted, or it may be a symlink whose node (rather than target) changed.
+ */
+function canonicalizeReportedPath(value) {
+    const parent = canonicalizeFromExistingAncestor(path.dirname(value));
+    return path.resolve(parent, path.basename(value));
+}
+function canonicalizeFromExistingAncestor(value) {
+    const original = path.resolve(value);
+    let current = original;
+    const missingSegments = [];
+    while (true) {
+        try {
+            const canonical = fs.realpathSync.native(current);
+            return path.resolve(canonical, ...missingSegments.reverse());
+        }
+        catch (error) {
+            if (!isMissingPathError(error))
+                return original;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return original;
+        missingSegments.push(path.basename(current));
+        current = parent;
+    }
+}
+function isMissingPathError(error) {
+    if (typeof error !== "object" || error === null || !("code" in error))
+        return false;
+    return error.code === "ENOENT" || error.code === "ENOTDIR";
+}
+function pathKey(value) {
+    return process.platform === "win32" ? value.toLowerCase() : value;
+}
+function hasControlCharacter(value) {
+    for (let index = 0; index < value.length; index++) {
+        const code = value.charCodeAt(index);
+        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f))
+            return true;
+    }
+    return false;
+}

package/dist/session-failure-extension.d.ts

@@ -0,0 +1,104 @@
+import type { ClientCapabilities, SessionNotification } from "@agentclientprotocol/sdk";
+import { getSessionMessages, type SDKAssistantMessageError } from "@anthropic-ai/claude-agent-sdk";
+export declare function airSessionFailureCapabilityMeta(...additionalCapabilities: string[]): {
+    jetbrains: {
+        air: {
+            version: number;
+            capabilities: string[];
+        };
+    };
+};
+export type ClaudeFailureKind = "advisory" | "auth_required" | "bad_request" | "budget_exhausted" | "context_exhausted" | "internal_error" | "overloaded" | "provider_error" | "quota_exhausted" | "rate_limited" | "transport_lost" | "worker_shutdown";
+type AirSessionFailureCategory = "connection" | "access" | "limit" | "request" | "service" | "unknown";
+type AirSessionFailureSeverity = "warning" | "error";
+type AirSessionFailureAction = "retry" | "login" | "new_session";
+type SessionFailureRecoveryPolicy = "never" | "next_attempt" | "real_model_success" | "auth_status" | "runtime_rebind";
+export type PublishedSessionFailure = {
+    id: string;
+    revision: number;
+    kind: ClaudeFailureKind;
+    category: AirSessionFailureCategory;
+    turnId?: string;
+    severity: AirSessionFailureSeverity;
+    title: string;
+    details?: string;
+    actions: AirSessionFailureAction[];
+    recoveryPolicy: SessionFailureRecoveryPolicy;
+};
+type SessionFailureOptions = {
+    turnId?: string;
+    sessionScoped?: boolean;
+    title?: string;
+    details?: string;
+    severity?: AirSessionFailureSeverity;
+};
+export type SessionFailureState = {
+    epoch: string;
+    revisions: Map<string, number>;
+    active: Map<string, PublishedSessionFailure>;
+    nextIncident?: number;
+    lastNotice?: {
+        title: string;
+        id: string;
+    };
+};
+type Logger = {
+    error: (...args: unknown[]) => void;
+};
+export declare function createSessionFailureState(): SessionFailureState;
+export declare function sessionFailureMeta(failure: PublishedSessionFailure): {
+    jetbrains: {
+        air: {
+            version: number;
+            sessionFailure: {
+                actions: AirSessionFailureAction[];
+                details?: string | undefined;
+                id: string;
+                revision: number;
+                category: AirSessionFailureCategory;
+                severity: AirSessionFailureSeverity;
+                title: string;
+            };
+        };
+    };
+};
+/** `getSessionMessages` deliberately exposes only the API message and strips
+ *  transcript-level `error` / `isApiErrorMessage` fields. The SDK exports the
+ *  exact stable prefixes used by its synthetic usage-limit errors, so replay
+ *  can recover this one typed failure without matching arbitrary model prose. */
+export declare function assistantMessageText(apiMessage: unknown): string | undefined;
+export declare function isSyntheticUsageLimitMessage(apiMessage: unknown): boolean;
+export declare function activeUsageLimitMessage(messages: Awaited<ReturnType<typeof getSessionMessages>>): {
+    uuid: string;
+    title: string;
+} | undefined;
+export declare function supportsAirSessionFailures(capabilities?: ClientCapabilities): boolean;
+/** Owns the AIR failure lifecycle for both the live consumer and history replay.
+ *  Published revisions become active only after delivery succeeds; recovery only
+ *  removes internal active state because transcript records are historical. */
+export declare class SessionFailureController {
+    private readonly sessionId;
+    private readonly state;
+    private readonly capabilities?;
+    private readonly isCurrent;
+    private readonly sendUpdate;
+    private readonly logger;
+    constructor(options: {
+        sessionId: string;
+        state: SessionFailureState;
+        capabilities?: ClientCapabilities;
+        isCurrent: () => boolean;
+        sendUpdate: (notification: SessionNotification) => Promise<void>;
+        logger: Logger;
+    });
+    private isSupported;
+    private emit;
+    recordActive(failure: PublishedSessionFailure): void;
+    clear(shouldClear?: (failure: PublishedSessionFailure) => boolean): Promise<boolean>;
+    prepare(kind: ClaudeFailureKind, failureOptions?: SessionFailureOptions): Promise<PublishedSessionFailure | undefined>;
+    publish(kind: ClaudeFailureKind, failureOptions?: SessionFailureOptions): Promise<void>;
+    restore(id: string, kind: ClaudeFailureKind, title: string, active?: boolean): Promise<boolean>;
+}
+export declare function providerFailureCategory(errorKind?: SDKAssistantMessageError, isUsageLimit?: boolean): ClaudeFailureKind;
+export {};
+//# sourceMappingURL=session-failure-extension.d.ts.map

package/dist/session-failure-extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-failure-extension.d.ts","sourceRoot":"","sources":["../src/session-failure-extension.ts"],"names":[],"mappings":"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"}