@hcflabs/pi-subagent 0.0.0-stage → 27.10.8

package/dist/runner.d.ts

@@ -0,0 +1,431 @@
+import { type DiscardGuards, type DiscardPlan } from "./discard.ts";
+import { type EphemeralSubagentExecutor } from "./ephemeral.ts";
+import type { PruneOwnership } from "./prune.ts";
+import { IntegrationGit } from "./integration-git.ts";
+import { type AllocationKind, type CheckCommand, type ChangesetTaskRequest, type CleanupKind, type ExecuteRequest, type ExecutionPolicySnapshot, type HostAllocationIntent, type HostAllocationPlan, type ModelClass, type ReviewEvidence, type ResumeRequest, type RunState, type TaskAttempt, type TaskRequest, type TaskState, type WorktreeAllocationIntent, type WorktreeAllocationPlan, type WorkspaceIdentity } from "./schema.ts";
+import { FileRunStore } from "./store.ts";
+/** One durable follow-up per attempt; this instruction permits a worker commit, never discarded work. */
+export declare const COMMIT_NUDGE_INSTRUCTION = "Your turn ended with uncommitted changes in your worktree. Commit the intended changes now so the worktree is clean, or explain in your reply why they must not be committed. Do not discard work.";
+export declare const CLEANUP_SAFETY_BUDGET_MS = 30000;
+export declare const TERMINATION_SAFETY_BUDGET_MS = 15000;
+export declare const STATUS_INSPECTION_BUDGET_MS = 5000;
+export interface OperationContext {
+    readonly signal: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly deadline?: number;
+}
+export interface CommandResult extends CheckCommand {
+    code: number;
+    killed?: boolean;
+    stdout: string;
+    stderr: string;
+}
+type AllocationFailureResult<Kind extends AllocationKind> = {
+    kind: Kind;
+    outcome: "absent";
+    failure: string;
+} | {
+    kind: Kind;
+    outcome: "unknown";
+    failure: string;
+    possibleResources?: string[];
+};
+export type WorktreeAllocationResult = {
+    kind: "worktree";
+    outcome: "owned";
+} | AllocationFailureResult<"worktree">;
+export type WorkspaceAllocationResult = {
+    kind: "workspace";
+    outcome: "owned";
+    workspaceId: string;
+    rootTabId: string;
+    rootPaneId: string;
+} | AllocationFailureResult<"workspace">;
+export type WorkerTabAllocationResult = {
+    kind: "worker_tab";
+    outcome: "owned";
+    tabId: string;
+    paneId: string;
+} | AllocationFailureResult<"worker_tab">;
+export type AgentAllocationResult = {
+    kind: "agent";
+    outcome: "owned";
+} | AllocationFailureResult<"agent">;
+export type HostAllocationResult = WorkspaceAllocationResult | WorkerTabAllocationResult | AgentAllocationResult;
+export type AllocationResult = WorktreeAllocationResult | HostAllocationResult;
+export type AllocationReconciliation<Kind extends AllocationKind = AllocationKind> = {
+    kind: Kind;
+    outcome: "absent";
+} | {
+    kind: Kind;
+    outcome: "possible";
+    failure: string;
+    possibleResources?: string[];
+};
+export type WorkerResult = {
+    outcome: "candidate";
+    candidate: WorkspaceIdentity;
+    diagnostic?: string;
+} | {
+    outcome: "blocked" | "not_prompted";
+    diagnostic: string;
+}
+/** The exact turn finished in its valid owned worktree with tracked or untracked changes. */
+ | {
+    outcome: "uncommitted";
+    diagnostic: string;
+} | {
+    outcome: "unknown" | "interrupted";
+    diagnostic: string;
+};
+export interface CheckRunResult {
+    results: CommandResult[];
+    identityAfter: WorkspaceIdentity;
+}
+export interface ReviewResult {
+    verdict: string;
+    identityAfter: WorkspaceIdentity;
+}
+/** A just-in-time launch whose argv contains only an ephemeral Role prompt path. */
+export interface VerifiedLaunch {
+    readonly role: string;
+    readonly modelClass: ModelClass;
+    readonly model: string;
+    readonly thinkingLevel: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+    readonly tools: readonly string[];
+}
+export type ResolvedRoute = Pick<VerifiedLaunch, "role" | "modelClass" | "model" | "thinkingLevel">;
+/** A dry-run result: the normalized request and the resolved routes; no state exists for it. */
+export interface ExecutePlan {
+    request: ExecuteRequest;
+    root: string;
+    main: WorkspaceIdentity;
+    routes: readonly ResolvedRoute[];
+}
+export interface TransientLaunchHandle<Launch extends VerifiedLaunch = VerifiedLaunch> {
+    readonly launch: Launch;
+    cleanup(): Promise<void>;
+}
+/** Run one launch action and surface cleanup failure, including after action failure or abort. */
+export declare function withTransientLaunch<Launch extends VerifiedLaunch, Result>(handle: TransientLaunchHandle<Launch>, operation: (launch: Launch) => Promise<Result>): Promise<Result>;
+/**
+ * Productive hooks may inspect or change implementation state. Every call receives
+ * the same request abort signal. Individual I/O operations keep their own caps.
+ */
+export interface CoordinatorRuntime {
+    now(): number;
+    randomToken(): string;
+    /** `dryRun` skips checks that call Herdr; every other check runs. */
+    preflight(input: {
+        request: ExecuteRequest;
+        cwd: string;
+        dryRun?: boolean;
+    }, context: OperationContext): Promise<{
+        root: string;
+        main: WorkspaceIdentity;
+        /** Resolved route of each distinct Role and model class, when the coordinator reports it. */
+        routes?: readonly ResolvedRoute[];
+    }>;
+    acquireLaunch(role: string, modelClass: ModelClass, context: OperationContext): Promise<TransientLaunchHandle<VerifiedLaunch>>;
+}
+export type HostAllocationKind = Exclude<AllocationKind, "worktree">;
+export type HostCleanupKind = Extract<CleanupKind, "worker_tab" | "workspace">;
+export interface HostRuntime {
+    planHostAllocation(input: {
+        readonly requestId: ExecuteRequest["id"];
+        readonly goal: ExecuteRequest["goal"];
+        kind: HostAllocationKind;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+    }, context: OperationContext): Promise<HostAllocationPlan>;
+    allocateHost(input: {
+        requestId: ExecuteRequest["id"];
+        intent: HostAllocationIntent;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+        /** Invoked only after pane, lease, and startability checks at the final agent-start boundary. */
+        acquireLaunch?: () => Promise<TransientLaunchHandle<VerifiedLaunch>>;
+    }, context: OperationContext): Promise<HostAllocationResult>;
+    reconcileHostAllocation(input: {
+        requestId: ExecuteRequest["id"];
+        intent: HostAllocationIntent;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+    }, context: OperationContext): Promise<AllocationReconciliation<HostAllocationKind>>;
+    runWorker(input: {
+        readonly goal: ExecuteRequest["goal"];
+        readonly contexts: readonly TextTaskContext[];
+        task: TaskRequest;
+        attempt: TaskAttempt;
+        workerId: string;
+        kind: "initial" | "correction" | "followup";
+        preCandidate: WorkspaceIdentity;
+        failure?: string;
+        instruction?: string;
+    }, context: OperationContext): Promise<WorkerResult>;
+    terminateWorker(input: {
+        task: TaskRequest;
+        attempt: TaskAttempt;
+        workerId: string;
+        candidate: WorkspaceIdentity;
+    }, context: OperationContext): Promise<{
+        outcome: "terminated";
+    } | {
+        outcome: "unknown";
+        failure: string;
+    }>;
+    reconcileWorkerTermination(input: {
+        task: TaskRequest;
+        attempt: TaskAttempt;
+        workerId: string;
+        candidate: WorkspaceIdentity;
+    }, context: OperationContext): Promise<{
+        outcome: "terminated" | "active";
+    } | {
+        outcome: "unknown";
+        failure: string;
+    }>;
+    cleanupHost(input: {
+        requestId: ExecuteRequest["id"];
+        kind: HostCleanupKind;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+    }, context: OperationContext): Promise<{
+        outcome: "completed" | "absent";
+    } | {
+        outcome: "blocked";
+        failure: string;
+    }>;
+}
+export interface InFlightTaskCandidateInspection {
+    candidate: WorkspaceIdentity;
+    clean: boolean;
+    valid: boolean;
+}
+export interface InFlightTaskCandidateInspector {
+    inspectInFlightTaskCandidate(input: {
+        root: string;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+    }, context: OperationContext): Promise<InFlightTaskCandidateInspection>;
+}
+export interface GitRuntime {
+    inspectTaskCandidate(input: {
+        root: string;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+    }, context: OperationContext): Promise<WorkspaceIdentity>;
+    inspectMain(input: {
+        root: string;
+    }, context: OperationContext): Promise<WorkspaceIdentity>;
+    inspectMainBase(input: {
+        root: string;
+    }, context: OperationContext): Promise<WorkspaceIdentity>;
+    allocateWorktree(input: {
+        requestId: string;
+        root: string;
+        baseRoot?: string;
+        intent: WorktreeAllocationIntent;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+        onPrepared(worktree: WorktreeAllocationPlan): Promise<void>;
+    }, context: OperationContext): Promise<WorktreeAllocationResult>;
+    reconcileWorktreeAllocation(input: {
+        root: string;
+        intent: WorktreeAllocationIntent;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+    }, context: OperationContext): Promise<AllocationReconciliation<"worktree">>;
+    runChecks(input: {
+        root: string;
+        scope: "task" | "final";
+        taskId?: string;
+        attempt?: TaskAttempt;
+        checks: CheckCommand[];
+        candidate: WorkspaceIdentity;
+    }, context: OperationContext): Promise<CheckRunResult>;
+    review(input: {
+        root: string;
+        scope: "task" | "final";
+        phase: ReviewEvidence["phase"];
+        taskId?: string;
+        attempt?: TaskAttempt;
+        criterion: string;
+        base: WorkspaceIdentity;
+        tip: WorkspaceIdentity;
+        acquireLaunch(): Promise<TransientLaunchHandle<VerifiedLaunch>>;
+    }, context: OperationContext): Promise<ReviewResult>;
+    inspectRetainedTask(input: {
+        root: string;
+        task: TaskRequest;
+        attempt: TaskAttempt;
+    }, context: OperationContext): Promise<WorkspaceIdentity>;
+}
+export type MainStatus = {
+    status: "current" | "drifted";
+    expected: WorkspaceIdentity;
+    actual: WorkspaceIdentity;
+} | {
+    status: "unavailable";
+    expected: WorkspaceIdentity;
+    failure: string;
+};
+export interface RunResponse {
+    text: string;
+    state: RunState;
+    main?: MainStatus;
+    continuation?: ResumeRequest;
+}
+export type TextTaskContext = {
+    taskId: string;
+    text: string;
+};
+/** Build one bounded changeset assignment. Call this before acquiring its Role launch. */
+export declare function buildChangesetTaskPrompt(input: {
+    readonly goal: ExecuteRequest["goal"];
+    readonly contexts: readonly TextTaskContext[];
+    task: ChangesetTaskRequest;
+    kind: "initial" | "correction" | "followup";
+    worktreeCwd: string;
+    failure?: string;
+    instruction?: string;
+}): string;
+/** Resolve completed text outputs in the consumer's declared context order. */
+export declare function resolveTextTaskContexts(state: {
+    readonly tasks: readonly TaskState[];
+}, task: Pick<TaskRequest, "id" | "contextFrom">): TextTaskContext[];
+/** Format complete context blocks or fail; prompt data is never truncated. */
+export declare function formatTextTaskContexts(contexts: readonly TextTaskContext[], maxBytes: number): string;
+/** Build a bounded text-task assignment with upstream output marked as task data. */
+export declare function buildTextTaskPrompt(goal: ExecuteRequest["goal"], task: Pick<TaskRequest, "id" | "requirements" | "deliverable">, contexts: readonly TextTaskContext[]): string;
+export declare function readyPendingTasks(state: RunState): TaskState[];
+/** Main's next integration step while the request waits only for Main; undefined when a task or the final gate needs attention. */
+export declare function nextIntegrationAction(state: RunState): string | undefined;
+export declare class IsolatedRunner {
+    private readonly coordinatorRuntime;
+    private readonly hostRuntime;
+    private readonly gitRuntime;
+    private readonly store;
+    private readonly integrationGit;
+    private readonly textExecutor;
+    private readonly currentPolicy;
+    private readonly productiveLifecycles;
+    private readonly followupControls;
+    constructor(coordinatorRuntime: CoordinatorRuntime, hostRuntime: HostRuntime, gitRuntime: GitRuntime, store: FileRunStore | undefined, textExecutor: EphemeralSubagentExecutor, policy?: ExecutionPolicySnapshot, currentPolicy?: () => ExecutionPolicySnapshot, integrationGit?: IntegrationGit);
+    listRequests(root: string): Promise<{
+        requests: Array<{
+            id: string;
+            name: string;
+            status: string;
+            directory: string;
+            root: string;
+            tasks: Array<{
+                id: string;
+                name: string;
+                status: string;
+                kind: string;
+            }>;
+        }>;
+        invalidIds: string[];
+        states: RunState[];
+    }>;
+    /** True while a live productive run holds this root's lease; the lease does not name its request. */
+    hasProductiveRunLease(root: string): Promise<boolean>;
+    /** Classify orphaned work under the same repository lease as productive execution.
+     * Status remains read-only; Main alone chooses any subsequent action. */
+    recoverRepository(root: string): Promise<{
+        requests: RunResponse[];
+        invalidIds: string[];
+        leaseBusy: boolean;
+    }>;
+    /** Prune evidence across checkouts, primary first, and orphaned requests whose parent checkout was removed.
+     * A non-terminal state owns every resource name its saved text mentions; an unreadable state owns every
+     * name its raw text mentions, or every name when unreadable. */
+    pruneOwnership(checkouts: readonly string[]): Promise<PruneOwnership>;
+    /** After pruning, reconcile aborted requests that recorded a removed resource through the guarded abort path. */
+    reconcilePrunedAborts(checkouts: readonly string[], names: readonly string[]): Promise<string[]>;
+    canFollowup(root: string, requestId: string, taskId: string): boolean;
+    drainFollowups(root: string, requestId: string, taskId: string): string[];
+    queueFollowup(root: string, requestId: string, taskId: string, instruction: string): string;
+    private withProductiveRun;
+    private withLifecycleLock;
+    private saveProductive;
+    private callProductive;
+    private rethrowStopped;
+    /** Every execute check before durable state; a dry run also skips the Herdr host preflight. */
+    private admitExecute;
+    /** Dry run of execute: no state, lock, lease, worktree, or Herdr call. */
+    plan(value: unknown, cwd: string, outerSignal?: AbortSignal): Promise<ExecutePlan>;
+    execute(value: unknown, cwd: string, outerSignal?: AbortSignal): Promise<RunResponse>;
+    resume(value: unknown, root: string, outerSignal?: AbortSignal): Promise<RunResponse>;
+    /** Main selects an exact retained candidate; only the owned integration checkout is writable. */
+    stage(value: unknown, root: string, outerSignal?: AbortSignal): Promise<RunResponse>;
+    private stageReceipts;
+    /** Only Main can validate/promote the exact selected, clean combined tip. */
+    integrate(value: unknown, root: string, outerSignal?: AbortSignal): Promise<RunResponse>;
+    private releaseRejected;
+    private releaseSuperseded;
+    private cleanupPromoted;
+    private cleanupPromotedStage;
+    private requireExactIntegration;
+    listOrphanRequests(cwd: string): Promise<{
+        invalidIds: string[];
+        requests: {
+            id: string;
+            name: string;
+            status: string;
+            directory: string;
+            root: string;
+            orphaned: boolean;
+            tasks: never[];
+        }[];
+    }>;
+    private discardGuards;
+    discardPlan(cwd: string, id: string, directory: string | undefined, guards: DiscardGuards): Promise<DiscardPlan>;
+    /** Command-only explicit discard. No tool calls this method. */
+    discard(cwd: string, plan: DiscardPlan, guards: DiscardGuards): Promise<import("./discard.ts").DiscardRemoval[]>;
+    private terminateAbortedAttempt;
+    private cleanupAbortedHost;
+    private closeDiscardResource;
+    abort(id: string, root: string, outerSignal?: AbortSignal): Promise<RunResponse>;
+    /** Read-only proof that every retained candidate checkout and staged integration checkout is already gone. */
+    private retainedWorkAbsent;
+    private cleanupAborted;
+    status(id: string, root: string, outerSignal?: AbortSignal): Promise<RunResponse>;
+    private run;
+    private dispatchTask;
+    private dispatchTextTask;
+    private correctionAllowed;
+    private driveWorkerSafely;
+    private driveWorker;
+    private terminationCandidate;
+    /**
+     * Proves exact worker termination without replay. Reconciliation records a worker that is already gone;
+     * only an observed live worker without saved termination intent is closed.
+     */
+    private proveTermination;
+    private terminateWithSafety;
+    private runCheckBatch;
+    private runReview;
+    private retainCandidate;
+    private verifyRetainedTask;
+    private retry;
+    private finalize;
+    private runFinal;
+    private markFinalFailed;
+    private markSuperseded;
+    private recoverInterrupted;
+    private ensureFollowupControl;
+    private controlKey;
+    private activeControl;
+    private activeControls;
+    private hasActiveControl;
+    private hasAnyActiveControl;
+    private closeFollowupControl;
+    private closeRequestControls;
+    private attention;
+    private response;
+}
+export {};