@hyperdrive.bot/fleet-server 0.3.99

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

@@ -0,0 +1,491 @@
+import { type AgentDefinition, type McpServerConfig as ClaudeSdkMcpServerConfig, type PermissionMode, type SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { Logger } from "pino";
+import { type ClaudeBackgroundTaskRecord } from "./background-task-tracker.js";
+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 AgentBackgroundTaskOutput, 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;
+    readonly supportsToolAllowlist = true;
+    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;
+}
+/**
+ * Tool names whose tool_result can ANNOUNCE background work that outlives the turn.
+ *
+ * This gate is the reason the tracker sees anything at all. It was previously
+ * `toolName !== "Bash"`, which made the monitor and cron start-patterns in
+ * `background-task-tracker.ts` unreachable: a `Monitor` tool_result returned
+ * here before `noteToolResultText` was ever called, so a monitor-only session
+ * reported zero background tasks, bucketed as "done", and kept lighting the
+ * unread chip on every tick.
+ *
+ * ⚠️ The parser having a pattern is NOT enough — the tool name must be in this
+ * set too. Any new kind of background work needs BOTH, and an integration test
+ * that drives `handleToolResult` (not the parser directly), or the same hole
+ * reopens silently. See `background-work-kinds.ts`.
+ */
+export declare const BACKGROUND_WORK_TOOL_NAMES: Set<string>;
+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;
+    /** Permission id currently standing in for a PTY TUI dialog, if any. */
+    private ptyDialogRequestId;
+    /** tool_use id of the dialog the card above represents; see handlePtyDialogChange. */
+    private ptyDialogToolUseId;
+    private activeForegroundTurnId;
+    private autonomousTurn;
+    private readonly subscribers;
+    private readonly timelineAssembler;
+    private readonly sidechainTracker;
+    private readonly backgroundTaskTracker;
+    /**
+     * True only while an already-persisted transcript is being replayed.
+     *
+     * Replay walks the SAME `handleToolResult` path as a live turn, so every
+     * background-shell announcement in history was being re-registered as live
+     * work on every resume - and the replay path never reaches
+     * `noteTaskNotification`, so none of it could ever retire. A transcript with
+     * 268 announcements therefore resurrected 268 immortal tasks per restart.
+     *
+     * A shell announced in persisted history is by definition not this process's
+     * live work: background shells are children of the CLI that started them and
+     * die with it. Anything genuinely still running announces itself on the live
+     * stream. Set around a fully synchronous read, so nothing interleaves.
+     */
+    private replayingPersistedHistory;
+    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;
+    /**
+     * Pairs the ids paseo mints with the uuids claude writes to the transcript, so Edit and
+     * Rewind can resolve a turn on the PTY transport. See TurnIdReconciler.
+     */
+    private readonly turnIdReconciler;
+    private readonly rewindTurnAnchors;
+    private pendingFreshSessionId;
+    /**
+     * Parsed per-run tool allowlist. Empty array = no allowlist configured, which
+     * is the historical behaviour (everything the permission mode permits runs).
+     */
+    private readonly toolAllowRules;
+    /** PTY-transport guard files for the current session; removed on teardown. */
+    private toolAllowGuard;
+    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;
+    private rememberMintedPrompt;
+    /**
+     * Called for each plain user prompt claude writes to the transcript. Identity only: the
+     * message was already rendered from the mint, and re-emitting would double the bubble.
+     * See TranscriptSdkReader#onUserPrompt.
+     */
+    private onTranscriptUserPrompt;
+    /** Map a turn id the app sent onto one that exists in this session's transcript. */
+    resolveTranscriptTurnId(turnId: string): string;
+    /**
+     * This session's terminal screen as tmux currently renders it, or null when there is none
+     * to read.
+     *
+     * Null is the normal answer, not an error: it is what an SDK-transport session returns
+     * (there is no terminal at all), and what a PTY session without `PASEO_PTY_TMUX=1`
+     * returns (there is a pty, but nothing holding a rendered screen to ask). The client
+     * shows the pane affordance only where this comes back non-null, so the distinction has
+     * to survive as a value rather than an exception.
+     */
+    capturePane(options?: {
+        ansi?: boolean;
+        scrollbackLines?: number;
+    }): Promise<string | null>;
+    /**
+     * 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;
+    /**
+     * Install the per-run tool allowlist as a `PreToolUse` hook on the SDK options.
+     *
+     * Deliberately NOT `options.allowedTools`: that field is a permission ALLOW rule
+     * (pre-approve, do not prompt), and this session also sets
+     * allowDangerouslySkipPermissions, under which permission rules are moot. A
+     * PreToolUse hook is the only gate that still fires; the SDK says so outright
+     * ("PreToolUse hook denies bypass canUseTool"). Applied last so an
+     * `extra.claude.hooks` override cannot displace it.
+     */
+    private applyToolAllowlistHook;
+    /**
+     * PTY-transport half of allowlist enforcement: (re)generate the hook script and
+     * the `--settings` file that registers it.
+     *
+     * Returns a spreadable fragment (`{}` when no allowlist is configured) so the
+     * caller stays branch-free. Regenerated per spawn because a session can restart
+     * (mode swap, model swap, rewind) and the artifacts are keyed to the session id.
+     */
+    private refreshToolAllowGuard;
+    /**
+     * SDK-transport half of allowlist enforcement. The PTY transport enforces the
+     * same rules through a generated hook script (see tool-allowlist-guard.ts);
+     * both call `isToolAllowed`, so the two transports cannot diverge.
+     */
+    private enforceToolAllowlistHook;
+    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;
+    /**
+     * Raise (and retract) a permission request for a dialog the PTY's TUI is showing.
+     *
+     * The SDK path gets these through `canUseTool`, which is how the app renders a real
+     * question card with its options. The PTY path has no such hook - the TUI owns the
+     * dialog - so before this the app only saw an inert `AskUserQuestion` tool chip and the
+     * session sat waiting with nothing to tap (observed live: 11h51m). Surfacing the same
+     * request shape reuses the app's existing question UI, and the answer is played back
+     * into the terminal as the dialog's own keystrokes.
+     *
+     * Scoped to questions on purpose: a plan dialog's options are the CLI's and version-
+     * dependent, so guessing an index there could approve an implementation nobody chose.
+     */
+    /**
+     * Surface a delivery-path notice to whoever sent the message.
+     *
+     * Uses the same synthetic-timeline-message channel executeRewindTurn() already uses, so
+     * this needs no protocol change and renders in every client that renders a turn today.
+     * The alternative, PtyQuery.emit(), is the SDK message stream, where the only shapes
+     * available are `result` messages -- and a result ENDS the turn, which is the opposite
+     * of what a "still queued" notice means.
+     */
+    private emitPtyNotice;
+    /**
+     * Retract whatever question card is currently up, if any. Returns silently when there
+     * is none. Split out of handlePtyDialogChange so a SUPERSEDING dialog can clear the
+     * previous one instead of being dropped by the latch.
+     */
+    private retractPtyDialogCard;
+    private handlePtyDialogChange;
+    /** Map the app's chosen answer back to the dialog's option index and press the keys. */
+    private answerPtyDialogFromPermission;
+    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.
+     *
+     * The result text carries the id and the output-file path; the COMMAND lives
+     * on the matching tool_use, which we still hold in the cache at this point.
+     * Both go into the record so the UI can show what is actually running.
+     */
+    private trackBackgroundShellStart;
+    /**
+     * Every background shell this agent owns — live ones first, then a bounded
+     * tail of recently finished ones so their output stays reachable.
+     */
+    listBackgroundTasks(): ClaudeBackgroundTaskRecord[];
+    /**
+     * Read a background shell's output back off disk. The harness streams each
+     * backgrounded command into its own file and announces the path in the
+     * tool_result, so this is the artifact, not a scrape of the terminal.
+     *
+     * Returns null when the id is unknown or never announced a file. Output is
+     * tailed (last `maxBytes`) and redacted before it leaves the daemon.
+     */
+    readBackgroundTaskOutput(taskId: string, options?: {
+        maxBytes?: number;
+    }): Promise<AgentBackgroundTaskOutput | null>;
+    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