@inflexa-ai/harness 0.1.1

package/dist/sandbox/exec-id.js

@@ -0,0 +1,20 @@
+/**
+ * `execId` parsing — execId is `${workflowId}:${stepId}:${fnId}` where the
+ * workflowId portion itself contains exactly one colon (child workflow ids
+ * are `${analysisId}:${runId}-${stepIdx}`, parent ids are
+ * `${analysisId}:${runId}`). `indexOf(":")` / `split(":")[0]` over an
+ * execId would stop INSIDE the workflowId and return only the analysisId,
+ * which `DBOS.send` would treat as a wrong-workflow target. Strip the last
+ * two colon-delimited segments (`:${stepId}:${fnId}`) to recover the
+ * workflowId. `stepId` is a plan-defined slug and `fnId` is `fn-${n.toString(36)}`,
+ * neither of which can contain colons.
+ */
+export function workflowIdFromExec(execId) {
+    const lastColon = execId.lastIndexOf(":");
+    if (lastColon <= 0)
+        return null;
+    const secondLastColon = execId.lastIndexOf(":", lastColon - 1);
+    if (secondLastColon <= 0)
+        return null;
+    return execId.slice(0, secondLastColon);
+}

package/dist/sandbox/execution-id.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Execution ID generation — ported from shared/lib/execution-id.ts.
+ *
+ * Produces a single ID that embeds the agent name, used everywhere:
+ * sandbox pod name, K8s Job name, audit log files.
+ *
+ * Format: {sanitizedAgentName}-{nanoid8}  (e.g., qc-agent-a1b2c3d4)
+ */
+/** Length of the nanoid suffix (8 characters). */
+export declare const EXECUTION_ID_NANOID_LENGTH = 8;
+/** Maximum length for the sanitized agent name portion. */
+export declare const AGENT_NAME_MAX_LENGTH = 40;
+/**
+ * Sanitize an agent name for use in K8s pod/job names.
+ *
+ * Rules:
+ * - Lowercase only
+ * - Only `[a-z0-9-]` characters allowed
+ * - Leading/trailing hyphens stripped
+ * - Consecutive hyphens collapsed
+ * - Truncated to 40 characters
+ */
+export declare function sanitizeAgentName(name: string): string;
+/**
+ * Generate a unified execution ID for an agent invocation.
+ *
+ * @param agentName - The agent name from the registry
+ * @returns An ID in the format `{sanitizedAgentName}-{nanoid8}`
+ */
+export declare function generateExecutionId(agentName: string): string;

package/dist/sandbox/execution-id.js

@@ -0,0 +1,47 @@
+/**
+ * Execution ID generation — ported from shared/lib/execution-id.ts.
+ *
+ * Produces a single ID that embeds the agent name, used everywhere:
+ * sandbox pod name, K8s Job name, audit log files.
+ *
+ * Format: {sanitizedAgentName}-{nanoid8}  (e.g., qc-agent-a1b2c3d4)
+ */
+import { customAlphabet } from "nanoid";
+/** Length of the nanoid suffix (8 characters). */
+export const EXECUTION_ID_NANOID_LENGTH = 8;
+/** Maximum length for the sanitized agent name portion. */
+export const AGENT_NAME_MAX_LENGTH = 40;
+/**
+ * Lowercase alphanumeric alphabet for nanoid suffix.
+ * Ensures IDs are valid RFC 1123 DNS labels (required by K8s Job names).
+ */
+const nanoid = customAlphabet("abcdefghijklmnopqrstuvwxyz0123456789");
+/**
+ * Sanitize an agent name for use in K8s pod/job names.
+ *
+ * Rules:
+ * - Lowercase only
+ * - Only `[a-z0-9-]` characters allowed
+ * - Leading/trailing hyphens stripped
+ * - Consecutive hyphens collapsed
+ * - Truncated to 40 characters
+ */
+export function sanitizeAgentName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, AGENT_NAME_MAX_LENGTH);
+}
+/**
+ * Generate a unified execution ID for an agent invocation.
+ *
+ * @param agentName - The agent name from the registry
+ * @returns An ID in the format `{sanitizedAgentName}-{nanoid8}`
+ */
+export function generateExecutionId(agentName) {
+    const sanitized = sanitizeAgentName(agentName);
+    const suffix = nanoid(EXECUTION_ID_NANOID_LENGTH);
+    return `${sanitized}-${suffix}`;
+}

