@alpacakit/agents 0.1.0-beta.20 → 0.1.0-beta.21

package/dist/internal/controlled-process/supervisor-schema.d.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+export declare const supervisorBootstrapSchema: z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"bootstrap">;
+    runtimeDirectory: z.ZodString;
+    shimEntryPath: z.ZodString;
+    worker: z.ZodReadonly<z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+        cwd: z.ZodString;
+        env: z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>;
+        stdin: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    timing: z.ZodReadonly<z.ZodObject<{
+        termGraceMs: z.ZodNumber;
+        killProbeTimeoutMs: z.ZodNumber;
+        probeIntervalMs: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+export declare const supervisorHostAckSchema: z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"host_ack">;
+}, z.core.$strip>>;
+export declare const supervisorIdentityFrameSchema: z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"identity">;
+    identity: z.ZodReadonly<z.ZodObject<{
+        pid: z.ZodPipe<z.ZodNumber, z.ZodTransform<import("./model.js").ShimProcessId, number>>;
+        processStartToken: z.ZodPipe<z.ZodString, z.ZodTransform<import("./model.js").ProcessStartToken, string>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+export declare const supervisorLaunchFailedFrameSchema: z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"launch_failed">;
+    reason: z.ZodString;
+}, z.core.$strip>>;
+export declare const shimBootstrapSchema: z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"shim_bootstrap">;
+    worker: z.ZodReadonly<z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+        cwd: z.ZodString;
+        env: z.ZodReadonly<z.ZodRecord<z.ZodString, z.ZodString>>;
+        stdin: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+export declare const shimAckSchema: z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"shim_ack">;
+}, z.core.$strip>>;
+export declare const shimRunningSchema: z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"shim_running">;
+}, z.core.$strip>>;
+export declare const workerExitSchema: z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"worker_exit">;
+    code: z.ZodNullable<z.ZodNumber>;
+    signal: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>>;
+export declare const supervisorRequestSchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"probe">;
+}, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"terminate">;
+}, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"release">;
+}, z.core.$strip>>], "kind">;
+export declare const supervisorResponseSchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"termination">;
+    result: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+        kind: z.ZodLiteral<"absent">;
+        proof: z.ZodEnum<{
+            supervisor_probe: "supervisor_probe";
+            boot_changed: "boot_changed";
+            released_receipt: "released_receipt";
+        }>;
+    }, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
+        kind: z.ZodLiteral<"pending">;
+        phase: z.ZodEnum<{
+            term_grace: "term_grace";
+            kill_probe: "kill_probe";
+        }>;
+        retryAfterMs: z.ZodNumber;
+    }, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
+        kind: z.ZodLiteral<"unkillable">;
+        reason: z.ZodEnum<{
+            invalid_identity: "invalid_identity";
+            boot_identity_unavailable: "boot_identity_unavailable";
+            supervisor_unreachable: "supervisor_unreachable";
+            record_authentication_failed: "record_authentication_failed";
+            record_identity_mismatch: "record_identity_mismatch";
+            protocol_failure: "protocol_failure";
+            probe_permission_denied: "probe_permission_denied";
+            shim_lost_with_live_group: "shim_lost_with_live_group";
+            group_survived_sigkill: "group_survived_sigkill";
+        }>;
+    }, z.core.$strip>>], "kind">;
+    workerExit: z.ZodNullable<z.ZodReadonly<z.ZodObject<{
+        code: z.ZodNullable<z.ZodNumber>;
+        signal: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"released">;
+}, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"release_before_absent">;
+}, z.core.$strip>>], "kind">;
+//# sourceMappingURL=supervisor-schema.d.ts.map

