@inflexa-ai/harness 0.46.2 → 0.48.0

package/dist/sandbox/identity.js

@@ -1,27 +1,11 @@
 /**
- * Sandbox identity minting — the durable half of the two-step create (ADR
- * 0016). Backend-agnostic: the `sandboxId` is minted here, checkpointed by the
- * `sandbox.mint` DBOS step, then handed to the backend's spawn step. Because the
- * identity is durable before any machine exists, a crash between spawn and the
- * spawn-step checkpoint is recoverable — the re-run adopts the existing machine
- * under the same name.
+ * The name of a sandbox machine. It comes from a key: the id of the lease workflow and the machine generation. Thus
+ * a rerun of the spawn step adopts the machine of the earlier attempt, and no step checkpoints a name before a spawn.
  */
-import { createHash, randomUUID } from "node:crypto";
-/** `sbx-{run8}-{rand8}` — run prefix aids `kubectl` triage; the 8-hex random
- *  suffix makes within-run collisions across a run's concurrent steps
- *  negligible. Names are NOT the idempotency mechanism (the checkpoint is), and
- *  adoption is owner-label-guarded, but a unique name keeps a collision from
- *  ever reaching that guard. */
-export function mintSandboxIdentity(runId) {
-    const run8 = runId.replaceAll("-", "").slice(0, 8);
-    const suffix = randomUUID().replaceAll("-", "").slice(0, 8);
-    return { sandboxId: `sbx-${run8}-${suffix}` };
-}
+import { createHash } from "node:crypto";
 /**
- * `sbx-{run8}-{hash12}` — the name of a sandbox whose identity comes from a
- * key, not from a checkpoint. The same key gives the same name, thus a rerun
- * of a step adopts the machine of the earlier attempt. The key is hashed,
- * because a workflow id can hold characters that a container name refuses.
+ * `sbx-{run8}-{hash12}`. The run prefix aids `kubectl` triage. The same key gives the same name, and the key is
+ * hashed, because a workflow id can hold characters that a container name refuses.
  */
 export function keyedSandboxIdentity(runId, key) {
     const run8 = runId.replaceAll("-", "").slice(0, 8);

package/dist/sandbox/k8s-client.d.ts

@@ -105,7 +105,6 @@ export type K8sClientConfig = {
     /** Injected for tests. */
     batchApi?: BatchJobApi;
     coreApi?: CorePodApi;
-    registerSandbox: (session: SpawnSession, spec: SandboxSpec, ref: SandboxRef) => Promise<void>;
 };
 /** Clock and sleep seams, so a test can drive the slow-pod warning without waiting a minute. */
 export type WaitForPodReadyDeps = {

package/dist/sandbox/k8s-client.js

@@ -171,6 +171,12 @@ async function buildJobSpec(session, sandboxSpec, hostLabels, config, identity,
                 readOnly: false,
             });
         }
+        volumeMounts.push({
+            name: SESSION_VOLUME_NAME,
+            mountPath: plan.recordsPath,
+            subPath: subPaths.records,
+            readOnly: false,
+        });
     }
     if (config.libStorePvc && plan.libsPath) {
         const cacheSubPath = farm?.cachePath !== undefined && plan.cachePath ? pvcSubPath(farm.cachePath, "the farm cache") : undefined;
@@ -263,7 +269,7 @@ async function buildJobSpec(session, sandboxSpec, hostLabels, config, identity,
             name: sandboxId,
             namespace: config.namespace,
             annotations: {
-                [OWNER_WORKFLOW_ANNOTATION]: sandboxSpec.childWorkflowId,
+                [OWNER_WORKFLOW_ANNOTATION]: sandboxSpec.ownerWorkflowId,
             },
             labels,
         },
@@ -493,7 +499,7 @@ export function createK8sSandboxOps(config) {
                     }
                 }
                 const job = await buildJobSpec(session, spec, hostLabels, config, identity, farm, libsMounted);
