@peakflo/agent-harness 0.0.0-stage → 0.2.1-rc.3

package/dist/harness.d.ts

@@ -0,0 +1,333 @@
+import type { CodingAgentAdapter } from './adapters';
+import { SessionModelGateway } from './adapters/model-gateway';
+import { ControlPlaneClient } from './control-plane';
+import { CredentialStore } from './credential-store';
+import { ArtifactInspector, EventSink, Notifier, SecretProvider, Telemetry, ConversationStore, TranscriptStore, WorkspaceProvider } from './ports';
+import { HarnessOptions, HealthReport } from './types';
+/**
+ * The control plane refused this harness's PROTOCOL or VERSION. FINAL.
+ *
+ * A distinct class rather than a message match, so a caller cannot break the
+ * gate by rewording an error string. The process must EXIT — not merely throw —
+ * because the health socket keeps the Node event loop alive for ever, and a
+ * harness that only threw would hang while the gate quietly never took effect.
+ * Phase 0 shipped exactly that bug.
+ */
+export declare class VersionRefusedError extends Error {
+    constructor(message: string);
+}
+/** The sandbox supervisor, not the harness, owns package installation. */
+export declare class UpgradeRequestedError extends Error {
+    readonly harnessVersion: string;
+    constructor(harnessVersion: string);
+}
+export interface HarnessUpgradeRequest {
+    harnessVersion: string;
+    /**
+     * Present when a TOOLS-only pin is what actually woke the idle drain.
+     * Advisory for the supervisor's logging — pf-bootstrap's recursed main()
+     * re-dials /harness/bootstrap regardless and resyncs both layers off that
+     * fresh response, not off this field.
+     */
+    sandboxToolsVersion?: string;
+    runnerId: string;
+    tenantId: string | null;
+    runnerCredential: string;
+}
+/**
+ * The per-turn ports an adapter is built against.
+ *
+ * Passed to `getAdapter` rather than read from a module singleton, because the
+ * credential inside changes every turn and an adapter constructed once must see
+ * the CURRENT one.
+ */
+export interface AdapterPorts {
+    /** Holds the model-gateway credential minted for the running turn. */
+    modelGateway: SessionModelGateway;
+}
+export interface HarnessDeps {
+    /**
+     * Resolves a backend name from a lease to a working adapter.
+     *
+     * OPTIONAL, so a host with no backend installed still boots, registers and
+     * reports its capabilities. That matters: a runner whose `pi` install
+     * failed should appear in the fleet as present-but-unusable, not as a host
+     * that never came back at all.
+     */
+    getAdapter?: (backend: string, ports: AdapterPorts) => CodingAgentAdapter;
+    store?: TranscriptStore;
+    /** Injected in tests; defaults to a sqlite file beside the workspace root. */
+    conversation?: ConversationStore;
+    workspace?: WorkspaceProvider;
+    secrets?: SecretProvider;
+    events?: EventSink;
+    telemetry?: Telemetry;
+    notifier?: Notifier;
+    artifacts?: ArtifactInspector;
+    /**
+     * Where the runner credential is persisted between runs.
+     *
+     * Injected in tests; in production it is derived from the runtime — a
+     * durable file store for `self-hosted`/`desktop`, a no-op for `sandbox`.
+     */
+    credentialStore?: CredentialStore;
+    /**
+     * How often the lease is renewed during a turn. Defaults to
+     * `DEFAULT_RENEW_INTERVAL_MS` (half of LEASE_TTL_MS). Injected in tests so a
+     * renewal can be driven in milliseconds rather than a minute.
+     */
+    leaseRenewIntervalMs?: number;
+    /** Pass the live runner identity to the sandbox supervisor over IPC. */
+    onUpgradeRequested?: (request: HarnessUpgradeRequest) => void;
+    /**
+     * How often the lease is renewed WHILE A PERMISSION PROMPT IS OUTSTANDING.
+     * Defaults to `APPROVAL_RENEW_INTERVAL_MS` (2 s).
+     *
+     * The renewal call is also the channel the user's answer comes back on, so
+     * this is the approval latency — see the long note on that constant for why
+     * the renew route carries it rather than the 30 s heartbeat.
+     */
+    approvalRenewIntervalMs?: number;
+    /** Injected in tests. */
+    clientFactory?: (url: string) => ControlPlaneClient;
+}
+/**
+ * THE HARNESS.
+ *
+ * ONE PROGRAM, THREE HOSTING MODES. A Daytona sandbox, a customer VM and the
+ * 20x desktop run this identical loop; nothing below asks which it is. Where a
+ * host genuinely differs it supplies a PORT, and the ports are capabilities
+ * ("can you notify a human?"), never identities ("are you the desktop?").
+ *
+ * THE LOOP, and why it has this shape:
+ *
+ *   register  ->  heartbeat (30s, forever)  +  lease (25s poll, forever)
+ *
+ * Both are OUTBOUND. Nothing dials in, there is no listening port reachable
+ * from the network, and that single property is what lets a customer VM behind
+ * NAT work with no tunnel and no firewall change. It is also why an abort or a
+ * user's answer to a question rides back on `sessionCommands` in the HEARTBEAT
+ * response rather than arriving on a socket.
+ *
+ * Long-poll rather than a WebSocket because Cloud Run bills a request slot for
+ * the WHOLE life of a connection and caps it at 3600s. One persistent socket per
+ * runner would be one billed slot per runner, permanently.
+ */
+export declare class Harness {
+    private readonly options;
+    private readonly deps;
+    private readonly client;
+    private readonly health;
+    private readonly proxy;
+    private readonly store;
+    /** The model-facing conversation log. See `ports.ts#ConversationStore`. */
+    private readonly conversation;
+    /** False when the log is in memory only, so a restart forgets. Reported. */
+    private readonly conversationDurable;
+    private readonly storeDurable;
+    private readonly storeReason;
+    private readonly workspace;
+    private readonly secrets;
+    private readonly events;
+    private readonly telemetry;
+    private readonly notifier;
+    private readonly artifacts;
+    private readonly tokens;
+    private readonly startedAt;
+    private status;
+    private tenantId;
+    private runnerId;
+    private capabilities;
+    /**
+     * The cached model catalogue, probed at start-up and on a LONG interval.
+     *
+     * Probed ONCE, not per heartbeat: Pi discovery starts a short-lived RPC
+     * process, and doing that every 30 seconds would be a regression. The cache
+     * is the flat `models` + per-backend list
+     * that every capability report after start reuses.
+     */
+    private modelCatalog;
+    /** Epoch ms of the last successful (or attempted) model probe. */
+    private modelProbeAt;
+    /**
+     * Empty gateway for the model probe. The probe builds a FRESH adapter and
+     * must not read a live turn's credential; a null config is "no gateway",
+     * which makes the probe list the host's own local models — and the control
+     * plane separately supplies the gateway list.
+     */
+    private readonly modelProbeGateway;
+    private heartbeatIntervalMs;
+    private leaseWaitSeconds;
+    private heartbeatTimer;
+    /** Fires when the runner credential should be rotated. Durable runtimes re-persist the new one. */
+    private rotateTimer;
+    private readonly credentialStore;
+    /** True when this run reused a persisted credential rather than enrolling. */
+    private reusedStoredCredential;
+    private lastHeartbeatAt;
+    private lastHeartbeatError;
+    private consecutiveHeartbeatFailures;
+    private stopping;
+    /** Releases this Harness's reference to the process-wide generic wrappers. */
+    private releaseGitHubGuard;
+    /** sessionId -> the controller that aborts its turn. */
+    private readonly active;
+    /** Renewal workers that must receive a credential rotation in flight. */
+    private readonly activeRenewals;
+    /** commandIds already applied. `SessionCommand` is idempotent by contract. */
+    private readonly appliedCommands;
+    /** Session-end cleanup waits for an active turn to save its dirty work. */
+    private readonly pendingWorkspaceReleases;
+    /**
+     * sessionId -> the runner executing its turn.
+     *
+     * `active` above holds only an AbortController, which is all an `abort`
+     * command needs. An `answer` needs the RUNNER: the adapter and the backend
+     * session id live inside the turn, and the answer has to reach them from the
+     * command handler's stack. This map is what makes wire 3 possible.
+     */
+    private readonly runners;
+    private leaseLoop;
+    /** Set when the control plane refuses this build. Ends the process. */
+    private fatal;
+    /** A changed pin waits here until every live lease has completed. */
+    private pendingHarnessVersion;
+    /** Same idea, for the INDEPENDENT sandbox-tools pin (gh, node deps, ...). */
+    private pendingSandboxToolsVersion;
+    constructor(options: HarnessOptions, deps?: HarnessDeps);
+    /** The actual bound health port. Used by tests to prove the socket closed. */
+    getHealthPort(): number | null;
+    snapshot(): HealthReport;
+    start(): Promise<void>;
+    /**
+     * Block until the harness stops for a reason worth reporting.
+     *
+     * Resolves on a clean drain; rejects when the control plane refused this
+     * build, so the CLI can exit non-zero and the host is recycled onto a
+     * supported version.
+     */
+    wait(): Promise<void>;
+    stop(options?: {
+        preserveRegistration?: boolean;
+    }): Promise<void>;
+    private register;
+    /**
+     * Try to authenticate with a persisted credential. Returns true on success.
+     *
+     * The stored credential is VALIDATED by an actual authenticated call — a
+     * heartbeat, the lightest one — before the harness commits to it. That is what
+     * makes the fallback safe: a stored credential that the control plane has
+     * revoked (a `401`/`403`) is dropped here and enrolment is retried, so a stale
+     * credential cannot wedge the runner. A TRANSIENT failure is NOT treated as a
+     * rejection — re-enrolling on a network blip would burn an already-spent token
+     * — so the harness keeps the credential and lets the normal loop retry.
+     */
+    private tryStoredCredential;
+    /**
+     * Persist the runner credential for durable runtimes.
+     *
+     * A no-op for `sandbox` (its store discards everything) and for a response
+     * that carried no credential. This is what a crash on the NEXT run reuses.
+     */
+    private persistCredential;
+    /**
+     * Schedule a rotation at `rotateAfter`, comfortably before the credential
+     * expires. The control plane owns the cadence; if it names neither a
+     * `rotateAfter` nor an expiry, no rotation is scheduled and the credential
+     * simply lives out its TTL.
+     */
+    private scheduleRotation;
+    /**
+     * Rotate the runner credential and re-persist it.
+     *
+     * A credential cannot authenticate its own replacement once expired, so
+     * rotation is scheduled AHEAD of expiry and never used to climb out of a 401.
+     * A failed rotation keeps the current credential and retries later; a final
+     * status stops trying, because the credential is gone for good and the loop
+     * will surface that.
+     */
+    private rotateCredential;
+    /**
+     * Re-probe the model catalogue.
+     *
+     * Runs ONCE at start-up and on a long interval after that — never per
+     * heartbeat, because the probe starts a Pi discovery process.
+     * `force` re-probes regardless of age (used at start-up). Never rejects.
+     */
+    private refreshModelCatalog;
+    /**
+     * Attach the cached model catalogue to a capability report.
+     *
+     * Mutates `capabilities` in place: the flat list on `models`, and each
+     * installed backend's own list on `backends[].models`. Absent (rather than
+     * an empty-but-meaningful list) when the catalogue is empty.
+     */
+    private applyModelCatalog;
+    /**
+     * Whether the model catalogue needs a (rare) re-probe.
+     *
+     * Interval-only, and the interval doubles as a cooldown: `refreshModelCatalog`
+     * stamps `modelProbeAt` even when the probe itself fails, so a host whose
+     * models cannot be enumerated does not keep starting a process on every
+     * heartbeat trying. Start-up force bypasses this.
+     *
+     * NEVER WHILE A TURN IS RUNNING. Pi discovery and a live turn share the Pi
+     * agent directory, including models.json; avoiding concurrent discovery
+     * keeps provider configuration changes out of an active model call.
+     * Deferring costs nothing: the catalogue only
+     * changes when the host's model config does, and the next idle heartbeat
+     * picks it up.
+     */
+    private modelsNeedRefresh;
+    private scheduleHeartbeat;
+    private sendHeartbeat;
+    /**
+     * Apply a command that rode back on a heartbeat.
+     *
+     * Idempotent by `commandId`, because the contract lets the control plane
+     * repeat a command until it observes the effect — it has no other way to
+     * know, since it cannot dial in and ask.
+     */
+    private applyCommand;
+    private releaseSessionWorkspace;
+    /**
+     * A user's answer did not reach the backend. Do the two things that keep it
+     * from vanishing.
+     *
+     * 1. FORGET THE commandId, so a redelivery is retried rather than discarded
+     *    as a duplicate. On its own this fixes nothing — the control plane stamps
+     *    `delivered_at` at hand-off and does not resend today — so it is a latch
+     *    for a retry that does not yet exist.
+     * 2. TELL THE USER, in the transcript. This is the half that actually
+     *    reaches them: without it the question card stays open, the turn keeps
+     *    waiting (approval time is deliberately outside the turn deadline, so
+     *    nothing else ends it), and a click is indistinguishable from a slow
+     *    backend.
+     */
+    private recoverFailedAnswer;
+    private runLeaseLoop;
+    /**
+     * Record a changed pin. Only managed sandboxes have the baked supervisor
+     * that can service the distinguished exit code.
+     */
+    private observeHarnessPin;
+    /**
+     * Same shape as observeHarnessPin(), for the INDEPENDENT sandbox-tools pin.
+     * A host that never reported an installed tools version (self-hosted,
+     * desktop, or a sandbox that predates this layer) has nothing to compare
+     * against and is left alone rather than treated as "version none, always
+     * behind" — that would drain and exit-75 every such host on every lease.
+     */
+    private observeSandboxToolsPin;
+    /** Stop once. A failed install is then the supervisor's terminal decision. */
+    private requestUpgrade;
+    /**
+     * Run one leased turn.
+     *
+     * NOT awaited by the loop, so a runner allowed more than one concurrent
+     * session actually gets one. Every failure is contained here: a turn that
+     * throws must not end the lease loop, or one bad session would take the whole
+     * runner offline.
+     */
+    private runLeasedTurn;
+}