package/dist/internal/controlled-process/supervisor-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-schema.d.ts","sourceRoot":"","sources":["../../../src/internal/controlled-process/supervisor-schema.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA0CxB,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;kBAMK,CAAC;AAE5C,eAAO,MAAM,uBAAuB;;kBAEK,CAAC;AAE1C,eAAO,MAAM,6BAA6B;;;;;;kBAGK,CAAC;AAEhD,eAAO,MAAM,iCAAiC;;;kBAGK,CAAC;AAEpD,eAAO,MAAM,mBAAmB;;;;;;;;;kBAGK,CAAC;AAEtC,eAAO,MAAM,aAAa;;kBAEK,CAAC;AAEhC,eAAO,MAAM,iBAAiB;;kBAEK,CAAC;AAEpC,eAAO,MAAM,gBAAgB;;;;kBAIK,CAAC;AAEnC,eAAO,MAAM,uBAAuB;;;;;;4BAIK,CAAC;AAE1C,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAaK,CAAC"}

package/dist/internal/controlled-process/supervisor-schema.js

@@ -0,0 +1,73 @@
+import { strictReadonlyObject } from "@alpacakit/core";
+import { z } from "zod";
+import { SHIM_FRAME_KIND, SUPERVISOR_BOOTSTRAP_FRAME_KIND, SUPERVISOR_REQUEST_KIND, SUPERVISOR_RESPONSE_KIND, } from "./supervisor-values.js";
+import { childProcessTerminationResultSchema, controlledProcessIdentitySchema, } from "./schema.js";
+const nonBlankStringSchema = z
+    .string()
+    .min(1)
+    .refine((value) => value.trim() !== "");
+const durationSchema = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const workerOptionsSchema = strictReadonlyObject({
+    command: nonBlankStringSchema,
+    args: z.array(z.string()).readonly(),
+    cwd: nonBlankStringSchema,
+    env: z.record(z.string(), z.string()).readonly(),
+    stdin: z.string().nullable(),
+});
+const timingOptionsSchema = strictReadonlyObject({
+    termGraceMs: durationSchema,
+    killProbeTimeoutMs: durationSchema,
+    probeIntervalMs: durationSchema,
+});
+export const supervisorBootstrapSchema = strictReadonlyObject({
+    kind: z.literal(SUPERVISOR_BOOTSTRAP_FRAME_KIND.bootstrap),
+    runtimeDirectory: nonBlankStringSchema,
+    shimEntryPath: nonBlankStringSchema,
+    worker: workerOptionsSchema,
+    timing: timingOptionsSchema,
+});
+export const supervisorHostAckSchema = strictReadonlyObject({
+    kind: z.literal(SUPERVISOR_BOOTSTRAP_FRAME_KIND.hostAck),
+});
+export const supervisorIdentityFrameSchema = strictReadonlyObject({
+    kind: z.literal(SUPERVISOR_BOOTSTRAP_FRAME_KIND.identity),
+    identity: controlledProcessIdentitySchema,
+});
+export const supervisorLaunchFailedFrameSchema = strictReadonlyObject({
+    kind: z.literal(SUPERVISOR_BOOTSTRAP_FRAME_KIND.launchFailed),
+    reason: z.string().min(1),
+});
+export const shimBootstrapSchema = strictReadonlyObject({
+    kind: z.literal(SHIM_FRAME_KIND.bootstrap),
+    worker: workerOptionsSchema,
+});
+export const shimAckSchema = strictReadonlyObject({
+    kind: z.literal(SHIM_FRAME_KIND.ack),
+});
+export const shimRunningSchema = strictReadonlyObject({
+    kind: z.literal(SHIM_FRAME_KIND.running),
+});
+export const workerExitSchema = strictReadonlyObject({
+    kind: z.literal(SHIM_FRAME_KIND.workerExit),
+    code: z.number().int().nullable(),
+    signal: z.string().nullable(),
+});
+export const supervisorRequestSchema = z.discriminatedUnion("kind", [
+    strictReadonlyObject({ kind: z.literal(SUPERVISOR_REQUEST_KIND.probe) }),
+    strictReadonlyObject({ kind: z.literal(SUPERVISOR_REQUEST_KIND.terminate) }),
+    strictReadonlyObject({ kind: z.literal(SUPERVISOR_REQUEST_KIND.release) }),
+]);
+export const supervisorResponseSchema = z.discriminatedUnion("kind", [
+    strictReadonlyObject({
+        kind: z.literal(SUPERVISOR_RESPONSE_KIND.termination),
+        result: childProcessTerminationResultSchema,
+        workerExit: strictReadonlyObject({
+            code: z.number().int().nullable(),
+            signal: z.string().nullable(),
+        }).nullable(),
+    }),
+    strictReadonlyObject({ kind: z.literal(SUPERVISOR_RESPONSE_KIND.released) }),
+    strictReadonlyObject({
+        kind: z.literal(SUPERVISOR_RESPONSE_KIND.releaseBeforeAbsent),
+    }),
+]);

