@hyperdrive.bot/paseo-server 0.2.6

package/dist/server/server/agent/providers/claude/agent.d.ts

@@ -0,0 +1,341 @@
+import { type AgentDefinition, type McpServerConfig as ClaudeSdkMcpServerConfig, type PermissionMode, type SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { Logger } from "pino";
+import { type ClaudeQueryFactory } from "./transport/sdk.js";
+import type { AgentTransport } from "./transport/types.js";
+import { type AgentCapabilityFlags, type AgentClient, type AgentCreateSessionOptions, type AgentFeature, type AgentLaunchContext, type AgentMetadata, type AgentMode, type AgentPermissionRequest, type AgentPermissionResponse, type AgentPersistenceHandle, type AgentProviderNotice, type AgentPromptInput, type AgentRunOptions, type AgentRunResult, type AgentSession, type AgentSessionConfig, type AgentSlashCommand, type AgentStreamEvent, type AgentTimelineItem, type AgentRuntimeInfo, type FetchCatalogOptions, type ImportableProviderSession, type ImportProviderSessionContext, type ImportProviderSessionInput, type ListImportableSessionsOptions, type McpServerConfig, type ProviderCatalog } from "../../agent-sdk-types.js";
+import { type ProviderRuntimeSettings } from "../../provider-launch-config.js";
+import type { HookEventHandler } from "./hook-handler.js";
+export declare function normalizeClaudeAskUserQuestionRequestInput(toolName: string, input: AgentMetadata): AgentMetadata;
+export declare function normalizeClaudeAskUserQuestionUpdatedInput(updatedInput: AgentMetadata | undefined, fallbackInput: AgentMetadata | undefined): AgentMetadata;
+interface EventIdentifiers {
+    taskId: string | null;
+    parentMessageId: string | null;
+    messageId: string | null;
+}
+type ClaudeAgentConfig = AgentSessionConfig & {
+    provider: "claude";
+};
+export interface ClaudeContentChunk {
+    type: string;
+    [key: string]: unknown;
+}
+interface ClaudeAgentClientOptions {
+    defaults?: {
+        agents?: Record<string, AgentDefinition>;
+    };
+    logger: Logger;
+    runtimeSettings?: ProviderRuntimeSettings;
+    queryFactory?: ClaudeQueryFactory;
+    resolveBinary?: () => Promise<string>;
+    configDir?: string;
+}
+interface ClaudeAgentSessionOptions {
+    defaults?: {
+        agents?: Record<string, AgentDefinition>;
+    };
+    runtimeSettings?: ProviderRuntimeSettings;
+    handle?: AgentPersistenceHandle;
+    agentId?: string;
+    launchEnv?: Record<string, string>;
+    persistSession?: boolean;
+    logger: Logger;
+    queryFactory?: ClaudeQueryFactory;
+    resolveBinary: () => Promise<string>;
+    resumeSessionId?: string;
+}
+export declare function extractUserMessageText(content: unknown): string | null;
+export declare function toClaudeSdkMcpConfig(config: McpServerConfig): ClaudeSdkMcpServerConfig;
+export declare function readEventIdentifiers(message: SDKMessage): EventIdentifiers;
+export declare class ClaudeAgentClient implements AgentClient {
+    readonly provider: "claude";
+    readonly capabilities: AgentCapabilityFlags;
+    private readonly defaults?;
+    private readonly logger;
+    private readonly runtimeSettings?;
+    private readonly queryFactory?;
+    private readonly resolveBinary;
+    private readonly configDir?;
+    constructor(options: ClaudeAgentClientOptions);
+    createSession(config: AgentSessionConfig, launchContext?: AgentLaunchContext, options?: AgentCreateSessionOptions): Promise<AgentSession>;
+    resumeSession(handle: AgentPersistenceHandle, overrides?: Partial<AgentSessionConfig>, launchContext?: AgentLaunchContext): Promise<AgentSession>;
+    fetchCatalog(_options: FetchCatalogOptions): Promise<ProviderCatalog>;
+    listFeatures(config: AgentSessionConfig): Promise<AgentFeature[]>;
+    listImportableSessions(options?: ListImportableSessionsOptions): Promise<ImportableProviderSession[]>;
+    importSession(input: ImportProviderSessionInput, context: ImportProviderSessionContext): Promise<import("../../agent-sdk-types.js").ImportedProviderSession>;
+    isAvailable(): Promise<boolean>;
+    /**
+     * Story 4.1 — Detailed availability with rebuild diagnostic. The public
+     * `isAvailable()` keeps its Promise<boolean> contract (AgentClient interface);
+     * tests and `getDiagnostic()` consume this for the rebuild hint.
+     */
+    checkAvailability(): Promise<{
+        available: boolean;
+        reason?: string;
+    }>;
+    getDiagnostic(): Promise<{
+        diagnostic: string;
+    }>;
+    private assertConfig;
+}
+export declare class ClaudeAgentSession implements AgentSession {
+    readonly provider: "claude";
+    readonly capabilities: AgentCapabilityFlags;
+    private readonly config;
+    private readonly launchEnv?;
+    private readonly agentId?;
+    private readonly defaults?;
+    private readonly runtimeSettings?;
+    private readonly persistSession?;
+    private readonly logger;
+    private readonly queryFactory?;
+    private readonly resolveBinary;
+    private query;
+    private childProcess;
+    private input;
+    private claudeSessionId;
+    private persistence;
+    private currentMode;
+    private planResumeMode;
+    private availableModes;
+    private toolUseCache;
+    private toolUseIndexToId;
+    private toolUseInputBuffers;
+    private pendingPermissions;
+    private activeForegroundTurnId;
+    private autonomousTurn;
+    private readonly subscribers;
+    private readonly timelineAssembler;
+    private readonly sidechainTracker;
+    private readonly backgroundTaskTracker;
+    private persistedHistory;
+    private historyPending;
+    private turnState;
+    private nextTurnOrdinal;
+    private cancelCurrentTurn;
+    private cachedRuntimeInfo;
+    private lastOptionsModel;
+    private lastRuntimeModel;
+    private compacting;
+    private queryPumpPromise;
+    private queryRestartNeeded;
+    activeTransport: AgentTransport | null;
+    private resolvedTransport;
+    private claudeVersion;
+    private transportSpawnedTelemetryFired;
+    private pendingInterruptAbort;
+    private foregroundHasVisibleActivity;
+    private activeTurnHasAssistantText;
+    private readonly contextUsage;
+    private userMessageIds;
+    private readonly emittedUserMessageIds;
+    private readonly rewindTurnAnchors;
+    private pendingFreshSessionId;
+    private cumulativeImageBase64Bytes;
+    private cumulativeImageWarnEmitted;
+    private recentStderr;
+    private closed;
+    private readonly hookEventHandlers;
+    /**
+     * Register a hook event handler for an agent. Stub in Epic 1 — Epic 3 wires
+     * incoming hook events from the PTY transport into this handler.
+     */
+    registerHookHandler(agentId: string, handler: HookEventHandler): void;
+    unregisterHookHandler(agentId: string): void;
+    constructor(config: ClaudeAgentConfig, options: ClaudeAgentSessionOptions);
+    get id(): string | null;
+    get features(): AgentFeature[];
+    getRuntimeInfo(): Promise<AgentRuntimeInfo>;
+    run(prompt: AgentPromptInput, options?: AgentRunOptions): Promise<AgentRunResult>;
+    startTurn(prompt: AgentPromptInput, _options?: AgentRunOptions): Promise<{
+        turnId: string;
+    }>;
+    subscribe(callback: (event: AgentStreamEvent) => void): () => void;
+    interrupt(): Promise<void>;
+    streamHistory(): AsyncGenerator<AgentStreamEvent>;
+    getAvailableModes(): Promise<AgentMode[]>;
+    getCurrentMode(): Promise<string | null>;
+    setMode(modeId: string): Promise<void>;
+    setModel(modelId: string | null): Promise<void>;
+    setThinkingOption(thinkingOptionId: string | null): Promise<void | AgentProviderNotice>;
+    /**
+     * Story 3.3 — PTY-path session reload hook.
+     *
+     * On the PTY transport, runtime config changes that require a respawn (e.g.
+     * permission mode) call this method. Default impl is a no-op stub so the
+     * unit tests can `vi.spyOn(session, "reloadAgentSession")` to assert the
+     * branch fires. The full integration is wired by agent-manager in a later
+     * story; until then this method updates the in-session `currentMode` so the
+     * next ensureQuery() rebuild picks up the new mode.
+     */
+    reloadAgentSession(opts?: {
+        overrides?: {
+            permissionMode?: PermissionMode;
+        };
+    }): Promise<void>;
+    setFeature(featureId: string, value: unknown): Promise<void>;
+    private applyFastModeFeature;
+    getPendingPermissions(): AgentPermissionRequest[];
+    getActiveBackgroundTaskCount(): number;
+    /**
+     * Dismiss live background shell(s) the way a human would in the Claude Code
+     * CLI: drive Claude Code's own TUI over the PTY with its `ctrl+x ctrl+k` kill
+     * chord (sent twice — arm + confirm), killing the shell INSIDE Claude Code
+     * rather than via an external OS kill. Then clear our tracked set.
+     *
+     * Caveat: `ctrl+x ctrl+k` is Claude Code's *global* stop-background-work
+     * chord (no per-shell-by-id interactive binding exists), so we clear the
+     * whole set afterward. `taskId` is accepted for API symmetry/logging.
+     *
+     * Returns true if keystrokes were delivered to a live PTY-driven session. On
+     * the SDK transport (no TUI to drive) it falls back to untracking the id.
+     */
+    dismissBackgroundTask(taskId: string): Promise<boolean>;
+    respondToPermission(requestId: string, response: AgentPermissionResponse): Promise<void>;
+    describePersistence(): AgentPersistenceHandle | null;
+    close(): Promise<void>;
+    listCommands(): Promise<AgentSlashCommand[]>;
+    revertConversation(input: {
+        messageId: string;
+    }): Promise<void>;
+    revertFiles(input: {
+        messageId: string;
+    }): Promise<void>;
+    revertBoth(input: {
+        messageId: string;
+    }): Promise<void>;
+    private resolveSlashCommandInvocation;
+    private parseSlashCommandInput;
+    private buildRewindSuccessMessage;
+    private attemptRewind;
+    private rewindFilesOnce;
+    private ensureFreshQuery;
+    private getRewindCandidateUserMessageIds;
+    private rebindConversationSession;
+    private startFreshConversationSession;
+    private rememberUserMessageId;
+    /**
+     * Story 4.1 — Resolve the effective transport for this session and cache it.
+     * Called once per session lifetime; further calls return the cached value.
+     * Epic 3 wiring will use this to choose between SdkTransport and PtyTransport.
+     */
+    ensureTransport(): "sdk" | "pty";
+    /**
+     * Story 4.4 — Fire `agent.transport.spawned` once per session. Probes
+     * `claude --version` in the background; emits with `version: "unknown"` if
+     * the probe is not yet resolved or fails. Never throws.
+     */
+    private fireTransportSpawnedTelemetry;
+    private rememberEmittedUserMessageId;
+    private rememberRewindUserAnchor;
+    private rememberRewindAssistantAnchor;
+    private rememberTranscriptProgress;
+    private resolveClaudeMessageId;
+    private resolveConversationRewindTarget;
+    private ensureQuery;
+    private awaitWithTimeout;
+    private resolveThinkingConfig;
+    private buildAppendedSystemPrompt;
+    private buildSdkEnv;
+    private buildOptions;
+    private buildSettingsOptions;
+    private resolveFastModeSetting;
+    private normalizeMcpServers;
+    private toSdkUserMessage;
+    private enforceCumulativeImageBudget;
+    private transitionTurnState;
+    private syncTurnState;
+    private isAbortError;
+    private buildTurnFailedEvent;
+    private captureStderr;
+    private clearRecentStderr;
+    private getRecentStderrDiagnostic;
+    private awaitRecentStderrAfterProcessExit;
+    private createTurnId;
+    private isTerminalTurnEvent;
+    private executeRewindTurn;
+    private shouldRecoverInterruptedQueryAbort;
+    private finishForegroundTurn;
+    private dispatchEvents;
+    private startAutonomousTurn;
+    private completeAutonomousTurn;
+    private failActiveTurns;
+    private startQueryPump;
+    private runQueryPump;
+    private shouldSuppressStaleResult;
+    private isAssistantishMessage;
+    private routeSdkMessageFromPump;
+    private buildPumpedMessageEvents;
+    private handleMissingResumedConversation;
+    private interruptActiveTurn;
+    private translateMessageToEvents;
+    private emitSubmittedUserMessage;
+    private appendSystemMessageEvents;
+    private appendTaskNotificationEvents;
+    private appendUserMessageEvents;
+    private appendUserContentArrayEvents;
+    private appendStreamEventEvents;
+    private appendResultEvents;
+    private createClaudeSessionChangedNotice;
+    private captureSessionIdFromMessage;
+    private handleSystemMessage;
+    private readMissingResumedConversationError;
+    private convertUsage;
+    private handlePermissionRequest;
+    private enqueueTimeline;
+    private flushPendingToolCalls;
+    private pushToolCall;
+    private pushEvent;
+    private notifySubscribers;
+    private normalizePermissionUpdates;
+    private rejectAllPendingPermissions;
+    private loadPersistedHistory;
+    private ingestPersistedHistory;
+    private ingestPersistedHistoryLine;
+    private resolveHistoryPath;
+    private convertHistoryEntry;
+    private mapBlocksToTimeline;
+    private appendTextBlockToTimeline;
+    private mapBlockToTimeline;
+    private handleToolUseStart;
+    private handleToolResult;
+    /**
+     * A backgrounded Bash ("Bash" with run_in_background) returns its handle
+     * immediately — "Command running in background with ID: <id>" — so its
+     * tool_result is the START signal for a shell that will outlive the turn.
+     */
+    private trackBackgroundShellStart;
+    private buildToolOutput;
+    private isCommandExecutionTool;
+    private static isFileWriteTool;
+    private static isFileEditTool;
+    private static isFileReadTool;
+    private buildStructuredToolResult;
+    private updatePartialEventToolState;
+    private mapPartialEvent;
+    private upsertToolUseEntry;
+    private handleToolInputDelta;
+    private normalizeToolInput;
+    private areToolInputsEqual;
+    private applyToolInput;
+    private isCommandTool;
+    private extractCommandText;
+    private extractFileChanges;
+    private detectFileKind;
+    private relativizePath;
+    private parsePatchFileList;
+}
+interface ClaudeHistoryEntry {
+    type?: unknown;
+    subtype?: unknown;
+    isCompactSummary?: unknown;
+    isSidechain?: unknown;
+    uuid?: unknown;
+    message?: {
+        content?: unknown;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export declare function convertClaudeHistoryEntry(entry: ClaudeHistoryEntry, mapBlocks: (content: string | ClaudeContentChunk[]) => AgentTimelineItem[]): AgentTimelineItem[];
+export {};
+//# sourceMappingURL=agent.d.ts.map