agent-hitch 0.2.6 → 0.2.7

package/dist/src/control-plane/remote-worker-configuration.js

@@ -0,0 +1,34 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { atomicWriteJSON, invalidInput } from "../foundation/index.js";
+import { parseRemoteWorkerCredential } from "./remote-worker-client.js";
+import { parseRemoteWorkerRegistration } from "./remote-workers.js";
+export async function loadRemoteWorkerRegistration(file) {
+    return parseRemoteWorkerRegistration(await jsonFile(file, "worker registration"));
+}
+export async function loadRemoteWorkerCredential(file) {
+    return parseRemoteWorkerCredential(await jsonFile(file, "worker credential"));
+}
+export async function loadRemoteWorkerToken(file) {
+    try {
+        return (await readFile(path.resolve(file), "utf8")).trim();
+    }
+    catch (error) {
+        throw invalidInput(`worker admin credential is not readable: ${safeMessage(error)}`);
+    }
+}
+export function writeRemoteWorkerCredential(file, credential) {
+    return atomicWriteJSON(path.resolve(file), parseRemoteWorkerCredential(credential), 0o600);
+}
+async function jsonFile(file, label) {
+    try {
+        return JSON.parse(await readFile(path.resolve(file), "utf8"));
+    }
+    catch (error) {
+        throw invalidInput(`${label} is not readable JSON: ${safeMessage(error)}`);
+    }
+}
+function safeMessage(error) {
+    return (error?.message || String(error)).replace(/[\0\r\n]/g, " ").slice(0, 1_024);
+}
+//# sourceMappingURL=remote-worker-configuration.js.map

package/dist/src/control-plane/remote-worker-configuration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-worker-configuration.js","sourceRoot":"","sources":["../../../src/control-plane/remote-worker-configuration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACvE,OAAO,EAAE,2BAA2B,EAAE,MAAM,2BAA2B,CAAC;AAExE,OAAO,EAAE,6BAA6B,EAAE,MAAM,qBAAqB,CAAC;AAEpE,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,IAAY;IAC7D,OAAO,6BAA6B,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC,CAAC;AACpF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAAC,IAAY;IAC3D,OAAO,2BAA2B,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC;AAChF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,IAAY;IACtD,IAAI,CAAC;QAAC,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAAC,CAAC;IACnE,OAAO,KAAK,EAAE,CAAC;QAAC,MAAM,YAAY,CAAC,4CAA4C,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAAC,CAAC;AACzG,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,IAAY,EAAE,UAAoC;IAC5F,OAAO,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,2BAA2B,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC,CAAC;AAC7F,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,IAAY,EAAE,KAAa;IACjD,IAAI,CAAC;QAAC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAY,CAAC;IAAC,CAAC;IACjF,OAAO,KAAK,EAAE,CAAC;QAAC,MAAM,YAAY,CAAC,GAAG,KAAK,0BAA0B,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAAC,CAAC;AAC/F,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,CAAE,KAAe,EAAE,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAChG,CAAC"}

package/dist/src/control-plane/remote-worker-credentials.js

