@rallycry/conveyor-agent 6.4.2 → 7.0.1

package/dist/index.d.ts

@@ -1,303 +1,272 @@
 import * as _project_shared from '@project/shared';
-import { AgentRunnerStatus, MultimodalBlock, ProjectEnvironmentStatus, ChatMessageResponse, TaskFileResponse, TaskContext, AgentEvent, AgentQuestion, IncomingMessagePayload, SetModePayload, AgentMode, SubtaskCreatePayload, SubtaskUpdateFields, SubtaskResponse, StartChildCloudBuildResponse, TaskLookupResponse, UpdateTaskPropertiesPayload, IconListItem, GenerateIconResponse, TaskPropertiesResponse, TriggerIdentificationResponse, ModeTransitionPayload, DebugSessionState, DebugSessionSummary, IncidentDTO, TaskIncidentDTO, ResourceTierName, ScaleUpResponse, TaskDependencySummary, QueryGcpLogsResponse, TagAuditRunnerRequest, TagAuditRunnerResponse, TagAuditProgressActivity, DebugTelemetryEvent } from '@project/shared';
-export { AgentEvent, ChatMessage, DebugBreakpointHit, DebugModeEvent, TaskContext, TaskFileContext } from '@project/shared';
+import { AgentSessionServiceMethods, AgentMode, AgentQuestion, AgentRunnerStatus, DebugTelemetryEvent, DebugSessionSummary } from '@project/shared';
+export * from '@project/shared';
 import { ChildProcess } from 'node:child_process';
 