-                const adopted = await createOrAdoptJob(batchApi, coreApi, config.namespace, sandboxId, spec.childWorkflowId, job);
+                const adopted = await createOrAdoptJob(batchApi, coreApi, config.namespace, sandboxId, spec.ownerWorkflowId, job);
                 if (adopted.isErr())
                     return err(adopted.error);
                 // A Job whose pod never schedules (quota rejection, no nodes, spot
@@ -510,17 +516,6 @@ export function createK8sSandboxOps(config) {
                         port: SANDBOX_SERVER_PORT,
                         backend: "k8s",
                     };
-                    const registered = await trySandbox(() => config.registerSandbox(session, spec, ref), (status, cause) => ({
-                        type: "container_create_failed",
-                        op: "k8s.registerSandbox",
-                        sandboxId,
-                        status,
-                        cause,
-                    }));
-                    if (registered.isErr()) {
-                        await cleanupFailedJob(batchApi, config.namespace, sandboxId, config.logger ?? createNoopLogger());
-                        return err(registered.error);
-                    }
                     return ok(ref);
                 }
                 await cleanupFailedJob(batchApi, config.namespace, sandboxId, config.logger ?? createNoopLogger());

package/dist/sandbox/lease-names.d.ts

@@ -0,0 +1,6 @@
+/** The names that the lease module, the reconciler, and the purge share. */
+/** The prefix of each lease workflow id. A purge finds the lease workflows of an analysis by it. */
+export declare const LEASE_WORKFLOW_PREFIX = "sandboxlease";
+export declare function leaseWorkflowIdOf(analysisId: string, leaseKey: string, generation: number): string;
+/** The workspace-relative records directory of a lease key. Each generation of the key uses it. */
+export declare function leaseRecordTail(leaseKey: string): string;

package/dist/sandbox/lease-names.js

@@ -0,0 +1,12 @@
+/** The names that the lease module, the reconciler, and the purge share. */
+import { createHash } from "node:crypto";
+import { HARNESS_PRIVATE_DIR } from "../workspace/paths.js";
+/** The prefix of each lease workflow id. A purge finds the lease workflows of an analysis by it. */
+export const LEASE_WORKFLOW_PREFIX = "sandboxlease";
+export function leaseWorkflowIdOf(analysisId, leaseKey, generation) {
+    return `${LEASE_WORKFLOW_PREFIX}:${analysisId}:${leaseKey}:${generation}`;
+}
+/** The workspace-relative records directory of a lease key. Each generation of the key uses it. */
+export function leaseRecordTail(leaseKey) {
+    return `${HARNESS_PRIVATE_DIR}/exec-records/${createHash("sha256").update(leaseKey, "utf8").digest("hex").slice(0, 16)}`;
+}