package/dist/internal/controlled-process/supervisor-transport.d.ts

@@ -0,0 +1,46 @@
+import type { ControlledProcessRecordId, SupervisorCapability } from "./model.js";
+import type { SupervisorRequest, SupervisorResponse } from "./supervisor-model.js";
+export type SupervisorSessionHandler = (request: SupervisorRequest) => Promise<SupervisorResponse>;
+type SupervisorSocketState = {
+    readonly kind: "owned";
+} | {
+    readonly kind: "ownership_lost";
+} | {
+    readonly kind: "closed";
+};
+export declare class SupervisorSocketServer {
+    private readonly socketPath;
+    private readonly uid;
+    private readonly recordId;
+    private readonly capability;
+    private readonly handler;
+    private server;
+    private ownedSocket;
+    private bound;
+    private ownershipLost;
+    private closed;
+    private readonly sessions;
+    private finalizationPromise;
+    private closePromise;
+    constructor(socketPath: string, uid: number, recordId: ControlledProcessRecordId, capability: SupervisorCapability, handler: SupervisorSessionHandler);
+    listen(): Promise<void>;
+    close(): Promise<void>;
+    observeOwnership(): Promise<SupervisorSocketState>;
+    finalize(): Promise<SupervisorSocketState>;
+    settleAcceptedSessions(): Promise<void>;
+    private finalizeOwnedSocket;
+    private inspectOwnership;
+    private latchOwnershipLost;
+    private handle;
+}
+export declare function requestSupervisor(input: {
+    readonly socketPath: string;
+    readonly uid: number;
+    readonly recordId: ControlledProcessRecordId;
+    readonly capability: SupervisorCapability;
+    readonly request: SupervisorRequest;
+    readonly signal: AbortSignal;
+}): Promise<SupervisorResponse>;
+export declare function assertSecureSocket(socketPath: string, uid: number): Promise<void>;
+export {};
+//# sourceMappingURL=supervisor-transport.d.ts.map

package/dist/internal/controlled-process/supervisor-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-transport.d.ts","sourceRoot":"","sources":["../../../src/internal/controlled-process/supervisor-transport.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,yBAAyB,EACzB,oBAAoB,EAIrB,MAAM,YAAY,CAAC;AAQpB,OAAO,KAAK,EACV,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,uBAAuB,CAAC;AAe/B,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,iBAAiB,KACvB,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAYjC,KAAK,qBAAqB,GACtB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GACnC;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAMhC,qBAAa,sBAAsB;IAW/B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAd1B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,mBAAmB,CAA+C;IAC1E,OAAO,CAAC,YAAY,CAA8B;gBAG/B,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,yBAAyB,EACnC,UAAU,EAAE,oBAAoB,EAChC,OAAO,EAAE,wBAAwB;IAG9C,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAmE7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,gBAAgB,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAIlD,QAAQ,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAK1C,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;YAIzB,mBAAmB;YAsCnB,gBAAgB;IAuB9B,OAAO,CAAC,kBAAkB;YAKZ,MAAM;CAmCrB;AAED,wBAAsB,iBAAiB,CAAC,KAAK,EAAE;IAC7C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAuC9B;AAED,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CAWf"}

package/dist/internal/controlled-process/supervisor-transport.js

