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

package/dist/types.d.ts

@@ -0,0 +1,952 @@
+/**
+ * THE RUNNER WIRE CONTRACT — the single meeting point between the control
+ * plane (Track A, workflow-builder) and the harness (Track B, extracted from
+ * 20x).
+ *
+ * This file is the contract. `packages/agentSandbox/test/control-plane-stub.mjs`
+ * is the SAME contract in executable form. The two are kept in lockstep on
+ * purpose: prose drifts, a running stub does not.
+ *
+ * FOUR PROPERTIES THAT ARE NOT NEGOTIABLE
+ *
+ * 1. VERSIONED. Every request carries `protocolVersion`. A harness below the
+ *    control plane's floor is refused, and the refusal is FINAL — the harness
+ *    exits so the host is recycled onto a supported version. See
+ *    `./contract.ts`.
+ *
+ * 2. OUTBOUND ONLY. Nothing here requires the harness to accept an inbound
+ *    connection. Work is delivered by a bounded long-poll (`GET .../lease`),
+ *    never by the control plane dialling in. That single property is what lets
+ *    a customer VM behind NAT work with no tunnel and no listening port.
+ *    Anything that needs to reach a running harness — abort, an answer to a
+ *    question — travels back on the NEXT poll, which is why
+ *    `RunnerHeartbeatResponse.sessionCommands` exists.
+ *
+ * 3. RUNTIME NEUTRAL. A Daytona sandbox, a customer VM and the 20x desktop are
+ *    the same client. There is no route, field or token that only one of them
+ *    can use. `POST /api/coding-agents/sessions/:id/ingest` in particular is
+ *    identical for all three; that is the whole payoff of the extraction.
+ *
+ * 4. TOKENS TRAVEL IN THE ENVIRONMENT OR IN HEADERS, NEVER IN ARGV.
+ *    `/proc/<pid>/cmdline` is world-readable; `/proc/<pid>/environ` is readable
+ *    only by the process owner. Every credential below is either an
+ *    `Authorization: Bearer` header or an environment variable handed to a
+ *    child process. Do not "improve" this by adding a `--token` flag.
+ */
+export interface HarnessOptions {
+    /** workflow-api base url, e.g. https://stage-api.peakflo.ai */
+    controlPlaneUrl: string;
+    /**
+     * Enrolment token. Single-use and short-lived. Injected as a sandbox env
+     * var at creation for managed sandboxes, or pasted by an operator for a
+     * self-hosted install. Exchanged ONCE at the register route.
+     */
+    enrolmentToken: string;
+    /** Loopback port for the health check. Never bound to 0.0.0.0. */
+    healthPort: number;
+    /** Preferred loopback port for the sentinel-authenticated GitHub TLS proxy. */
+    githubProxyPort?: number;
+    /**
+     * Commit and push dirty repository worktrees after each turn.
+     *
+     * Defaults on for the managed sandbox runtime. Operators can disable it,
+     * but the checkout still stays on disk until the session is released.
+     */
+    autoCommitDirtyWorktree?: boolean;
+    /** Milliseconds between heartbeats. The control plane may override this. */
+    heartbeatIntervalMs: number;
+    /**
+     * True when pf-bootstrap could not reach the private registry and started
+     * the warm fallback copy instead. Reported at registration so the control
+     * plane can see a degraded fleet.
+     */
+    degraded: boolean;
+    degradedReason?: string;
+    /**
+     * Root under which every session workspace is created, one directory each.
+     *
+     * `/var/pf/workspaces` in the sandbox image, owned `pfharness` mode 0700.
+     * Decision 2 dropped the unix-user-per-session design, so this path IS the
+     * filesystem separation between two sessions of the same tenant — everything
+     * stronger is enforced by the harness and the phase-3 MCP gateway.
+     */
+    workspaceRoot: string;
+    /**
+     * Which hosting mode this is. ADVISORY: it changes routing and what an
+     * operator sees, never a permission. The control plane already knows the
+     * truth from how the enrolment token was minted, so a runner that lied here
+     * would gain nothing.
+     */
+    runtime: RunnerRuntime;
+    /**
+     * How many sessions this host will run at once.
+     *
+     * DEFAULTS TO 1, and that default is a security position: cross-session
+     * isolation on a shared customer VM is the customer's duty, and 1 is the only
+     * value that needs no such assumption.
+     */
+    maxConcurrentSessions: number;
+    /** Free-form routing labels, e.g. ['eu-only', 'has-vpn']. */
+    labels?: string[];
+}
+/**
+ * Every request body in this contract carries the protocol version, so the
+ * control plane can gate on it without depending on a header surviving a
+ * proxy. The header `x-pf-protocol-version` is sent as well and must agree.
+ */
+export interface ProtocolEnvelope {
+    protocolVersion: number;
+}
+/**
+ * Anything that survives a JSON round trip. Used for `payload`, which is
+ * stored as JSONB and must therefore be exactly this and nothing wider.
+ */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * The error body every non-2xx response uses. `retryable` is advisory; the
+ * authority on whether to retry is the HTTP status (see `FINAL_HTTP_STATUSES`
+ * in `./contract.ts`), because a status survives a proxy rewriting a body.
+ */
+export interface ControlPlaneErrorBody {
+    error: string;
+    /** Stable machine-readable reason. See `CONTRACT_ERROR_CODES`. */
+    code?: string;
+    retryable?: boolean;
+    /** Present on a protocol refusal, so an operator can see the floor. */
+    minProtocolVersion?: number;
+    /** Present on a harness-version refusal. */
+    minHarnessVersion?: string;
+}
+/**
+ * Called by `pf-bootstrap`, BEFORE any harness code exists on the host, with
+ * the enrolment token as the bearer. It is the only route in this contract
+ * whose caller is not the harness.
+ *
+ * The enrolment token is valid for one BOOT WINDOW, not one HTTP call:
+ * pf-bootstrap presents it here, then hands it to the harness, which presents
+ * it again at the register route. A control plane that wants a strictly
+ * single-use token returns a FRESH one in `harnessEnrolmentToken`;
+ * pf-bootstrap already prefers that field when it is present.
+ */
+export interface BootstrapRequest {
+    /**
+     * OPTIONAL here, unlike every other request in this contract, and the one
+     * deliberate exception to the envelope rule.
+     *
+     * `pf-bootstrap` ships inside the Daytona snapshot and predates the runner
+     * protocol, so the deployed copies do not send it. Making it required would
+     * declare a contract that the only real client already violates. The control
+     * plane must therefore treat an absent value here as "unknown, pre-protocol
+     * bootstrap" and still answer — refusing would brick every existing sandbox
+     * image on the first deploy.
+     *
+     * This is safe precisely because bootstrap grants nothing: it hands out a
+     * pinned version, a read-only registry token and a URL. The gate that
+     * matters runs at REGISTER, where the envelope is required and enforced.
+     */
+    protocolVersion?: number;
+    /** Best-effort machine identity. Advisory — never an authorisation input. */
+    hostname?: string;
+    platform?: string;
+    arch?: string;
+    nodeVersion?: string;
+}
+export interface BootstrapResponse {
+    /** EXACT version. Never a semver range — the boot must be reproducible. */
+    harnessVersion: string;
+    /** Private registry base url. Public npm is refused in pf-bootstrap. */
+    registryUrl: string;
+    /**
+     * Short-lived registry READ token. Written to a 0600 .npmrc owned by the
+     * harness user, then deleted. Must contain no control characters —
+     * pf-bootstrap refuses it otherwise, because the value is written straight
+     * into an .npmrc and a newline would inject further npm directives.
+     */
+    registryToken: string;
+    /** sha512 of the tarball, verified before anything is executed. */
+    integritySha512: string;
+    /** Must be reachable FROM THE HOST, not from the control plane's own host. */
+    controlPlaneUrl: string;
+    /** Optional fresh enrolment token, preferred by pf-bootstrap when present. */
+    harnessEnrolmentToken?: string;
+    /** The floor, so a doomed boot can be abandoned before fetching anything. */
+    minProtocolVersion?: number;
+}
+/**
+ * What this host can actually do. Reported at registration and refreshed on
+ * every heartbeat, because a host is upgraded in place: `docker` can appear
+ * and a backend can be installed without the runner ever restarting.
+ */
+export interface RunnerCapabilities {
+    /** `process.platform` — 'linux' | 'darwin' | 'win32' | ... */
+    os: string;
+    /** `process.arch` — 'x64' | 'arm64' | ... */
+    arch: string;
+    harnessVersion: string;
+    /**
+     * The sandbox TOOLS layer (gh, @peculiar/x509, ...) currently installed,
+     * synced by pf-bootstrap independently of the harness. Absent on
+     * self-hosted runners and desktop, which never had this layer, and on a
+     * sandbox that booted before it existed.
+     */
+    sandboxToolsVersion?: string;
+    nodeVersion: string;
+    hostname: string;
+    /** Coding-agent backends found on this host, with the version detected. */
+    backends: RunnerBackend[];
+    /**
+     * Flat union of every backend's reported models, deduplicated by id.
+     *
+     * Redundant with `backends[].models`, but the control-plane model picker
+     * reads this form because it does not have to walk the backend list. Absent
+     * or empty means "the host could not enumerate models" — NEVER a guess.
+     */
+    models?: RunnerModel[];
+    /** A repository-backed session is impossible without git. */
+    git: boolean;
+    /** Some backends shell out to Docker. Absent is not an error. */
+    docker: boolean;
+    /**
+     * How many sessions this host will run at once. DEFAULTS TO 1 on a
+     * self-hosted runner: cross-session isolation on a shared customer VM is the
+     * customer's duty, and 1 is the only value that needs no such assumption.
+     */
+    maxConcurrentSessions: number;
+    /** Free-form routing labels, e.g. ['eu-only', 'has-vpn']. */
+    labels?: string[];
+}
+export interface RunnerBackend {
+    /** 'opencode' | 'claude-code' | 'codex' | 'acp' | ... — an open vocabulary. */
+    name: string;
+    version: string | null;
+    /**
+     * Models this backend can drive, when the host can enumerate them.
+     *
+     * Absent means the host could not say — NEVER an empty-but-meaningful list.
+     * A model list is advisory, not a validation gate: the id a lease names is
+     * what is actually called, and even a model the harness never heard of is
+     * sent through verbatim.
+     */
+    models?: RunnerModel[];
+}
+/** One model a harness can drive, in the shape the control-plane UI renders. */
+export interface RunnerModel {
+    /** Full model reference, e.g. 'peakflo/gpt-5.6-sol' or 'gpt-4.1'. */
+    id: string;
+    name: string;
+}
+export interface RunnerRegisterRequest extends ProtocolEnvelope {
+    capabilities: RunnerCapabilities;
+    /**
+     * Which of the three hosting modes this is. Advisory: it changes ROUTING and
+     * what an operator sees, never a permission. The control plane already knows
+     * the truth from how the enrolment token was minted.
+     */
+    runtime: RunnerRuntime;
+    /** True when the warm fallback harness was booted instead of the pinned one. */
+    degraded: boolean;
+    degradedReason?: string;
+}
+export type RunnerRuntime = 'sandbox' | 'self-hosted' | 'desktop';
+export interface RunnerRegisterResponse {
+    /**
+     * The version gate. `false` is FINAL — never retried. The harness exits
+     * non-zero so the host is recycled onto a supported version. It must EXIT
+     * and not merely throw: a listening health socket keeps the Node event loop
+     * alive for ever, so a harness that only threw would hang and the gate would
+     * never take effect.
+     */
+    accepted: boolean;
+    /** Why, in words an operator can act on. Required when accepted is false. */
+    reason?: string;
+    code?: string;
+    minProtocolVersion?: number;
+    minHarnessVersion?: string;
+    /** Absent when accepted is false. */
+    runnerId?: string;
+    tenantId?: string;
+    /**
+     * Long-lived runner credential. Replaces the enrolment token, which burns
+     * here. MEMORY ONLY — never written to disk, never handed to a session
+     * process, never in argv.
+     */
+    runnerCredential?: string;
+    /** ISO 8601. Rotate before this using the rotate route. */
+    credentialExpiresAt?: string;
+    /** ISO 8601. Rotate at this point, comfortably before expiry. */
+    rotateAfter?: string;
+    /** The control plane owns the cadence. */
+    heartbeatIntervalMs?: number;
+    /** Seconds the harness should ask the lease route to hold a poll open. */
+    leaseWaitSeconds?: number;
+}
+export type RunnerStatus = 'starting' | 'ready' | 'busy' | 'draining';
+export interface RunnerHeartbeatRequest extends ProtocolEnvelope {
+    status: RunnerStatus;
+    uptimeMs: number;
+    activeSessions: number;
+    /** Session ids currently held, so the control plane can spot a split brain. */
+    activeSessionIds?: string[];
+    degraded: boolean;
+    /**
+     * Capability REFRESH. A host is upgraded in place, so the control plane must
+     * never treat the registration-time snapshot as permanent.
+     */
+    capabilities: RunnerCapabilities;
+}
+export interface RunnerHeartbeatResponse {
+    ok: boolean;
+    /** Exact harness pin currently selected by the control plane. */
+    harnessVersion?: string;
+    /**
+     * Exact sandbox-tools pin, when the control plane has the tools layer
+     * turned on. Additive and independent of harnessVersion — either can
+     * change without the other.
+     */
+    sandboxToolsVersion?: string;
+    /**
+     * 'drain' asks the harness to finish its work and take no more.
+     * 'restart' asks it to exit so the host is recycled.
+     */
+    action?: 'none' | 'drain' | 'restart';
+    heartbeatIntervalMs?: number;
+    /**
+     * The outbound-only answer to "how does anything reach a running session?".
+     * The control plane cannot dial in, so an abort or a user's answer to a
+     * question rides back on the next heartbeat. Commands are idempotent and may
+     * be repeated until the harness acknowledges them by their effect.
+     */
+    sessionCommands?: SessionCommand[];
+}
+export interface SessionCommand {
+    sessionId: string;
+    /**
+     * 'abort' stops the turn; 'answer' resolves a pending question part;
+     * 'release-workspace' removes a checkout after the session ends.
+     */
+    command: 'abort' | 'answer' | 'release-workspace';
+    /** Set when command is 'answer' — the partId of the question being answered. */
+    partId?: string;
+    /** Set when command is 'answer' — the user's reply. */
+    answer?: string;
+    /**
+     * Set when command is 'answer' AND the user picked a NAMED OPTION rather
+     * than typing free text.
+     *
+     * ADDITIVE AND OPTIONAL, so it does not break protocol version 1: a harness
+     * built before this field existed ignores an unknown key and continues to use
+     * `answer`, which still carries the human-readable text. A harness that reads
+     * it can branch on the exact option instead of matching a display label by
+     * string — labels are ambiguous, translatable and repeatable between
+     * questions, and ids are none of those things.
+     */
+    optionId?: string;
+    /** De-duplication key. The same commandId must be applied at most once. */
+    commandId: string;
+}
+/**
+ * The bounded long-poll that replaces a socket.
+ *
+ *   204 No Content   no work; poll again immediately
+ *   200              a lease, in the body below
+ *
+ * `wait` is in SECONDS and defaults to 25. 25 matches the existing
+ * `boundSseStream` heartbeat, and it is chosen against Cloud Run: a request
+ * slot is billed for the whole life of a connection and capped at 3600s, which
+ * is what rules out one persistent WebSocket per runner.
+ */
+export interface LeaseResponse {
+    /**
+     * Exact harness pin currently selected by the control plane.
+     *
+     * This is additive. A runner that already received a live lease finishes it
+     * before it acts on a changed pin. Idle runners also receive the pin on the
+     * heartbeat response, because a 204 lease response has no body by contract.
+     */
+    harnessVersion?: string;
+    /**
+     * Exact sandbox-tools pin (gh, @peculiar/x509, ...), independent of
+     * harnessVersion. Same additivity rule: idle runners get it on the
+     * heartbeat response too, since a 204 lease has no body.
+     */
+    sandboxToolsVersion?: string;
+    session: LeasedSession;
+    leaseId: string;
+    /**
+     * ISO 8601 visibility timeout. Renew before this or the watchdog requeues
+     * the session onto another runner. Every successful ingest also extends it,
+     * so a runner that is producing output rarely needs to call renew at all.
+     */
+    leaseExpiresAt: string;
+    /**
+     * Session-scoped MCP token. Bound to runnerId AND sessionId, short TTL,
+     * revoked when the session ends. It carries NO tool list — the allowlist is
+     * re-read from the database on every call so revocation is immediate.
+     *
+     * NO VENDOR CREDENTIAL EVER LEAVES THE CONTROL PLANE. This token buys access
+     * to the gateway, and the gateway injects the real credentials server-side.
+     */
+    mcpToken: string;
+    /**
+     * Per-session, budget-capped model token. NOT the tenant's model key — a
+     * customer VM is outside our security perimeter and must never hold one.
+     */
+    modelToken: string;
+    /**
+     * ISO 8601 expiry of `modelToken`, when the control plane minted one with a
+     * known lifetime (a `self-hosted`/`desktop` per-turn key; absent for a
+     * sandbox's longer-lived per-SANDBOX key, which is not refreshed this way).
+     * Echoed back on `/renew` as `modelTokenExpiresAt` so the control plane can
+     * re-mint it near expiry, on the same cadence the GitHub credential already
+     * uses — a fixed 1h key TTL would otherwise cut a healthy turn on these
+     * runtimes on its own, independent of `maxTurnDurationMs`.
+     */
+    modelTokenExpiresAt?: string;
+    /** In-memory only. It is never passed through a process environment. */
+    githubCredential?: LeasedGitHubCredential;
+}
+export interface LeasedSession {
+    sessionId: string;
+    tenantId: string;
+    /** One lease is one TURN. A new turn on the same session is a new lease. */
+    turnId: string;
+    runtime: RunnerRuntime;
+    agent: LeasedAgent;
+    input: LeasedTurnInput;
+    /**
+     * The harness keeps a local SQLite store so it survives its own crash. When
+     * this is non-null the harness already holds transcript up to this rev and
+     * need not replay it. Null means start cold.
+     */
+    resumeFromRev: number | null;
+    /**
+     * The backend's own handle for this conversation, when the control plane has
+     * one recorded.
+     *
+     * AN OPAQUE CHECKPOINT. The control plane never interprets it; it stores what
+     * the last runner reported and hands it back, so a runner that still has that
+     * backend session alive can RESUME the conversation instead of rebuilding it
+     * from a log. Null means no backend session is known and the runner must
+     * replay history into a fresh one.
+     */
+    backendSessionId?: string | null;
+    /**
+     * Which backend minted `backendSessionId`.
+     *
+     * Without this the cross-backend safety check below could only ever run on a
+     * runner that happened to have run the earlier turn itself — that is, never
+     * in the case it exists for.
+     */
+    backendName?: string | null;
+    /**
+     * WHICH BACKEND INSTANCE minted `backendSessionId` — see `TurnMetadata`.
+     *
+     * A runner resumes only when this equals its OWN backend instance id. Any
+     * other value, including absent, means the handle belongs to somebody else's
+     * opencode state directory and is not a session at all from here.
+     */
+    backendOwnerId?: string | null;
+    workspace: LeasedWorkspace;
+    limits: LeasedLimits;
+}
+export interface LeasedAgent {
+    agentId: string;
+    name: string;
+    /** 'opencode' first. An open vocabulary, not a union. */
+    backend: string;
+    systemPrompt: string | null;
+    model: LeasedModel;
+    /**
+     * The real permission mode, honoured for real. Phase 0 recorded G1: the
+     * 20x claude-code adapter hardcodes 'bypassPermissions'. This field exists so
+     * that stops being possible.
+     */
+    permissionMode: 'default' | 'plan' | 'acceptEdits' | 'bypassPermissions';
+    /** Always the skill's PUBLISHED content, never its draft. */
+    skills: LeasedSkill[];
+    mcpServers: LeasedMcpServer[];
+}
+export interface LeasedModel {
+    provider: string;
+    model: string;
+    /**
+     * The model gateway base url. The harness talks to this with `modelToken`,
+     * never directly to a vendor with a tenant key.
+     */
+    gatewayUrl: string;
+}
+export interface LeasedSkill {
+    skillId: string;
+    name: string;
+    /** From skills.published_content. A draft must never reach a runner. */
+    content: string;
+}
+export interface LeasedMcpServer {
+    serverId: string;
+    name: string;
+    /**
+     * Always 'http'. A 'local' (stdio) server is refused for a cloud sandbox and
+     * is never expressible here, because a stdio server would mean a credential
+     * on the host.
+     */
+    transport: 'http';
+    /** /api/mcp/agent/:sessionId/:serverId — authenticated with `mcpToken`. */
+    url: string;
+    /**
+     * ADVISORY ONLY, for generating AGENTS.md and for what the UI shows.
+     * THE GATEWAY IS AUTHORITATIVE: `tools/list` returns only allowed tools and
+     * `tools/call` refuses anything outside the allowlist before dispatch. A
+     * harness must never be trusted to enforce this — that is exactly defect G2.
+     * `null` means "every tool the server exposes".
+     */
+    allowedTools: string[] | null;
+}
+export interface LeasedTurnInput {
+    /** 'message' is a new user turn; 'resume' continues an interrupted one. */
+    kind: 'message' | 'resume';
+    role: 'user';
+    content: string;
+    attachments?: LeasedAttachment[];
+    /**
+     * Attachments the control plane could NOT turn into a `LeasedAttachment`
+     * at lease time — a local-storage `local://` URL the harness cannot fetch,
+     * or a signing failure. Without this the harness has no way to know these
+     * ever existed: they are absent from `attachments`, so its own download
+     * loop never runs for them and never adds them to its OWN failure list
+     * either. `session-runner.ts` merges these into that same list before
+     * building the prompt note, so the model (and the user, via the
+     * transcript) is told a file it was named is not available, instead of
+     * the turn silently running as if it had never been attached at all.
+     */
+    droppedAttachments?: Array<{
+        name: string;
+        reason: string;
+    }>;
+}
+export interface LeasedAttachment {
+    name: string;
+    mimeType: string;
+    /** Pre-signed, short-lived. The harness fetches it; it is not inlined. */
+    url: string;
+    sizeBytes?: number;
+}
+export interface LeasedWorkspace {
+    /**
+     * 'scratch' is a bare working directory and is the default — the product
+     * requirement is an agent with MCP access, not filesystem access.
+     * 'repository' is an explicit per-agent opt-in and only ever on a runner
+     * the customer chose.
+     */
+    mode: 'scratch' | 'repository';
+    repositoryUrl?: string;
+    ref?: string;
+    repositories?: LeasedGitHubRepository[];
+    /** Names requested by the session, retained even when the server refuses them. */
+    requestedRepositories?: string[];
+    /** A server-side ruleset or installation refusal. The harness fails loudly. */
+    refusalReason?: string;
+}
+export interface LeasedGitHubRepository {
+    id: number;
+    fullName: string;
+    defaultBranch: string;
+    cloneUrl: string;
+}
+export interface LeasedGitHubCredential {
+    token: string;
+    expiresAt: string;
+    repositories: LeasedGitHubRepository[];
+}
+export interface LeasedLimits {
+    /**
+     * Last-line wall-clock ceiling on the turn, or `null` for NO ceiling.
+     *
+     * THIS IS NOT THE PRIMARY GUARD ANY MORE. A runaway model is caught by
+     * `maxTurnIdleMs` below — the wall clock stayed the enforcement instrument
+     * for too long, and a real coding turn routinely runs 30-90 minutes, so a
+     * fixed cap cut healthy turns as often as it caught broken ones.
+     *
+     * `null` is the default: no operator has opted into a ceiling, so none is
+     * enforced. Set only when `CODING_AGENT_MAX_TURN_MINUTES` is configured
+     * (services/coding-agents/config.ts), in which case it is a real backstop —
+     * the watchdog requeues a session whose lease outlives it, but a healthy
+     * runner should never reach it, because the idle guard below stops a hung
+     * turn first.
+     */
+    maxTurnDurationMs: number | null;
+    /**
+     * No progress — a new message part, a tool call start/end, or streamed
+     * text — for this long ends the turn: the backend is hung, not merely slow.
+     * A single tool call that legitimately runs long (a big test suite, a slow
+     * build) produces nothing until it COMPLETES, so this has to be generous
+     * enough to outlast one, not just a network hiccup. Approval wait time is
+     * excluded, exactly like `maxTurnDurationMs`. Defaults to 20 minutes in the
+     * runner when absent; configurable via `CODING_AGENT_MAX_TURN_IDLE_MINUTES`.
+     */
+    maxTurnIdleMs?: number;
+    maxOutputTokens?: number;
+    /** Per-session spend ceiling in USD. */
+    spendCapUsd?: number;
+}
+export interface LeaseRenewRequest extends ProtocolEnvelope {
+    /** Advisory progress note, so an operator can see a slow turn is alive. */
+    status?: RunnerStatus;
+    /** The server returns a replacement only when this enters its safety window. */
+    githubTokenExpiresAt?: string;
+    /** Same idea, for the per-turn LiteLLM key. See `LeaseResponse.modelTokenExpiresAt`. */
+    modelTokenExpiresAt?: string;
+}
+export interface LeaseRenewResponse {
+    /**
+     * False when the lease has already expired and been requeued elsewhere. The
+     * harness must then ABANDON the turn and stop ingesting for it: another
+     * runner owns the session now, and two writers would interleave a transcript.
+     */
+    renewed: boolean;
+    leaseExpiresAt?: string;
+    reason?: string;
+    githubCredential?: LeasedGitHubCredential;
+    /**
+     * A replacement per-turn model token, present only when
+     * `modelTokenExpiresAt` on the request was inside the refresh margin AND
+     * this runner is not a sandbox (whose key is not refreshed this way).
+     */
+    modelToken?: string;
+    /** Expiry of the token above, when one was minted. */
+    modelTokenExpiresAt?: string;
+    /**
+     * Commands queued for this runner, delivered on the renewal.
+     *
+     * WHY HERE AND NOT ONLY ON THE HEARTBEAT. The heartbeat is 30 s. That is fine
+     * for an abort and far too slow for a PERMISSION PROMPT, where the user
+     * clicks Allow and then watches an unchanged screen. Renew is the only
+     * control-plane call that runs for the whole duration of a turn — which is
+     * exactly the window an approval lives in — and while a prompt is open the
+     * harness tightens it to `APPROVAL_RENEW_INTERVAL_MS`.
+     *
+     * ADDITIVE AND OPTIONAL, so protocol v1 is unaffected: a harness built before
+     * this field existed ignores an unknown key and keeps collecting commands on
+     * the heartbeat alone, exactly as it did.
+     *
+     * Only present when the lease was actually renewed. A runner that has lost
+     * its lease must not be handed a command for a turn another runner now owns.
+     */
+    sessionCommands?: SessionCommand[];
+}
+/**
+ * THE RUNTIME-NEUTRAL ROUTE. A Daytona sandbox, a customer VM and the 20x
+ * desktop all call exactly this, with exactly this body. Nothing in it names a
+ * hosting mode. If a future change makes one runtime special here, the change
+ * is wrong.
+ */
+export interface IngestRequest extends ProtocolEnvelope {
+    /** Proves the caller still owns the session. Parts without a live lease are refused. */
+    leaseId: string;
+    parts: TranscriptPartInput[];
+    /**
+     * The EXACT MODEL-FACING messages this turn produced, appended to the
+     * session's durable conversation log.
+     *
+     * Sent BESIDE `parts`, never derived from them. `parts` is a UI projection —
+     * ephemeral markers dropped, tool calls flattened for display, streaming
+     * deltas overwritten in place. That shape is right for a screen and lossy for
+     * a prompt, and replaying it at a model is guessing at what the model was
+     * told. `seq` is absent here for the same reason it is absent from
+     * `TranscriptPartInput`: the server allocates the ordering.
+     */
+    modelMessages?: ModelMessageInput[];
+    /** Durable step metadata. Closes G7 — the ephemeral parts carry none. */
+    turn?: TurnMetadata;
+    /** True on the last ingest of the turn. Releases the lease. */
+    final?: boolean;
+}
+/** One model-facing message on the wire. Order is allocated server-side. */
+export interface ModelMessageInput {
+    role: 'user' | 'assistant';
+    content: string;
+}
+/**
+ * What `GET /api/runners/sessions/:sessionId/history` answers.
+ *
+ * THE RUNNER'S HISTORY READ PATH. Before this existed the harness could only
+ * ever WRITE the conversation out; there was no way to read it back, which is
+ * why a runner that had not personally run the earlier turns had no way to know
+ * what they were.
+ */
+export interface SessionHistoryResponse {
+    sessionId: string;
+    /** The backend checkpoint, when the control plane holds one. */
+    backendSessionId: string | null;
+    /** Which backend INSTANCE minted it — see `TurnMetadata.backendOwnerId`. */
+    backendOwnerId?: string | null;
+    /** The whole model-facing log, ordered by `seq` ascending. */
+    messages: Array<{
+        seq: number;
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
+}
+export interface IngestResponse {
+    /** How many parts were written or updated. */
+    accepted: number;
+    /**
+     * Parts the control plane declined, with a reason each. A rejection is NOT
+     * an error: an ephemeral part is dropped on purpose and the harness should
+     * not retry it.
+     */
+    rejected: IngestRejection[];
+    /**
+     * The session's highest rev after this call. This is the client cursor —
+     * the browser passes it back as `sinceRev`.
+     */
+    maxRev: number;
+    /**
+     * Piggy-backed lease renewal. A runner that is producing output therefore
+     * never needs a separate renew call, which removes a whole class of
+     * "the lease expired while it was working" bug.
+     */
+    leaseExpiresAt: string;
+}
+export interface IngestRejection {
+    partId: string;
+    reason: IngestRejectionReason;
+    detail?: string;
+}
+/**
+ * PER-PART rejection reasons. Every one of these is reachable, and the stub
+ * emits each.
+ *
+ * Ownership is deliberately NOT in this list: a lease that does not own the
+ * session fails the WHOLE request with 409, because a batch half-written by a
+ * runner that no longer owns the session is worse than one not written at all.
+ */
+export type IngestRejectionReason = 
+/** partType is one of the three ephemeral types. Dropped on purpose. */
+'ephemeral'
+/** No content and no payload. Dropped on purpose. */
+ | 'empty'
+/** Missing partId, bad role, unparseable createdAt, ... */
+ | 'malformed'
+/**
+ * Over `MAX_INGEST_PART_BYTES`. Rejected individually, so one enormous tool
+ * result cannot take the rest of the batch down with it.
+ */
+ | 'too-large';
+/**
+ * THE TRANSCRIPT PART — the shape is not negotiable.
+ *
+ * It mirrors the 20x projection field for field (20x/src/main/database.ts:1225)
+ * so that a cloud session can be written straight into the desktop's local
+ * `transcript_parts` and THE 20x TRANSCRIPT UI NEEDS NO CHANGE. Adding a field
+ * here without adding it there breaks that, which is the entire reason cloud
+ * agents in 20x are cheap.
+ *
+ * This is the READ shape. `seq` and `rev` are allocated by the control plane
+ * and appear on the way out; see `TranscriptPartInput` for what goes in.
+ */
+export interface TranscriptPart {
+    partId: string;
+    /**
+     * SERVER-ASSIGNED. New parts take MAX(seq)+1; an existing part KEEPS its seq
+     * and only its content is replaced. That is precisely how token streaming
+     * works — a growing part must not jump to the end of the transcript on every
+     * delta.
+     */
+    seq: number;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    /**
+     * A PLAIN STRING, deliberately not a union.
+     *
+     * A new part type must be addable by the harness without a control-plane
+     * deploy, and an unknown type must render as text rather than crash a reader.
+     * `PERSISTED_PART_TYPES` in ./contract.ts documents the vocabulary in use;
+     * it is not a closed set.
+     *
+     * The three EPHEMERAL types — 'step-start', 'step-finish', 'system-status' —
+     * must NEVER be persisted or ingested. They are UI-only transitions with no
+     * durable meaning; `TurnMetadata` is where their information actually lives.
+     */
+    partType: string;
+    /** Tool name for a tool part. */
+    tool: string | null;
+    /**
+     * Structured metadata: tool arguments, results, question options, ...
+     *
+     * Typed `JsonValue | null` rather than `unknown | null`, which TypeScript
+     * collapses straight back to `unknown` — the `| null` would convey nothing
+     * and the COALESCE distinction below would have no type-level meaning at all.
+     */
+    payload: JsonValue | null;
+    /** ISO 8601. NEVER overwritten on conflict — the first write wins. */
+    createdAt: string;
+    /**
+     * SERVER-ASSIGNED, globally monotonic, bumped on UPDATES as well as inserts.
+     * Allocated from a dedicated sequence, never from SELECT MAX(rev), which is
+     * unsafe under Postgres concurrency.
+     */
+    rev: number;
+}
+/**
+ * What the harness sends. `seq` and `rev` are absent by construction, so a
+ * runner cannot fabricate an ordering and cannot replay an old rev over a
+ * newer one.
+ */
+export interface TranscriptPartInput {
+    /** Idempotency key. The upsert is on (sessionId, partId). */
+    partId: string;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    partType: string;
+    /**
+     * `undefined` means "do not change" and is COALESCEd against the stored
+     * value, so a partial update can never erase metadata a fuller earlier
+     * update established. `null` means "explicitly clear".
+     *
+     * That distinction is the whole of upsert invariant 3, so both fields are
+     * typed to carry it: `?` for absent, an explicit `| null` for cleared.
+     */
+    tool?: string | null;
+    payload?: JsonValue | null;
+    /** ISO 8601. Honoured on INSERT only; a later update never moves it. */
+    createdAt: string;
+}
+/**
+ * Durable step metadata. The ephemeral parts that carry duration and token
+ * counts in 20x are never persisted, so without this the cost panel has no
+ * source. That is defect G7.
+ */
+export interface TurnMetadata {
+    turnId: string;
+    startedAt: string;
+    finishedAt?: string;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    costUsd?: number;
+    /** 'completed' | 'aborted' | 'error' | 'turn_time_limit' | 'no_progress' */
+    stopReason?: string;
+    error?: string;
+    /** Checkout outcome for each repository requested by this session. */
+    repositories?: Array<{
+        fullName: string;
+        status: 'checkedOut' | 'refused' | 'failed';
+        reason?: string;
+    }>;
+    /**
+     * The backend session this turn ran on, reported so the NEXT turn can resume
+     * it instead of starting the model cold.
+     *
+     * Carried on the turn metadata rather than on a route of its own precisely
+     * because the final ingest is already the one message that is guaranteed to
+     * be sent — it is what releases the lease, and it is sent even when the turn
+     * failed. A checkpoint that travelled on a separate call would be lost in
+     * exactly the cases where losing it hurts most.
+     */
+    backendSessionId?: string | null;
+    /**
+     * WHICH backend minted `backendSessionId`.
+     *
+     * Sent because a checkpoint is only meaningful to the backend that created
+     * it — an OpenCode session id handed to Claude Code is not a session, it is a
+     * string. Without this the control plane stores a handle it cannot describe,
+     * and a runner receiving it on a cold start has no way to know whether
+     * resuming it is even sensible.
+     */
+    backendName?: string | null;
+    /**
+     * WHICH BACKEND INSTANCE minted `backendSessionId`.
+     *
+     * `backendName` says "opencode". It does not say WHICH opencode, and that is
+     * the difference between a checkpoint that works and one that has never once
+     * worked.
+     *
+     * An opencode session id is a key into ONE opencode state directory. Two
+     * runners on two machines both run "opencode", so `backendName` matches, and
+     * the second is then handed a `ses_...` its own server never issued. It
+     * answers "Session not found", the runner logs "could not resume", and the
+     * whole conversation is replayed and re-billed. Measured on the owner's
+     * machine: a conversation leased alternately to a laptop and to a
+     * cloud-sandbox runner did this on EVERY turn from the moment the second
+     * runner joined, and never once succeeded.
+     *
+     * Absent means "the runner did not say", which is treated as "not mine" —
+     * the fail-safe direction, because replaying once is recoverable and
+     * resuming someone else's handle is not.
+     */
+    backendOwnerId?: string | null;
+}
+/**
+ * Authenticated with the CURRENT runner credential. The old credential stays
+ * valid for a short grace window, so a rotation that races a request in flight
+ * does not knock the runner offline.
+ */
+export interface CredentialRotateRequest extends ProtocolEnvelope {
+    harnessVersion: string;
+}
+export interface CredentialRotateResponse {
+    runnerCredential: string;
+    credentialExpiresAt: string;
+    rotateAfter: string;
+    /** How long the previous credential keeps working. */
+    previousCredentialValidForMs: number;
+}
+/**
+ * A polite goodbye. IDEMPOTENT: deregistering an already-deregistered runner
+ * answers 200, because the alternative is a shutdown path that can fail.
+ *
+ * The control plane must not depend on this ever arriving — a runner is killed
+ * far more often than it is asked to leave. Liveness is the 30s heartbeat:
+ * offline after three missed beats, in-flight leases requeued.
+ */
+export interface DeregisterRequest extends ProtocolEnvelope {
+    reason?: string;
+    /** True when sessions were still running. The control plane requeues them. */
+    hadActiveSessions?: boolean;
+}
+export interface DeregisterResponse {
+    ok: boolean;
+    /** How many in-flight leases were requeued as a result. */
+    requeuedLeases?: number;
+}
+/**
+ * Served on 127.0.0.1 only, for a container probe. It is not an inbound
+ * control channel and it carries NO token: property 2 above still holds.
+ */
+export interface HealthReport {
+    /**
+     * Deliberately NARROWER than `RunnerStatus`: it omits 'busy'. A probe asks
+     * "may this host be used at all", and a host mid-turn is still healthy.
+     * Occupancy is `activeSessions`, and it is the control plane's business, not
+     * a container probe's.
+     */
+    status: 'starting' | 'ready' | 'draining';
+    harnessVersion: string;
+    nodeVersion: string;
+    piVersion: string | null;
+    registered: boolean;
+    tenantId: string | null;
+    /**
+     * @deprecated The Phase 0 name for the runner id.
+     *
+     * STILL POPULATED, with the same value as `runnerId`. A deployed container
+     * probe reads this field, and a rename that breaks a probe turns a healthy
+     * host into an unhealthy one on the next deploy. It goes when nothing reads
+     * it — which is a separate, observable change, not a side effect of this one.
+     */
+    sandboxId: string | null;
+    degraded: boolean;
+    degradedReason?: string;
+    uptimeMs: number;
+    activeSessions: number;
+    lastHeartbeatAt: string | null;
+    lastHeartbeatError: string | null;
+    /** The protocol revision this build speaks. */
+    protocolVersion?: number;
+    /** THE CANONICAL NAME. Always populated once registered. */
+    runnerId?: string | null;
+}