lastlight 0.15.0 → 0.16.1

package/dist/workflows/phase-executor.d.ts

@@ -1,215 +0,0 @@
-import type { ExecutorConfig, ExecutionResult, GitSandboxAccess } from "../engine/github/profiles.js";
-import { type CommandSpec } from "../engine/agent-executor.js";
-import type { StateDb } from "../state/db.js";
-import type { AgentWorkflowDefinition, PhaseDefinition } from "./schema.js";
-import { type TemplateContext } from "./templates.js";
-import type { DagNode } from "./dag.js";
-import type { PhaseResult } from "./runner.js";
-import type { StepStatus, ProgressStep } from "../notify/types.js";
-/**
- * The single per-phase executor. Constructed once per workflow run, it owns
- * every per-phase body — context / standard agent / reviewer-loop /
- * generic-loop — behind one `execute(node, outputs)` entry point. The
- * scheduler (`runner.ts`) owns the DAG, the `phases[]`/`outputs{}`
- * accumulation, and the in-memory node status; `execute` reads the current
- * outputs and returns its delta.
- *
- * Dependencies are grouped into three cohesive collaborators:
- *   - {@link PhaseRunContext}  run-scoped immutable data
- *   - {@link PhaseReporter}    progress / notification surface
- *   - {@link PhaseResolver}    model / variant / prompt / gate resolution
- *
- * This makes the executor unit-testable with fakes (see
- * `phase-executor.test.ts`), and — because both chain and explicit-DAG nodes
- * now route through the same code — loop nodes finally support the approval /
- * reply gates that the old DAG fork dropped.
- */
-/** Run-scoped immutable data shared by every phase execution. */
-export interface PhaseRunContext {
-    definition: AgentWorkflowDefinition;
-    ctx: TemplateContext;
-    config: ExecutorConfig;
-    /** Single workspace shared by every phase + loop iteration of the run. */
-    taskId: string;
-    triggerId: string;
-    githubAccess: GitSandboxAccess;
-    /** Mutable scratch bag (generic-loop resume state). */
-    scratch: Record<string, unknown>;
-    db?: StateDb;
-    workflowId?: string;
-}
-export interface ReportStepOpts {
-    label?: string;
-    insertBefore?: string;
-    insert?: boolean;
-    alsoNote?: boolean;
-}
-/** Progress / notification surface — the reporting collaborator. */
-export interface PhaseReporter {
-    onStart(phase: string): Promise<void>;
-    onEnd(phase: string, result: PhaseResult): Promise<void>;
-    /** Transition a checklist step (and optionally render a YAML message detail). */
-    step(key: string, status: StepStatus, template?: string, extraCtx?: Partial<TemplateContext>, opts?: ReportStepOpts): Promise<void>;
-    /** Render a YAML message template and post it as a standalone note. */
-    message(template: string | undefined, extraCtx?: Partial<TemplateContext>): Promise<void>;
-    /** Post a pre-rendered standalone message. */
-    postNote(text: string): Promise<void>;
-    /** Persist a phase-history entry on the workflow run. */
-    persistPhase(phase: string, summary?: string): void;
-    /** Mark the workflow run failed. */
-    failWorkflow(errorMsg?: string): void;
-}
-/** Model / variant / prompt / gate resolution — the resolution collaborator. */
-export interface PhaseResolver {
-    modelFor(taskType: string): string | undefined;
-    variantFor(taskType: string): string | undefined;
-    renderPrompt(promptPath: string, extraCtx?: Partial<TemplateContext>): string;
-    gateEnabled(gateName: string | undefined): boolean;
-}
-/** The delta a single `execute(node, outputs)` returns to the scheduler. */
-export interface PhaseOutcome {
-    results: PhaseResult[];
-    status: "succeeded" | "failed" | "skipped";
-    /** Approval / reply gate hit — scheduler returns `{ success: true, paused: true }`. */
-    paused?: boolean;
-    /**
-     * Dedup running-skip — another instance is mid-flight on this exact phase.
-     * Scheduler stops the whole run immediately with `success: false` and does
-     * NOT cascade skips (it isn't a phase failure).
-     */
-    aborted?: boolean;
-    /** Output map additions to merge into the scheduler's accumulated outputs. */
-    outputVars?: Record<string, unknown>;
-}
-/**
- * Build the agent prompt for a phase, handling both `prompt:` (template file)
- * and `skill:`/`skills:` (skill references) phase definitions.
- */
-export declare function buildPhasePrompt(phase: PhaseDefinition, ctx: TemplateContext, extraCtx?: Partial<TemplateContext>): string;
-/**
- * Overlay per-phase executor config fields (`unrestricted_egress`,
- * `web_search`, `sandbox_image`, resolved skill paths) onto the run-level
- * config.
- */
-export declare function phaseConfigFor(config: ExecutorConfig, phase: PhaseDefinition): ExecutorConfig;
-/** Check if an error was caused by manual termination (OOM/cancel/kill). */
-export declare function isTerminated(error?: string): boolean;
-/**
- * Classify an execution outcome as *soft* — a clean exit that produced no
- * usable output — versus *hard* (a real crash). Generic and phase-agnostic:
- * it reads only the result fields, with no notion of reviewer/socratic. Both
- * the reviewer loop and the generic loop consume it so their recovery logic
- * stays in lockstep. A soft outcome is recoverable (retry / trust an on-disk
- * artifact / advance); a hard one — terminated, fatal, tool error, non-zero
- * exit — is not. See `mapStopReason` in the executors for the stop-reason
- * vocabulary this keys off (`unknown` / `error_truncated` are the soft ones).
- */
-export declare function isSoftOutcome(r: Pick<ExecutionResult, "success" | "error" | "stopReason">): boolean;
-type RunPhaseResult = {
-    result: ExecutionResult;
-    executionId: string;
-    skipped: false;
-} | {
-    result: ExecutionResult;
-    skipped: false;
-} | {
-    skipped: true;
-    reason: "running" | "done";
-};
-/**
- * Run a single agent phase with DB-tracked deduplication. The dedup ledger
- * (`shouldRunPhase`) is the single source of truth for resume, so re-running
- * from the top skips completed phases here.
- */
-export declare function runPhase(workflowName: string, phaseName: string, taskId: string, triggerId: string, prompt: string, config: ExecutorConfig, db?: StateDb, modelOverride?: string, workflowRunId?: string, githubAccess?: GitSandboxAccess, variantOverride?: string): Promise<RunPhaseResult>;
-/**
- * Run a single deterministic `bash`/`script` phase, sharing the agent phase's
- * dedup ledger + executions row so it appears (and dedups on resume) exactly
- * like an agent phase — just with `turns: 0` and no model cost.
- */
-export declare function runCommandPhase(workflowName: string, phaseName: string, taskId: string, triggerId: string, spec: CommandSpec, config: ExecutorConfig, db?: StateDb, workflowRunId?: string, githubAccess?: GitSandboxAccess, timeoutSeconds?: number, sandboxEnv?: Record<string, string>): Promise<RunPhaseResult>;
-export declare class PhaseExecutor {
-    private readonly run;
-    private readonly reporter;
-    private readonly resolver;
-    constructor(run: PhaseRunContext, reporter: PhaseReporter, resolver: PhaseResolver);
-    /**
-     * Execute one DAG node and return its delta. The scheduler accumulates
-     * `results` into `phases[]`, merges `outputVars` into the shared outputs
-     * map, and maps `status`/`paused`/`aborted` onto node state + run control.
-     */
-    execute(node: DagNode, outputs: Readonly<Record<string, unknown>>): Promise<PhaseOutcome>;
-    private runContext;
-    /**
-     * First-class, in-process PR-review submission (`type: post-review`). The
-     * reviewer agent writes only *content* to `.lastlight/pr-review/findings.json`
-     * (`{ skip?, summary, event, findings[] }`); THIS action supplies every fact
-     * the harness already knows — the PR number (from the run context), the base
-     * ref, the head SHA and the diff (from the pre-cloned checkout) — anchors each
-     * finding to a changed line, and posts one formal review via `GitHubClient`.
-     *
-     * This replaces the ~150-line in-sandbox `type: script` blob that depended on
-     * the AI hand-copying `pr_number`/`base_ref`/`head_sha` into the JSON and
-     * silently `exit 0`'d on any mismatch (the "ran but posted nothing" bug).
-     * Here a genuine failure — missing findings after a real review, or a GitHub
-     * error that survives the body-only retry — FAILS the phase visibly; only a
-     * legitimate `skip` succeeds without posting. Idempotent on resume: it no-ops
-     * when a bot review already exists on the current head SHA.
-     */
-    private runPostReview;
-    /** Host path of the run's repo checkout — mirrors sandbox/index.ts layout. */
-    /**
-     * The reviewer's authoritative verdict lives in reviewer-verdict.md (its
-     * OUTPUT CONTRACT), so recover it when the stdout marker is missing. Server
-     * mode reads the harvested doc from the build-asset store; repo mode reads the
-     * committed doc from the host checkout under issueDir. Returns the parsed
-     * verdict only when the file actually carries a `VERDICT:` marker (else
-     * undefined — we don't want to launder the same fragile fallback through a
-     * different source).
-     */
-    private readReviewerVerdictFromFile;
-    private resolveHostRepoDir;
-    /** Build the GitHub client for the post: token+baseUrl in evals, App auth in prod. */
-    private buildReviewClient;
-    private gitHeadSha;
-    /** Compute the base…head diff locally and parse it into a commentable set. */
-    private gitCommentableDiff;
-    /** Resolve model + variant for a phase/task, honouring YAML templates first. */
-    private resolveModelVariant;
-    private runPhaseCall;
-    private runStandard;
-    /**
-     * Body for `type: bash` / `type: script` phases. Runs a deterministic command
-     * in the sandbox (no LLM), then mirrors the agent-phase lifecycle: report
-     * progress, expose stdout downstream via `output_var` →
-     * `{{phaseOutputs.<name>.output}}`, fail the workflow on a non-zero exit, and
-     * honour an optional `approval_gate`.
-     */
-    private runCommandBody;
-    /** Render a command/script phase's template fields into a {@link CommandSpec}. */
-    private buildCommandSpec;
-    private runCommandPhaseCall;
-    /**
-     * Evaluate a `generic_loop.until_bash` condition INSIDE the sandbox (against
-     * the persisted workspace), replacing the old harness-host `execSync`. Exit 0
-     * ⇒ loop complete. The check inherits the phase's egress; no session log is
-     * written (it's an internal loop condition, not a user-facing phase).
-     */
-    private runUntilBash;
-    /**
-     * Evaluate the `contains_BLOCKED` rule. Returns "fail" when the workflow
-     * should fail, or "continue" when the marker is absent or bypassed.
-     */
-    private evaluateBlocked;
-    /**
-     * Persist + pause for an approval/reply gate, atomically. The approval
-     * insert, the `waiting_approval` phase marker, the optional scratch persist
-     * (loops record their iteration/cycle state here), and the run pause all
-     * happen in one transaction via `db.runs.pauseForApproval` — a partial
-     * failure can't leave the run paused without its gate, or vice versa.
-     */
-    private pauseForApproval;
-    private runReviewerLoop;
-    private runGenericLoop;
-}
-export type { ProgressStep };