@@ -0,0 +1,368 @@
+import { randomBytes } from "node:crypto";
+import { chmod, lstat, unlink } from "node:fs/promises";
+import { createConnection, createServer, } from "node:net";
+import { consumeClientProof, createClientProof, issueSupervisorChallenge, verifySupervisorChallenge, } from "./authentication.js";
+import { readFramedRecords, readRequiredFrame, writeFramedRecord, } from "./framed-transport.js";
+import { supervisorChallengeSchema, supervisorClientChallengeSchema, supervisorClientNonceSchema, supervisorClientProofSchema, supervisorServerNonceSchema, } from "./schema.js";
+import { supervisorRequestSchema, supervisorResponseSchema, } from "./supervisor-schema.js";
+import { SUPERVISOR_AUTHENTICATION_FRAME_KIND, SUPERVISOR_AUTHENTICATION_RESULT_KIND, } from "./values.js";
+const SOCKET_MODE = 0o600;
+const PERMISSION_BITS = 0o777;
+const NONCE_BYTES = 32;
+const CONNECTION_TIMEOUT_MS = 1_000;
+const OWNED_SOCKET_STATE = { kind: "owned" };
+const OWNERSHIP_LOST_SOCKET_STATE = { kind: "ownership_lost" };
+const CLOSED_SOCKET_STATE = { kind: "closed" };
+export class SupervisorSocketServer {
+    socketPath;
+    uid;
+    recordId;
+    capability;
+    handler;
+    server = null;
+    ownedSocket = null;
+    bound = false;
+    ownershipLost = false;
+    closed = false;
+    sessions = new Set();
+    finalizationPromise = null;
+    closePromise = null;
+    constructor(socketPath, uid, recordId, capability, handler) {
+        this.socketPath = socketPath;
+        this.uid = uid;
+        this.recordId = recordId;
+        this.capability = capability;
+        this.handler = handler;
+    }
+    async listen() {
+        await assertSocketTargetAbsent(this.socketPath);
+        const server = createServer((socket) => {
+            if (this.ownershipLost || this.closed) {
+                socket.destroy();
+                return;
+            }
+            const onTimeout = () => {
+                socket.destroy();
+            };
+            const stopSessionControls = () => {
+                socket.setTimeout(0);
+                socket.off("timeout", onTimeout);
+            };
+            socket.setTimeout(CONNECTION_TIMEOUT_MS, onTimeout);
+            const session = this.handle(socket).then(() => {
+                stopSessionControls();
+                return observeSocketClose(socket);
+            }, () => {
+                stopSessionControls();
+                socket.destroy();
+                return observeSocketClose(socket);
+            });
+            this.sessions.add(session);
+            void session.finally(() => this.sessions.delete(session));
+        });
+        this.server = server;
+        try {
+            await new Promise((resolve, reject) => {
+                server.once("error", reject);
+                server.listen(this.socketPath, () => {
+                    server.off("error", reject);
+                    resolve();
+                });
+            });
+            this.bound = true;
+            try {
+                this.ownedSocket = await readOwnedSocketIdentity(this.socketPath, this.uid);
+            }
+            catch {
+                this.latchOwnershipLost();
+                return;
+            }
+            await chmod(this.socketPath, SOCKET_MODE);
+            await assertSecureSocket(this.socketPath, this.uid);
+        }
+        catch (primaryFailure) {
+            let finalization;
+            try {
+                finalization = await this.finalize();
+            }
+            catch (cleanupFailure) {
+                throw new AggregateError([primaryFailure, cleanupFailure], "Supervisor socket listen and cleanup both failed.");
+            }
+            if (finalization.kind === OWNERSHIP_LOST_SOCKET_STATE.kind) {
+                return;
+            }
+            throw primaryFailure;
+        }
+    }
+    close() {
+        this.closePromise ??= this.finalize().then(() => undefined);
+        return this.closePromise;
+    }
+    observeOwnership() {
+        return this.inspectOwnership();
+    }
+    finalize() {
+        this.finalizationPromise ??= this.finalizeOwnedSocket();
+        return this.finalizationPromise;
+    }
+    settleAcceptedSessions() {
+        return Promise.all(this.sessions).then(() => undefined);
+    }
+    async finalizeOwnedSocket() {
+        const server = this.server;
+        if (!this.bound || server?.listening !== true) {
+            this.server = null;
+            this.ownedSocket = null;
+            this.closed = true;
+            return CLOSED_SOCKET_STATE;
+        }
+        const started = await this.inspectOwnership();
+        if (started.kind !== OWNED_SOCKET_STATE.kind) {
+            return started;
+        }
+        const final = await this.inspectOwnership();
+        if (final.kind !== OWNED_SOCKET_STATE.kind) {
+            return final;
+        }
+        const ownedSocket = this.ownedSocket;
+        if (ownedSocket === null) {
+            return this.latchOwnershipLost();
+        }
+        await new Promise((resolve, reject) => {
+            server.close((error) => {
+                if (error === undefined) {
+                    resolve();
+                }
+                else {
+                    reject(error);
+                }
+            });
+        });
+        await this.settleAcceptedSessions();
+        await unlinkOwnedSocket(this.socketPath, ownedSocket);
+        this.server = null;
+        this.ownedSocket = null;
+        this.bound = false;
+        this.closed = true;
+        return CLOSED_SOCKET_STATE;
+    }
+    async inspectOwnership() {
+        if (this.ownershipLost) {
+            return OWNERSHIP_LOST_SOCKET_STATE;
+        }
+        if (this.closed) {
+            return CLOSED_SOCKET_STATE;
+        }
+        const ownedSocket = this.ownedSocket;
+        if (!this.bound || ownedSocket === null) {
+            return this.latchOwnershipLost();
+        }
+        let current;
+        try {
+            current = await readOwnedSocketIdentity(this.socketPath, this.uid);
+        }
+        catch {
+            return this.latchOwnershipLost();
+        }
+        return current.device === ownedSocket.device &&
+            current.inode === ownedSocket.inode
+            ? OWNED_SOCKET_STATE
+            : this.latchOwnershipLost();
+    }
+    latchOwnershipLost() {
+        this.ownershipLost = true;
+        return OWNERSHIP_LOST_SOCKET_STATE;
+    }
+    async handle(socket) {
+        const frames = readFramedRecords(socket)[Symbol.asyncIterator]();
+        const challenge = supervisorClientChallengeSchema.parse(await readRequiredFrame(frames));
+        if (challenge.recordId !== this.recordId) {
+            socket.destroy();
+            return;
+        }
+        const issued = issueSupervisorChallenge(challenge, randomServerNonce(), this.capability);
+        await writeFramedRecord(socket, issued.challenge);
+        const proof = supervisorClientProofSchema.parse(await readRequiredFrame(frames));
+        const authentication = consumeClientProof(issued.state, proof, this.capability);
+        if (authentication.kind !== SUPERVISOR_AUTHENTICATION_RESULT_KIND.accepted) {
+            socket.destroy();
+            return;
+        }
+        const request = supervisorRequestSchema.parse(await readRequiredFrame(frames));
+        await writeFramedRecord(socket, await this.handler(request));
+        socket.end();
+    }
+}
+export async function requestSupervisor(input) {
+    input.signal.throwIfAborted();
+    await assertSecureSocket(input.socketPath, input.uid);
+    input.signal.throwIfAborted();
+    const connection = await connect(input.socketPath, input.signal);
+    const { socket } = connection;
+    let response;
+    try {
+        const frames = readFramedRecords(socket)[Symbol.asyncIterator]();
+        const clientChallenge = {
+            kind: SUPERVISOR_AUTHENTICATION_FRAME_KIND.clientChallenge,
+            recordId: input.recordId,
+            clientNonce: randomClientNonce(),
+        };
+        await writeFramedRecord(socket, clientChallenge);
+        const challenge = supervisorChallengeSchema.parse(await readRequiredFrame(frames));
+        if (challenge.recordId !== clientChallenge.recordId ||
+            challenge.clientNonce !== clientChallenge.clientNonce ||
+            !verifySupervisorChallenge(challenge, input.capability)) {
+            throw new Error("Supervisor socket authentication failed.");
+        }
+        await writeFramedRecord(socket, createClientProof(challenge, input.capability));
+        await writeFramedRecord(socket, input.request);
+        response = supervisorResponseSchema.parse(await readRequiredFrame(frames));
+    }
+    catch (error) {
+        input.signal.throwIfAborted();
+        throw error;
+    }
+    finally {
+        await connection.close();
+    }
+    input.signal.throwIfAborted();
+    return response;
+}
+export async function assertSecureSocket(socketPath, uid) {
+    const stat = await lstat(socketPath);
+    if (stat.isSymbolicLink() || !stat.isSocket()) {
+        throw new Error("Supervisor socket must be a real Unix socket.");
+    }
+    if (stat.uid !== uid) {
+        throw new Error("Supervisor socket owner does not match uid.");
+    }
+    if ((stat.mode & PERMISSION_BITS) !== SOCKET_MODE) {
+        throw new Error("Supervisor socket mode must be 0600.");
+    }
+}
+async function readOwnedSocketIdentity(socketPath, uid) {
+    const stat = await lstat(socketPath);
+    if (stat.isSymbolicLink() || !stat.isSocket()) {
+        throw new Error("Supervisor owned socket must be a real Unix socket.");
+    }
+    if (stat.uid !== uid) {
+        throw new Error("Supervisor owned socket owner does not match uid.");
+    }
+    return { device: stat.dev, inode: stat.ino };
+}
+async function unlinkOwnedSocket(socketPath, ownedSocket) {
+    let current;
+    try {
+        current = await lstat(socketPath);
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            return;
+        }
+        throw error;
+    }
+    if (current.dev !== ownedSocket.device || current.ino !== ownedSocket.inode) {
+        return;
+    }
+    await unlink(socketPath);
+}
+async function connect(socketPath, signal) {
+    signal.throwIfAborted();
+    const socket = createConnection(socketPath);
+    const closed = observeSocketClose(socket);
+    let controlsStopped = false;
+    const stopControls = () => {
+        if (controlsStopped) {
+            return;
+        }
+        controlsStopped = true;
+        signal.removeEventListener("abort", onAbort);
+        socket.setTimeout(0);
+        socket.off("timeout", onTimeout);
+    };
+    const onTimeout = () => {
+        stopControls();
+        socket.destroy(new Error("Supervisor socket request timed out."));
+    };
+    const onAbort = () => {
+        stopControls();
+        socket.destroy();
+    };
+    socket.setTimeout(CONNECTION_TIMEOUT_MS, onTimeout);
+    signal.addEventListener("abort", onAbort, { once: true });
+    try {
+        await waitForSocketConnect(socket);
+    }
+    catch (error) {
+        stopControls();
+        socket.destroy();
+        await closed;
+        signal.throwIfAborted();
+        throw error;
+    }
+    let closePromise = null;
+    return {
+        socket,
+        close: () => {
+            closePromise ??= (async () => {
+                stopControls();
+                socket.destroy();
+                await closed;
+            })();
+            return closePromise;
+        },
+    };
+}
+function waitForSocketConnect(socket) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            socket.off("connect", connected);
+            socket.off("error", failed);
+            socket.off("close", closed);
+        };
+        const connected = () => {
+            cleanup();
+            resolve();
+        };
+        const failed = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const closed = () => {
+            cleanup();
+            reject(new Error("Supervisor socket closed before connect."));
+        };
+        socket.once("connect", connected);
+        socket.once("error", failed);
+        socket.once("close", closed);
+    });
+}
+function observeSocketClose(socket) {
+    if (socket.closed) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+        socket.once("close", () => resolve());
+    });
+}
+async function assertSocketTargetAbsent(socketPath) {
+    try {
+        await lstat(socketPath);
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            return;
+        }
+        throw error;
+    }
+    throw new Error("Supervisor socket path already exists.");
+}
+function randomClientNonce() {
+    return supervisorClientNonceSchema.parse(randomBytes(NONCE_BYTES).toString("hex"));
+}
+function randomServerNonce() {
+    return supervisorServerNonceSchema.parse(randomBytes(NONCE_BYTES).toString("hex"));
+}
+function isErrno(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}

