@alpacakit/agents 0.1.0-beta.31 → 0.1.0-beta.36

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

@@ -2,22 +2,26 @@
 import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { CHILD_PROCESS_TERMINATION_KIND } from "../../core/controlled-process.js";
+import { CONTROLLED_PROCESS_LAUNCH_FAILURE_CODE } from "../../core/error.js";
 import { readString } from "../../core/json.js";
 import { closeWritableFd, readableFd, writableFd } from "./child-fd.js";
 import { readFramedRecords, readRequiredFrame, writeFramedRecord, } from "./framed-transport.js";
+import { ControlledProcessLaunchError, launchFailure, transferWorkerInput, } from "./input-transport.js";
 import { assertSecureRuntimeDirectory, resolveSupervisorSocketNamespace, SignedRecordStore, supervisorSocketPath, } from "./record-store.js";
 import { controlledProcessRecordIdSchema, shimProcessIdSchema, supervisorCapabilitySchema, supervisorInstanceIdSchema, supervisorSocketLocatorSchema, } from "./schema.js";
 import { SupervisorCoordinator } from "./supervisor-coordinator.js";
 import { createSupervisorPlatformAdapter } from "./supervisor-platform.js";
-import { shimRunningSchema, supervisorBootstrapSchema, supervisorHostAckSchema, workerExitSchema, } from "./supervisor-schema.js";
+import { shimLaunchFailedSchema, shimRunningSchema, supervisorBootstrapSchema, supervisorHostAckSchema, workerExitSchema, } from "./supervisor-schema.js";
 import { SupervisorSocketServer } from "./supervisor-transport.js";
 import { PROCESS_PROBE_KIND, SHIM_FRAME_KIND, SUPERVISOR_BOOTSTRAP_FRAME_KIND, SUPERVISOR_CONVERGENCE_REASON, SUPERVISOR_REQUEST_KIND, SUPERVISOR_RESPONSE_KIND, } from "./supervisor-values.js";
 import { encodeProcessStartToken } from "./token.js";
 import { CONTROLLED_PROCESS_PROTOCOL_VERSION, CONTROLLED_PROCESS_STATE, } from "./values.js";
 const HOST_BOOTSTRAP_FD = 3;
 const HOST_IDENTITY_FD = 4;
+const HOST_INPUT_FD = 5;
 const SHIM_CONTROL_FD = 3;
 const SHIM_STATUS_FD = 4;
+const SHIM_INPUT_FD = 5;
 const RANDOM_ID_BYTES = 16;
 const CAPABILITY_BYTES = 32;
 const ATTACHED_STDOUT = process.stdout;
