@peakflo/agent-harness 0.0.0-stage → 0.2.2-rc.1

package/dist/runtime/session-runner.d.ts

@@ -0,0 +1,520 @@
+/**
+ * THE SESSION RUNNER — one leased turn, start to finish.
+ *
+ * This is the loop 20x's `AgentManager` runs, reduced to the part that is
+ * actually about running an agent: prepare a workspace, wire the MCP servers
+ * through the loopback auth proxy, drive a backend adapter, and push every part
+ * it produces into the durable projection and then out to the control plane.
+ *
+ * WHAT IT DELIBERATELY IS NOT. `AgentManager` also owns tasks, worktrees, pull
+ * requests, plugin actions, skills sync, output-field extraction and heartbeat
+ * scheduling. None of that is a property of running an agent; all of it is a
+ * property of 20x's TASK model. Dragging it across would have made this package
+ * "20x without a window" rather than a harness, and would have required the
+ * control plane to grow a task table to match. The seam is cut at the turn.
+ *
+ * THE TURN IS THE UNIT OF WORK, which is what makes the lease design work: one
+ * lease is one turn, a lease that expires is requeued, and a runner that dies
+ * mid-turn loses at most that turn — because the parts it already produced were
+ * ingested as it went, not at the end.
+ */
+import type { CodingAgentAdapter } from '../adapters';
+import { SessionModelGateway } from '../adapters/model-gateway';
+import { ArtifactInspector, ConversationStore, EventSink, ModelMessageRecord, Notifier, SecretProvider, Telemetry, TranscriptStore, WorkspaceProvider } from '../ports';
+import { LeaseResponse, ModelMessageInput, TranscriptPartInput, TurnMetadata } from '../types';
+import { McpAuthProxy } from './mcp-auth-proxy';
+export interface SessionRunnerDeps {
+    /** Resolves a backend name from the lease to a working adapter. */
+    getAdapter(backend: string): CodingAgentAdapter;
+    /**
+     * The per-turn model-gateway credential holder the adapter reads from.
+     *
+     * Optional so the existing tests, which drive a fake adapter that never
+     * consults a gateway, keep constructing a runner without one.
+     */
+    modelGateway?: SessionModelGateway;
+    store: TranscriptStore;
+    workspace: WorkspaceProvider;
+    proxy: McpAuthProxy;
+    secrets: SecretProvider;
+    events: EventSink;
+    telemetry: Telemetry;
+    notifier: Notifier;
+    artifacts: ArtifactInspector;
+    /**
+     * Push a batch out. Returns the control plane's new cursor.
+     *
+     * Injected rather than taking a `ControlPlaneClient`, so the runner can be
+     * tested — and so the 20x desktop can later reuse it with an ingest that
+     * writes to the local database instead of over HTTPS.
+     */
+    ingest(sessionId: string, parts: TranscriptPartInput[], turn: TurnMetadata | undefined, final: boolean, modelMessages?: ModelMessageInput[]): Promise<void>;
+    /**
+     * Where the harness remembers the conversation between turns.
+     *
+     * OPTIONAL so every existing caller and test keeps working unchanged — and
+     * a runner without one behaves EXACTLY as it did before this fix, which is
+     * to say it forgets everything. That is deliberate: the degradation is a
+     * missing dependency, not a silent code path, and `MemoryConversationStore`
+     * is the default the harness actually wires.
+     */
+    conversation?: ConversationStore;
+    /**
+     * Called when the turn starts or stops waiting on a human permission.
+     *
+     * THIS IS THE LATENCY WIRE. The harness uses it to tighten how often it talks
+     * to the control plane while a prompt is outstanding — see
+     * `APPROVAL_RENEW_INTERVAL_MS` in harness.ts. Without it an approval would
+     * ride the 30s heartbeat and every permission prompt would cost up to half a
+     * minute, which is long enough that the feature reads as broken even when it
+     * works.
+     *
+     * Optional, so a runner constructed without one behaves exactly as before.
+     */
+    onApprovalStateChange?(sessionId: string, waiting: boolean): void;
+    /**
+     * Read the session's history from the CONTROL PLANE.
+     *
+     * Needed because a runner is disposable. When a turn is leased to a machine
+     * that did not run the earlier turns — a new sandbox, a redeployed VM — its
+     * local cache is empty and the control plane is the only place the
+     * conversation still exists. Optional for the same reason as above.
+     */
+    fetchHistory?(sessionId: string): Promise<{
+        backendSessionId: string | null;
+        /**
+         * REQUIRED, not optional, and that is the point.
+         *
+         * The history route returns the checkpoint from the SAME row the ownership
+         * guard consults, so this path can hand a runner a foreign handle exactly
+         * like the lease can. An earlier version of this type omitted the field
+         * entirely, so the closure in `harness.ts` silently dropped it and the
+         * compiler had nothing to object to — the guard was bypassed on the ONE
+         * path it exists for. Making it required means a caller that cannot supply
+         * it has to say so with an explicit `null`.
+         */
+        backendOwnerId: string | null;
+        messages: ModelMessageRecord[];
+    }>;
+    logger?: Pick<Console, 'log' | 'warn' | 'error'>;
+    /**
+     * The HTTP client used to download a turn's attachments. Optional; the
+     * global `fetch` otherwise. Injected so tests need no network.
+     */
+    fetchAttachment?: typeof fetch;
+}
+export interface RunTurnResult {
+    turn: TurnMetadata;
+    /** The session's max rev in the LOCAL store after the turn. */
+    maxRev: number;
+    partsProduced: number;
+}
+/**
+ * The model id the backend actually understands.
+ *
+ * The lease carries `provider` and `model` as SEPARATE fields, but Pi selects
+ * a provider/model pair from ONE qualified string at the adapter boundary.
+ * Passing `model.model` alone therefore threw the provider away: a lease
+ * saying `{provider:'anthropic', model:'claude-sonnet-4'}` reached the adapter
+ * as `claude-sonnet-4`, which has no `/`, so the adapter sent NO model at all
+ * and the backend silently used its own default. The control plane's choice of
+ * model was being ignored on every turn.
+ *
+ * Splitting on the FIRST slash is why this is a plain join and not a
+ * "does it already contain a slash" test: a real gateway model id is
+ * `peakflo/vertex_ai/gemini-3-flash-preview`, whose modelID legitimately
+ * contains a slash of its own.
+ */
+export declare function qualifiedModelId(model: {
+    provider?: string | null;
+    model?: string | null;
+}): string | undefined;
+/**
+ * Refuse to run a turn that would fall back to the host's own credentials.
+ *
+ * THIS IS THE SECURITY POINT OF THE GATEWAY, not a nicety. When the lease
+ * names a gateway but carries no `modelToken`, the adapter builds no `peakflo`
+ * provider, Pi can fall through to whatever is in the host's provider store,
+ * and the turn may run anyway — silently spending
+ * the machine owner's credentials, unmetered, with no per-tenant budget. On a
+ * customer VM, which is outside our security perimeter, that is somebody
+ * else's key being used by our software without anybody noticing.
+ *
+ * A missing token must therefore be LOUD. Returning a reason rather than
+ * throwing keeps the decision testable on its own.
+ */
+/**
+ * Say WHICH model was refused, and by whom.
+ *
+ * The bare provider text is often one word. A turn on
+ * a non-gateway model reported exactly `Forbidden`, which names
+ * neither the model nor the provider that refused it, so it reads as a fault
+ * in this runner. It is not: the provider rejected a model this machine holds
+ * no credential for.
+ *
+ * A model id names its provider (decision recorded in `modelGatewayRefusal`),
+ * and only the gateway provider is credentialed per turn from the lease.
+ * Every other provider needs a credential on the RUNNER, so for those the
+ * refusal is worth naming as a likely missing credential — likely, not
+ * certain, because a quota or a withdrawn model refuses identically and
+ * claiming otherwise would send the reader to the wrong place.
+ */
+export declare function describeProviderError(error: string, qualifiedModel: string | undefined): string;
+export declare function modelGatewayRefusal(lease: {
+    modelToken?: string | null;
+    session: {
+        runtime?: string;
+        agent: {
+            model: {
+                provider?: string | null;
+                gatewayUrl?: string | null;
+            };
+        };
+    };
+}): string | null;
+/**
+ * Option ids that mean YES.
+ *
+ * AN ALLOWLIST, NOT "anything that is not deny". The difference matters the
+ * moment a backend adds a fifth option: under a denylist an unrecognised id
+ * would be APPROVED, and the cost of being wrong in that direction is an
+ * unattended agent running a command the user meant to refuse. Under this list
+ * an unrecognised id is refused, and the cost of being wrong is a prompt the
+ * user has to answer twice.
+ *
+ * `once` and `always` are OpenCode's own wire words; `allow`, `allow-always`
+ * and `approved-for-session` are what `getPendingApproval` offers and what 20x
+ * sends. All five are accepted because both vocabularies reach this function.
+ */
+/**
+ * What happened to an `answer` command.
+ *
+ * A DISCRIMINATED RESULT, NOT A BOOLEAN, and the distinction is load-bearing.
+ * `false` used to mean both "there was nothing to answer" and "the backend
+ * refused the answer", and the caller's recovery path — forgetting the
+ * commandId, telling the user — is right for the second and WRONG for the
+ * first. Collapsing them is what made that recovery path unreachable: the
+ * catch below swallowed the delivery failure and returned the same `false` a
+ * stale answer returns, so the harness's `.catch()` never fired and the user's
+ * click vanished with no error anywhere.
+ */
+/**
+ * The permission identity a backend session was created under.
+ *
+ * THE FULL PAIR, NOT JUST `permissionMode`. `default`, `plan` and `acceptEdits`
+ * all map to `'ask'` and differ only in `sandboxMode`, so comparing the
+ * two-valued mode alone would miss a `default` -> `plan` change entirely.
+ * Dormant on OpenCode, where those are indistinguishable anyway — but Codex
+ * reads `sandboxMode` directly, and a guard written generically should not
+ * quietly depend on which backend happens to be wired.
+ *
+ * A LEGACY VALUE ('ask' / 'allow', written before this carried the pair) can
+ * never equal a fingerprint, so it reads as "unrecorded" and forces a rebuild.
+ * That is the intended fail-closed outcome, not an accident of the format.
+ */
+export declare function permissionFingerprint(mode: string | null | undefined): string;
+export type ApprovalOutcome = 
+/** Delivered to the backend. */
+'delivered'
+/** Nothing to answer, or the answer named a different question. Not an error. */
+ | 'ignored'
+/** The backend could not be told. The user must be informed and may retry. */
+ | 'failed';
+/**
+ * Decode the wire format produced by the browser's question card.
+ *
+ * This deliberately matches 20x's AgentManager: each line is either
+ * `Header: answer` or an unlabelled single answer. OpenCode needs the headers
+ * to align answers with a multi-question request.
+ */
+export declare function decodeQuestionAnswers(answer: string | undefined): Record<string, string>;
+/**
+ * Is this option id an approval?
+ *
+ * Exported so `approving-option-ids.test.ts` can check it against what the
+ * ADAPTERS actually offer, rather than against a restatement of the same list —
+ * a hardcoded copy in the test would have passed against the bug that made
+ * Codex's "Allow" read as a denial.
+ */
+export declare function isApprovingOptionId(optionId: string): boolean;
+export declare class SessionRunner {
+    private readonly deps;
+    private readonly logger;
+    /**
+     * What the running turn needs in order to ANSWER a permission from outside
+     * the turn's own call stack.
+     *
+     * `run()` is a single long await; the answer arrives on a control-plane
+     * command handled by the harness, on a completely different stack. These
+     * three are what `answerPendingApproval` needs and cannot otherwise reach.
+     */
+    private turnContext;
+    /** The approval currently shown to the user, if any. */
+    private openApproval;
+    /** The transcript identity of an ordinary agent question, if one is open. */
+    private openQuestionPartId;
+    /**
+     * Expiry of the model token THIS RUNNING BACKEND is holding, when the
+     * control plane reported one — see `LeaseResponse.modelTokenExpiresAt`.
+     * Updated by `updateModelCredential` on a mid-turn refresh. `null` for a
+     * sandbox turn (its per-SANDBOX key has no per-turn expiry to track).
+     */
+    private modelTokenExpiresAt;
+    /**
+     * Written once per turn, the first time `modelTokenExpiresAt` is found to
+     * be in the past on a backend that cannot take a live credential update
+     * (`notifyConfigChanged` absent — currently Pi). Without this a self-hosted
+     * or desktop Pi turn that outlives its 1h key fails its NEXT model call
+     * with an ordinary-looking auth error and no indication why, which reads as
+     * a random provider outage rather than the known, disclosed limitation it
+     * is.
+     */
+    private modelKeyExpiryNoticeShown;
+    /** toolCallIds already turned into a question part, so it is emitted once. */
+    private readonly emittedApprovals;
+    /**
+     * Total wall-clock this turn has spent blocked on a human.
+     *
+     * ADDED BACK ONTO THE TURN DEADLINE. `maxTurnDurationMs` is 600 s and it
+     * exists to stop a runaway MODEL, not to put a stopwatch on the user: a
+     * person who takes eleven minutes to decide whether to allow a shell command
+     * is behaving normally, and killing their turn for it would make the approval
+     * feature useless for exactly the cautious user it is built for.
+     */
+    private approvalWaitMs;
+    private approvalWaitStartedAt;
+    constructor(deps: SessionRunnerDeps);
+    /**
+     * True while a permission prompt is outstanding. Read by the harness to
+     * decide how hard to poll the control plane for the answer.
+     */
+    isAwaitingApproval(): boolean;
+    /**
+     * Run the leased turn to completion, or until `signal` aborts it.
+     *
+     * NEVER THROWS FOR AN AGENT-SIDE FAILURE. A backend that crashes, a model that
+     * errors, a tool that hangs — all of those are OUTCOMES of a turn and are
+     * reported in `TurnMetadata.stopReason`, because the control plane needs to
+     * record them and the user needs to see them. Only a failure to talk to the
+     * control plane at all propagates, since that is the one thing the runner
+     * cannot report through the control plane.
+     */
+    run(lease: LeaseResponse, signal: AbortSignal): Promise<RunTurnResult>;
+    /**
+     * Does this polled part merely mirror the prompt the runner itself sent?
+     *
+     * Matched on TEXT, not on id, because the echo's id belongs to the backend
+     * (`user-message-3`, `user-173…`, `<uuid>-text`) and no runner can predict
+     * it. Matched as a PREFIX of the sent prompt, not equality, because ACP
+     * agents deliver the echo as `user_message_chunk` updates whose accumulated
+     * text grows to the full prompt over several polls — dropping only the final
+     * equal one would strand the intermediate versions in the store.
+     *
+     * Both sides are trimmed first: a backend that strips a trailing newline
+     * from the echoed text must not slip past the prefix check on that alone.
+     */
+    private isEchoOfTurnPrompt;
+    /**
+     * Poll the adapter until the turn goes quiet or the signal aborts.
+     *
+     * The adapter's `onDataAvailable` callback wakes this immediately when the
+     * backend has buffered output, so the 2s interval is a FLOOR for liveness
+     * rather than the streaming latency. Without it every token would arrive up
+     * to two seconds late and the UI would look broken.
+     */
+    /**
+     * Pump the backend until it goes quiet, returning what was produced AND any
+     * provider error the backend reported.
+     *
+     * THE ERROR HALF OF THE RETURN IS THE POINT. `getStatus` reports a provider
+     * failure as `type: 'error'` with a message, and this loop used to fold that
+     * into `quiet` alongside `idle` — it stopped draining, which is correct, and
+     * then threw the message away, which is not. The turn went on to be recorded
+     * as `stopReason: 'completed'` with `error: null`.
+     *
+     * That is not theoretical. On 2026-08-22 a gateway stopped serving the
+     * configured model; five consecutive turns logged
+     * `Provider error … Invalid model name passed in model=gpt-4.1`, produced no
+     * assistant output at all, and were all stored as SUCCESSFUL turns. The UI
+     * faithfully showed five user messages and no replies, the runner showed
+     * `ready`, and nothing anywhere said the model call had failed.
+     */
+    private drain;
+    /**
+     * THE SOFT WARNING, fired once at 90% of a CONFIGURED hard ceiling.
+     *
+     * Always written into the transcript so the user sees the countdown even
+     * when the backend cannot take a mid-turn nudge. `steerTurn` is optional on
+     * `CodingAgentAdapter` for exactly that reason: Pi can deliver a message to
+     * a running turn (`streamingBehavior: 'steer'`); OpenCode's `sendPrompt` is
+     * a single long-lived HTTP call per session and calling it again while one
+     * is already in flight is not safe, so it does not implement this and the
+     * warning stays transcript-only there.
+     */
+    private warnOfHardCeiling;
+    /** Wall-clock spent in the approval we are in RIGHT NOW, if any. */
+    private liveApprovalWaitMs;
+    /**
+     * WIRE 2. Turn a pending backend permission into a `question` transcript part.
+     *
+     * The whole channel below this already existed and was simply never joined
+     * up. The OpenCode adapter queues `permission.asked` events, reports
+     * `WAITING_APPROVAL` from `getStatus` while any are outstanding, and exposes
+     * `getPendingApproval`. The control plane already accepts an answer and
+     * queues it as a session command. The UI already renders a `question` part,
+     * already shows its options as buttons, and already posts `optionId` back.
+     * The only thing missing was somebody asking the adapter.
+     *
+     * THIS IS DELIBERATELY THE SAME SHAPE 20x EMITS (agent-manager.ts:2342-2367),
+     * because the two products render the same transcript and a second shape
+     * would mean a second renderer. ONE DIFFERENCE, ON PURPOSE: 20x builds its
+     * options as `{ label }` and throws `optionId` away, which forces its IPC
+     * layer to recover the choice by matching a display label against a hardcoded
+     * map of English strings (agent-manager.ts:4510-4516). We keep the id. Labels
+     * are ambiguous, repeatable between questions and translatable; ids are none
+     * of those things.
+     *
+     * `getPendingApproval` is DUCK-TYPED rather than declared on
+     * `CodingAgentAdapter` — again matching 20x — so a backend with no permission
+     * concept needs no stub and is simply never asked.
+     */
+    private emitPendingApproval;
+    /**
+     * Tell the USER that their answer could not be delivered.
+     *
+     * Without this, a failed delivery is a server-side log line and nothing else:
+     * the question card stays open, the turn keeps waiting (approval time is
+     * deliberately excluded from the turn deadline), and the person who clicked
+     * Allow has no way to tell their click from a slow backend. An error part is
+     * the only channel that reaches them.
+     *
+     * The approval is deliberately left OPEN — the backend never heard the
+     * answer, so the prompt is still genuinely outstanding and answering again is
+     * the right thing to do.
+     */
+    reportApprovalFailure(sessionId: string, reason: string): Promise<void>;
+    /**
+     * MID-TURN MODEL-CREDENTIAL REFRESH — the LONG TURNS audit's answer to a
+     * fixed per-turn LiteLLM key TTL. Called from the harness's lease-renewal
+     * callback when the control plane re-mints the token near its old expiry.
+     *
+     * Updates the shared gateway holder unconditionally (so the NEXT model call
+     * on this turn already uses it), then asks the adapter to push it to a
+     * running backend that can take a live config update. `notifyConfigChanged`
+     * is optional on `CodingAgentAdapter` for exactly this reason: OpenCode
+     * implements it (a shared server, config pushed over HTTP); Pi does not —
+     * its credential is fixed in the child process's environment at spawn, so a
+     * refresh here updates the holder for the SAME session's next turn (a fresh
+     * Pi process) but not the one currently running. That is a real, disclosed
+     * gap, not a silent one: Pi turns still rely on the 1h key outlasting the
+     * turn, same as before this method existed — `expiresAt` is recorded
+     * regardless, so `drain()`'s expiry notice still fires on the correct
+     * (refreshed) deadline rather than the original, already-superseded one.
+     */
+    updateModelCredential(sessionId: string, apiKey: string, expiresAt?: string): void;
+    /** Stop the approval clock and tell the harness it may relax. */
+    private closeApproval;
+    private closeQuestion;
+    /**
+     * WIRE 3. Apply an `answer` session command to the running turn.
+     *
+     * Before this existed, `harness.applyCommand` marked an `answer` as applied
+     * and DROPPED IT. That is what made the permission mode unshippable rather
+     * than merely unenforced: turning the mode on without this would have turned
+     * "silently unrestricted" into "silently hangs on every turn", and because
+     * the default agent stores `permissionMode: 'default'`, it would have hit
+     * every session at once.
+     *
+     * Returns true when the answer reached the backend.
+     */
+    answerPendingApproval(command: {
+        sessionId: string;
+        partId?: string;
+        answer?: string;
+        optionId?: string;
+    }): Promise<ApprovalOutcome>;
+    private pending;
+    /**
+     * Everything this turn projected, in order.
+     *
+     * Reset at the start of every `run`. Used only to derive the assistant half
+     * of the model-facing log; the transcript itself is already stored by then.
+     */
+    private turnParts;
+    /**
+     * STORE FIRST, SEND SECOND, and never the other way round.
+     *
+     * The local store is what lets a harness survive its own crash; if a part
+     * were sent before it was stored, a crash between the two would leave the
+     * control plane holding a part the runner does not know it produced, and a
+     * resumed turn would produce it again with a NEW id — a visible duplicate in
+     * the user's transcript. Storing first makes the send idempotent, because the
+     * upsert is keyed on (sessionId, partId).
+     */
+    private record;
+    /**
+     * Push a batch to the control plane, chunked to the contract's ceiling.
+     *
+     * The ceiling is enforced HERE rather than discovered as an opaque rejection
+     * mid-turn. `MAX_INGEST_PARTS` is shared with the control plane precisely so
+     * both sides agree on it; a limit only one side knows is not a limit.
+     */
+    private flush;
+    /**
+     * WHERE `resumeFromRev` FINALLY DOES SOMETHING.
+     *
+     * The field was specified in the frozen contract, declared in `types.ts`,
+     * documented in the README and named in three test files. The control plane
+     * computed it and put it on every lease. Nothing in the runtime had ever read
+     * it. This is the read.
+     *
+     * ITS MEANING, taken from the contract's own comment: "the harness already
+     * holds transcript up to this rev and need not replay it. Null means start
+     * cold." So it is a statement about what the SERVER has, which the runner
+     * compares against what IT has:
+     *
+     *   null                    -> a brand-new conversation. Nothing to load.
+     *   local maxRev >= it      -> this runner ran the earlier turns and its
+     *                              cache is current. No network call.
+     *   local maxRev  < it      -> this runner is behind, or has never seen this
+     *                              session at all. The control plane is the only
+     *                              place the conversation still exists; fetch it.
+     *
+     * That third case is the one that matters, and it is not an edge case: it is
+     * every cold sandbox, every redeployed runner, and every turn that happens to
+     * be leased to a different machine than the one before it.
+     *
+     * NEVER THROWS. A conversation that cannot be loaded is a turn that starts
+     * cold — degraded, and worth a warning — whereas a throw here would refuse a
+     * turn the user is waiting on. The warning is loud because a fleet silently
+     * forgetting everything is precisely the failure this whole change exists to
+     * end.
+     */
+    private priorMessageCount;
+    private loadMemory;
+    /**
+     * Authorise this session for exactly the secrets it was granted.
+     *
+     * Returns null when the host has no secret broker, which is the ordinary case
+     * on a runner — see `NoSecretProvider`, where holding no vendor credential is
+     * a security position rather than a gap.
+     */
+    private setUpSecrets;
+    /**
+     * Build the backend's session config.
+     *
+     * EVERY MCP SERVER GOES THROUGH THE LOOPBACK PROXY. The real gateway URL and
+     * the session token never reach the backend, never land in an MCP config file
+     * on disk, and never appear in the backend's own session state — so a leaked
+     * workspace does not leak the tenant's tool access. This is also what makes
+     * the token refreshable mid-session, which is the defect the proxy was
+     * originally written for.
+     *
+     * `allowedTools` from the lease is NOT enforced here, and that is deliberate.
+     * It is advisory — for generating AGENTS.md and for what the UI shows. THE
+     * GATEWAY IS AUTHORITATIVE, because a harness on a customer VM is outside our
+     * security perimeter and trusting it to filter its own tools is exactly
+     * defect G2.
+     */
+    private buildSessionConfig;
+}