package/dist/internal/controlled-process/supervisor-values.d.ts

@@ -0,0 +1,39 @@
+export declare const SUPERVISOR_BOOTSTRAP_FRAME_KIND: {
+    readonly bootstrap: "bootstrap";
+    readonly hostAck: "host_ack";
+    readonly identity: "identity";
+    readonly launchFailed: "launch_failed";
+};
+export declare const SHIM_FRAME_KIND: {
+    readonly bootstrap: "shim_bootstrap";
+    readonly ack: "shim_ack";
+    readonly running: "shim_running";
+    readonly workerExit: "worker_exit";
+};
+export declare const SUPERVISOR_REQUEST_KIND: {
+    readonly probe: "probe";
+    readonly terminate: "terminate";
+    readonly release: "release";
+};
+export declare const SUPERVISOR_RESPONSE_KIND: {
+    readonly termination: "termination";
+    readonly released: "released";
+    readonly releaseBeforeAbsent: "release_before_absent";
+};
+export declare const PROCESS_PROBE_KIND: {
+    readonly alive: "alive";
+    readonly absent: "absent";
+    readonly denied: "denied";
+    readonly failed: "failed";
+};
+export declare const PROCESS_SIGNAL_RESULT_KIND: {
+    readonly sent: "sent";
+    readonly absent: "absent";
+    readonly denied: "denied";
+    readonly failed: "failed";
+};
+export declare const OUTPUT_CHANNEL_KIND: {
+    readonly stdout: "stdout";
+    readonly stderr: "stderr";
+};
+//# sourceMappingURL=supervisor-values.d.ts.map

