/**
 * Shared plumbing for the `/workflow` command handlers: the narrowed context they run against, the
 * single-run guard lifecycle (spec §7), and the notification helpers they format results with.
 *
 * Everything here is UI- and guard-shaped. The handlers themselves live in sibling modules and
 * depend only on this one, which keeps the command layer a flat, acyclic tree.
 */
import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
import type { AgentRequest, AgentSession, RunResult } from "../../engine/types.ts";
import type { RunLock } from "../run-lock.ts";
import type { RunStore } from "../types.ts";
/** How a command opens an agent session (spec §2.2), bound to the invoking context's model registry. */
export type StartAgent = (request: AgentRequest) => AgentSession;
/**
 * The slice of the command context the handlers actually use. The registered handler still receives the
 * full `ExtensionCommandContext` (structurally compatible), but narrowing here documents the surface and
 * makes the handlers unit-testable with a small fake.
 */
export type CommandCtx = Pick<ExtensionCommandContext, "ui" | "cwd" | "mode" | "hasUI" | "modelRegistry">;
/** The narrowest context a handler can take: enough to talk to the user, nothing more. */
export interface NotifyCtx {
    ui: Pick<CommandCtx["ui"], "notify">;
}
export type Notify = CommandCtx["ui"]["notify"];
/**
 * Own the project lock lifecycle for one execution (spec §7): acquire `begin(runId)`; if the lock is
 * held or contended, notify and return `undefined`; otherwise run with the run's abort signal and
 * release on every outcome (including `blocked` — blocked ≠ in_progress, spec §7.1). A successful
 * reclaim (spec §7.3) is announced too, since it silently rewrites another run's recorded status.
 * Returns the run result, or `undefined` when the lock could not be acquired.
 */
export declare function runGuarded(guard: RunLock, runId: string, projectRoot: string, store: Pick<RunStore, "appendEvent">, notify: Notify, run: (signal: AbortSignal) => Promise<RunResult>): Promise<RunResult | undefined>;
/**
 * Reject a command that needs an idle process (spec §7.2). Returns true — and notifies — when THIS
 * process is already executing a run. A cheap same-process fast path only: the project lock (held
 * across sessions/processes, spec §7.2) is the actual gate, enforced by `runGuarded`'s `begin()` call;
 * this just avoids wasted work (e.g. resolving a workflow file) when the answer is already known here.
 * `verb` completes "…before <verb> another", so callers read as the user does.
 */
export declare function rejectIfBusy(ctx: NotifyCtx, guard: RunLock, verb: string): boolean;
/**
 * Turn a `resume`/`cancel`/`delete` argument into a run-id, or notify why it cannot be one and return
 * `undefined` (spec §6.2/§6.4/§6.5).
 *
 * Run-ids are slugs now (naming.ts), which are readable but long, so what the user types is matched the
 * way the harness matches its own session ids: exact first, then the short hash, then any unique prefix.
 * Several matches are reported WITH the candidates rather than resolved by picking one — two of these
 * three commands destroy state. `verb` completes "no run … to <verb>", so callers read as the user does.
 */
export declare function resolveRunRef(ctx: NotifyCtx, store: Pick<RunStore, "list">, arg: string, verb: string): Promise<string | undefined>;
/**
 * Report a run's terminal (or blocked) outcome (spec §5.1), unless the progress card already did.
 *
 * Progress §7.8: the card REPLACES this notification wherever it lands, rather than sitting beside it —
 * two reports of one outcome is noise. It does not always land (§7.7: `appendEntry` needs a session,
 * and the entry only renders in the interactive TUI), and a run that went silent about its own result
 * would be a strictly worse outcome than a duplicate, so the fallback is unconditional.
 */
export declare function reportResult(ctx: NotifyCtx, workflowName: string, result: RunResult, reportedByCard: boolean): void;
/** Report a run's terminal (or blocked) outcome to the user (spec §5.1). */
export declare function notifyResult(ctx: NotifyCtx, workflowName: string, result: RunResult): void;
/** A `this`-safe {@link Notify} bound to a context's UI, for passing into {@link runGuarded}. */
export declare function notifier(ctx: NotifyCtx): Notify;
export declare function describe(err: unknown): string;
//# sourceMappingURL=context.d.ts.map