-/**
- * Harness-neutral types for agent query execution.
- *
- * These types abstract the underlying agent SDK so that the runner,
- * execution, and tool layers never reference SDK-specific imports
- * directly.  The only place that should import from
- * `@anthropic-ai/claude-agent-sdk` is `harness/claude-code/`.
- */
-
-interface HarnessUserMessage {
-    type: "user";
-    session_id: string;
-    message: {
-        role: "user";
-        content: string | unknown[];
-    };
-    parent_tool_use_id: null;
+interface ModelUsageEntry {
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+    costUSD: number;
 }
 
-interface AgentRunnerConfig {
-    conveyorApiUrl: string;
+interface AgentConnectionConfig {
+    apiUrl: string;
     taskToken: string;
-    taskId: string;
-    model: string;
-    instructions: string;
-    workspaceDir: string;
-    mode?: _project_shared.RunnerMode;
-    isAuto?: boolean;
-    agentSettings?: _project_shared.AgentSettings;
+    sessionId: string;
+    runnerMode?: "task" | "pm" | "code-review";
 }
-interface AgentRunnerCallbacks {
-    onEvent: (event: _project_shared.AgentEvent) => void | Promise<void>;
-    onStatusChange: (status: _project_shared.AgentRunnerStatus) => void | Promise<void>;
+interface IncomingMessage {
+    content: string;
+    userId: string;
+    files?: Array<{
+        name: string;
+        content: string;
+        mimeType?: string;
+    }>;
 }
-
-declare class AgentRunner {
-    private config;
-    private connection;
-    private callbacks;
-    private _state;
-    private stopped;
-    private interrupted;
-    private inputResolver;
-    private pendingMessages;
-    private setupLog;
-    private heartbeatTimer;
-    private taskContext;
-    private planSync;
-    private costTracker;
-    private worktreeActive;
-    private agentMode;
-    private hasExitedPlanMode;
-    private pendingModeRestart;
-    private pendingModeAutoStart;
-    private sessionIds;
-    private lastQueryModeRestart;
-    private startCommandStarted;
-    private prNudgeCount;
-    private idleTimer;
-    private idleCheckInterval;
-    private conveyorConfig;
-    private _queryHost;
-    private tunnelClient;
-    private harness;
-    constructor(config: AgentRunnerConfig, callbacks: AgentRunnerCallbacks);
-    get state(): AgentRunnerStatus;
-    private get effectiveAgentMode();
-    private setState;
-    private startHeartbeat;
-    private stopHeartbeat;
-    private clearIdleTimers;
-    start(): Promise<void>;
-    private tryInitWorktree;
-    private fetchAndInitContext;
-    /**
-     * For auto-mode tasks, bypass planning if the task is already past Planning
-     * or if it's still in Planning but has all required properties set (e.g. from
-     * a prior PM discovery session).
-     */
-    private tryAutoModeBypass;
-    private transitionToBuilding;
-    private tryPostContextWorktree;
-    private startPreviewTunnel;
-    private activateWorktree;
-    private checkoutWorktreeBranch;
-    private needsPRNudge;
-    private maybeSendPRNudge;
-    private sendPRNudgeQuery;
-    private executeInitialMode;
-    private runQuerySafe;
-    private handleModeRestartCycle;
-    private runCoreLoop;
-    private handleRunStartCommand;
-    private logEffectiveSettings;
-    private injectHumanMessage;
-    private waitForMessage;
-    private waitForUserContent;
-    createInputStream(initialPrompt: string | MultimodalBlock[]): AsyncGenerator<HarnessUserMessage, void, unknown>;
-    private asQueryHost;
-    private lastAnnouncedMode;
-    private handleModeChange;
-    private updateExitedPlanModeFlag;
-    softStop(): void;
-    stop(): void;
+interface SetModeData {
+    agentMode: AgentMode;
 }
-
-interface ProjectRunnerConfig {
-    conveyorApiUrl: string;
-    projectToken: string;
-    projectId: string;
-    projectDir: string;
+interface ApiKeyUpdateData {
+    apiKey: string;
+    isSubscription?: boolean;
 }
-declare class ProjectRunner {
-    private connection;
-    private projectDir;
-    private activeAgents;
-    private heartbeatTimer;
-    private stopping;
-    private resolveLifecycle;
-    private chatSessionIds;
-    private startCommandChild;
-    private startCommandRunning;
-    private setupComplete;
-    private branchSwitchCommand;
-    private commitWatcher;
-    constructor(config: ProjectRunnerConfig);
-    private checkoutWorkspaceBranch;
-    private executeSetupCommand;
-    private executeStartCommand;
-    killStartCommand(): Promise<void>;
-    restartStartCommand(): Promise<void>;
-    getEnvironmentStatus(): ProjectEnvironmentStatus;
-    private getCurrentBranch;
-    private smartSync;
-    private handleSwitchBranch;
-    private handleSyncEnvironment;
-    private handleGetEnvStatus;
-    start(): Promise<void>;
-    private setupSignalHandlers;
-    private handleAssignment;
-    private handleStopTask;
-    stop(): Promise<void>;
-}
-
-declare class ConveyorConnection {
+declare class AgentConnection {
     private socket;
-    private config;
+    private readonly config;
     private eventBuffer;
     private flushTimer;
     private lastEmittedStatus;
-    private static readonly EVENT_BATCH_MS;
     private earlyMessages;
     private earlyStop;
     private earlySoftStop;
     private earlyModeChanges;
-    private chatMessageCallback;
+    private messageCallback;
     private stopCallback;
     private softStopCallback;
     private modeChangeCallback;
-    private runStartCommandCallback;
-    private pendingQuestionResolvers;
-    constructor(config: AgentRunnerConfig);
+    private wakeCallback;
+    private apiKeyUpdateCallback;
+    constructor(config: AgentConnectionConfig);
+    get sessionId(): string;
+    get connected(): boolean;
+    call<M extends keyof AgentSessionServiceMethods>(method: M, payload: AgentSessionServiceMethods[M]["payload"]): Promise<AgentSessionServiceMethods[M]["response"]>;
     connect(): Promise<void>;
-    fetchChatMessages(limit?: number, taskId?: string): Promise<ChatMessageResponse[]>;
-    fetchTaskFiles(): Promise<TaskFileResponse[]>;
-    fetchTaskFile(fileId: string): Promise<TaskFileResponse>;
-    fetchTaskContext(): Promise<TaskContext>;
-    sendEvent(event: AgentEvent): void;
-    flushEvents(): void;
-    updateStatus(status: string): void;
+    disconnect(): void;
+    onMessage(callback: (msg: IncomingMessage) => void): void;
+    onStop(callback: () => void): void;
+    onSoftStop(callback: () => void): void;
+    onModeChange(callback: (data: SetModeData) => void): void;
+    onWake(callback: () => void): void;
+    onApiKeyUpdate(callback: (data: ApiKeyUpdateData) => void): void;
+    emitStatus(status: string): void;
     postChatMessage(content: string): void;
-    createPR(params: {
-        title: string;
-        body: string;
-        baseBranch?: string;
-        branch?: string;
-    }): Promise<{
-        url: string;
-        number: number;
-    }>;
-    askUserQuestion(requestId: string, questions: AgentQuestion[]): Promise<Record<string, string>>;
-    cancelPendingQuestions(): void;
-    storeSessionId(sessionId: string): void;
+    sendHeartbeat(): void;
+    emitModeChanged(agentMode?: AgentMode | null): void;
     updateTaskFields(fields: {
         plan?: string;
         description?: string;
     }): void;
-    onChatMessage(callback: (message: IncomingMessagePayload) => void): void;
-    onStopRequested(callback: () => void): void;
-    onSoftStopRequested(callback: () => void): void;
-    onModeChange(callback: (data: SetModePayload) => void): void;
-    onRunStartCommand(callback: () => void): void;
-    private handleRunAuthTokenCommand;
-    emitModeChanged(agentMode?: AgentMode | null): void;
+    storeSessionId(sdkSessionId: string): void;
+    sendTypingStart(): void;
+    sendTypingStop(): void;
     trackSpending(params: {
         agentId: string;
         sessionId: string;
         totalCostUsd: number;
         onSubscription: boolean;
-        modelUsage?: {
-            model: string;
-            inputTokens: number;
-            outputTokens: number;
-            cacheReadInputTokens: number;
-            cacheCreationInputTokens: number;
-            costUSD: number;
-        }[];
+        modelUsage?: ModelUsageEntry[];
     }): void;
-    emitStatus(status: string): void;
     emitRateLimitPause(resetsAt: string): void;
-    sendHeartbeat(): void;
-    sendTypingStart(): void;
-    sendTypingStop(): void;
-    createSubtask(data: SubtaskCreatePayload): Promise<{
-        id: string;
-    }>;
-    updateSubtask(subtaskId: string, fields: SubtaskUpdateFields): void;
-    deleteSubtask(subtaskId: string): void;
-    listSubtasks(): Promise<SubtaskResponse[]>;
-    fetchCliHistory(taskId?: string, limit?: number, source?: string): Promise<{
-        event: AgentEvent;
-        time: string;
-    }[]>;
-    startChildCloudBuild(childTaskId: string): Promise<StartChildCloudBuildResponse>;
-    approveAndMergePR(childTaskId: string): Promise<{
-        merged: boolean;
-        queued?: boolean;
-        childTaskId: string;
-        prNumber: number;
-    }>;
-    postChildChatMessage(childTaskId: string, content: string): Promise<void>;
-    updateChildStatus(childTaskId: string, status: string): Promise<void>;
-    stopChildBuild(childTaskId: string): Promise<void>;
-    fetchTask(slugOrId: string): Promise<TaskLookupResponse>;
-    updateTaskProperties(data: UpdateTaskPropertiesPayload): void;
-    listIcons(): Promise<IconListItem[]>;
-    generateTaskIcon(prompt: string, aspectRatio?: "auto" | "portrait" | "landscape" | "square"): Promise<GenerateIconResponse>;
-    getTaskProperties(): Promise<TaskPropertiesResponse>;
-    triggerIdentification(): Promise<TriggerIdentificationResponse>;
-    refreshAuthToken(): Promise<boolean>;
-    emitModeTransition(payload: ModeTransitionPayload): void;
-    emitDebugStateChanged(state: DebugSessionState): void;
-    emitDebugSessionComplete(summary: DebugSessionSummary): void;
-    emitDebugReproduceRequested(hypothesis?: string): void;
+    updateStatus(status: string): void;
     emitCodeReviewResult(content: string, approved: boolean): void;
-    searchIncidents(status?: string, source?: string): Promise<IncidentDTO[]>;
-    getTaskIncidents(taskId?: string): Promise<TaskIncidentDTO[]>;
-    requestScaleUp(tier: ResourceTierName, reason?: string): Promise<ScaleUpResponse>;
-    addDependency(dependsOnSlugOrId: string): Promise<void>;
-    removeDependency(dependsOnSlugOrId: string): Promise<void>;
-    getDependencies(): Promise<TaskDependencySummary[]>;
-    createFollowUpTask(data: {
-        title: string;
-        description?: string;
+    askUserQuestion(questions: AgentQuestion[]): Promise<Record<string, string>>;
+    getTaskProperties(): Promise<{
         plan?: string;
-        storyPointValue?: number;
-    }): Promise<{
-        id: string;
-        slug: string;
+        storyPointId?: string;
+        title?: string;
     }>;
-    queryGcpLogs(params: {
-        filter?: string;
-        startTime?: string;
-        endTime?: string;
-        severity?: string;
-        pageSize?: number;
-    }): Promise<QueryGcpLogsResponse>;
-    createSuggestion(title: string, description?: string, tagNames?: string[]): Promise<{
-        id: string;
-        merged: boolean;
-        mergedIntoId?: string;
+    triggerIdentification(): Promise<{
+        identified: boolean;
     }>;
-    voteSuggestion(suggestionId: string, value: 1 | -1): Promise<{
-        score: number;
+    requestScaleUp(tier: string, reason?: string): Promise<{
+        scaled: boolean;
     }>;
-    getSuggestions(status?: string, limit?: number): Promise<Array<{
-        id: string;
-        title: string;
-        description: string | null;
-        score: number;
-        status: string;
-        tags: string[];
-    }>>;
-    disconnect(): void;
+    refreshAuthToken(): Promise<boolean>;
+    sendEvent(event: Record<string, unknown>): void;
+    flushEvents(): void;
+}
+
+type ModeAction = {
+    type: "noop";
+} | {
+    type: "restart_query";
+    newMode: AgentMode;
+} | {
+    type: "soft_stop";
+} | {
+    type: "start_auto";
+};
+interface ModeTaskContext {
+    status: string;
+    plan: string | null;
+    storyPointId: string | null;
+    isParentTask?: boolean;
+    model: string;
+    builderModel?: string | null;
+    githubPRUrl?: string | null;
+}
+declare class ModeController {
+    private _mode;
+    private _hasExitedPlanMode;
+    private _pendingModeRestart;
+    private _runnerMode;
+    private _isAuto;
+    constructor(initialMode: AgentMode, runnerMode?: "task" | "pm" | "code-review", isAuto?: boolean);
+    get mode(): AgentMode;
+    get hasExitedPlanMode(): boolean;
+    set hasExitedPlanMode(val: boolean);
+    get pendingModeRestart(): boolean;
+    set pendingModeRestart(val: boolean);
+    /** Effective mode accounting for PM/task defaults */
+    get effectiveMode(): AgentMode;
+    get isReadOnly(): boolean;
+    get isAutoPlanning(): boolean;
+    get isBuildCapable(): boolean;
+    /** Resolve the initial mode based on task context */
+    resolveInitialMode(context: ModeTaskContext): AgentMode;
+    /** Check if auto-mode can bypass planning (task already has plan + properties) */
+    canBypassPlanning(context: ModeTaskContext): boolean;
+    /** Handle mode change from server */
+    handleModeChange(newMode: AgentMode): ModeAction;
+    /** Handle ExitPlanMode call from the agent */
+    handleExitPlanMode(context: ModeTaskContext): ModeAction;
+    /** Check if pack runner behavior should be used */
+    isPackRunner(context: ModeTaskContext): boolean;
+    private transitionToBuilding;
+    private updateExitedPlanModeFlag;
+}
+
+interface LifecycleConfig {
+    /** Idle timeout before entering sleep mode (default: 30 min) */
+    idleTimeoutMs: number;
+    /** Grace period after sleep announcement before shutdown (default: 5s) */
+    sleepGracePeriodMs: number;
+    /** Heartbeat interval (default: 30s) */
+    heartbeatIntervalMs: number;
+}
+interface LifecycleCallbacks {
+    onHeartbeat: () => void;
+    onIdleTimeout: () => void;
+    onSleep: () => void;
+    onSleepGraceExpired: () => void;
+    onWake: () => void;
+}
+/** 30 min idle, 5s sleep grace, 30s heartbeat */
+declare const DEFAULT_LIFECYCLE_CONFIG: LifecycleConfig;
+declare class Lifecycle {
+    private readonly config;
+    private readonly callbacks;
+    private heartbeatTimer;
+    private idleTimer;
+    private idleCheckInterval;
+    private sleepShutdownTimer;
+    private _isSleeping;
+    constructor(config: LifecycleConfig, callbacks: LifecycleCallbacks);
+    get isSleeping(): boolean;
+    startHeartbeat(): void;
+    stopHeartbeat(): void;
+    startIdleTimer(): void;
+    cancelIdleTimer(): void;
+    private enterSleepMode;
+    /** Wake from sleep — cancels shutdown timer, resets idle */
+    wake(): void;
+    /** Cancel the sleep shutdown timer (e.g. when a message arrives) */
+    cancelSleepShutdown(): void;
+    destroy(): void;
+    private clearIdleTimers;
+}
+
+interface SessionRunnerConfig {
+    connection: AgentConnectionConfig;
+    agentMode?: AgentMode;
+    runnerMode?: "task" | "pm" | "code-review";
+    isAuto?: boolean;
+    workspaceDir: string;
+    model?: string;
+    lifecycle?: Partial<LifecycleConfig>;
+}
+interface SessionRunnerCallbacks {
+    onStatusChange: (status: AgentRunnerStatus) => void | Promise<void>;
+    onEvent: (event: Record<string, unknown>) => void | Promise<void>;
+}
+declare class SessionRunner {
+    readonly connection: AgentConnection;
+    readonly mode: ModeController;
+    readonly lifecycle: Lifecycle;
+    private readonly config;
+    private readonly callbacks;
+    private _state;
+    private stopped;
+    private interrupted;
+    private taskContext;
+    private fullContext;
+    private queryBridge;
+    private inputResolver;
+    private pendingMessages;
+    private prNudgeCount;
+    constructor(config: SessionRunnerConfig, callbacks: SessionRunnerCallbacks);
+    get state(): AgentRunnerStatus;
+    get sessionId(): string;
+    get isStopped(): boolean;
+    start(): Promise<void>;
+    private coreLoop;
+    private executeInitialMode;
+    private waitForMessage;
+    /** Inject a message (from connection callback or external source) */
+    injectMessage(msg: IncomingMessage): void;
+    stop(): void;
+    softStop(): void;
+    private static readonly MAX_PR_NUDGES;
+    private needsPRNudge;
+    private refreshTaskContext;
+    private maybeSendPRNudge;
+    private buildFullContext;
+    private createQueryBridge;
+    private wireConnectionCallbacks;
+    private setState;
+    private shutdown;
+    private logInitialization;
+}
+
+interface AgentRunnerConfig {
+    conveyorApiUrl: string;
+    taskToken: string;
+    taskId: string;
+    model: string;
+    instructions: string;
+    workspaceDir: string;
+    mode?: _project_shared.RunnerMode;
+    isAuto?: boolean;
+    agentSettings?: _project_shared.AgentSettings;
+}
+interface AgentRunnerCallbacks {
+    onEvent: (event: Record<string, unknown>) => void | Promise<void>;
+    onStatusChange: (status: string) => void | Promise<void>;
 }
 
 interface ProjectConnectionConfig {
     apiUrl: string;
     projectToken: string;
     projectId: string;
-    projectDir?: string;
 }
 interface TaskAssignment {
     taskId: string;
     taskToken: string;
+    sessionId?: string;
     apiUrl: string;
     mode: string;
     branch: string;
@@ -311,151 +280,106 @@ interface IncomingChatMessage {
     content: string;
     userId: string;
     chatId?: string;
-    files?: {
-        id: string;
-        fileName: string;
-        mimeType: string;
-        downloadUrl: string;
-        content?: string;
-        contentEncoding?: "base64" | "utf-8";
-    }[];
-}
-interface ChatHistoryMessage {
-    role: string;
-    content: string;
-    userId: string | null;
-    userName?: string;
-    createdAt: string;
-}
-interface AgentContext {
-    projectName: string;
-    projectDescription: string | null;
-    agentId: string | null;
-    agentName: string | null;
-    agentInstructions: string;
-    model: string;
-    agentSettings: Record<string, unknown> | null;
-    branchSwitchCommand?: string;
-}
-type SwitchBranchCallback = (res: {
-    ok: boolean;
-    data?: _project_shared.ProjectEnvironmentStatus;
-    error?: string;
-}) => void;
-type SyncEnvironmentCallback = (res: {
-    ok: boolean;
-    data?: _project_shared.ProjectEnvironmentStatus;
-    error?: string;
-}) => void;
-type GetEnvStatusCallback = (res: {
-    ok: boolean;
-    data?: _project_shared.ProjectEnvironmentStatus;
-}) => void;
+    projectId: string;
+    timestamp: string;
+}
+interface SwitchBranchRequest {
+    branch: string;
+    syncAfter?: boolean;
+}
 declare class ProjectConnection {
     private socket;
-    private config;
-    private taskAssignmentCallback;
-    private stopTaskCallback;
-    private shutdownCallback;
-    private chatMessageCallback;
-    private earlyChatMessages;
-    private auditRequestCallback;
-    onSwitchBranch: ((data: {
-        branch: string;
-        syncAfter?: boolean;
-    }, cb: SwitchBranchCallback) => void) | null;
-    onSyncEnvironment: ((cb: SyncEnvironmentCallback) => void) | null;
-    onGetEnvStatus: ((cb: GetEnvStatusCallback) => void) | null;
-    onRestartStartCommand: ((cb: (res: {
-        ok: boolean;
-        error?: string;
-    }) => void) => void) | null;
+    private readonly config;
+    private eventBuffer;
+    private flushTimer;
+    private reconnectCallbacks;
     constructor(config: ProjectConnectionConfig);
+    get projectId(): string;
+    get connected(): boolean;
+    call<M extends keyof AgentSessionServiceMethods>(method: M, payload: AgentSessionServiceMethods[M]["payload"]): Promise<AgentSessionServiceMethods[M]["response"]>;
     connect(): Promise<void>;
+    disconnect(): void;
+    onReconnect(callback: () => void): void;
     onTaskAssignment(callback: (assignment: TaskAssignment) => void): void;
     onStopTask(callback: (data: {
         taskId: string;
     }) => void): void;
     onShutdown(callback: () => void): void;
     onChatMessage(callback: (msg: IncomingChatMessage) => void): void;
-    onAuditRequest(callback: (request: TagAuditRunnerRequest) => void): void;
-    emitAuditResult(data: TagAuditRunnerResponse): void;
-    emitAuditProgress(data: {
-        requestId: string;
-        activity: TagAuditProgressActivity;
-    }): void;
+    onSwitchBranch(callback: (data: SwitchBranchRequest, cb: (res: {
+        ok: boolean;
+        error?: string;
+    }) => void) => void): void;
+    onSyncEnvironment(callback: (cb: (res: {
+        ok: boolean;
+        error?: string;
+    }) => void) => void): void;
+    onRestartStartCommand(callback: (cb: (res: {
+        ok: boolean;
+        error?: string;
+    }) => void) => void): void;
     sendHeartbeat(): void;
+    sendEvent(event: Record<string, unknown>): void;
+    emitStatus(status: "busy" | "idle"): void;
     emitTaskStarted(taskId: string): void;
     emitTaskStopped(taskId: string, reason: string): void;
-    emitEvent(event: Record<string, unknown>): void;
-    emitChatMessage(content: string): Promise<void>;
-    emitAgentStatus(status: string): void;
-    fetchAgentContext(): Promise<AgentContext | null>;
-    fetchChatHistory(limit?: number, chatId?: string): Promise<ChatHistoryMessage[]>;
-    requestListTasks(params: {
-        status?: string;
-        assigneeId?: string;
-        limit?: number;
-    }): Promise<unknown[]>;
-    requestGetTask(taskId: string): Promise<unknown>;
-    requestCreateTask(params: {
-        title: string;
-        description?: string;
-        plan?: string;
-        status?: string;
-        isBug?: boolean;
-    }): Promise<{
-        id: string;
-        slug: string;
-    }>;
-    requestUpdateTask(params: {
-        taskId: string;
-        title?: string;
-        description?: string;
-        plan?: string;
-        status?: string;
-        assignedUserId?: string | null;
-    }): Promise<unknown>;
-    requestSearchTasks(params: {
-        tagNames?: string[];
-        searchQuery?: string;
-        statusFilters?: string[];
-        limit?: number;
-    }): Promise<unknown[]>;
-    requestListTags(): Promise<unknown[]>;
-    requestGetProjectSummary(): Promise<unknown>;
-    private requestWithCallback;
-    emitNewCommitsDetected(data: {
-        branch: string;
-        commitCount: number;
-        latestCommit: {
-            sha: string;
-            message: string;
-            author: string;
-        };
-        autoSyncing: boolean;
-    }): void;
-    emitEnvironmentReady(data: {
-        branch: string;
-        commitsSynced: number;
-        syncDurationMs: number;
-        stepsRun: string[];
-    }): void;
-    emitEnvSwitchProgress(data: {
-        step: string;
-        status: "running" | "success" | "error";
-        message?: string;
-    }): void;
-    private handleRunAuthTokenCommand;
-    disconnect(): void;
+    private flushEvents;
+    private requireSocket;
 }
 
-declare function ensureWorktree(projectDir: string, taskId: string, branch?: string): string;
-/**
- * Force-remove is intentional: this runs after task completion or explicit stop.
- * Any uncommitted changes at this point are scratch artifacts, not valuable work.
- */
-declare function removeWorktree(projectDir: string, taskId: string): void;
+interface ProjectRunnerConfig {
+    conveyorApiUrl: string;
+    projectToken: string;
+    projectId: string;
+    projectDir: string;
+}
+declare class ProjectRunner {
+    private connection;
+    private projectDir;
+    private activeAgents;
+    private heartbeatTimer;
+    private stopping;
+    private resolveLifecycle;
+    private chatSessionIds;
+    private startCommandChild;
+    private startCommandRunning;
+    private setupComplete;
+    private branchSwitchCommand;
+    private commitWatcher;
+    constructor(config: ProjectRunnerConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private wireEventHandlers;
+    private handleReconnect;
+    private handleAssignment;
+    private handleStopTask;
+    private checkoutWorkspaceBranch;
+    private executeSetupCommand;
+    private executeStartCommand;
+    private killStartCommand;
+    private restartStartCommand;
+    private getCurrentBranch;
+    private handleSwitchBranch;
+    private handleSyncEnvironment;
+    private handleNewCommits;
+    private smartSync;
+    private syncDependencies;
+    private runIndividualSyncSteps;
+    private getChangedFiles;
+}
+
+declare class PlanSync {
+    private planFileSnapshot;
+    private lockedPlanFile;
+    private workspaceDir;
+    private connection;
+    constructor(workspaceDir: string, connection: AgentConnection);
+    updateWorkspaceDir(workspaceDir: string): void;
+    private getPlanDirs;
+    snapshotPlanFiles(): void;
+    private findNewestPlanFile;
+    syncPlanFile(): void;
+}
 
 interface CacheEntry {
     content: Buffer;
@@ -481,18 +405,63 @@ declare class FileCache {
     };
 }
 
-interface ConveyorConfig {
-    setupCommand?: string;
-    startCommand?: string;
-    previewPort?: number;
+interface CommitWatcherConfig {
+    projectDir: string;
+    pollIntervalMs: number;
+    debounceMs: number;
+}
+interface NewCommitsData {
+    branch: string;
+    previousSha: string;
+    newCommitSha: string;
+    commitCount: number;
+    latestMessage: string;
+    latestAuthor: string;
 }
+interface CommitWatcherCallbacks {
+    onNewCommits: (data: NewCommitsData) => Promise<void>;
+}
+declare class CommitWatcher {
+    private config;
+    private callbacks;
+    private interval;
+    private lastKnownRemoteSha;
+    private branch;
+    private debounceTimer;
+    private isSyncing;
+    constructor(config: CommitWatcherConfig, callbacks: CommitWatcherCallbacks);
+    start(branch: string): void;
+    stop(): void;
+    private getLocalHeadSha;
+    private poll;
+    private handleNewCommits;
+}
+
+/** Returns true if the working tree has uncommitted changes (staged or unstaged). */
+declare function hasUncommittedChanges(cwd: string): boolean;
+/** Returns the current branch name, or null if on detached HEAD. */
+declare function getCurrentBranch(cwd: string): string | null;
+/** Returns true if there are committed changes that haven't been pushed to origin. */
+declare function hasUnpushedCommits(cwd: string): boolean;
+/** Stage all changes and create a commit. Returns the commit hash if successful. */
+declare function stageAndCommit(cwd: string, message: string): string | null;
+/** Update the git remote URL with a fresh token. */
+declare function updateRemoteToken(cwd: string, token: string): void;
+/** Push current branch to origin. On auth failure, refreshes the GitHub token and retries. */
+declare function pushToOrigin(cwd: string, refreshToken?: () => Promise<string | undefined>): Promise<boolean>;
+
+declare function ensureWorktree(projectDir: string, taskId: string, branch?: string): string;
 /**
- * Load config from env vars (project-level settings injected via bootstrap).
+ * Detach any task worktree that has `branch` checked out, releasing the branch lock
+ * so the main project directory can check it out. Only touches worktrees inside
+ * `.worktrees/` — never the main project directory.
  */
-declare function loadConveyorConfig(_workspaceDir?: string): ConveyorConfig | null;
-
-declare function runSetupCommand(cmd: string, cwd: string, onOutput: (stream: "stdout" | "stderr", data: string) => void): Promise<void>;
-declare function runStartCommand(cmd: string, cwd: string, onOutput: (stream: "stdout" | "stderr", data: string) => void): ChildProcess;
+declare function detachWorktreeBranch(projectDir: string, branch: string): void;
+/**
+ * Force-remove is intentional: this runs after task completion or explicit stop.
+ * Any uncommitted changes at this point are scratch artifacts, not valuable work.
+ */
+declare function removeWorktree(projectDir: string, taskId: string): void;
 
 interface BreakpointInfo {
     breakpointId: string;
@@ -671,6 +640,7 @@ declare class PlaywrightDebugClient {
     private clearInactivityTimer;
 }
 
+type InspectorRuntime = "node" | "bun" | "unknown";
 interface DebugEventHandler {
     onDebugModeEntered: () => void;
     onDebugModeExited: () => void;
@@ -710,11 +680,13 @@ declare class DebugManager {
     private ensurePlaywrightInstalled;
     private startWithInspector;
 }
+declare function detectRuntime(startCommand: string): InspectorRuntime;
+declare function injectBunInspectFlag(command: string): string;
 
 /**
  * Orchestrates the debug session lifecycle, tracks state for the web UI,
  * and generates session summaries. Wraps DebugManager events and forwards
- * state changes to the API via ConveyorConnection.
+ * state changes to the API via AgentConnection.
  */
 declare class DebugLifecycleManager {
     private connection;
@@ -726,7 +698,7 @@ declare class DebugLifecycleManager {
     private reproduceRequested;
     private keyFindings;
     private _isActive;
-    constructor(connection: ConveyorConnection);
+    constructor(connection: AgentConnection);
     get isActive(): boolean;
     setDebugManager(manager: DebugManager): void;
     /**
@@ -750,4 +722,71 @@ declare class DebugLifecycleManager {
     private broadcastState;
 }
 
-export { type AgentContext, AgentRunner, type AgentRunnerCallbacks, type AgentRunnerConfig, type BreakpointInfo, type CallFrameInfo, CdpDebugClient, type ChatHistoryMessage, type ConveyorConfig, ConveyorConnection, type DebugEventHandler, DebugLifecycleManager, DebugManager, FileCache, type IncomingChatMessage, type PausedState, ProjectConnection, type ProjectConnectionConfig, ProjectRunner, type ProjectRunnerConfig, type ScopeVariable, type TaskAssignment, ensureWorktree, loadConveyorConfig, removeWorktree, runSetupCommand, runStartCommand };
+interface Observation {
+    description: string;
+    confirmsHypothesis: boolean;
+    iteration: number;
+    timestamp: number;
+}
+interface HypothesisState {
+    hypothesis: string | null;
+    iteration: number;
+    observations: Observation[];
+    active: boolean;
+    conclusion: string | null;
+}
+declare class HypothesisTracker {
+    private hypothesis;
+    private iteration;
+    private observations;
+    private _active;
+    private conclusion;
+    /**
+     * Start or update the current debugging hypothesis.
+     * Increments the iteration count if a hypothesis was already set.
+     */
+    setHypothesis(text: string): {
+        accepted: boolean;
+        message: string;
+    };
+    /**
+     * Record an observation from debug data (breakpoint hit, telemetry, etc.).
+     */
+    recordObservation(description: string, confirmsHypothesis: boolean): void;
+    /**
+     * End the debug session with a conclusion.
+     */
+    concludeSession(conclusion: string): string;
+    /**
+     * Get formatted debug context for injection into the agent's system prompt.
+     * Returns empty string if no active session.
+     */
+    getDebugContext(): string;
+    /**
+     * Get the full state (for serialization/testing).
+     */
+    getState(): HypothesisState;
+    isActive(): boolean;
+    getIteration(): number;
+    getMaxIterations(): number;
+    private getSessionSummary;
+    private reset;
+}
+
+interface ConveyorConfig {
+    setupCommand?: string;
+    startCommand?: string;
+    previewPort?: number;
+}
+declare function loadForwardPorts(workspaceDir: string): Promise<number[]>;
+/** Load config from env vars (project-level settings injected via bootstrap). */
+declare function loadConveyorConfig(): ConveyorConfig | null;
+
+declare function runSetupCommand(cmd: string, cwd: string, onOutput: (stream: "stdout" | "stderr", data: string) => void): Promise<void>;
+declare function runAuthTokenCommand(cmd: string, userEmail: string, cwd: string): string | null;
+declare function runStartCommand(cmd: string, cwd: string, onOutput: (stream: "stdout" | "stderr", data: string) => void): ChildProcess;
+
+/** Fetch full git history if the repo was cloned with --depth=1. */
+declare function unshallowRepo(workspaceDir: string): void;
+
+export { AgentConnection, type AgentConnectionConfig, type AgentRunnerCallbacks, type AgentRunnerConfig, type ApiKeyUpdateData, CommitWatcher, type ConveyorConfig, DEFAULT_LIFECYCLE_CONFIG, type DebugEventHandler, DebugLifecycleManager, DebugManager, type DebugModeOptions, FileCache, HypothesisTracker, type IncomingMessage, type InspectorRuntime, Lifecycle, type LifecycleCallbacks, type LifecycleConfig, type ModeAction, ModeController, type ModeTaskContext, PlanSync, ProjectConnection, ProjectRunner, SessionRunner, type SessionRunnerCallbacks, type SessionRunnerConfig, type SetModeData, detachWorktreeBranch, detectRuntime, ensureWorktree, getCurrentBranch, hasUncommittedChanges, hasUnpushedCommits, injectBunInspectFlag, loadConveyorConfig, loadForwardPorts, pushToOrigin, removeWorktree, runAuthTokenCommand, runSetupCommand, runStartCommand, stageAndCommit, unshallowRepo, updateRemoteToken };