package/dist/internal/controlled-process/supervisor-values.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-values.d.ts","sourceRoot":"","sources":["../../../src/internal/controlled-process/supervisor-values.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,+BAA+B;;;;;CAKlC,CAAC;AAEX,eAAO,MAAM,eAAe;;;;;CAKlB,CAAC;AAEX,eAAO,MAAM,uBAAuB;;;;CAI1B,CAAC;AAEX,eAAO,MAAM,wBAAwB;;;;CAI3B,CAAC;AAEX,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AAEX,eAAO,MAAM,0BAA0B;;;;;CAK7B,CAAC;AAEX,eAAO,MAAM,mBAAmB;;;CAGtB,CAAC"}

package/dist/internal/controlled-process/supervisor-values.js

@@ -0,0 +1,38 @@
+export const SUPERVISOR_BOOTSTRAP_FRAME_KIND = {
+    bootstrap: "bootstrap",
+    hostAck: "host_ack",
+    identity: "identity",
+    launchFailed: "launch_failed",
+};
+export const SHIM_FRAME_KIND = {
+    bootstrap: "shim_bootstrap",
+    ack: "shim_ack",
+    running: "shim_running",
+    workerExit: "worker_exit",
+};
+export const SUPERVISOR_REQUEST_KIND = {
+    probe: "probe",
+    terminate: "terminate",
+    release: "release",
+};
+export const SUPERVISOR_RESPONSE_KIND = {
+    termination: "termination",
+    released: "released",
+    releaseBeforeAbsent: "release_before_absent",
+};
+export const PROCESS_PROBE_KIND = {
+    alive: "alive",
+    absent: "absent",
+    denied: "denied",
+    failed: "failed",
+};
+export const PROCESS_SIGNAL_RESULT_KIND = {
+    sent: "sent",
+    absent: "absent",
+    denied: "denied",
+    failed: "failed",
+};
+export const OUTPUT_CHANNEL_KIND = {
+    stdout: "stdout",
+    stderr: "stderr",
+};

package/dist/internal/controlled-process/token.d.ts

@@ -0,0 +1,4 @@
+import type { ProcessStartToken, ProcessStartTokenFields } from "./model.js";
+export declare function encodeProcessStartToken(fields: ProcessStartTokenFields): ProcessStartToken;
+export declare function decodeProcessStartToken(value: unknown): ProcessStartTokenFields;
+//# sourceMappingURL=token.d.ts.map