lastlight 0.5.1 → 0.6.2

package/dist/engine/executors/shared.d.ts

@@ -0,0 +1,189 @@
+import type { RunResult, ThinkingLevel } from "agentic-pi";
+import { type ExecutorConfig, type ExecutionResult, type ExtensionStatusMap, type SkillsStatus } from "../profiles.js";
+import { AgenticShim } from "../event-shim.js";
+import { BuildAssetStore, type BuildAssetRef } from "../../state/build-assets.js";
+/**
+ * Shared building blocks for the per-backend executors
+ * ({@link ../executors/backends.ts}). These have NO dependency on the
+ * executors or the dispatcher, so the import DAG stays acyclic:
+ * shared → backends → agent-executor.
+ */
+export declare const DEFAULT_MODEL = "anthropic/claude-sonnet-4-6";
+export declare const DOCKER_WORKSPACE_DIR = "/home/agent/workspace";
+export declare const SKILL_BUNDLE_ROOT = ".lastlight-skills";
+export declare const THINKING_LEVELS: ReadonlySet<string>;
+/**
+ * Stage this phase's declared skills into a per-phase bundle directory at
+ * `<workspaceRoot>/.lastlight-skills/<phaseKey>/<basename>/` and return the
+ * staged skill dirs, so the caller can point pi at them explicitly (via
+ * `--skill` for docker or `skillPaths` for the in-process backends). Each
+ * skill is a directory containing SKILL.md plus any `scripts/` / `references/`
+ * / `assets/` — the whole tree comes along.
+ *
+ * Keyed by phase so concurrent phases in one workspace never touch each
+ * other's bundle: only the phase's own `<phaseKey>` subtree is cleared, so a
+ * clean slate per phase doesn't disturb a sibling phase mid-run.
+ *
+ * `mode` controls how each skill lands:
+ *   - "symlink": one symlink per skill → host source. gondolin/none, where pi
+ *     reads skill files host-side / through the cwd mount. Zero-copy.
+ *   - "copy": recursive copy. docker, where the agent's tools run inside the
+ *     container and host symlink targets wouldn't resolve; the copy lands
+ *     under the bind-mounted workspace.
+ *
+ * Returns `undefined` when the phase declares no skills (after clearing its
+ * bundle), so a phase with no `skills:` gets no catalogue at all.
+ */
+export declare function stageSkillBundle(workspaceRoot: string, phaseKey: string, skillPaths: string[] | undefined, mode: "symlink" | "copy"): string[] | undefined;
+/**
+ * Sanitized per-phase key for the skill bundle directory. Phase name first
+ * (unique even for loop iterations like `reviewer_fix_1`), then workflow name,
+ * then a constant fallback — so the bundle is always isolated per phase.
+ */
+export declare function skillBundleKey(config: ExecutorConfig): string;
+/**
+ * Add `entry` to a checkout's local `.git/info/exclude` (idempotent) so the
+ * agent's own `git add`/`commit` can never pick it up. This file lives inside
+ * `.git/` — it is never tracked, committed, or pushed, and it leaves the repo's
+ * real `.gitignore` untouched; the exclusion applies only to this ephemeral
+ * sandbox checkout. Used for the gondolin backend, where the skill bundle must
+ * be staged under cwd (the only mounted dir) rather than as an out-of-repo
+ * sibling. No-op when `repoDir` isn't a git checkout (e.g. the workspace root).
+ */
+export declare function excludeFromGit(repoDir: string, entry: string): void;
+export interface ServerArtifacts {
+    store: BuildAssetStore;
+    ref: BuildAssetRef;
+    /** Host path to `<repo>/.lastlight/<issueKey>` (the staged doc dir). */
+    dir: string;
+    /** Host path to the repo checkout root. */
+    repoDir: string;
+}
+/**
+ * Resolve the server-mode artifact context for a run, or undefined when not in
+ * server mode (the default — the whole seam is then skipped and behaviour is
+ * byte-for-byte repo mode). `hostRepoDir` is the host-visible repo checkout
+ * (for docker that's the bind-mounted workspace path, not the in-container one).
+ */
+export declare function serverArtifacts(config: ExecutorConfig, hostRepoDir: string): ServerArtifacts | undefined;
+/** Stage stored docs into the workspace + exclude the dir from git (server mode). */
+export declare function stageArtifactsIn(art: ServerArtifacts | undefined): void;
+/** Persist docs the phase wrote back to the store (server mode). */
+export declare function harvestArtifactsOut(art: ServerArtifacts | undefined): void;
+export declare class RunResultAccumulator {
+    private sessionId?;
+    private finalText;
+    private agentEnded;
+    private toolErrors;
+    private maxStepsReached;
+    private lastToolError?;
+    private lastAssistantHadToolCall;
+    private fatalError?;
+    private snapshotStats?;
+    private messages;
+    private assistantMessages;
+    private userMessages;
+    private toolCalls;
+    private toolResults;
+    private msgInput;
+    private msgOutput;
+    private msgCacheRead;
+    private msgCacheWrite;
+    private msgCost;
+    private ext;
+    private skillsRaw?;
+    feed(r: Record<string, unknown>): void;
+    private accumulateUsage;
+    /** Stats summed from per-message usage, or undefined if none was seen. */
+    private accumulatedStats;
+    /**
+     * Prefer the per-message accumulation (compaction-proof) over pi's
+     * terminal `usage_snapshot`. Fall back to the snapshot only when the
+     * accumulation carries no token data — e.g. a provider that doesn't
+     * report per-message usage — so a non-compacted snapshot still wins.
+     */
+    bestStats(): RunResult["stats"] | undefined;
+    build(exitCode: 0 | 1 | 2): RunResult;
+    /**
+     * Normalized extension status captured from `extension_status` events
+     * (file-search / github / web-search), or undefined if none reported.
+     * Decoupled from agentic-pi's `RunResult` type, which lags the runtime —
+     * the docker sandbox's agentic-pi emits file-search even when the harness's
+     * pinned `RunResult` type doesn't yet declare it.
+     */
+    extensions(): ExtensionStatusMap | undefined;
+    /**
+     * Normalized skill-loading status from the gated `skills_status` event, or
+     * undefined if none was reported (agentic-pi suppresses it on a run that
+     * configured no skills and discovered none). The skill-loading counterpart
+     * to {@link extensions}.
+     */
+    skills(): SkillsStatus | undefined;
+    /**
+     * The last tool result that came back with `isError: true`, including the
+     * failure text — or undefined if no tool errored. This is what turns a
+     * bare `error_tool` stop reason into a human-readable cause.
+     */
+    toolError(): {
+        tool?: string;
+        message: string;
+    } | undefined;
+    /**
+     * True iff the run's final assistant turn ended on a tool call — meaning
+     * the agent intended to keep going but the loop stopped before it could
+     * respond to the tool result and write its answer. The signal a run was
+     * truncated (step-limit) rather than genuinely finished.
+     */
+    endedOnToolCall(): boolean;
+}
+/**
+ * Detect a provider account error (out of credit, quota, rate-limited, bad key)
+ * that pi may have surfaced as plain text rather than a hard failure.
+ *
+ * Critically, on a **successful** run we scan ONLY the genuine provider-error
+ * channel (`agentErrorMessage`, which `extractAgentError` already turns into a
+ * non-success stopReason when set — so it's empty here). The agent's own output
+ * (`finalText`) and tool results (`fatalError`, `toolError`) are NOT scanned on
+ * success: a legitimate `verify`/`qa-test` report or a `curl` probing a 401
+ * endpoint routinely contains "unauthorized" / "rate limit" as part of the task
+ * itself, and folding that in would wrongly fail a genuinely successful run
+ * (and drop its report). Only on a failed run do we fold those in to label why.
+ */
+export declare function detectAccountError(opts: {
+    success: boolean;
+    fatalErrorMessage?: string;
+    agentErrorMessage?: string;
+    finalText?: string;
+    toolErrorText?: string;
+}): boolean;
+export declare function finalizeFromRunResult(result: RunResult, _prompt: string, shim: AgenticShim, startTime: number, extensions?: ExtensionStatusMap, skills?: SkillsStatus, toolError?: {
+    tool?: string;
+    message: string;
+}, endedOnToolCall?: boolean): ExecutionResult;
+export declare function mapStopReason(result: RunResult): string;
+/**
+ * Scan agent_end's messages for a failed assistant turn. pi-agent-core's
+ * `handleRunFailure` catches provider errors, synthesizes an assistant
+ * message with stopReason "error"/"aborted" + errorMessage, and emits a
+ * normal agent_end — so the only signal that the run actually failed
+ * lives on the last assistant message.
+ */
+export declare function extractAgentError(result: RunResult): {
+    stopReason: string;
+    errorMessage: string;
+} | undefined;
+export declare function coerceThinking(raw: string | undefined): ThinkingLevel | undefined;
+export declare function resolveSessionsDir(config: ExecutorConfig): string;
+export declare function emptyResult(stopReason: string, durationMs: number): {
+    finalText: string;
+    turns: number;
+    costUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+    stopReason: string;
+    durationMs: number;
+};
+/** Splice values into process.env for the duration of a sync block. */
+export declare function applyEnv(env: Record<string, string>): () => void;