package/dist/sandbox/hmac.d.ts

@@ -0,0 +1,54 @@
+/**
+ * HMAC verification for sandbox callbacks (see the harness-sandbox-exec spec).
+ *
+ * sandbox-server signs every outbound event/completion POST with
+ * `X-Sandbox-Signature = hex(HMAC-SHA256(callbackSecret,
+ *   "${execId}:${timestamp}:${sha256Hex(body)}"))` plus a
+ * `X-Sandbox-Timestamp` header. The Cortex-side callback endpoint is
+ * **dumb** — it forwards the headers verbatim onto the per-exec DBOS
+ * topic. Verification happens here, in the workflow-body recv loop,
+ * because that body holds the `callbackSecret` from the cached
+ * `createSandbox` step output.
+ *
+ * A bad or stale signature triggers a hard cancel of the run — under
+ * NetworkPolicy isolation a forged event implies a bug or a breach,
+ * neither of which should keep a 3-hour sandbox burning.
+ */
+export interface VerifyCallbackInput {
+    execId: string;
+    /** The bytes the sandbox-server POSTed. The dumb route preserves them. */
+    body: Buffer | string;
+    /** `X-Sandbox-Signature` value (lowercase hex). */
+    signature: string | null;
+    /** `X-Sandbox-Timestamp` value (unix seconds). */
+    timestamp: number | null;
+    /** Per-sandbox secret from the cached `createSandbox` step output. */
+    secret: string;
+    /** Current unix-second wall-clock — injectable for tests. */
+    nowSec: number;
+    /** Symmetric freshness window in seconds. */
+    freshnessSec: number;
+}
+export type VerifyResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: "bad-signature" | "stale-timestamp" | "missing";
+};
+/**
+ * Recompute the HMAC and compare in constant time, then check the
+ * timestamp falls within a symmetric `freshnessSec` window of `nowSec`.
+ *
+ * Order: `missing` (one of signature/timestamp is null) is reported
+ * separately from `bad-signature` so the caller can log it precisely.
+ * Freshness is checked AFTER signature, so a stale-but-valid signature
+ * is distinguishable from a forgery.
+ */
+export declare function verifyCallback(input: VerifyCallbackInput): VerifyResult;
+/** Convenience for the Cortex side to compute a signature for tests. */
+export declare function signCallback({ execId, body, timestamp, secret }: {
+    execId: string;
+    body: Buffer | string;
+    timestamp: number;
+    secret: string;
+}): string;

package/dist/sandbox/hmac.js