@@ -30,6 +34,7 @@ const SUPERVISOR_RUNTIME_DEPENDENCIES = {
 };
 export async function runControlledProcessSupervisor(dependencies = SUPERVISOR_RUNTIME_DEPENDENCIES) {
     const hostInput = readableFd(HOST_BOOTSTRAP_FD);
+    const hostData = readableFd(HOST_INPUT_FD);
     const hostOutput = {
         stream: writableFd(HOST_IDENTITY_FD),
         closePromise: null,
@@ -41,6 +46,7 @@ export async function runControlledProcessSupervisor(dependencies = SUPERVISOR_R
             bootstrap,
             frames,
             hostInput,
+            hostData,
             hostOutput,
             dependencies,
         });
@@ -49,7 +55,7 @@ export async function runControlledProcessSupervisor(dependencies = SUPERVISOR_R
         if (hostOutput.closePromise === null) {
             await writeFramedRecord(hostOutput.stream, {
                 kind: SUPERVISOR_BOOTSTRAP_FRAME_KIND.launchFailed,
-                reason: error instanceof Error ? error.message : "Supervisor launch failed.",
+                failure: launchFailureFromUnknown(error),
             }).catch(() => undefined);
             await closeHostOutput(hostOutput).catch(() => undefined);
         }
@@ -57,6 +63,7 @@ export async function runControlledProcessSupervisor(dependencies = SUPERVISOR_R
     }
 }
 // biome-ignore lint/complexity/noExcessiveLinesPerFunction: The lifecycle sequence is kept contiguous because section 5.103 forbids a new runtime owner.
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: The lifecycle sequence keeps failure custody and cleanup flags in one owner.
 async function runSupervisorSession(input) {
     const platform = createSupervisorPlatformAdapter();
     const runtimeDirectory = await assertSecureRuntimeDirectory(input.bootstrap.runtimeDirectory, platform.uid);
@@ -72,6 +79,7 @@ async function runSupervisorSession(input) {
     let shimPid = null;
     let shimControl = null;
     let shimStatus = null;
+    let shimInput = null;
     let shimClosed = null;
     let lifecycleMonitor = null;
     let lifecycleMonitorInFlight = null;
@@ -80,7 +88,8 @@ async function runSupervisorSession(input) {
     let initialPersistCommitted = false;
     let initialPersistReceipt = null;
     let identityDelivered = false;
-    let ready = false;
+    let workerReady = false;
+    let hostCustodyStarted = false;
     let rollbackAttempted = false;
     let ownershipLossObserved = false;
     let ownershipLossPromise = null;
@@ -133,7 +142,7 @@ async function runSupervisorSession(input) {
             stopLifecycleMonitor();
             input.hostInput.destroy();
             await beforeOwnershipLossDeadline(Promise.all([
-                settleOwnershipLossHostOutput(input.hostOutput, convergenceDescription(reason, identityDelivered)),
+                settleOwnershipLossHostOutput(input.hostOutput, reason, convergenceDescription(reason, identityDelivered)),
                 server.settleAcceptedSessions(),
             ]).then(() => undefined), deadline, "Supervisor ownership-loss host output or session drain timed out.");
             const persistReceipt = initialPersistReceipt;
@@ -196,7 +205,7 @@ async function runSupervisorSession(input) {
                 void startOwnershipLossConvergence(SUPERVISOR_CONVERGENCE_REASON.socketOwnershipLost);
                 return;
             }
-            if (ready &&
+            if (hostCustodyStarted &&
                 hostIdleDeadline !== null &&
                 Date.now() >= hostIdleDeadline) {
                 void startOwnershipLossConvergence(SUPERVISOR_CONVERGENCE_REASON.hostIdleTimeout);
@@ -228,6 +237,8 @@ async function runSupervisorSession(input) {
         shimClosed = waitForShimClose(shim);
         shimControl = shim.stdio[SHIM_CONTROL_FD];
         shimStatus = shim.stdio[SHIM_STATUS_FD];
+        shimInput = shim.stdio.at(SHIM_INPUT_FD);
+        shimInput.on("error", () => { });
         const pid = requireShimPid(shim);
         shimPid = pid;
         const record = {
@@ -281,7 +292,19 @@ async function runSupervisorSession(input) {
             return response;
         };
         trackLocalCoordinatorOperation(attachOutput(shim, runLocalCoordinatorOperation));
-        trackLocalCoordinatorOperation(pumpShimStatus(shimStatus, runLocalCoordinatorOperation).catch(() => runLocalCoordinatorOperation(async (current) => current.recordProtocolFailure())));
+        let resolveShimReady = () => { };
+        let rejectShimReady = (_error) => { };
+        const shimReady = new Promise((resolve, reject) => {
+            resolveShimReady = resolve;
+            rejectShimReady = reject;
+        });
+        void shimReady.catch(() => undefined);
+        trackLocalCoordinatorOperation(pumpShimStatus(shimStatus, runLocalCoordinatorOperation, resolveShimReady).catch(async (error) => {
+            rejectShimReady(error);
+            if (!(error instanceof ControlledProcessLaunchError)) {
+                await runLocalCoordinatorOperation(async (current) => current.recordProtocolFailure());
+            }
+        }));
         shim.once("exit", () => {
             trackLocalCoordinatorOperation(runLocalCoordinatorOperation(async (current) => current.recordShimExit()));
         });
@@ -291,7 +314,17 @@ async function runSupervisorSession(input) {
         await writeFramedRecord(shimControl, {
             kind: SHIM_FRAME_KIND.bootstrap,
             worker: input.bootstrap.worker,
+            input: input.bootstrap.input,
+            inputTimeoutMs: input.bootstrap.timing.hostIdleTimeoutMs,
+        });
+        const inputRelay = transferWorkerInput({
+            readable: input.hostData,
+            writable: shimInput,
+            manifest: input.bootstrap.input,
+            stage: "supervisor_to_shim",
+            timeoutMs: input.bootstrap.timing.hostIdleTimeoutMs,
         });
+        void inputRelay.catch(() => undefined);
         await observeOwnership(true);
         const persistOperation = (input.dependencies.persistInitialRecord ??
             SUPERVISOR_RUNTIME_DEPENDENCIES.persistInitialRecord)(activeCoordinator);
@@ -336,10 +369,18 @@ async function runSupervisorSession(input) {
         await runCoordinatorOperation(async (current) => current.acknowledge());
         coordinatorAckMayHaveCommitted = true;
         await input.dependencies.writeShimAck(shimControl);
+        const [inputRelaySettlement, shimReadySettlement] = await Promise.allSettled([inputRelay, shimReady]);
+        if (shimReadySettlement.status === "rejected") {
+            throw shimReadySettlement.reason;
+        }
+        if (inputRelaySettlement.status === "rejected") {
+            throw inputRelaySettlement.reason;
+        }
         await observeOwnership(false);
         coordinatorTickEnabled = true;
-        ready = true;
-        recordHostActivity({ kind: "ready" });
+        workerReady = true;
+        hostCustodyStarted = true;
+        recordHostActivity({ kind: "custody_started" });
         await closeHostOutput(input.hostOutput);
         input.hostInput.destroy();
         await released;
@@ -354,17 +395,50 @@ async function runSupervisorSession(input) {
         }
         shimControl.destroy();
         shimStatus.destroy();
+        shimInput.destroy();
     }
     catch (primaryFailure) {
         await observeOwnership(false).catch(() => undefined);
         if (ownershipLossPromise !== null) {
             await ownershipLossPromise;
         }
-        if (ready || rollbackAttempted) {
+        if (workerReady || rollbackAttempted) {
             stopLifecycleMonitor();
             await settleLifecycleMonitor().catch(() => undefined);
             throw primaryFailure;
         }
+        if (primaryFailure instanceof ControlledProcessLaunchError &&
+            identityDelivered &&
+            coordinator !== null &&
+            shimControl !== null &&
+            shimStatus !== null &&
+            shimClosed !== null &&
+            input.hostOutput.closePromise === null) {
+            input.hostData.destroy();
+            hostCustodyStarted = true;
+            recordHostActivity({ kind: "custody_started" });
+            const failureReported = await writeStructuredLaunchFailure(input.hostOutput, launchFailureFromUnknown(primaryFailure)).then(() => true, () => false);
+            if (!failureReported && ownershipLossPromise !== null) {
+                await ownershipLossPromise;
+            }
+            if (failureReported) {
+                await released;
+                await shimClosed;
+                await settleLocalCoordinatorOperations();
+                stopLifecycleMonitor();
+                await settleLifecycleMonitor();
+                const finalization = await (input.dependencies.finalizeSupervisorSocket ??
+                    SUPERVISOR_RUNTIME_DEPENDENCIES.finalizeSupervisorSocket)(server);
+                if (finalization.kind === "ownership_lost") {
+                    await startOwnershipLossConvergence(SUPERVISOR_CONVERGENCE_REASON.socketOwnershipLost);
+                }
+                shimControl.destroy();
+                shimStatus.destroy();
+                shimInput?.destroy();
+                input.hostInput.destroy();
+                return;
+            }
+        }
         try {
             rollbackAttempted = true;
             if (coordinator !== null &&
@@ -410,6 +484,7 @@ async function runSupervisorSession(input) {
         }
         finally {
             input.hostInput.destroy();
+            input.hostData.destroy();
         }
         throw primaryFailure;
     }
@@ -518,16 +593,20 @@ async function convergeAfterOwnershipLoss(input) {
     await beforeOwnershipLossDeadline(input.settleLifecycleMonitor(), input.deadline, "Supervisor ownership-loss lifecycle monitor did not settle.");
     return selfSigkill();
 }
-function settleOwnershipLossHostOutput(hostOutput, reason) {
+function settleOwnershipLossHostOutput(hostOutput, reason, description) {
+    if (reason === SUPERVISOR_CONVERGENCE_REASON.hostIdleTimeout) {
+        hostOutput.stream.destroy();
+        return waitForWritableFinish(hostOutput.stream);
+    }
     return hostOutput.closePromise === null
-        ? writeLaunchFailure(hostOutput, reason)
+        ? writeLaunchFailure(hostOutput, description)
         : hostOutput.closePromise;
 }
 function isHostActivityEvidence(input) {
     if (input.convergenceStarted) {
         return false;
     }
-    if (input.activity.kind === "ready") {
+    if (input.activity.kind === "custody_started") {
         return true;
     }
     const beforeDeadline = input.hostIdleDeadline === null || input.now < input.hostIdleDeadline;
@@ -620,7 +699,7 @@ function spawnShim(bootstrap) {
     const shim = spawn(process.execPath, [bootstrap.shimEntryPath], {
         detached: true,
         env: {},
-        stdio: ["ignore", "pipe", "pipe", "pipe", "pipe"],
+        stdio: ["ignore", "pipe", "pipe", "pipe", "pipe", "pipe"],
     });
     shim.once("error", () => { });
     return shim;
@@ -653,12 +732,19 @@ function attachOutput(shim, runCoordinatorOperation) {
         pumpOutput(stderr, ATTACHED_STDERR),
     ]).then(async () => runCoordinatorOperation(async (coordinator) => coordinator.recordOutputClosed()), async () => runCoordinatorOperation(async (coordinator) => coordinator.recordProtocolFailure()));
 }
-async function pumpShimStatus(status, runCoordinatorOperation) {
+async function pumpShimStatus(status, runCoordinatorOperation, onRunning) {
+    let running = false;
     for await (const frame of readFramedRecords(status)) {
         const kind = readString(frame, "kind");
         if (kind === SHIM_FRAME_KIND.running) {
             shimRunningSchema.parse(frame);
             await runCoordinatorOperation(async (coordinator) => coordinator.running());
+            running = true;
+            onRunning();
+        }
+        else if (kind === SHIM_FRAME_KIND.launchFailed) {
+            const failure = shimLaunchFailedSchema.parse(frame);
+            throw new ControlledProcessLaunchError(failure.failure);
         }
         else if (kind === SHIM_FRAME_KIND.workerExit) {
             const workerExit = workerExitSchema.parse(frame);
@@ -671,6 +757,9 @@ async function pumpShimStatus(status, runCoordinatorOperation) {
             throw new Error("Shim status frame is invalid.");
         }
     }
+    if (!running) {
+        throw launchFailure(CONTROLLED_PROCESS_LAUNCH_FAILURE_CODE.protocolViolation, "control_protocol", null, null, "Shim status closed before reporting running.");
+    }
 }
 async function handleRequest(coordinator, kind) {
     if (kind === SUPERVISOR_REQUEST_KIND.probe) {
@@ -815,10 +904,22 @@ function requireCapturedCoordinator(coordinator) {
 async function writeLaunchFailure(hostOutput, reason) {
     await writeFramedRecord(hostOutput.stream, {
         kind: SUPERVISOR_BOOTSTRAP_FRAME_KIND.launchFailed,
-        reason,
+        failure: launchFailure(CONTROLLED_PROCESS_LAUNCH_FAILURE_CODE.protocolViolation, "control_protocol", null, null, reason).failure,
     });
     await closeHostOutput(hostOutput);
 }
+async function writeStructuredLaunchFailure(hostOutput, failure) {
+    await writeFramedRecord(hostOutput.stream, {
+        kind: SUPERVISOR_BOOTSTRAP_FRAME_KIND.launchFailed,
+        failure,
+    });
+    await closeHostOutput(hostOutput);
+}
+function launchFailureFromUnknown(error) {
+    return error instanceof ControlledProcessLaunchError
+        ? error.failure
+        : launchFailure(CONTROLLED_PROCESS_LAUNCH_FAILURE_CODE.protocolViolation, "control_protocol", null, null, error instanceof Error ? error.message : "Supervisor launch failed.", error).failure;
+}
 function closeHostOutput(hostOutput) {
     hostOutput.closePromise ??= closeWritableFd(hostOutput.stream, HOST_IDENTITY_FD);
     return hostOutput.closePromise;

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

@@ -8,8 +8,14 @@ export declare const supervisorBootstrapSchema: z.ZodReadonly<z.ZodObject<{
         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>>;
+    input: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+        kind: z.ZodLiteral<"none">;
+    }, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
+        kind: z.ZodLiteral<"stream">;
+        byteLength: z.ZodNumber;
+        sha256: z.ZodString;
+    }, z.core.$strip>>], "kind">;
     timing: z.ZodReadonly<z.ZodObject<{
         termGraceMs: z.ZodNumber;
         killProbeTimeoutMs: z.ZodNumber;
@@ -29,7 +35,30 @@ export declare const supervisorIdentityFrameSchema: z.ZodReadonly<z.ZodObject<{
 }, z.core.$strip>>;
 export declare const supervisorLaunchFailedFrameSchema: z.ZodReadonly<z.ZodObject<{
     kind: z.ZodLiteral<"launch_failed">;
-    reason: z.ZodString;
+    failure: z.ZodReadonly<z.ZodObject<{
+        code: z.ZodEnum<{
+            readonly inputEarlyEof: "input_early_eof";
+            readonly inputOverrun: "input_overrun";
+            readonly inputDigestMismatch: "input_digest_mismatch";
+            readonly inputWriteFailed: "input_write_failed";
+            readonly inputTransferTimeout: "input_transfer_timeout";
+            readonly workerExited: "worker_exited_during_launch";
+            readonly protocolViolation: "protocol_violation";
+        }>;
+        retryability: z.ZodEnum<{
+            readonly permanent: "permanent";
+            readonly transient: "transient";
+        }>;
+        stage: z.ZodEnum<{
+            host_to_supervisor: "host_to_supervisor";
+            supervisor_to_shim: "supervisor_to_shim";
+            shim_to_worker: "shim_to_worker";
+            control_protocol: "control_protocol";
+        }>;
+        expectedBytes: z.ZodNullable<z.ZodNumber>;
+        actualBytes: z.ZodNullable<z.ZodNumber>;
+        message: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>>;
 export declare const shimBootstrapSchema: z.ZodReadonly<z.ZodObject<{
     kind: z.ZodLiteral<"shim_bootstrap">;
@@ -38,8 +67,15 @@ export declare const shimBootstrapSchema: z.ZodReadonly<z.ZodObject<{
         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>>;
+    input: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+        kind: z.ZodLiteral<"none">;
+    }, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
+        kind: z.ZodLiteral<"stream">;
+        byteLength: z.ZodNumber;
+        sha256: z.ZodString;
+    }, z.core.$strip>>], "kind">;
+    inputTimeoutMs: z.ZodNumber;
 }, z.core.$strip>>;
 export declare const shimAckSchema: z.ZodReadonly<z.ZodObject<{
     kind: z.ZodLiteral<"shim_ack">;
@@ -47,6 +83,33 @@ export declare const shimAckSchema: z.ZodReadonly<z.ZodObject<{
 export declare const shimRunningSchema: z.ZodReadonly<z.ZodObject<{
     kind: z.ZodLiteral<"shim_running">;
 }, z.core.$strip>>;
+export declare const shimLaunchFailedSchema: z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"shim_launch_failed">;
+    failure: z.ZodReadonly<z.ZodObject<{
+        code: z.ZodEnum<{
+            readonly inputEarlyEof: "input_early_eof";
+            readonly inputOverrun: "input_overrun";
+            readonly inputDigestMismatch: "input_digest_mismatch";
+            readonly inputWriteFailed: "input_write_failed";
+            readonly inputTransferTimeout: "input_transfer_timeout";
+            readonly workerExited: "worker_exited_during_launch";
+            readonly protocolViolation: "protocol_violation";
+        }>;
+        retryability: z.ZodEnum<{
+            readonly permanent: "permanent";
+            readonly transient: "transient";
+        }>;
+        stage: z.ZodEnum<{
+            host_to_supervisor: "host_to_supervisor";
+            supervisor_to_shim: "supervisor_to_shim";
+            shim_to_worker: "shim_to_worker";
+            control_protocol: "control_protocol";
+        }>;
+        expectedBytes: z.ZodNullable<z.ZodNumber>;
+        actualBytes: z.ZodNullable<z.ZodNumber>;
+        message: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
 export declare const workerExitSchema: z.ZodReadonly<z.ZodObject<{
     kind: z.ZodLiteral<"worker_exit">;
     code: z.ZodNullable<z.ZodNumber>;

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

@@ -1 +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;AAoDxB,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"}
+{"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;AA8ExB,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;kBAOK,CAAC;AAE5C,eAAO,MAAM,uBAAuB;;kBAEK,CAAC;AAE1C,eAAO,MAAM,6BAA6B;;;;;;kBAGK,CAAC;AAEhD,eAAO,MAAM,iCAAiC;;;;;;;;;;;;;;;;;;;;;;;;;;kBAGK,CAAC;AAEpD,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;kBAKK,CAAC;AAEtC,eAAO,MAAM,aAAa;;kBAEK,CAAC;AAEhC,eAAO,MAAM,iBAAiB;;kBAEK,CAAC;AAEpC,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;kBAGK,CAAC;AAEzC,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

@@ -1,7 +1,8 @@
 import { strictReadonlyObject } from "@alpacakit/core";
 import { z } from "zod";
+import { CONTROLLED_PROCESS_LAUNCH_FAILURE_CODE, CONTROLLED_PROCESS_LAUNCH_FAILURE_RETRYABILITY, } from "../../core/error.js";
 import { childProcessTerminationResultSchema, controlledProcessIdentitySchema, } from "./schema.js";
-import { SHIM_FRAME_KIND, SUPERVISOR_BOOTSTRAP_FRAME_KIND, SUPERVISOR_REQUEST_KIND, SUPERVISOR_RESPONSE_KIND, } from "./supervisor-values.js";
+import { SHIM_FRAME_KIND, SUPERVISOR_BOOTSTRAP_FRAME_KIND, SUPERVISOR_REQUEST_KIND, SUPERVISOR_RESPONSE_KIND, WORKER_INPUT_KIND, } from "./supervisor-values.js";
 const nonBlankStringSchema = z
     .string()
     .min(1)
@@ -12,7 +13,27 @@ const workerOptionsSchema = strictReadonlyObject({
     args: z.array(z.string()).readonly(),
     cwd: nonBlankStringSchema,
     env: z.record(z.string(), z.string()).readonly(),
-    stdin: z.string().nullable(),
+});
+const workerInputManifestSchema = z.discriminatedUnion("kind", [
+    strictReadonlyObject({ kind: z.literal(WORKER_INPUT_KIND.none) }),
+    strictReadonlyObject({
+        kind: z.literal(WORKER_INPUT_KIND.stream),
+        byteLength: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/u),
+    }),
+]);
+const launchFailureSchema = strictReadonlyObject({
+    code: z.enum(CONTROLLED_PROCESS_LAUNCH_FAILURE_CODE),
+    retryability: z.enum(CONTROLLED_PROCESS_LAUNCH_FAILURE_RETRYABILITY),
+    stage: z.enum([
+        "host_to_supervisor",
+        "supervisor_to_shim",
+        "shim_to_worker",
+        "control_protocol",
+    ]),
+    expectedBytes: z.number().int().nonnegative().nullable(),
+    actualBytes: z.number().int().nonnegative().nullable(),
+    message: nonBlankStringSchema,
 });
 // A worker that is still running is re-probed every `probeIntervalMs`, and an
 // accepted request is the only thing that resets the idle deadline. An idle
@@ -33,6 +54,7 @@ export const supervisorBootstrapSchema = strictReadonlyObject({
     runtimeDirectory: nonBlankStringSchema,
     shimEntryPath: nonBlankStringSchema,
     worker: workerOptionsSchema,
+    input: workerInputManifestSchema,
     timing: timingOptionsSchema,
 });
 export const supervisorHostAckSchema = strictReadonlyObject({
@@ -44,11 +66,13 @@ export const supervisorIdentityFrameSchema = strictReadonlyObject({
 });
 export const supervisorLaunchFailedFrameSchema = strictReadonlyObject({
     kind: z.literal(SUPERVISOR_BOOTSTRAP_FRAME_KIND.launchFailed),
-    reason: z.string().min(1),
+    failure: launchFailureSchema,
 });
 export const shimBootstrapSchema = strictReadonlyObject({
     kind: z.literal(SHIM_FRAME_KIND.bootstrap),
     worker: workerOptionsSchema,
+    input: workerInputManifestSchema,
+    inputTimeoutMs: durationSchema,
 });
 export const shimAckSchema = strictReadonlyObject({
     kind: z.literal(SHIM_FRAME_KIND.ack),
@@ -56,6 +80,10 @@ export const shimAckSchema = strictReadonlyObject({
 export const shimRunningSchema = strictReadonlyObject({
     kind: z.literal(SHIM_FRAME_KIND.running),
 });
+export const shimLaunchFailedSchema = strictReadonlyObject({
+    kind: z.literal(SHIM_FRAME_KIND.launchFailed),
+    failure: launchFailureSchema,
+});
 export const workerExitSchema = strictReadonlyObject({
     kind: z.literal(SHIM_FRAME_KIND.workerExit),
     code: z.number().int().nullable(),

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

@@ -8,8 +8,13 @@ export declare const SHIM_FRAME_KIND: {
     readonly bootstrap: "shim_bootstrap";
     readonly ack: "shim_ack";
     readonly running: "shim_running";
+    readonly launchFailed: "shim_launch_failed";
     readonly workerExit: "worker_exit";
 };
+export declare const WORKER_INPUT_KIND: {
+    readonly none: "none";
+    readonly stream: "stream";
+};
 export declare const SUPERVISOR_REQUEST_KIND: {
     readonly probe: "probe";
     readonly terminate: "terminate";

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

@@ -1 +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,6BAA6B;;;CAGhC,CAAC;AAEX,eAAO,MAAM,mBAAmB;;;CAGtB,CAAC"}
+{"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;;;;;;CAMlB,CAAC;AAEX,eAAO,MAAM,iBAAiB;;;CAGpB,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,6BAA6B;;;CAGhC,CAAC;AAEX,eAAO,MAAM,mBAAmB;;;CAGtB,CAAC"}

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

@@ -8,8 +8,13 @@ export const SHIM_FRAME_KIND = {
     bootstrap: "shim_bootstrap",
     ack: "shim_ack",
     running: "shim_running",
+    launchFailed: "shim_launch_failed",
     workerExit: "worker_exit",
 };
+export const WORKER_INPUT_KIND = {
+    none: "none",
+    stream: "stream",
+};
 export const SUPERVISOR_REQUEST_KIND = {
     probe: "probe",
     terminate: "terminate",

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

@@ -1,4 +1,4 @@
-export declare const CONTROLLED_PROCESS_PROTOCOL_VERSION: "alpacakit-supervisor-v1";
+export declare const CONTROLLED_PROCESS_PROTOCOL_VERSION: "alpacakit-supervisor-v2";
 export declare const CONTROLLED_PROCESS_PLATFORM: {
     readonly darwin: "darwin";
     readonly linux: "linux";
@@ -32,8 +32,8 @@ export declare const SUPERVISOR_AUTHENTICATION_REJECTION_REASON: {
     readonly replay: "replay";
 };
 export declare const SUPERVISOR_MAC_DOMAIN: {
-    readonly record: "alpacakit-supervisor-v1/record/v1";
-    readonly supervisorChallenge: "alpacakit-supervisor-v1/auth/supervisor/v1";
-    readonly clientProof: "alpacakit-supervisor-v1/auth/client/v1";
+    readonly record: "alpacakit-supervisor-v2/record/v1";
+    readonly supervisorChallenge: "alpacakit-supervisor-v2/auth/supervisor/v1";
+    readonly clientProof: "alpacakit-supervisor-v2/auth/client/v1";
 };
 //# sourceMappingURL=values.d.ts.map

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

@@ -1,4 +1,4 @@
-export const CONTROLLED_PROCESS_PROTOCOL_VERSION = "alpacakit-supervisor-v1";
+export const CONTROLLED_PROCESS_PROTOCOL_VERSION = "alpacakit-supervisor-v2";
 export const CONTROLLED_PROCESS_PLATFORM = {
     darwin: "darwin",
     linux: "linux",
@@ -32,7 +32,7 @@ export const SUPERVISOR_AUTHENTICATION_REJECTION_REASON = {
     replay: "replay",
 };
 export const SUPERVISOR_MAC_DOMAIN = {
-    record: "alpacakit-supervisor-v1/record/v1",
-    supervisorChallenge: "alpacakit-supervisor-v1/auth/supervisor/v1",
-    clientProof: "alpacakit-supervisor-v1/auth/client/v1",
+    record: "alpacakit-supervisor-v2/record/v1",
+    supervisorChallenge: "alpacakit-supervisor-v2/auth/supervisor/v1",
+    clientProof: "alpacakit-supervisor-v2/auth/client/v1",
 };

package/dist/kernel/cli-agent.d.ts

@@ -9,6 +9,7 @@
 import type { LoginCapability } from "../auth/login.js";
 import type { MaterialHandlers } from "../auth/material.js";
 import type { AgentEvent, RunUsage } from "../core/run.js";
+import { type AgentAvailabilityCapability, type AgentRemediation } from "../host/availability.js";
 import type { DoctorCapability, McpCapability, SkillsCapability } from "../host/capabilities.js";
 import { type FailureMatcher } from "./classify.js";
 import type { AgentDefinition } from "./definition.js";
@@ -52,6 +53,8 @@ export type CliAgentBlueprint<Id extends string = string> = {
      * output would misclassify runs that merely talk about limits.
      */
     readonly classifyOnSuccess?: readonly FailureMatcher[];
+    readonly availability?: AgentAvailabilityCapability;
+    readonly commandMissingRemediation?: AgentRemediation | null;
     readonly auth?: MaterialHandlers;
     readonly login?: LoginCapability;
     readonly doctor?: DoctorCapability;

package/dist/kernel/cli-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-agent.d.ts","sourceRoot":"","sources":["../../src/kernel/cli-agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli-agent.d.ts","sourceRoot":"","sources":["../../src/kernel/cli-agent.ts"],"names":[],"mappings":"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"}

package/dist/kernel/cli-agent.js

@@ -11,7 +11,8 @@ import { AGENT_ERROR_CODE, AGENT_INFRASTRUCTURE_FAILURE_CODE, AgentError, infras
 import { redactSecrets } from "../core/redact.js";
 import { AGENT_EVENT_TYPE, RUN_COMPLETION_KIND } from "../core/run.js";
 import { OUTPUT_CHANNEL, PROCESS_SIGNAL, } from "../core/values.js";
-import { DOCTOR_CHECK_STATUS } from "../host/capabilities.js";
+import { cliAvailability, } from "../host/availability.js";
+import { cliCommandDoctor } from "../host/command-doctor.js";
 import { classifyFailure, sharedFailureMatchers, } from "./classify.js";
 import { requireKeyedHandler } from "./keyed.js";
 const SIGKILL_ESCALATION_MS = 5_000;
@@ -538,27 +539,15 @@ export function defineCliAgent(blueprint) {
         detectCompletion: blueprint.detectCompletion?.bind(blueprint) ?? (() => false),
     };
     const matchers = [...(blueprint.classify ?? []), ...sharedFailureMatchers];
-    const doctor = blueprint.doctor ??
-        {
-            probe: async (ctx) => {
-                const command = await ctx.exec.which(blueprint.command, ctx.env);
-                return {
-                    available: command !== null,
-                    checks: [
-                        {
-                            id: "command-on-path",
-                            status: command === null
-                                ? DOCTOR_CHECK_STATUS.fail
-                                : DOCTOR_CHECK_STATUS.pass,
-                            detail: command,
-                        },
-                    ],
-                };
-            },
-        };
+    const doctor = blueprint.doctor ?? cliCommandDoctor(blueprint.command);
     const definition = {
         id: blueprint.id,
         run: buildRun(blueprint, hooks, matchers, blueprint.classifyOnSuccess ?? []),
+        availability: blueprint.availability ??
+            cliAvailability({
+                command: blueprint.command,
+                commandMissingRemediation: blueprint.commandMissingRemediation ?? null,
+            }),
         doctor,
     };
     if (blueprint.auth !== undefined) {

package/dist/kernel/definition.d.ts

@@ -8,6 +8,7 @@ import type { LoginCapability } from "../auth/login.js";
 import type { AuthCapability } from "../auth/material.js";
 import type { Clock, Exec, HttpClient, Logger } from "../core/ports.js";
 import type { AgentEvent, AgentRunOutcome } from "../core/run.js";
+import type { AgentAvailabilityCapability } from "../host/availability.js";
 import type { DoctorCapability, McpCapability, SkillsCapability } from "../host/capabilities.js";
 import type { ResolvedRunOptions } from "./options.js";
 /** Resolved (rule 2): the adapter's whole world. */
@@ -27,6 +28,7 @@ export type AgentRun = AsyncGenerator<AgentEvent, AgentRunOutcome, void>;
 export interface AgentDefinition<Id extends string = string> {
     id: Id;
     run(options: ResolvedRunOptions, ctx: RunContext): AgentRun;
+    availability?: AgentAvailabilityCapability;
     auth?: AuthCapability;
     login?: LoginCapability;
     doctor?: DoctorCapability;