package/dist/sandbox/leases.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The sandbox module (sandbox-leases spec). A consumer holds a sandbox through a lease, and the module owns each
+ * machine: the admission, the spawn, the replacement, the idle removal, and the teardown.
+ *
+ * Each generation of a lease has one lease workflow. A consumer enqueues it through a `DBOSClient`, thus the lease
+ * workflow is not a child of the consumer: a cancel, a pause, or a crash of the consumer does not stop it, and its
+ * teardown step can always run. The consumer waits for the events of the lease workflow with the same client,
+ * because DBOS refuses `recv` and `getEvent` inside a step, and each tool call is a step.
+ *
+ * A machine of a lease is replaceable. The state of a lease is its files, the exec records in its records
+ * directory, and the checkpoints of its consumer. Thus the module removes the machine of an idle lease, and the
+ * next exec gets a new one.
+ */
+import { type DBOSClient } from "@dbos-inc/dbos-sdk";
+import { type Result } from "neverthrow";
+import type { SpawnSession } from "../auth/types.js";
+import { type ResourcePolicy, type ResourceSpec } from "../config/resource-limits.js";
+import type { PausePart, WorkKind } from "../contracts/chat-parts.js";
+import type { RunAuthorizer } from "../execution/run-authorizer.js";
+import type { Connectable } from "../lib/db-result.js";
+import type { Logger } from "../lib/logger.js";
+import type { Querier } from "../state/db.js";
+import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
+import type { SandboxClient } from "./client.js";
+import type { ExecEmit, ExecRequest, ExecResult, ToolchainSource } from "./types.js";
+export declare const LEASE_WORKFLOW = "sandbox-lease";
+export declare const LEASE_QUEUE = "sandbox-leases";
+export declare const DEFAULT_IDLE_PERIOD_MS: number;
+/** The timeout of a command that gives none. A step has no deadline of its own, thus each command has one. */
+export declare const DEFAULT_COMMAND_TIMEOUT_SECONDS = 3600;
+/** The spawn settings of a consumer, beside the size. */
+export type LeaseSpawnSpec = {
+    readonly image?: string;
+    readonly extraEnv?: Readonly<Record<string, string>>;
+    readonly readOnly?: boolean;
+    readonly writableTail?: string;
+};
+/** Who holds a lease, and where its pause and its parts go. */
+export type LeaseBinding = {
+    /** The key of the lease. A tool gives the id of its workflow. */
+    readonly leaseKey: string;
+    /** The spawn session of a run step or of a data profile. It goes into the input of the lease workflow. */
+    readonly session: SpawnSession;
+    /** The work of the consumer. A pause of the lease workflow belongs to it. */
+    readonly work: {
+        readonly kind: WorkKind;
+        readonly id: string;
+    };
+    readonly spawn?: LeaseSpawnSpec;
+    /** Writes a part to the stream of the consumer. A wait mirrors the pause of the lease workflow through it. */
+    readonly emit?: (part: PausePart) => Promise<void>;
+};
+export type AcquireOutcome = {
+    readonly kind: "granted";
+    readonly size: ResourceSpec;
+} | {
+    readonly kind: "refused";
+    readonly reason: string;
+} | {
+    readonly kind: "failed";
+    readonly detail: string;
+};
+/** An exec found no lease that can run it. `detail` says why, for a lease that ended. */
+export type NoLease = {
+    readonly kind: "no_lease";
+    readonly detail?: string;
+};
+/** A lease bound to its consumer. A tool holds one, and gives the size and the command only. */
+export type BoundLease = {
+    acquire(size: ResourceSpec): Promise<AcquireOutcome>;
+    release(): Promise<void>;
+    exec(request: ExecRequest, emit: ExecEmit): Promise<Result<ExecResult, NoLease>>;
+};
+export type SandboxLeases = {
+    readonly toolchainSource: ToolchainSource;
+    acquire(binding: LeaseBinding, size: ResourceSpec): Promise<AcquireOutcome>;
+    release(leaseKey: string): Promise<void>;
+    /**
+     * End each lease of the given owner workflows, and do not wait for the lease workflows. A host that cancels
+     * work calls it, thus the machines go now and not at the next tick of each lease workflow.
+     */
+    releaseOwnedBy(ownerWorkflowIds: readonly string[]): Promise<void>;
+    exec(leaseKey: string, request: ExecRequest, emit: ExecEmit, mirror?: LeaseBinding["emit"]): Promise<Result<ExecResult, NoLease>>;
+    bind(binding: LeaseBinding): BoundLease;
+};
+export type SandboxLeasesConfig = {
+    /** The application pool, which holds the lease table and the pause rows. */
+    readonly pool: Querier & Connectable;
+    readonly client: SandboxClient;
+    /** The budget of the grant. Absent: each lease gets its grant at once. */
+    readonly resourcePolicy?: ResourcePolicy;
+    readonly resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    readonly runAuthorizer: RunAuthorizer;
+    /** Default {@link DEFAULT_IDLE_PERIOD_MS}. */
+    readonly idlePeriodMs?: number;
+    readonly pauseRetryDelaysMs?: readonly number[];
+    readonly logger?: Logger;
+    /** The DBOS client of the enqueue, the sends, and the waits of a consumer. */
+    readonly dbosClient: () => Promise<DBOSClient>;
+    /** The fetch of the health probe. Defaults to `globalThis.fetch`. */
+    readonly fetch?: (url: string, init?: RequestInit) => Promise<Response>;
+    /** The tick of a lease workflow, in seconds. Default 60. */
+    readonly tickSeconds?: number;
+};
+export declare function createSandboxLeases(config: SandboxLeasesConfig): SandboxLeases;