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

package/dist/contract.d.ts

@@ -0,0 +1,273 @@
+/**
+ * The executable half of the wire contract: versions, routes, the part-type
+ * vocabulary and the predicates that enforce them.
+ *
+ * Everything here is PURE — no I/O, no process state, no harness behaviour.
+ * That is deliberate: the control plane (Track A) imports the same predicates
+ * the harness (Track B) does, so the two cannot disagree about what "supported"
+ * or "ephemeral" means. A rule written twice is a rule that drifts.
+ */
+/**
+ * The wire contract revision. A plain integer, not semver: there is no useful
+ * distinction between a "minor" and a "patch" change to a protocol that two
+ * independently deployed programs must agree on.
+ *
+ * BUMP THIS when a change would make an older peer misbehave — a removed
+ * field, a narrowed type, a changed default, a new REQUIRED field. Do NOT bump
+ * it for a new OPTIONAL field: both sides already tolerate those, and bumping
+ * needlessly forces a fleet-wide upgrade for nothing.
+ *
+ * v1 — register, heartbeat, lease, renew, ingest, rotate, deregister,
+ *      bootstrap. Frozen at Step 1, before Tracks A and B started.
+ * v2 — LONG TURNS: `LeasedLimits.maxTurnDurationMs` may now be `null` ("no
+ *      ceiling"). A v1 harness computes `Date.now() + maxTurnDurationMs`
+ *      directly (session-runner.ts, pre-fix), and `Date.now() + null`
+ *      coerces to `Date.now()` — an already-past deadline that cuts the turn
+ *      as `turn_time_limit` on its very first poll. THIS IS EXACTLY THE
+ *      "changed default" case the rule above bumps for: the control plane's
+ *      DEFAULT is unaffected (see `MIN_PROTOCOL_VERSION_FOR_NO_CEILING` — a
+ *      v1 harness still gets a real number by default), and only a control
+ *      plane an operator has explicitly configured for no ceiling at all
+ *      needs to tell such a harness apart, which it does by refusing it
+ *      rather than silently serving a value that would misbehave.
+ */
+export declare const PROTOCOL_VERSION = 2;
+/**
+ * The floor a harness must meet to be served `maxTurnDurationMs: null`.
+ *
+ * NOT the same thing as `MIN_SUPPORTED_PROTOCOL_VERSION` below, which is a
+ * blanket floor for the whole fleet — raising that would force every runner
+ * to upgrade before ANY of them can do ANYTHING, for a case (an operator
+ * opting a tenant out of the hard ceiling entirely) that most deployments
+ * never hit. This floor is checked ONLY at the moment a lease is about to
+ * carry `null`, so a v1 harness keeps working normally right up until an
+ * operator asks this control plane for the one behaviour it cannot express.
+ */
+export declare const MIN_PROTOCOL_VERSION_FOR_NO_CEILING = 2;
+/**
+ * The harness asks its host supervisor to install the current pin again.
+ * All other exit codes keep their normal process meaning.
+ */
+export declare const HARNESS_UPGRADE_EXIT_CODE = 75;
+/**
+ * The floor this build will talk to. The control plane holds the authoritative
+ * floor in configuration and may raise it above this without a harness
+ * release; this constant is the harness's own view, used to fail fast rather
+ * than to grant anything.
+ */
+export declare const MIN_SUPPORTED_PROTOCOL_VERSION = 1;
+/**
+ * An OPTIONAL echo of the body's `protocolVersion`.
+ *
+ * THE BODY IS AUTHORITATIVE. This header exists only so a proxy, an access log
+ * or a `curl -v` can see the version without parsing a JSON body — it is a
+ * debugging affordance, not a second source of truth, and a peer that omits it
+ * is perfectly conformant. `pf-bootstrap` does not send it.
+ *
+ * A server that sees it and finds it DISAGREEING with the body must refuse the
+ * request (400): the two disagreeing means something between the peers rewrote
+ * one of them, and guessing which to believe is how a version gate gets
+ * bypassed.
+ */
+export declare const PROTOCOL_VERSION_HEADER = "x-pf-protocol-version";
+/**
+ * Is a peer speaking a version this side can serve?
+ *
+ * FAILS CLOSED: a missing, non-integer, zero or negative version is refused.
+ * Phase 0 learned this the hard way — the first version gate tested only
+ * `accepted === false`, so a 200 that simply omitted the field sailed through.
+ * An absent version is not a permissive default; it is an unknown peer.
+ *
+ * A peer NEWER than this build is allowed. The contract only ever adds
+ * optional fields within a version, and the newer side is responsible for
+ * remaining readable by the older one. Refusing forward would make every
+ * control-plane deploy a synchronised fleet upgrade.
+ */
+export declare function isProtocolSupported(peerProtocolVersion: unknown, floor?: number): boolean;
+/**
+ * Statuses that are FINAL. Never retried, at any route.
+ *
+ * Matched on the STATUS and never on the message, so that rewording an error
+ * string cannot quietly turn a fail-fast into six attempts over ~31 seconds.
+ *
+ * 426 Upgrade Required is the RUNNING-FLEET version gate. Registration is
+ * gated by `accepted: false`, but a floor can also be raised under runners
+ * that are already registered; they then meet 426 at heartbeat, lease or
+ * ingest and must exit rather than hammer a control plane that will never
+ * serve them.
+ *
+ * 401 IS FINAL, AND THAT IS DELIBERATE — a harness must NOT try to rotate its
+ * way out of one. Rotation is authenticated with the CURRENT credential, so a
+ * credential that has already expired cannot rotate itself; a harness that
+ * tried would loop between two routes that can only both fail. `rotateAfter`
+ * is the mechanism: rotate on schedule, comfortably before expiry, and treat
+ * an actual 401 as "this host is finished, exit and be re-enrolled".
+ *
+ * NOTE FOR TRACK B: `harness.ts` currently inlines [400, 401, 403, 404, 409]
+ * and so does NOT treat 426 as final. Import this constant instead of
+ * re-typing the list when the skeleton body is replaced.
+ */
+export declare const FINAL_HTTP_STATUSES: readonly number[];
+export declare function isFinalStatus(status: number): boolean;
+/** Stable, machine-readable error codes. */
+export declare const CONTRACT_ERROR_CODES: {
+    readonly protocolUnsupported: "protocol_version_unsupported";
+    readonly harnessVersionUnsupported: "harness_version_unsupported";
+    readonly enrolmentTokenInvalid: "enrolment_token_invalid";
+    readonly enrolmentTokenSpent: "enrolment_token_spent";
+    readonly credentialInvalid: "runner_credential_invalid";
+    readonly credentialExpired: "runner_credential_expired";
+    readonly runnerUnknown: "runner_unknown";
+    readonly runnerDisabled: "runner_disabled";
+    readonly leaseUnknown: "lease_unknown";
+    readonly leaseExpired: "lease_expired";
+    readonly leaseNotOwned: "lease_not_owned";
+    readonly sessionUnknown: "session_unknown";
+    readonly rateLimited: "rate_limited";
+};
+/**
+ * How long the lease route holds a poll open.
+ *
+ * 25s matches the existing `boundSseStream` heartbeat, and it is chosen
+ * against Cloud Run, which bills a request slot for the WHOLE life of a
+ * connection and caps it at 3600s. That economics is what rules out one
+ * persistent WebSocket per runner and produces this long-poll in its place.
+ */
+export declare const DEFAULT_LEASE_WAIT_SECONDS = 25;
+/** A poll longer than this wastes a Cloud Run request slot. */
+export declare const MAX_LEASE_WAIT_SECONDS = 60;
+/** Liveness: 30s beats, offline after three missed, in-flight leases requeued. */
+export declare const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000;
+export declare const MISSED_HEARTBEATS_BEFORE_OFFLINE = 3;
+/** Visibility timeout. Every successful ingest extends it by this much. */
+export declare const DEFAULT_LEASE_TTL_MS = 120000;
+/** Registration and ingest back-off, shared so both tracks agree. */
+export declare const DEFAULT_MAX_ATTEMPTS = 6;
+export declare const DEFAULT_BASE_DELAY_MS = 1000;
+/**
+ * The ceilings behind the `too-large` rejection reason.
+ *
+ * They are stated here rather than left to Track A because a limit only one
+ * side knows is not a limit — the harness would discover it as an opaque
+ * rejection mid-turn, with a partly-written transcript and no way to tell a
+ * transient failure from a permanent one.
+ *
+ * A part over `MAX_INGEST_PART_BYTES` is rejected individually, so one
+ * enormous tool result cannot take the whole batch down with it. A batch over
+ * `MAX_INGEST_PARTS` is rejected whole, with 413.
+ */
+export declare const MAX_INGEST_PART_BYTES = 1000000;
+export declare const MAX_INGEST_PARTS = 500;
+/** UTF-8 byte length of a part's content plus its serialised payload. */
+export declare function ingestPartByteLength(part: {
+    content?: unknown;
+    payload?: unknown;
+}): number;
+/**
+ * The route table. Ids are interpolated with `encodeURIComponent`, so a runner
+ * or session id containing a slash cannot walk out of its own path.
+ *
+ * EVERY route here is called BY THE HARNESS, OUTBOUND. There is no inverse
+ * table, and there must never be one: the moment the control plane needs to
+ * dial a runner, a customer VM behind NAT stops working without a tunnel.
+ */
+export declare const ROUTES: {
+    /** Called by pf-bootstrap, before the harness exists. Bearer: enrolment token. */
+    readonly bootstrap: () => string;
+    /** Bearer: enrolment token. Burns it, returns the runner credential. */
+    readonly register: () => string;
+    /** Bearer: runner credential. 30s period. */
+    readonly heartbeat: (runnerId: string) => string;
+    /**
+     * Bearer: runner credential. Bounded long-poll: 204 idle, 200 with work.
+     *
+     * `wait` is CLAMPED here rather than left to the server to trim silently. A
+     * harness that asked for 300s and was quietly given 60s would look, from its
+     * own logs, like a control plane returning 204 five times too often.
+     *
+     * `protocolVersion` rides in the QUERY STRING because this is the one
+     * gated route with no request body to put it in. Leaving it off would make
+     * lease the single route a below-floor runner could still call — and lease
+     * is the route it would call hardest, in a tight poll loop, precisely when
+     * it should be exiting.
+     */
+    readonly lease: (runnerId: string, waitSeconds?: number, protocolVersion?: number) => string;
+    /** Bearer: runner credential. Visibility-timeout renewal. */
+    readonly leaseRenew: (runnerId: string, leaseId: string) => string;
+    /**
+     * Bearer: runner credential. THE RUNTIME-NEUTRAL ROUTE — a Daytona sandbox,
+     * a customer VM and the 20x desktop all call this identical path.
+     */
+    readonly ingest: (sessionId: string) => string;
+    /**
+     * The runner's HISTORY READ PATH.
+     *
+     * Bearer: the runner credential, scoped to a live lease on the session. Added
+     * because until it existed the harness could only ever WRITE a conversation
+     * out — there was no way to read one back, so a runner that had not
+     * personally run the earlier turns had no way to learn what they were, and
+     * the model started every turn blank.
+     */
+    readonly sessionHistory: (sessionId: string, leaseId: string) => string;
+    /** Bearer: the CURRENT runner credential. */
+    readonly credentialRotate: (runnerId: string) => string;
+    /** Bearer: runner credential. Idempotent. */
+    readonly deregister: (runnerId: string) => string;
+};
+/**
+ * The part-type vocabulary in use today.
+ *
+ * THIS IS NOT A CLOSED SET, and `TranscriptPart.partType` is deliberately
+ * `string`. 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. Use this list for documentation and UI switches, never as a
+ * validation allowlist.
+ */
+export declare const PERSISTED_PART_TYPES: readonly string[];
+/**
+ * THE CLOSED SET. These three are UI-only transitions and MUST NEVER be
+ * persisted or ingested.
+ *
+ * They are frame markers, not content: they carry duration and token counts
+ * that belong in `TurnMetadata` (defect G7), and persisting them would put
+ * thousands of meaningless rows in every transcript and stream them to every
+ * reader. The control plane rejects them at ingest with reason 'ephemeral',
+ * which is NOT an error — the harness must not retry a dropped part.
+ *
+ * Unlike the vocabulary above, this list IS exhaustive and IS enforced.
+ */
+export declare const EPHEMERAL_PART_TYPES: readonly string[];
+/**
+ * Must this part be dropped rather than stored?
+ *
+ * Compared case-insensitively after trimming. A part type is produced by
+ * several different backends, and ' Step-Start ' being persisted because of a
+ * stray space would be a silent, permanent corruption of the projection.
+ */
+export declare function isEphemeralPartType(partType: unknown): boolean;
+/**
+ * Is this part worth storing at all?
+ *
+ * Drops the ephemeral three, and drops parts with neither content nor payload.
+ * An empty part is usually a stream artefact — the opening frame of a text
+ * part that never received a delta — and storing it puts a blank bubble in the
+ * UI for ever.
+ *
+ * A part with a payload but no content is KEPT: a tool call with arguments and
+ * no textual body is perfectly ordinary.
+ *
+ * `isUpdate` MATTERS, and getting it wrong is subtle. On an update,
+ * `payload: null` is a deliberate CLEAR (invariant 3), not an absence — so a
+ * caller sending empty content together with `payload: null` to wipe a
+ * previously-set payload must reach the coalesce step. Treating that as
+ * "empty" would drop it here, silently, and the contract documents rejections
+ * as "not an error" — so the caller would never learn the clear had not
+ * happened. On an INSERT the same body really is an empty part, and is dropped.
+ */
+export declare function isPersistablePart(part: {
+    partType?: unknown;
+    content?: unknown;
+    payload?: unknown;
+}, options?: {
+    isUpdate?: boolean;
+}): boolean;

