@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5685

package/dist/workflows/run.d.ts

@@ -0,0 +1,275 @@
+import type { Home } from '../home/home.ts';
+export { IDLE_TIMEOUT_MS, UNREAD_INPUT_GRACE_MS, NO_WAIT_NUDGE_REPLY_MS, COMPLETION_WILL_WAIT, MAX_AUTO_CONTINUES, MAX_WAKE_DELIVERY_ATTEMPTS, WAKE_DELIVERY_CAP_NOTE, WAKE_SESSION_CLOSED_ERROR, WAITS_DISCARDED_NOTE, REFUSAL_DISCARDED_NOTE, QUEUE_WATCHDOG_MS } from './run/constants.ts';
+export { repositoryRootLockDisabled } from './run/repo-root-lease.ts';
+export { isUntouchedCancelledRun } from './run/run-guards.ts';
+import type { DelegationExecutionSettings, StartRunInput, WorkerTerminationBlocker, AutomationToolService } from './run/types.ts';
+export type { TurnTail, DelegationExecutionSettings, StartRunInput, WorkerTerminationBlocker, AutomationToolService } from './run/types.ts';
+import type { ContinueRunOptions } from './continuation-admission.ts';
+import { type CezarDoneAnswer, type CezarDoneRequest, type CezarWaitRequestInput, type PeerWaitEntry, type PrWaitEntry, type ProcessWaitEntry, type TimerWaitEntry, type WaitVia, type WorkerWaitEntry, type DeadlinedWorkerWaitEntry } from '../contract/index.js';
+import { NO_WAIT_NUDGE_NOTE, NO_WAIT_NOTE, NO_WAIT_NO_REPLY_NOTE, COMPLETION_NO_REPLY_NOTE, WORKER_FALLBACK_NOTE, WORKER_FALLBACK_REPLY_NOTE, COMPLETION_NUDGE_NOTE, AUTONOMOUS_NUDGE } from './turn-end.ts';
+export { nativeTimerDelay, appendTurnText, trackTurnTail, classifyTurnEnd } from './run/turn-markers.ts';
+export { AUTO_RESUME_GRACE_MS, MAX_AUTO_RESUMES, AUTO_RESUME_MISSED_WINDOW_MS } from './run/auto-resume.ts';
+import { TrackedWork } from './run/tracked-work.ts';
+export { agentDirectories, composeSystemPrompt, expandRegistrySlashSkill, expandRegistrySlashSkillText, leadingSlashSkillName, resolveExtraSystemPrompt, skillSystemPrompt } from './run/prompts.ts';
+export { stepLabel } from './run/steps.ts';
+export { makeRunTitle } from '../runs/run-title.ts';
+export { runAccountKey } from './run-scheduling.ts';
+import { type PreviewHostLike } from '../preview/registration.ts';
+import type { CiProgressRegistry } from '../ci-wait/progress.ts';
+import type { CezarToolHandlers } from '../ci-wait/controller.ts';
+import type { DelegationProvisioner } from '../delegation/provision.ts';
+import { type CwdSource } from '../delegation/process-liveness.ts';
+import type { RunnerFactory, RunnerId } from '../core/agent-runner.ts';
+import { type AgentInput, type WorkerStopResult, type WorkerWait, type WorkerWaitRequest } from '../contract/index.js';
+import { type RequestWaitRequest } from '../contract/index.js';
+import { type PastedContent } from './pasted-content.ts';
+export { contentBlocksOf, highestImageSeq, mediaTypeFor, pastedAttachmentsNote, pastedAttachmentsText, toPastedContent, type FileBlock, type PastedContent, type PersistedAttachment } from './pasted-content.ts';
+import type { ToolActivityTracker } from '../activity/tool-activity.ts';
+import { type Skill } from '../skills.ts';
+import { type QueuedMessage, type RunRecord, type RunStore } from '../runs/store.ts';
+import { WorkspaceSemaphore, type AccountHolds } from '../workspace/semaphore.ts';
+import { type WorkflowDef } from './types.ts';
+export { CHECK_KILL_GRACE_MS, CHECK_TERMINATION_CONFIRM_MS } from './grouped-command.ts';
+export { periodicAutosaveEnabled, AUTOSAVE_INTERVAL_MS } from './run/worktree-autosave.ts';
+/** #486: recheck a turn-end that deferred close/park only because the harness still held a human follow-up. */
+export { HELD_HUMAN_INPUT_RECHECK_MS } from './run/input-delivery.ts';
+export { WORKER_FALLBACK_QUESTION, WORKER_FALLBACK_HEADER } from './run/worker-questions.ts';
+export { AUTONOMOUS_NUDGE, NO_WAIT_NUDGE_NOTE, NO_WAIT_NOTE, NO_WAIT_NO_REPLY_NOTE, COMPLETION_NO_REPLY_NOTE, WORKER_FALLBACK_NOTE, WORKER_FALLBACK_REPLY_NOTE, COMPLETION_NUDGE_NOTE };
+/**
+ * The mini workflow engine: executes a `WorkflowDef` against a repo, one step
+ * at a time, persisting every event to the RunStore (which the SSE endpoints
+ * relay live to the GUI). No GitHub choreography — agent steps and shell
+ * checks with bounded retry loops, plus live sessions: the last agent step
+ * stays open for follow-ups (`waiting`) until "finish", idle timeout, or
+ * cancel. Runs queue behind the workspace-wide `maxParallel` slots (the shared
+ * `WorkspaceSemaphore`, spec 2026-07-20 step 2.5) and each run executes in its
+ * own git worktree on a `cez/<id8>` branch (spec 006), autosave-committed at
+ * turn end and before a draft PR — plus every 90 s when opted in via
+ * CEZ_AUTOSAVE=1 (#471). Each autosave records its trigger in the commit
+ * subject, so the always-on flushes are not mistaken for the opt-in timer.
+ * The user's working tree is never touched.
+ */
+export declare class RunManager {
+    #private;
+    settleOrphanedWorkerExecution(runId: string, opts?: {
+        admitting?: boolean;
+        fresh?: boolean;
+        cwds?: CwdSource;
+    }): boolean;
+    takeWorkerTerminationBlocker(runId: string): {
+        blocker: WorkerTerminationBlocker;
+        changed: boolean;
+    } | undefined;
+    requestWorkerStop(runId: string): WorkerStopResult;
+    awaitRunTermination(runId: string, timeoutMs: number, opts?: {
+        reapOrphans?: boolean;
+    }): Promise<boolean>;
+    /** The check progress of the workspace's CI waits, for the activity view. */
+    get ciProgress(): CiProgressRegistry;
+    /** The same host, for a removal outside this manager that must release a run's preview first. */
+    get previewHost(): PreviewHostLike | undefined;
+    /** The runner factory this manager was built with, for the planner beside it. */
+    get createRunner(): RunnerFactory;
+    constructor(store: RunStore, repoRoot: string, options: {
+        home: Home;
+        createRunner: RunnerFactory;
+        work?: TrackedWork;
+        semaphore?: WorkspaceSemaphore;
+        unreadInputGraceMs?: number;
+        noWaitNudgeReplyMs?: number;
+        subagentGraceMs?: number;
+        subagentDeadlineMs?: number;
+        preview?: PreviewHostLike | undefined;
+        cezarPort?: (() => number | undefined) | undefined;
+        cockpit?: {
+            origin: string;
+            projectId: string;
+        } | undefined;
+        sweepBranches?: ((keep: number) => void) | undefined;
+        toolActivity?: ToolActivityTracker | undefined;
+    });
+    /**
+     * Release everything this manager owns without touching run records
+     * (multi-project workspace, spec 2026-07-20: a removed project's context is
+     * torn down while the process lives on). Unsubscribes the shared usage
+     * sampler — before dispose() existed that subscription lived for the whole
+     * process — clears every per-run idle/autosave timer, releases any held
+     * repo-root locks, and empties the queued state so nothing fires later.
+     * Live sessions are NOT ended here: run lifecycle stays the caller's policy;
+     * dispose only guarantees the manager makes no further moves on its own.
+     */
+    dispose(): void;
+    setCockpitAddress(address: {
+        origin: string;
+        projectId: string;
+    } | undefined): void;
+    cockpitAddress(): {
+        origin: string;
+        projectId: string;
+    } | undefined;
+    /**
+     * hearsay-tools/cezarion#1465: the project's one-time schedule service behind
+     * `cezar_schedule_task` and `cezar_scheduled_tasks`, set by `startServer` beside the cockpit
+     * address. Headless `cez run` never sets it, so the tools answer `unavailable` there. The
+     * boot manager recovers runs before the server sets it, and a lazy project's manager recovers
+     * before its context is announced: a resumed session can call a tool in that window. With a
+     * cockpit address the call waits for the service, bounded like the CLI's startup retry.
+     */
+    setAutomationTools(tools: AutomationToolService | undefined): void;
+    builtinSkills(): Skill[];
+    setDelegationProvisioner(provisioner: DelegationProvisioner): () => void;
+    /**
+     * The trusted callbacks behind one session's cezar tools (hearsay-tools/cezarion#1233). Both
+     * answers list the waits still open; a coded refusal answers with its fixed message, never the
+     * thrower's text, and anything else is left to the tool server's `unavailable`.
+     */
+    cezarToolHandlers(runId: string, generation: string): CezarToolHandlers;
+    acceptDone(runId: string, generation: string, request: CezarDoneRequest, signal?: AbortSignal): CezarDoneAnswer;
+    registerWait(runId: string, request: CezarWaitRequestInput, via: WaitVia, generation: string, capabilitySignal?: AbortSignal): Promise<PrWaitEntry | TimerWaitEntry | WorkerWaitEntry | ProcessWaitEntry | PeerWaitEntry>;
+    cancelWait(runId: string, waitId: string, generation: string): {
+        cancelled: true;
+    } | {
+        cancelled: false;
+        code: 'not_found' | 'already_resolved' | 'human_question';
+    };
+    /** Snapshot of the actual active session, never guessed from partial run settings. */
+    delegationExecutionSettings(runId: string): DelegationExecutionSettings;
+    /**
+     * Resolve one agent step's selection before acceptance; permission grants always come from the
+     * parent. Called once per agent step of the accepted chain (#452): a same-backend step inherits
+     * the parent's account, model and effort, another runner resolves its own project/default
+     * account, and an explicit `agentProfile` names the account for either — an id the registry
+     * does not know is refused rather than degraded to the default, because a worker silently
+     * running on another login is a billing boundary crossed without anyone choosing it.
+     */
+    selectDelegationExecutionSettings(runId: string, selection: {
+        backend?: RunnerId | undefined;
+        model?: string | undefined;
+        effort?: string | undefined;
+        agentProfile?: string;
+    }, validateModel?: (settings: DelegationExecutionSettings) => Promise<void>): Promise<DelegationExecutionSettings>;
+    /**
+     * Idempotent start (#504, spec 2026-09-24-cez-task-cli). Lookup and create share one
+     * synchronous path, so the event loop serialises concurrent retries: the first creates, every
+     * later one with the same hash gets that run back, and a different hash is a conflict.
+     */
+    startRunIdempotent(workflow: WorkflowDef, input: StartRunInput, request: {
+        id: string;
+        hash: string;
+    }): {
+        run: RunRecord;
+        created: boolean;
+    } | {
+        conflict: true;
+    };
+    /** Async work this manager still owns (`TrackedWork`): a project migration fence waits for none. */
+    pendingWork(): number;
+    /** Every task start, from any source, passes the project's migration admission first. */
+    startRun(workflow: WorkflowDef, input: StartRunInput, clientRequest?: {
+        id: string;
+        hash: string;
+    }): RunRecord;
+    /** Accept only the store's already-durable owned creation, never caller-supplied paths/workflows. */
+    enqueueOwnedRun(runId: string): void;
+    /**
+     * Startup recovery (#367) — re-adopt runs that were live when the previous
+     * cezar process exited (requires the store opened with `keepLive`):
+     *  - `queued`  → back into the queue (FIFO by createdAt), from the persisted
+     *    workflowDef (or the catalog by name for older records);
+     *  - `waiting` → preserve the durable attention state, while reaping the
+     *    dead session's temporary resources (Continue or Finish still works);
+     *  - `running` → mark interrupted, then immediately resume the last agent
+     *    session via the Continue path, pointing the agent at its handoff file.
+     * Call once, before the server starts taking requests.
+     *
+     * With `familyRootId`, the same recovery for the one delegation family a dead process left
+     * behind, which `adoptOrphanedRun` has just loaded. Either way only runs this store owns are
+     * touched: another live process's runs are not in the live set, and the passes that read every
+     * worker or root skip their families (#779, plan step 3).
+     */
+    recover(familyRootId?: string): Promise<void>;
+    /**
+     * Adopt a dead owner’s family for a control, then recover the settled family without resuming
+     * work. Stop cancels its target; only Continue starts work. Serialize adoptions after recovery.
+     * False means missing or live-owned.
+     */
+    adoptOrphanedRun(runId: string, opts?: {
+        stop?: boolean;
+    }): Promise<boolean>;
+    /** Project detach cancels autonomous cleanup; reattach reconstructs the durable intents. */
+    pauseWorkerCleanup(): void;
+    recoverWorkerCleanup(): void;
+    claimWorkerCleanup(runId: string): (() => void) | undefined;
+    accountHolds(now?: number): AccountHolds;
+    cancelAutoResume(runId: string): boolean;
+    /** Test seam: the module owns this same map for its whole lifetime. */
+    cancel(runId: string): boolean;
+    isActive(runId: string): boolean;
+    claimWorktreeReclaim(runId: string): (() => void) | null;
+    claimForPublish(runId: string): (() => void) | null;
+    claimForBranchCleanup(runIds: readonly string[]): (() => void) | null;
+    enqueueMessage(runId: string, content: PastedContent[]): QueuedMessage | null;
+    editQueuedMessage(runId: string, msgId: string, edit: {
+        text?: string;
+        images?: PastedContent[];
+    }): QueuedMessage | null;
+    removeQueuedMessage(runId: string, msgId: string): boolean;
+    editTask(runId: string, task: string): boolean;
+    deferMessage(runId: string, content: PastedContent[]): boolean;
+    finishBlockedReason(runId: string): string | undefined;
+    registerWorkerWait(parentId: string, request: WorkerWaitRequest): WorkerWait;
+    registerWorkerListWait(runId: string, request: {
+        workerIds?: string[];
+        requestIds?: string[] | undefined;
+        mode?: WorkerWaitRequest['mode'];
+        timeoutSeconds: number;
+    }, via: 'cezar_wait' | 'cez-worker-wait'): DeadlinedWorkerWaitEntry;
+    registerRequestWait(runId: string, request: RequestWaitRequest): WorkerWait;
+    registerPeerWait(runId: string, request: {
+        peerIds: string[];
+        timeoutSeconds: number;
+    }, via: 'cezar_wait' | 'cez-message-wait'): PeerWaitEntry;
+    cancelPeerWait(runId: string, waitId: string): PeerWaitEntry;
+    canClaimInboxInput(runId: string, id: string): boolean;
+    reserveInboxInputs(runId: string, generation: string, ids: readonly string[]): {
+        receiptId: string;
+        expiresAt: string;
+        inputIds: string[];
+    } | undefined;
+    acknowledgeInbox(runId: string, generation: string, receiptId: string): 'acknowledged' | 'already-acknowledged';
+    releaseInbox(runId: string, generation: string, receiptId: string): 'released';
+    /** Accepted conversation input uses the existing scheduler admission for idle recipients. */
+    deliverConversationInput(runId: string): void;
+    /**
+     * `cez worker cancel-wait`: cancels a worker wait in the list, as `cezar_cancel_wait` does, and
+     * answers the legacy `WorkerWait` shape (hearsay-tools/cezarion#1235). A cancelled wait wakes
+     * nothing. A resolved wait is owed: it is returned as its `wake-pending` receipt and arrives with
+     * the next wake. A settled one returns its receipt; an unknown id is `incompatible_state`.
+     */
+    cancelWorkerWait(parentId: string, waitId: string): WorkerWait;
+    reconcileWorkerWaits(familyRootId?: string): void;
+    /** Durable queue is the single hydration source for fresh, continuing and recovered runs. */
+    steerWorker(runId: string, input: AgentInput): 'queued' | 'delivered';
+    /**
+     * Deliver a user message into the run's live claude session (mid-turn or
+     * while `waiting`). Returns false when there is no open session — the GUI
+     * then offers "Continue" instead.
+     */
+    sendMessage(runId: string, content: PastedContent[], messageId?: string): boolean;
+    /** Only an explicit option from the permission card may answer a native grant. */
+    respondPermission(runId: string, requestId: string, optionId: string): boolean;
+    finish(runId: string): boolean;
+    /**
+     * "Continue" (spec 003): reopen a finished run's claude session in-process
+     * (`claude --resume <sessionId>`) as a new synthetic step. The session then
+     * behaves exactly like an interactive step: `waiting` after each turn,
+     * messages via sendMessage, closed by finish/idle/cancel.
+     */
+    continueRun(runId: string, opts?: ContinueRunOptions, 
+    /** Restart recovery may discover several interrupted tasks at once. Those
+     *  continuations are queued; an explicit user Continue remains immediate. */
+    deferForCapacity?: boolean, conversation?: Parameters<RunStore['commitWorkerContinuation']>[4]): {
+        ok: boolean;
+        error?: string;
+    };
+}