@@ -0,0 +1,67 @@
+/**
+ * HMAC verification for sandbox callbacks (see the harness-sandbox-exec spec).
+ *
+ * sandbox-server signs every outbound event/completion POST with
+ * `X-Sandbox-Signature = hex(HMAC-SHA256(callbackSecret,
+ *   "${execId}:${timestamp}:${sha256Hex(body)}"))` plus a
+ * `X-Sandbox-Timestamp` header. The Cortex-side callback endpoint is
+ * **dumb** — it forwards the headers verbatim onto the per-exec DBOS
+ * topic. Verification happens here, in the workflow-body recv loop,
+ * because that body holds the `callbackSecret` from the cached
+ * `createSandbox` step output.
+ *
+ * A bad or stale signature triggers a hard cancel of the run — under
+ * NetworkPolicy isolation a forged event implies a bug or a breach,
+ * neither of which should keep a 3-hour sandbox burning.
+ */
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+/**
+ * Decode the per-sandbox secret. sandbox-server accepts both raw UTF-8
+ * and `base64:` prefixed values (change 4 spec); we mirror the same
+ * convention here so the Cortex and Go sides interpret the secret
+ * identically.
+ */
+function decodeSecret(secret) {
+    if (secret.startsWith("base64:")) {
+        return Buffer.from(secret.slice("base64:".length), "base64");
+    }
+    return Buffer.from(secret, "utf8");
+}
+function sha256Hex(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+/**
+ * Recompute the HMAC and compare in constant time, then check the
+ * timestamp falls within a symmetric `freshnessSec` window of `nowSec`.
+ *
+ * Order: `missing` (one of signature/timestamp is null) is reported
+ * separately from `bad-signature` so the caller can log it precisely.
+ * Freshness is checked AFTER signature, so a stale-but-valid signature
+ * is distinguishable from a forgery.
+ */
+export function verifyCallback(input) {
+    if (input.signature === null || input.timestamp === null) {
+        return { valid: false, reason: "missing" };
+    }
+    const secretBytes = decodeSecret(input.secret);
+    const message = `${input.execId}:${input.timestamp}:${sha256Hex(input.body)}`;
+    const expected = createHmac("sha256", secretBytes).update(message).digest("hex");
+    const provided = input.signature;
+    if (provided.length !== expected.length) {
+        return { valid: false, reason: "bad-signature" };
+    }
+    const matches = timingSafeEqual(Buffer.from(provided, "utf8"), Buffer.from(expected, "utf8"));
+    if (!matches) {
+        return { valid: false, reason: "bad-signature" };
+    }
+    if (Math.abs(input.nowSec - input.timestamp) > input.freshnessSec) {
+        return { valid: false, reason: "stale-timestamp" };
+    }
+    return { valid: true };
+}
+/** Convenience for the Cortex side to compute a signature for tests. */
+export function signCallback({ execId, body, timestamp, secret }) {
+    const secretBytes = decodeSecret(secret);
+    const message = `${execId}:${timestamp}:${sha256Hex(body)}`;
+    return createHmac("sha256", secretBytes).update(message).digest("hex");
+}

package/dist/sandbox/identity.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Sandbox identity minting — the durable half of the two-step create (ADR
+ * 0016). Backend-agnostic: the `sandboxId` and HMAC `callbackSecret` are 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 + secret.
+ */
+import type { SandboxIdentity } from "./types.js";
+/** `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 declare function mintSandboxIdentity(runId: string): SandboxIdentity;

package/dist/sandbox/identity.js

@@ -0,0 +1,22 @@
+/**
+ * Sandbox identity minting — the durable half of the two-step create (ADR
+ * 0016). Backend-agnostic: the `sandboxId` and HMAC `callbackSecret` are 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 + secret.
+ */
+import { randomBytes, 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.replace(/-/g, "").slice(0, 8);
+    const suffix = randomUUID().replace(/-/g, "").slice(0, 8);
+    return {
+        sandboxId: `sbx-${run8}-${suffix}`,
+        callbackSecret: "base64:" + randomBytes(32).toString("base64"),
+    };
+}

package/dist/sandbox/ignored-dirs.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Directory names that are tooling noise (interpreter caches, dependency
+ * trees) rather than analysis artifacts. `walkStepArtifacts`
+ * (`execution/post-step.js`) prunes these while walking a step's writable
+ * tree so caches never register as artifacts.
+ */
+export declare const IGNORED_DIRS: Set<string>;

package/dist/sandbox/ignored-dirs.js

@@ -0,0 +1,7 @@
+/**
+ * Directory names that are tooling noise (interpreter caches, dependency
+ * trees) rather than analysis artifacts. `walkStepArtifacts`
+ * (`execution/post-step.js`) prunes these while walking a step's writable
+ * tree so caches never register as artifacts.
+ */
+export const IGNORED_DIRS = new Set([".ruff_cache", "__pycache__", ".cache", ".ipynb_checkpoints", "node_modules", ".Rproj.user"]);

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

@@ -0,0 +1,71 @@
+/**
+ * K8s-backed `createSandbox` / `teardown` / `isAlive`.
+ *
+ * Launches a sandbox Job with `CORTEX_BASE_URL` and `SANDBOX_CALLBACK_SECRET`
+ * env vars; pod IP + port 8765 are the host/port Cortex POSTs `/exec` to.
+ * Storage is wired via the shared session PVC: a flat read-only `volumeMount`
+ * of the analysis tree at `/{resourceId}` plus a nested read-write mount of the
+ * step's artifact dir, with the lib/ref stores mounted read-only at `/mnt/libs`
+ * / `/mnt/refs` when their PVCs are set. Container paths and lib-store env come
+ * from the shared mount plan; the PVC `subPath`s are derived from the same
+ * `resolveWorkspaceRoot` seam the harness pre-creates the step tree under, so
+ * both sides address one directory by construction.
+ */
+import { BatchV1Api, CoreV1Api, type V1Toleration } from "@kubernetes/client-node";
+import { ResultAsync } from "neverthrow";
+import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
+import { type SandboxError } from "./sandbox-error.js";
+import type { CreateSandboxMeta, ManagedSandbox, SandboxIdentity, SandboxLiveness, SandboxRef, SandboxTransport } from "./types.js";
+/**
+ * Coerce an arbitrary identifier into a valid K8s label value:
+ * ≤63 chars, `[A-Za-z0-9._-]` only, starting and ending alphanumeric.
+ * Workflow ids legitimately contain `:` (exec-id routing packs
+ * `workflowId:stepId:fnId`), which is illegal in a label — without this an
+ * otherwise-valid Job is rejected with a 422 at admission. Sanitization is a
+ * no-op for already-valid ids, so DBOS-keyed lookups (adoption, reaper) match
+ * unchanged; only the synthetic, non-DBOS data-profile id is rewritten.
+ */
+export declare function sanitizeLabelValue(value: string): string;
+export interface K8sClientConfig {
+    image: string;
+    cortexBaseUrl: string;
+    /**
+     * Result transport, threaded to the pod as `SANDBOX_TRANSPORT`. Poll-mode
+     * confinement on K8s is a cluster-side NetworkPolicy, not an in-pod firewall.
+     * Defaults to `poll`.
+     */
+    transport?: SandboxTransport;
+    namespace: string;
+    /** PVC claim backing the shared session PVC the workspace roots live under. */
+    sessionPvc?: string;
+    /**
+     * Absolute mountpoint of `sessionPvc` on THIS process's filesystem. Required whenever
+     * `sessionPvc` is set: a pod addresses the PVC by `subPath`, so the harness must be able
+     * to express a resolved workspace root as a path relative to the volume's root. Every
+     * root the embedder resolves must therefore live under this directory.
+     */
+    sessionPvcRoot?: string;
+    /** Workspace-root resolution seam; the source of each analysis's PVC `subPath`. */
+    resolveWorkspaceRoot: ResolveWorkspaceRoot;
+    /** PVC claim mounted read-only at `/mnt/libs` when set. */
+    libStorePvc?: string;
+    /** PVC claim mounted read-only at `/mnt/refs` when set. */
+    refStorePvc?: string;
+    /** Node selector pinning sandbox pods to the dedicated agent pool. Omit for default scheduling. */
+    nodeSelector?: Record<string, string>;
+    /** Tolerations letting sandbox pods land on tainted agent nodes (e.g. `platform.io/agent-only:NoSchedule`). Omit for none. */
+    tolerations?: V1Toleration[];
+    /** RuntimeClass for runtime isolation (e.g. `gvisor`). Omit for the default runtime. */
+    runtimeClassName?: string;
+    /** Injected for tests. */
+    batchApi?: BatchV1Api;
+    coreApi?: CoreV1Api;
+    registerSandbox: (meta: CreateSandboxMeta, ref: SandboxRef) => Promise<void>;
+}
+export declare function createK8sSandboxOps(config: K8sClientConfig): {
+    createSandbox(meta: CreateSandboxMeta, identity: SandboxIdentity): ResultAsync<SandboxRef, SandboxError>;
+    teardown(ref: SandboxRef): ResultAsync<void, SandboxError>;
+    teardownById(sandboxId: string): ResultAsync<void, SandboxError>;
+    isAlive(ref: SandboxRef): ResultAsync<SandboxLiveness, SandboxError>;
+    listManagedSandboxes(): ResultAsync<ManagedSandbox[], SandboxError>;
+};