package/dist/contract.js

@@ -0,0 +1,357 @@
+"use strict";
+/**
+ * The executable half of the wire contract: versions, routes, the part-type
+ * vocabulary and the predicates that enforce them.
+ *
+ * Everything here is PURE — no I/O, no process state, no harness behaviour.
+ * That is deliberate: the control plane (Track A) imports the same predicates
+ * the harness (Track B) does, so the two cannot disagree about what "supported"
+ * or "ephemeral" means. A rule written twice is a rule that drifts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EPHEMERAL_PART_TYPES = exports.PERSISTED_PART_TYPES = exports.ROUTES = exports.MAX_INGEST_PARTS = exports.MAX_INGEST_PART_BYTES = exports.DEFAULT_BASE_DELAY_MS = exports.DEFAULT_MAX_ATTEMPTS = exports.DEFAULT_LEASE_TTL_MS = exports.MISSED_HEARTBEATS_BEFORE_OFFLINE = exports.DEFAULT_HEARTBEAT_INTERVAL_MS = exports.MAX_LEASE_WAIT_SECONDS = exports.DEFAULT_LEASE_WAIT_SECONDS = exports.CONTRACT_ERROR_CODES = exports.FINAL_HTTP_STATUSES = exports.PROTOCOL_VERSION_HEADER = exports.MIN_SUPPORTED_PROTOCOL_VERSION = exports.HARNESS_UPGRADE_EXIT_CODE = exports.MIN_PROTOCOL_VERSION_FOR_NO_CEILING = exports.PROTOCOL_VERSION = void 0;
+exports.isProtocolSupported = isProtocolSupported;
+exports.isFinalStatus = isFinalStatus;
+exports.ingestPartByteLength = ingestPartByteLength;
+exports.isEphemeralPartType = isEphemeralPartType;
+exports.isPersistablePart = isPersistablePart;
+/* -------------------------------------------------------------------------- */
+/* Versioning                                                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * The wire contract revision. A plain integer, not semver: there is no useful
+ * distinction between a "minor" and a "patch" change to a protocol that two
+ * independently deployed programs must agree on.
+ *
+ * BUMP THIS when a change would make an older peer misbehave — a removed
+ * field, a narrowed type, a changed default, a new REQUIRED field. Do NOT bump
+ * it for a new OPTIONAL field: both sides already tolerate those, and bumping
+ * needlessly forces a fleet-wide upgrade for nothing.
+ *
+ * v1 — register, heartbeat, lease, renew, ingest, rotate, deregister,
+ *      bootstrap. Frozen at Step 1, before Tracks A and B started.
+ * v2 — LONG TURNS: `LeasedLimits.maxTurnDurationMs` may now be `null` ("no
+ *      ceiling"). A v1 harness computes `Date.now() + maxTurnDurationMs`
+ *      directly (session-runner.ts, pre-fix), and `Date.now() + null`
+ *      coerces to `Date.now()` — an already-past deadline that cuts the turn
+ *      as `turn_time_limit` on its very first poll. THIS IS EXACTLY THE
+ *      "changed default" case the rule above bumps for: the control plane's
+ *      DEFAULT is unaffected (see `MIN_PROTOCOL_VERSION_FOR_NO_CEILING` — a
+ *      v1 harness still gets a real number by default), and only a control
+ *      plane an operator has explicitly configured for no ceiling at all
+ *      needs to tell such a harness apart, which it does by refusing it
+ *      rather than silently serving a value that would misbehave.
+ */
+exports.PROTOCOL_VERSION = 2;
+/**
+ * The floor a harness must meet to be served `maxTurnDurationMs: null`.
+ *
+ * NOT the same thing as `MIN_SUPPORTED_PROTOCOL_VERSION` below, which is a
+ * blanket floor for the whole fleet — raising that would force every runner
+ * to upgrade before ANY of them can do ANYTHING, for a case (an operator
+ * opting a tenant out of the hard ceiling entirely) that most deployments
+ * never hit. This floor is checked ONLY at the moment a lease is about to
+ * carry `null`, so a v1 harness keeps working normally right up until an
+ * operator asks this control plane for the one behaviour it cannot express.
+ */
+exports.MIN_PROTOCOL_VERSION_FOR_NO_CEILING = 2;
+/**
+ * The harness asks its host supervisor to install the current pin again.
+ * All other exit codes keep their normal process meaning.
+ */
+exports.HARNESS_UPGRADE_EXIT_CODE = 75;
+/**
+ * The floor this build will talk to. The control plane holds the authoritative
+ * floor in configuration and may raise it above this without a harness
+ * release; this constant is the harness's own view, used to fail fast rather
+ * than to grant anything.
+ */
+exports.MIN_SUPPORTED_PROTOCOL_VERSION = 1;
+/**
+ * An OPTIONAL echo of the body's `protocolVersion`.
+ *
+ * THE BODY IS AUTHORITATIVE. This header exists only so a proxy, an access log
+ * or a `curl -v` can see the version without parsing a JSON body — it is a
+ * debugging affordance, not a second source of truth, and a peer that omits it
+ * is perfectly conformant. `pf-bootstrap` does not send it.
+ *
+ * A server that sees it and finds it DISAGREEING with the body must refuse the
+ * request (400): the two disagreeing means something between the peers rewrote
+ * one of them, and guessing which to believe is how a version gate gets
+ * bypassed.
+ */
+exports.PROTOCOL_VERSION_HEADER = 'x-pf-protocol-version';
+/**
+ * Is a peer speaking a version this side can serve?
+ *
+ * FAILS CLOSED: a missing, non-integer, zero or negative version is refused.
+ * Phase 0 learned this the hard way — the first version gate tested only
+ * `accepted === false`, so a 200 that simply omitted the field sailed through.
+ * An absent version is not a permissive default; it is an unknown peer.
+ *
+ * A peer NEWER than this build is allowed. The contract only ever adds
+ * optional fields within a version, and the newer side is responsible for
+ * remaining readable by the older one. Refusing forward would make every
+ * control-plane deploy a synchronised fleet upgrade.
+ */
+function isProtocolSupported(peerProtocolVersion, floor = exports.MIN_SUPPORTED_PROTOCOL_VERSION) {
+    return (typeof peerProtocolVersion === 'number' &&
+        Number.isInteger(peerProtocolVersion) &&
+        peerProtocolVersion > 0 &&
+        peerProtocolVersion >= floor);
+}
+/* -------------------------------------------------------------------------- */
+/* Retry semantics                                                             */
+/* -------------------------------------------------------------------------- */
+/**
+ * Statuses that are FINAL. Never retried, at any route.
+ *
+ * Matched on the STATUS and never on the message, so that rewording an error
+ * string cannot quietly turn a fail-fast into six attempts over ~31 seconds.
+ *
+ * 426 Upgrade Required is the RUNNING-FLEET version gate. Registration is
+ * gated by `accepted: false`, but a floor can also be raised under runners
+ * that are already registered; they then meet 426 at heartbeat, lease or
+ * ingest and must exit rather than hammer a control plane that will never
+ * serve them.
+ *
+ * 401 IS FINAL, AND THAT IS DELIBERATE — a harness must NOT try to rotate its
+ * way out of one. Rotation is authenticated with the CURRENT credential, so a
+ * credential that has already expired cannot rotate itself; a harness that
+ * tried would loop between two routes that can only both fail. `rotateAfter`
+ * is the mechanism: rotate on schedule, comfortably before expiry, and treat
+ * an actual 401 as "this host is finished, exit and be re-enrolled".
+ *
+ * NOTE FOR TRACK B: `harness.ts` currently inlines [400, 401, 403, 404, 409]
+ * and so does NOT treat 426 as final. Import this constant instead of
+ * re-typing the list when the skeleton body is replaced.
+ */
+exports.FINAL_HTTP_STATUSES = [
+    400, 401, 403, 404, 409, 426
+];
+function isFinalStatus(status) {
+    return exports.FINAL_HTTP_STATUSES.includes(status);
+}
+/** Stable, machine-readable error codes. */
+exports.CONTRACT_ERROR_CODES = {
+    protocolUnsupported: 'protocol_version_unsupported',
+    harnessVersionUnsupported: 'harness_version_unsupported',
+    enrolmentTokenInvalid: 'enrolment_token_invalid',
+    enrolmentTokenSpent: 'enrolment_token_spent',
+    credentialInvalid: 'runner_credential_invalid',
+    credentialExpired: 'runner_credential_expired',
+    runnerUnknown: 'runner_unknown',
+    runnerDisabled: 'runner_disabled',
+    leaseUnknown: 'lease_unknown',
+    leaseExpired: 'lease_expired',
+    leaseNotOwned: 'lease_not_owned',
+    sessionUnknown: 'session_unknown',
+    rateLimited: 'rate_limited'
+};
+/* -------------------------------------------------------------------------- */
+/* Timing                                                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * How long the lease route holds a poll open.
+ *
+ * 25s matches the existing `boundSseStream` heartbeat, and it is chosen
+ * against Cloud Run, which bills a request slot for the WHOLE life of a
+ * connection and caps it at 3600s. That economics is what rules out one
+ * persistent WebSocket per runner and produces this long-poll in its place.
+ */
+exports.DEFAULT_LEASE_WAIT_SECONDS = 25;
+/** A poll longer than this wastes a Cloud Run request slot. */
+exports.MAX_LEASE_WAIT_SECONDS = 60;
+/** Liveness: 30s beats, offline after three missed, in-flight leases requeued. */
+exports.DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+exports.MISSED_HEARTBEATS_BEFORE_OFFLINE = 3;
+/** Visibility timeout. Every successful ingest extends it by this much. */
+exports.DEFAULT_LEASE_TTL_MS = 120_000;
+/** Registration and ingest back-off, shared so both tracks agree. */
+exports.DEFAULT_MAX_ATTEMPTS = 6;
+exports.DEFAULT_BASE_DELAY_MS = 1_000;
+/* -------------------------------------------------------------------------- */
+/* Ingest ceilings                                                             */
+/* -------------------------------------------------------------------------- */
+/**
+ * The ceilings behind the `too-large` rejection reason.
+ *
+ * They are stated here rather than left to Track A because a limit only one
+ * side knows is not a limit — the harness would discover it as an opaque
+ * rejection mid-turn, with a partly-written transcript and no way to tell a
+ * transient failure from a permanent one.
+ *
+ * A part over `MAX_INGEST_PART_BYTES` is rejected individually, so one
+ * enormous tool result cannot take the whole batch down with it. A batch over
+ * `MAX_INGEST_PARTS` is rejected whole, with 413.
+ */
+exports.MAX_INGEST_PART_BYTES = 1_000_000;
+exports.MAX_INGEST_PARTS = 500;
+/** UTF-8 byte length of a part's content plus its serialised payload. */
+function ingestPartByteLength(part) {
+    const content = typeof part.content === 'string' ? part.content : '';
+    const payload = part.payload === undefined || part.payload === null
+        ? ''
+        : JSON.stringify(part.payload);
+    // Byte length, not string length: a transcript is full of non-ASCII, and
+    // measuring in UTF-16 code units would let a limit be exceeded by ~3x.
+    return (Buffer.byteLength(content, 'utf8') + Buffer.byteLength(payload, 'utf8'));
+}
+/* -------------------------------------------------------------------------- */
+/* Routes                                                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * The route table. Ids are interpolated with `encodeURIComponent`, so a runner
+ * or session id containing a slash cannot walk out of its own path.
+ *
+ * EVERY route here is called BY THE HARNESS, OUTBOUND. There is no inverse
+ * table, and there must never be one: the moment the control plane needs to
+ * dial a runner, a customer VM behind NAT stops working without a tunnel.
+ */
+exports.ROUTES = {
+    /** Called by pf-bootstrap, before the harness exists. Bearer: enrolment token. */
+    bootstrap: () => '/api/coding-agents/harness/bootstrap',
+    /** Bearer: enrolment token. Burns it, returns the runner credential. */
+    register: () => '/api/runners/register',
+    /** Bearer: runner credential. 30s period. */
+    heartbeat: (runnerId) => `/api/runners/${encodeURIComponent(runnerId)}/heartbeat`,
+    /**
+     * Bearer: runner credential. Bounded long-poll: 204 idle, 200 with work.
+     *
+     * `wait` is CLAMPED here rather than left to the server to trim silently. A
+     * harness that asked for 300s and was quietly given 60s would look, from its
+     * own logs, like a control plane returning 204 five times too often.
+     *
+     * `protocolVersion` rides in the QUERY STRING because this is the one
+     * gated route with no request body to put it in. Leaving it off would make
+     * lease the single route a below-floor runner could still call — and lease
+     * is the route it would call hardest, in a tight poll loop, precisely when
+     * it should be exiting.
+     */
+    lease: (runnerId, waitSeconds = exports.DEFAULT_LEASE_WAIT_SECONDS, protocolVersion = exports.PROTOCOL_VERSION) => {
+        const wait = Math.min(Math.max(Math.trunc(waitSeconds) || 0, 0), exports.MAX_LEASE_WAIT_SECONDS);
+        return `/api/runners/${encodeURIComponent(runnerId)}/lease?wait=${wait}&protocolVersion=${protocolVersion}`;
+    },
+    /** Bearer: runner credential. Visibility-timeout renewal. */
+    leaseRenew: (runnerId, leaseId) => `/api/runners/${encodeURIComponent(runnerId)}/lease/${encodeURIComponent(leaseId)}/renew`,
+    /**
+     * Bearer: runner credential. THE RUNTIME-NEUTRAL ROUTE — a Daytona sandbox,
+     * a customer VM and the 20x desktop all call this identical path.
+     */
+    ingest: (sessionId) => `/api/coding-agents/sessions/${encodeURIComponent(sessionId)}/ingest`,
+    /**
+     * The runner's HISTORY READ PATH.
+     *
+     * Bearer: the runner credential, scoped to a live lease on the session. Added
+     * because until it existed the harness could only ever WRITE a conversation
+     * out — there was no way to read one back, so a runner that had not
+     * personally run the earlier turns had no way to learn what they were, and
+     * the model started every turn blank.
+     */
+    sessionHistory: (sessionId, leaseId) => `/api/coding-agents/sessions/${encodeURIComponent(sessionId)}/history` +
+        `?leaseId=${encodeURIComponent(leaseId)}`,
+    /** Bearer: the CURRENT runner credential. */
+    credentialRotate: (runnerId) => `/api/runners/${encodeURIComponent(runnerId)}/credential/rotate`,
+    /** Bearer: runner credential. Idempotent. */
+    deregister: (runnerId) => `/api/runners/${encodeURIComponent(runnerId)}/deregister`
+};
+/*
+ * THE PHASE 0 ROUTES ARE GONE.
+ *
+ * `/api/coding-agents/harness/register` and `.../heartbeat` were kept through
+ * Step 1 only so the sandbox e2e suite could drive the real image while the
+ * harness was still a skeleton. They were never aliases of the canonical
+ * `/api/runners/*` pair — the shapes differed, and the old request carried no
+ * `protocolVersion`, so THAT PATH COULD NOT BE PROTOCOL-VERSION GATED AT ALL.
+ * For as long as it existed, the only registration route running in production
+ * was exempt from half of the versioning guarantee.
+ *
+ * Track B deleted both, and the exemption went with them. Every route in this
+ * file now carries a version the control plane can refuse.
+ */
+/* -------------------------------------------------------------------------- */
+/* Transcript part types                                                       */
+/* -------------------------------------------------------------------------- */
+/**
+ * The part-type vocabulary in use today.
+ *
+ * THIS IS NOT A CLOSED SET, and `TranscriptPart.partType` is deliberately
+ * `string`. 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. Use this list for documentation and UI switches, never as a
+ * validation allowlist.
+ */
+exports.PERSISTED_PART_TYPES = [
+    'text',
+    'tool',
+    'question',
+    'reasoning',
+    'error',
+    'todowrite',
+    'task_progress',
+    'task-notification',
+    'planreview',
+    'retry'
+];
+/**
+ * THE CLOSED SET. These three are UI-only transitions and MUST NEVER be
+ * persisted or ingested.
+ *
+ * They are frame markers, not content: they carry duration and token counts
+ * that belong in `TurnMetadata` (defect G7), and persisting them would put
+ * thousands of meaningless rows in every transcript and stream them to every
+ * reader. The control plane rejects them at ingest with reason 'ephemeral',
+ * which is NOT an error — the harness must not retry a dropped part.
+ *
+ * Unlike the vocabulary above, this list IS exhaustive and IS enforced.
+ */
+exports.EPHEMERAL_PART_TYPES = [
+    'step-start',
+    'step-finish',
+    'system-status'
+];
+/**
+ * Must this part be dropped rather than stored?
+ *
+ * Compared case-insensitively after trimming. A part type is produced by
+ * several different backends, and ' Step-Start ' being persisted because of a
+ * stray space would be a silent, permanent corruption of the projection.
+ */
+function isEphemeralPartType(partType) {
+    return (typeof partType === 'string' &&
+        exports.EPHEMERAL_PART_TYPES.includes(partType.trim().toLowerCase()));
+}
+/**
+ * Is this part worth storing at all?
+ *
+ * Drops the ephemeral three, and drops parts with neither content nor payload.
+ * An empty part is usually a stream artefact — the opening frame of a text
+ * part that never received a delta — and storing it puts a blank bubble in the
+ * UI for ever.
+ *
+ * A part with a payload but no content is KEPT: a tool call with arguments and
+ * no textual body is perfectly ordinary.
+ *
+ * `isUpdate` MATTERS, and getting it wrong is subtle. On an update,
+ * `payload: null` is a deliberate CLEAR (invariant 3), not an absence — so a
+ * caller sending empty content together with `payload: null` to wipe a
+ * previously-set payload must reach the coalesce step. Treating that as
+ * "empty" would drop it here, silently, and the contract documents rejections
+ * as "not an error" — so the caller would never learn the clear had not
+ * happened. On an INSERT the same body really is an empty part, and is dropped.
+ */
+function isPersistablePart(part, options = {}) {
+    if (isEphemeralPartType(part.partType)) {
+        return false;
+    }
+    const hasContent = typeof part.content === 'string' && part.content.trim().length > 0;
+    if (hasContent) {
+        return true;
+    }
+    // A real payload always earns the part its place.
+    if (part.payload !== undefined && part.payload !== null) {
+        return true;
+    }
+    // An explicit null on an EXISTING part is a clear, and must be let through.
+    return options.isUpdate === true && part.payload === null;
+}