@@ -0,0 +1,58 @@
+import { HitchError, PROVIDER_ENVIRONMENT_NAMES } from "../foundation/index.js";
+export const DEFAULT_CREDENTIAL_ENVELOPE_TTL_MS = 60_000;
+export class RemoteCredentialEnvelopeIssuer {
+    env;
+    ttlMs;
+    constructor(input = {}) {
+        const ttl = input.ttlMs ?? DEFAULT_CREDENTIAL_ENVELOPE_TTL_MS;
+        if (!Number.isSafeInteger(ttl) || ttl < 1_000 || ttl > 5 * 60_000) {
+            throw new TypeError("remote credential envelope TTL is invalid");
+        }
+        this.env = input.env ?? process.env;
+        this.ttlMs = ttl;
+    }
+    namesFor(explicitNames) {
+        const names = new Set(PROVIDER_ENVIRONMENT_NAMES.filter((name) => this.env[name] !== undefined));
+        for (const name of canonicalRemoteCredentialNames(explicitNames))
+            names.add(name);
+        return this.requireAvailable([...names]);
+    }
+    requireAvailable(value) {
+        const names = canonicalRemoteCredentialNames(value);
+        for (const name of names) {
+            if (this.env[name] === undefined) {
+                throw new HitchError(`remote credential is unavailable: ${name}`, { code: "credential_unavailable", exitCode: 10 });
+            }
+        }
+        return names;
+    }
+    issue(offer) {
+        if (offer.state !== "accepted")
+            throw credentialError("remote credential envelope requires an accepted active lease");
+        const credentials = {};
+        for (const name of offer.credential_names ?? []) {
+            const value = this.env[name];
+            if (value === undefined) {
+                throw new HitchError(`remote credential is unavailable: ${name}`, { code: "credential_unavailable", exitCode: 10 });
+            }
+            credentials[name] = value;
+        }
+        const issued = new Date();
+        return {
+            schema_version: "1", worker_id: offer.worker_id, generation: offer.generation, offer_id: offer.offer_id,
+            lease_id: offer.lease.lease_id, epoch: offer.lease.epoch, issued_at: issued.toISOString(),
+            expires_at: new Date(issued.getTime() + this.ttlMs).toISOString(), credentials,
+        };
+    }
+}
+export function canonicalRemoteCredentialNames(value) {
+    if (!Array.isArray(value) || value.length > 256
+        || value.some((name) => typeof name !== "string" || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+        || new Set(value).size !== value.length)
+        throw credentialError("remote credential names are invalid");
+    return [...value].sort();
+}
+function credentialError(message) {
+    return new HitchError(message, { code: "worker_protocol_invalid", exitCode: 12 });
+}
+//# sourceMappingURL=remote-worker-credentials.js.map

package/dist/src/control-plane/remote-worker-credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-worker-credentials.js","sourceRoot":"","sources":["../../../src/control-plane/remote-worker-credentials.ts"],"names":[],"mappings":"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"}

package/dist/src/control-plane/remote-worker-protocol.js

@@ -0,0 +1,510 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { HitchError, atomicWriteJSON, ensureDir, readJSON, sha256JSON, statePaths, withFileLock } from "../foundation/index.js";
+import { parseExecutionLease } from "../evals/index.js";
+import { maxResourceVectors, resourceValue, subtractResourceVectors, sumResourceVectors, validateResourceVector } from "./resources.js";
+import { RemoteWorkerArtifactStore } from "./remote-worker-artifacts.js";
+import { RemoteWorkInputStore } from "./remote-work-inputs.js";
+import { RemoteCredentialEnvelopeIssuer, canonicalRemoteCredentialNames } from "./remote-worker-credentials.js";
+const OFFER_ID = /^offer_[a-f0-9]{32}$/;
+const LEASE_ID = /^lease_[a-f0-9]{32}$/;
+const SHA256 = /^sha256:[a-f0-9]{64}$/;
+const DEFAULT_OFFER_TTL_MS = 30_000;
+export class RemoteWorkerProtocol {
+    registry;
+    directory;
+    locks;
+    offerTtlMs;
+    credentials;
+    artifacts;
+    inputs;
+    constructor(input) {
+        const ttl = input.offerTtlMs ?? DEFAULT_OFFER_TTL_MS;
+        if (!input.root || !Number.isSafeInteger(ttl) || ttl < 1_000 || ttl > 5 * 60_000)
+            throw new TypeError("remote worker protocol configuration is invalid");
+        const paths = statePaths(input.root);
+        this.registry = input.registry;
+        this.directory = paths.workerProtocol;
+        this.locks = paths.workerProtocolLocks;
+        this.offerTtlMs = ttl;
+        this.credentials = new RemoteCredentialEnvelopeIssuer({
+            ...(input.credentialEnv ? { env: input.credentialEnv } : {}),
+            ...(input.credentialEnvelopeTtlMs === undefined ? {} : { ttlMs: input.credentialEnvelopeTtlMs }),
+        });
+        this.artifacts = new RemoteWorkerArtifactStore({ root: input.root });
+        this.inputs = new RemoteWorkInputStore(input.root);
+    }
+    async initialize() {
+        await Promise.all([ensureDir(this.directory), ensureDir(this.locks), this.artifacts.initialize(), this.inputs.initialize()]);
+    }
+    credentialNamesFor(explicitNames) {
+        return this.credentials.namesFor(explicitNames);
+    }
+    async createOffer(workerId, leaseValue, workValue, inputRefs = [], credentialNames = []) {
+        return withFileLock(this.locks, `offers-${workerId}`, async () => {
+            const worker = await this.requireReadyWorker(workerId);
+            const lease = parseExecutionLease(leaseValue);
+            const work = parseRemoteWorkItem(workValue);
+            const inputs = inputRefs.map(parseInputRef);
+            const credentials = this.credentials.requireAvailable(credentialNames);
+            if (new Set(inputs.map((entry) => entry.kind)).size !== inputs.length)
+                throw protocolError("remote work inputs are duplicated");
+            if (lease.state !== "offered" || lease.worker_id !== workerId || lease.provider !== worker.worker.provider
+                || lease.collision_domain_id !== worker.worker.collision_domain_id || lease.work_id !== work.work_id
+                || lease.eval_id !== work.eval_id || work.provider !== worker.worker.provider
+                || JSON.stringify(lease.reservation) !== JSON.stringify(work.reservation))
+                throw protocolError("remote work offer identity is invalid");
+            const outstanding = sumReservations(await this.listOffers(workerId, worker.generation));
+            const used = maxResources(worker.worker.capacity.allocated, outstanding);
+            assertFits(lease.reservation, available(worker.worker.capacity.allocatable, used));
+            const now = new Date();
+            const offer = {
+                schema_version: "1",
+                offer_id: `offer_${randomUUID().replaceAll("-", "")}`,
+                nonce: randomBytes(32).toString("hex"),
+                generation: worker.generation,
+                worker_id: workerId,
+                lease,
+                work,
+                ...(inputs.length > 0 ? { inputs } : {}),
+                ...(credentials.length > 0 ? { credential_names: credentials } : {}),
+                state: "offered",
+                issued_at: now.toISOString(),
+                expires_at: new Date(now.getTime() + this.offerTtlMs).toISOString(),
+            };
+            await atomicWriteJSON(this.offerPath(workerId, offer.offer_id), offer);
+            return offer;
+        }, { timeoutCode: "worker_offer_selection_locked", timeoutExitCode: 12 });
+    }
+    async listOffers(workerId, generation) {
+        await this.requireWorkerGeneration(workerId, generation);
+        const directory = this.offersDirectory(workerId);
+        await ensureDir(directory);
+        const entries = await readdir(directory, { withFileTypes: true });
+        const offers = [];
+        for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+            if (!entry.isFile() || !/^offer_[a-f0-9]{32}\.json$/.test(entry.name))
+                continue;
+            let offer = parseRemoteWorkOffer(await readJSON(path.join(directory, entry.name)));
+            if (offer.state === "offered" && Date.parse(offer.expires_at) <= Date.now())
+                offer = await this.expireOffer(offer);
+            if (offer.state === "offered" || offer.state === "accepted" || offer.state === "cancel-requested" || offer.state === "completed" || offer.state === "release-requested")
+                offers.push(offer);
+        }
+        return offers;
+    }
+    async acceptOffer(workerId, value) {
+        const receipt = parseAcceptReceipt(value);
+        await this.requireWorkerGeneration(workerId, receipt.generation);
+        return this.updateOffer(workerId, receipt.offer_id, async (offer) => {
+            assertOfferReceipt(offer, workerId, receipt.generation, receipt.nonce);
+            const digest = sha256JSON(receipt);
+            if (offer.accept_receipt_digest) {
+                if (offer.accept_receipt_digest !== digest)
+                    throw replayError("remote work offer acceptance conflicts with its receipt");
+                return offer;
+            }
+            if (offer.state !== "offered")
+                throw replayError(`remote work offer cannot be accepted from ${offer.state}`);
+            if (Date.parse(offer.expires_at) <= Date.now())
+                return { ...offer, state: "expired" };
+            const now = new Date().toISOString();
+            if (!receipt.accepted)
+                return {
+                    ...offer,
+                    state: "rejected",
+                    rejection_code: receipt.rejection_code,
+                    accept_receipt_digest: digest,
+                    completed_at: now,
+                };
+            await atomicWriteJSON(this.leaseIndexPath(offer.lease.lease_id), {
+                schema_version: "1", worker_id: workerId, offer_id: offer.offer_id,
+                lease_id: offer.lease.lease_id, epoch: offer.lease.epoch,
+            });
+            return { ...offer, state: "accepted", accepted_at: now, accept_receipt_digest: digest };
+        });
+    }
+    async recordEvent(workerId, value) {
+        const event = parseRemoteWorkerEvent(value);
+        await this.requireWorkerGeneration(workerId, event.generation);
+        const offer = await this.offerForLease(event.lease_id);
+        if (offer.worker_id !== workerId || offer.generation !== event.generation || offer.lease.epoch !== event.epoch
+            || !new Set(["accepted", "cancel-requested", "completed", "release-requested"]).has(offer.state))
+            throw protocolError("remote worker event lease is not active");
+        return withFileLock(this.locks, `event-${event.lease_id}`, async () => {
+            const statePath = this.eventStatePath(event.lease_id);
+            const state = await readJSON(statePath, null);
+            const sequence = state === null ? 0 : validSequence(state.sequence, true);
+            const file = this.eventPath(event.lease_id, event.sequence);
+            const existing = await readJSON(file, null);
+            if (existing !== null) {
+                const parsed = parseRemoteWorkerEvent(existing);
+                if (sha256JSON(parsed) !== sha256JSON(event))
+                    throw replayError("remote worker event sequence was replayed with different content");
+                if (event.sequence === sequence + 1)
+                    await atomicWriteJSON(statePath, { schema_version: "1", sequence: event.sequence });
+                else if (event.sequence > sequence)
+                    throw protocolError("remote worker event sequence has a gap");
+                return { event: parsed, duplicate: true };
+            }
+            if (event.sequence !== sequence + 1)
+                throw protocolError("remote worker event sequence is not contiguous");
+            await atomicWriteJSON(file, event);
+            await atomicWriteJSON(statePath, { schema_version: "1", sequence: event.sequence });
+            return { event, duplicate: false };
+        }, { timeoutCode: "worker_event_locked", timeoutExitCode: 12 });
+    }
+    async completeOffer(workerId, value) {
+        const receipt = parseTerminalReceipt(value);
+        await this.requireWorkerGeneration(workerId, receipt.generation);
+        return this.updateOffer(workerId, receipt.offer_id, async (offer) => {
+            assertOfferReceipt(offer, workerId, receipt.generation, receipt.nonce);
+            if (offer.lease.lease_id !== receipt.lease_id || offer.lease.epoch !== receipt.epoch)
+                throw protocolError("remote work terminal receipt lease is invalid");
+            const digest = sha256JSON(receipt);
+            if (offer.terminal_receipt_digest) {
+                if (offer.terminal_receipt_digest !== digest)
+                    throw replayError("remote work terminal receipt conflicts with the persisted receipt");
+                return offer;
+            }
+            if (offer.state !== "accepted" && offer.state !== "cancel-requested")
+                throw replayError(`remote work offer cannot complete from ${offer.state}`);
+            for (const artifact of receipt.artifacts)
+                await this.artifacts.verify(workerId, receipt.lease_id, artifact, receipt.epoch);
+            return {
+                ...offer,
+                state: "completed",
+                completed_at: receipt.sent_at,
+                terminal: { status: receipt.status, artifacts: receipt.artifacts, sent_at: receipt.sent_at },
+                terminal_receipt_digest: digest,
+            };
+        });
+    }
+    async requestCancel(workerId, offerId) {
+        return this.updateOffer(workerId, offerId, async (offer) => {
+            if (offer.state === "cancel-requested" || offer.state === "completed" || offer.state === "released")
+                return offer;
+            if (offer.state !== "offered" && offer.state !== "accepted")
+                throw protocolError(`remote work offer cannot be cancelled from ${offer.state}`);
+            return { ...offer, state: "cancel-requested" };
+        });
+    }
+    async withdrawUnacceptedOffer(workerId, offerId) {
+        return this.updateOffer(workerId, offerId, async (offer) => {
+            if (offer.state !== "offered")
+                return offer;
+            return { ...offer, state: "expired", completed_at: new Date().toISOString() };
+        });
+    }
+    async requestRelease(workerId, offerId) {
+        return this.updateOffer(workerId, offerId, async (offer) => {
+            if (offer.state === "release-requested" || offer.state === "released")
+                return offer;
+            if (offer.state !== "completed")
+                throw protocolError(`remote work offer cannot request release from ${offer.state}`);
+            return { ...offer, state: "release-requested" };
+        });
+    }
+    async releaseOffer(workerId, value) {
+        const receipt = parseReleaseReceipt(value);
+        await this.requireWorkerGeneration(workerId, receipt.generation);
+        return this.updateOffer(workerId, receipt.offer_id, async (offer) => {
+            assertOfferReceipt(offer, workerId, receipt.generation, receipt.nonce);
+            if (offer.lease.lease_id !== receipt.lease_id || offer.lease.epoch !== receipt.epoch)
+                throw protocolError("remote work release receipt lease is invalid");
+            const digest = sha256JSON(receipt);
+            if (offer.release_receipt_digest) {
+                if (offer.release_receipt_digest !== digest)
+                    throw replayError("remote work release receipt conflicts with the persisted receipt");
+                return offer;
+            }
+            if (offer.state !== "completed" && offer.state !== "release-requested" && offer.state !== "cancel-requested")
+                throw protocolError(`remote work offer cannot be released from ${offer.state}`);
+            return {
+                ...offer,
+                state: "released",
+                ...(offer.terminal ? {} : {
+                    completed_at: receipt.sent_at,
+                    terminal: { status: "cancelled", artifacts: [], sent_at: receipt.sent_at },
+                }),
+                released_at: receipt.sent_at,
+                release_receipt_digest: digest,
+            };
+        });
+    }
+    async getOffer(workerId, offerId) {
+        validateOfferIdentity(workerId, offerId);
+        const value = await readJSON(this.offerPath(workerId, offerId), null);
+        return value === null ? null : parseRemoteWorkOffer(value);
+    }
+    async getOfferForLease(leaseId) {
+        if (!LEASE_ID.test(leaseId))
+            throw protocolError("remote work lease id is invalid");
+        try {
+            return await this.offerForLease(leaseId);
+        }
+        catch (error) {
+            if (error.code === "worker_offer_not_found")
+                return null;
+            throw error;
+        }
+    }
+    async findOfferForLease(workerId, leaseId) {
+        if (!/^worker_[a-z0-9][a-z0-9_-]{0,62}$/.test(workerId) || !LEASE_ID.test(leaseId))
+            throw protocolError("remote work lease identity is invalid");
+        const directory = this.offersDirectory(workerId);
+        const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
+            if (error.code === "ENOENT")
+                return [];
+            throw error;
+        });
+        const matches = [];
+        for (const entry of entries) {
+            if (!entry.isFile() || !/^offer_[a-f0-9]{32}\.json$/.test(entry.name))
+                continue;
+            const offer = parseRemoteWorkOffer(await readJSON(path.join(directory, entry.name)));
+            if (offer.lease.lease_id === leaseId)
+                matches.push(offer);
+        }
+        if (matches.length > 1)
+            throw protocolError(`remote worker lease has multiple offers: ${leaseId}`);
+        return matches[0] ?? null;
+    }
+    async uploadArtifact(input) {
+        const offer = await this.activeOfferForLease(input.workerId, input.leaseId, input.generation, input.epoch);
+        if (offer.state !== "accepted" && offer.state !== "cancel-requested")
+            throw protocolError("remote worker artifact lease is not collecting evidence");
+        return this.artifacts.upload(input);
+    }
+    async activeOfferForLease(workerId, leaseId, generation, epoch) {
+        await this.requireWorkerGeneration(workerId, generation);
+        const offer = await this.offerForLease(leaseId);
+        if (offer.worker_id !== workerId || offer.generation !== generation || offer.lease.epoch !== epoch)
+            throw protocolError("remote worker lease identity is invalid");
+        return offer;
+    }
+    async issueCredentialEnvelope(workerId, leaseId, generation, epoch) {
+        const offer = await this.activeOfferForLease(workerId, leaseId, generation, epoch);
+        return this.credentials.issue(offer);
+    }
+    async validateHeartbeatLeases(workerId, heartbeat) {
+        await this.registry.validateHeartbeatGeneration(workerId, heartbeat.generation);
+        for (const lease of heartbeat.active_leases) {
+            const offer = await this.offerForLease(lease.lease_id).catch(() => null);
+            if (!offer || offer.worker_id !== workerId || offer.generation !== heartbeat.generation
+                || offer.lease.epoch !== lease.epoch || !acceptedOrCollecting(offer.state)) {
+                throw protocolError(`remote worker heartbeat reports an unauthorized lease: ${lease.lease_id}`);
+            }
+        }
+    }
+    async resolveInput(workerId, leaseId, generation, digest) {
+        await this.requireWorkerGeneration(workerId, generation);
+        const offer = await this.findOfferForLease(workerId, leaseId);
+        if (!offer || offer.generation !== generation || !new Set(["offered", "accepted", "cancel-requested"]).has(offer.state)) {
+            throw protocolError("remote work input lease is not active");
+        }
+        const ref = offer.inputs?.find((entry) => entry.digest === digest);
+        if (!ref)
+            throw protocolError("remote work input is not authorized for this lease");
+        return this.inputs.verify(ref);
+    }
+    artifactPath(workerId, leaseId, digest) {
+        return this.artifacts.pathFor(workerId, leaseId, digest);
+    }
+    async updateOffer(workerId, offerId, update) {
+        validateOfferIdentity(workerId, offerId);
+        return withFileLock(this.locks, offerId, async () => {
+            const current = await this.getOffer(workerId, offerId);
+            if (!current)
+                throw new HitchError(`remote work offer not found: ${offerId}`, { code: "worker_offer_not_found", exitCode: 3 });
+            const next = parseRemoteWorkOffer(await update(current));
+            if (next !== current)
+                await atomicWriteJSON(this.offerPath(workerId, offerId), next);
+            return next;
+        }, { timeoutCode: "worker_offer_locked", timeoutExitCode: 12 });
+    }
+    async expireOffer(offer) {
+        return this.updateOffer(offer.worker_id, offer.offer_id, async (current) => current.state === "offered" && Date.parse(current.expires_at) <= Date.now()
+            ? { ...current, state: "expired" }
+            : current);
+    }
+    async offerForLease(leaseId) {
+        if (!LEASE_ID.test(leaseId))
+            throw protocolError("remote worker lease id is invalid");
+        const index = await readJSON(this.leaseIndexPath(leaseId), null);
+        if (!index || typeof index.worker_id !== "string" || typeof index.offer_id !== "string")
+            throw protocolError("remote worker lease has no accepted offer");
+        const offer = await this.getOffer(index.worker_id, index.offer_id);
+        if (!offer || index.lease_id !== leaseId || index.epoch !== offer.lease.epoch)
+            throw protocolError("remote worker lease index is invalid");
+        return offer;
+    }
+    async requireReadyWorker(workerId) {
+        const worker = await this.registry.get(workerId);
+        if (!worker || worker.worker.status !== "ready" || worker.revoked_at)
+            throw new HitchError("remote worker is unavailable", { code: "worker_unavailable", exitCode: 10 });
+        return worker;
+    }
+    async requireWorkerGeneration(workerId, generation) {
+        const worker = await this.requireReadyWorker(workerId);
+        if (worker.generation !== generation)
+            throw new HitchError("remote worker generation is stale", { code: "worker_generation_mismatch", exitCode: 12 });
+    }
+    offersDirectory(workerId) { return path.join(this.directory, "workers", workerId, "offers"); }
+    offerPath(workerId, offerId) { return path.join(this.offersDirectory(workerId), `${offerId}.json`); }
+    leaseIndexPath(leaseId) { return path.join(this.directory, "leases", `${leaseId}.json`); }
+    eventStatePath(leaseId) { return path.join(this.directory, "events", leaseId, "state.json"); }
+    eventPath(leaseId, sequence) { return path.join(this.directory, "events", leaseId, `${String(sequence).padStart(12, "0")}.json`); }
+}
+export function parseRemoteWorkOffer(value) {
+    const record = exact(value, [
+        "schema_version", "offer_id", "nonce", "generation", "worker_id", "lease", "work", "inputs", "credential_names", "state", "issued_at", "expires_at",
+        "accepted_at", "completed_at", "released_at", "rejection_code", "terminal",
+        "accept_receipt_digest", "terminal_receipt_digest", "release_receipt_digest",
+    ], "remote work offer");
+    const states = new Set(["offered", "accepted", "rejected", "cancel-requested", "completed", "release-requested", "released", "expired"]);
+    if (record.schema_version !== "1" || typeof record.offer_id !== "string" || !OFFER_ID.test(record.offer_id)
+        || typeof record.nonce !== "string" || !/^[a-f0-9]{64}$/.test(record.nonce)
+        || !Number.isSafeInteger(record.generation) || record.generation < 1
+        || typeof record.worker_id !== "string" || !/^worker_[a-z0-9][a-z0-9_-]{0,62}$/.test(record.worker_id)
+        || !states.has(String(record.state)) || !timestamp(record.issued_at) || !timestamp(record.expires_at))
+        throw protocolError("remote work offer identity is invalid");
+    for (const field of ["accepted_at", "completed_at", "released_at"])
+        if (record[field] !== undefined && !timestamp(record[field]))
+            throw protocolError(`remote work offer ${field} is invalid`);
+    for (const field of ["accept_receipt_digest", "terminal_receipt_digest", "release_receipt_digest"])
+        if (record[field] !== undefined && (typeof record[field] !== "string" || !SHA256.test(record[field])))
+            throw protocolError(`remote work offer ${field} is invalid`);
+    const lease = parseExecutionLease(record.lease);
+    const work = parseRemoteWorkItem(record.work);
+    const inputs = record.inputs === undefined ? undefined : Array.isArray(record.inputs) ? record.inputs.map(parseInputRef) : (() => { throw protocolError("remote work inputs are invalid"); })();
+    if (inputs && new Set(inputs.map((entry) => entry.kind)).size !== inputs.length)
+        throw protocolError("remote work inputs are duplicated");
+    const credentialNames = record.credential_names === undefined ? undefined : canonicalRemoteCredentialNames(record.credential_names);
+    const terminal = record.terminal === undefined ? undefined : parseTerminal(record.terminal);
+    if (lease.worker_id !== record.worker_id || lease.work_id !== work.work_id || lease.eval_id !== work.eval_id
+        || (record.state === "completed" || record.state === "release-requested" || record.state === "released") !== (terminal !== undefined))
+        throw protocolError("remote work offer evidence is inconsistent");
+    return { ...record, ...(inputs ? { inputs } : {}), ...(credentialNames?.length ? { credential_names: credentialNames } : {}) };
+}
+function parseRemoteWorkItem(value) {
+    const record = exact(value, ["schema_version", "work_id", "eval_id", "backend", "logical_attempt", "task_ids", "slots", "opaque_membership", "requested_parallelism", "reservation", "provider", "image_refs", "artifact_id", "runtime_contract"], "remote work item");
+    if (record.schema_version !== "1" || typeof record.work_id !== "string" || !/^work_[a-f0-9]{32}$/.test(record.work_id)
+        || typeof record.eval_id !== "string" || !/^eval_[a-f0-9]{32}$/.test(record.eval_id) || record.backend !== "harbor"
+        || record.logical_attempt !== null && (!Number.isSafeInteger(record.logical_attempt) || record.logical_attempt < 1)
+        || !stringArray(record.task_ids) || !stringArray(record.slots) || typeof record.opaque_membership !== "boolean"
+        || !Number.isSafeInteger(record.requested_parallelism) || record.requested_parallelism < 1
+        || typeof record.provider !== "string" || !record.provider || record.image_refs !== undefined && !Array.isArray(record.image_refs)
+        || record.artifact_id !== undefined && (typeof record.artifact_id !== "string" || !SHA256.test(record.artifact_id))
+        || (record.artifact_id === undefined) !== (record.runtime_contract === undefined))
+        throw protocolError("remote work item is invalid");
+    if (record.runtime_contract !== undefined) {
+        const runtime = exact(record.runtime_contract, ["docker_platform", "artifact_platform", "node_version"], "remote work runtime contract");
+        if ((runtime.docker_platform !== "linux/amd64" && runtime.docker_platform !== "linux/arm64")
+            || (runtime.artifact_platform !== "linux-x64" && runtime.artifact_platform !== "linux-arm64")
+            || (runtime.docker_platform === "linux/amd64") !== (runtime.artifact_platform === "linux-x64")
+            || typeof runtime.node_version !== "string" || !/^v\d+\.\d+\.\d+$/.test(runtime.node_version))
+            throw protocolError("remote work runtime contract is invalid");
+    }
+    return { ...record, reservation: validateResourceVector(record.reservation, "remote work reservation") };
+}
+function parseAcceptReceipt(value) {
+    const record = exact(value, ["schema_version", "offer_id", "nonce", "generation", "accepted", "rejection_code", "sent_at"], "remote work accept receipt");
+    if (record.schema_version !== "1" || typeof record.offer_id !== "string" || !OFFER_ID.test(record.offer_id)
+        || typeof record.nonce !== "string" || !/^[a-f0-9]{64}$/.test(record.nonce) || !Number.isSafeInteger(record.generation) || record.generation < 1
+        || typeof record.accepted !== "boolean" || !timestamp(record.sent_at)
+        || record.accepted === false !== (typeof record.rejection_code === "string" && Boolean(record.rejection_code)))
+        throw protocolError("remote work accept receipt is invalid");
+    return record;
+}
+function parseTerminalReceipt(value) {
+    const record = exact(value, ["schema_version", "offer_id", "nonce", "generation", "lease_id", "epoch", "status", "artifacts", "sent_at"], "remote work terminal receipt");
+    if (record.schema_version !== "1" || typeof record.offer_id !== "string" || !OFFER_ID.test(record.offer_id)
+        || typeof record.nonce !== "string" || !/^[a-f0-9]{64}$/.test(record.nonce) || !Number.isSafeInteger(record.generation) || record.generation < 1
+        || typeof record.lease_id !== "string" || !LEASE_ID.test(record.lease_id) || !Number.isSafeInteger(record.epoch) || record.epoch < 1
+        || !new Set(["succeeded", "failed", "cancelled"]).has(String(record.status)) || !Array.isArray(record.artifacts) || !timestamp(record.sent_at))
+        throw protocolError("remote work terminal receipt is invalid");
+    const artifacts = record.artifacts.map(parseArtifactRef).sort((left, right) => left.digest.localeCompare(right.digest));
+    if (new Set(artifacts.map((entry) => `${entry.kind}:${entry.digest}`)).size !== artifacts.length)
+        throw protocolError("remote work terminal artifacts are duplicated");
+    return { ...record, artifacts };
+}
+function parseReleaseReceipt(value) {
+    const record = exact(value, ["schema_version", "offer_id", "nonce", "generation", "lease_id", "epoch", "sent_at"], "remote work release receipt");
+    if (record.schema_version !== "1" || typeof record.offer_id !== "string" || !OFFER_ID.test(record.offer_id)
+        || typeof record.nonce !== "string" || !/^[a-f0-9]{64}$/.test(record.nonce) || !Number.isSafeInteger(record.generation) || record.generation < 1
+        || typeof record.lease_id !== "string" || !LEASE_ID.test(record.lease_id) || !Number.isSafeInteger(record.epoch) || record.epoch < 1 || !timestamp(record.sent_at))
+        throw protocolError("remote work release receipt is invalid");
+    return record;
+}
+export function parseRemoteWorkerEvent(value) {
+    const record = exact(value, ["schema_version", "generation", "lease_id", "epoch", "sequence", "type", "payload", "sent_at"], "remote worker event");
+    if (record.schema_version !== "1" || !Number.isSafeInteger(record.generation) || record.generation < 1
+        || typeof record.lease_id !== "string" || !LEASE_ID.test(record.lease_id) || !Number.isSafeInteger(record.epoch) || record.epoch < 1
+        || !Number.isSafeInteger(record.sequence) || record.sequence < 1 || typeof record.type !== "string" || !record.type || record.type.length > 256
+        || record.payload !== undefined && (!record.payload || typeof record.payload !== "object" || Array.isArray(record.payload)) || !timestamp(record.sent_at))
+        throw protocolError("remote worker event is invalid");
+    return record;
+}
+function parseTerminal(value) {
+    const record = exact(value, ["status", "artifacts", "sent_at"], "remote work terminal evidence");
+    if (!new Set(["succeeded", "failed", "cancelled"]).has(String(record.status)) || !Array.isArray(record.artifacts) || !timestamp(record.sent_at))
+        throw protocolError("remote work terminal evidence is invalid");
+    return { status: record.status, artifacts: record.artifacts.map(parseArtifactRef), sent_at: record.sent_at };
+}
+function parseArtifactRef(value) {
+    const record = exact(value, ["kind", "digest", "size"], "remote work artifact ref");
+    if (record.kind !== "result-bundle" && record.kind !== "diagnostic" || typeof record.digest !== "string" || !SHA256.test(record.digest)
+        || !Number.isSafeInteger(record.size) || record.size < 0 || record.size > 512 * 1024 * 1024)
+        throw protocolError("remote work artifact ref is invalid");
+    return { kind: record.kind, digest: record.digest, size: record.size };
+}
+function parseInputRef(value) {
+    const record = exact(value, ["kind", "format", "digest", "size"], "remote work input ref");
+    if (!new Set(["work-spec", "harness-artifact", "controller-runtime", "task-input"]).has(String(record.kind))
+        || !new Set(["json", "hitch-tree-v1"]).has(String(record.format)) || typeof record.digest !== "string" || !SHA256.test(record.digest)
+        || !Number.isSafeInteger(record.size) || record.size < 1 || record.size > 256 * 1024 * 1024)
+        throw protocolError("remote work input ref is invalid");
+    return record;
+}
+function assertOfferReceipt(offer, workerId, generation, nonce) {
+    if (offer.worker_id !== workerId || offer.generation !== generation || offer.nonce !== nonce)
+        throw replayError("remote work receipt identity does not match the offer");
+}
+function validateOfferIdentity(workerId, offerId) {
+    if (!/^worker_[a-z0-9][a-z0-9_-]{0,62}$/.test(workerId) || !OFFER_ID.test(offerId))
+        throw protocolError("remote work offer lookup identity is invalid");
+}
+function available(allocatable, allocated) {
+    return subtractResourceVectors(allocatable, allocated);
+}
+function sumReservations(offers) {
+    return sumResourceVectors(offers.map((offer) => offer.lease.reservation));
+}
+function maxResources(left, right) {
+    return maxResourceVectors(left, right);
+}
+function assertFits(requested, capacity) {
+    if (fields().some((field) => resourceValue(requested, field) > resourceValue(capacity, field)))
+        throw new HitchError("remote worker rejected work capacity", { code: "worker_rejected", exitCode: 10 });
+}
+function acceptedOrCollecting(state) {
+    return state === "accepted" || state === "cancel-requested" || state === "completed" || state === "release-requested";
+}
+function fields() { return ["cpu_millis", "memory_bytes", "container_slots", "build_slots", "gpu_count", "ephemeral_disk_bytes"]; }
+function timestamp(value) { return typeof value === "string" && Number.isFinite(Date.parse(value)); }
+function stringArray(value) { return Array.isArray(value) && value.every((entry) => typeof entry === "string" && entry.length > 0 && !/[\0\r\n]/.test(entry)) && new Set(value).size === value.length; }
+function validSequence(value, allowZero) { if (!Number.isSafeInteger(value) || value < (allowZero ? 0 : 1))
+    throw protocolError("remote worker event sequence state is invalid"); return value; }
+function exact(value, keys, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw protocolError(`${label} must be an object`);
+    const record = value;
+    if (Object.keys(record).some((key) => !keys.includes(key)))
+        throw protocolError(`${label} has unknown fields`);
+    return record;
+}
+function protocolError(message) { return new HitchError(message, { code: "worker_protocol_invalid", exitCode: 2 }); }
+function replayError(message) { return new HitchError(message, { code: "worker_protocol_replay", exitCode: 12 }); }
+//# sourceMappingURL=remote-worker-protocol.js.map