intentdna 1.9.0 → 1.9.3

package/dist/runtime/windows-job-keeper.js

@@ -0,0 +1,231 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, realpathSync, } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export const WINDOWS_JOB_KEEPER_PROTOCOL_VERSION = "IDNA_WINDOWS_JOB_KEEPER_V1";
+export const WINDOWS_JOB_KEEPER_MANIFEST_SCHEMA = "intentdna.windows_job_keeper_manifest.v1";
+export class WindowsJobKeeperArtifactError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "WindowsJobKeeperArtifactError";
+    }
+}
+function canonicalDigest(value) {
+    return typeof value === "string" && /^sha256:[0-9a-f]{64}$/.test(value);
+}
+function exactKeys(value, expected) {
+    const actual = Object.keys(value).sort();
+    const sortedExpected = [...expected].sort();
+    return actual.length === sortedExpected.length
+        && actual.every((key, index) => key === sortedExpected[index]);
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function architecture(value) {
+    if (value === "x64")
+        return "x86_64";
+    if (value === "arm64")
+        return "aarch64";
+    throw new WindowsJobKeeperArtifactError(`Windows Job keeper does not support architecture '${value}'`);
+}
+function fileDigest(path) {
+    return `sha256:${createHash("sha256").update(readFileSync(path)).digest("hex")}`;
+}
+function trustedRegularFile(path, label) {
+    let metadata;
+    try {
+        metadata = lstatSync(path);
+    }
+    catch (error) {
+        throw new WindowsJobKeeperArtifactError(`${label} is unavailable: ${path}`, { cause: error });
+    }
+    if (!metadata.isFile() || metadata.isSymbolicLink()) {
+        throw new WindowsJobKeeperArtifactError(`${label} is not a regular non-symlink file: ${path}`);
+    }
+}
+function resolveManifestMember(manifestPath, member, label) {
+    if (member.length === 0 || isAbsolute(member) || member.includes("\0")) {
+        throw new WindowsJobKeeperArtifactError(`${label} path is not a safe relative path`);
+    }
+    const root = realpathSync(dirname(manifestPath));
+    const path = resolve(root, member);
+    trustedRegularFile(path, label);
+    const actual = realpathSync(path);
+    const memberRelative = relative(root, actual);
+    if (memberRelative === "" || memberRelative === ".." || memberRelative.startsWith("../") || memberRelative.startsWith("..\\") || isAbsolute(memberRelative)) {
+        throw new WindowsJobKeeperArtifactError(`${label} escapes the manifest directory`);
+    }
+    return actual;
+}
+function parseManifestFile(value, label) {
+    if (!record(value) || !exactKeys(value, ["path", "sha256"])) {
+        throw new WindowsJobKeeperArtifactError(`${label} has an invalid schema`);
+    }
+    if (typeof value.path !== "string" || !canonicalDigest(value.sha256)) {
+        throw new WindowsJobKeeperArtifactError(`${label} has invalid path or digest fields`);
+    }
+    return value;
+}
+function parseManifestBinary(value, expectedMachine, label) {
+    if (!record(value) || !exactKeys(value, ["path", "sha256", "pe_machine"])) {
+        throw new WindowsJobKeeperArtifactError(`${label} has an invalid schema`);
+    }
+    if (typeof value.path !== "string"
+        || !canonicalDigest(value.sha256)
+        || value.pe_machine !== expectedMachine) {
+        throw new WindowsJobKeeperArtifactError(`${label} has invalid artifact identity fields`);
+    }
+    return value;
+}
+export function parseWindowsJobKeeperManifest(value) {
+    if (!record(value) || !exactKeys(value, [
+        "schema_version",
+        "protocol_version",
+        "source",
+        "toolchain",
+        "binaries",
+    ])) {
+        throw new WindowsJobKeeperArtifactError("Windows Job keeper manifest has an invalid schema");
+    }
+    if (value.schema_version !== WINDOWS_JOB_KEEPER_MANIFEST_SCHEMA
+        || value.protocol_version !== WINDOWS_JOB_KEEPER_PROTOCOL_VERSION
+        || !record(value.toolchain)
+        || !exactKeys(value.toolchain, [
+            "name",
+            "version",
+            "build_script",
+            "source_date_epoch",
+            "targets",
+        ])
+        || value.toolchain.name !== "zig"
+        || value.toolchain.version !== "0.16.0"
+        || !record(value.toolchain.build_script)
+        || !exactKeys(value.toolchain.build_script, ["path", "sha256"])
+        || value.toolchain.build_script.path !== "../../scripts/build-windows-job-keeper.mjs"
+        || !canonicalDigest(value.toolchain.build_script.sha256)
+        || value.toolchain.source_date_epoch !== 0
+        || !record(value.toolchain.targets)
+        || !exactKeys(value.toolchain.targets, ["x86_64", "aarch64"])
+        || value.toolchain.targets.x86_64 !== "x86_64-windows-gnu"
+        || value.toolchain.targets.aarch64 !== "aarch64-windows-gnu"
+        || !record(value.binaries)
+        || !exactKeys(value.binaries, ["x86_64", "aarch64"])) {
+        throw new WindowsJobKeeperArtifactError("Windows Job keeper manifest has an unsupported identity");
+    }
+    return {
+        schema_version: WINDOWS_JOB_KEEPER_MANIFEST_SCHEMA,
+        protocol_version: WINDOWS_JOB_KEEPER_PROTOCOL_VERSION,
+        source: parseManifestFile(value.source, "Windows Job keeper source"),
+        toolchain: {
+            name: "zig",
+            version: "0.16.0",
+            build_script: {
+                path: "../../scripts/build-windows-job-keeper.mjs",
+                sha256: value.toolchain.build_script.sha256,
+            },
+            source_date_epoch: 0,
+            targets: {
+                x86_64: "x86_64-windows-gnu",
+                aarch64: "aarch64-windows-gnu",
+            },
+        },
+        binaries: {
+            x86_64: parseManifestBinary(value.binaries.x86_64, "0x8664", "Windows Job keeper x86_64 binary"),
+            aarch64: parseManifestBinary(value.binaries.aarch64, "0xaa64", "Windows Job keeper aarch64 binary"),
+        },
+    };
+}
+export function readPeMachine(path) {
+    const bytes = readFileSync(path);
+    if (bytes.length < 0x40 || bytes[0] !== 0x4d || bytes[1] !== 0x5a) {
+        throw new WindowsJobKeeperArtifactError("Windows Job keeper does not have an MZ header");
+    }
+    const peOffset = bytes.readUInt32LE(0x3c);
+    if (peOffset > bytes.length - 6
+        || bytes.toString("ascii", peOffset, peOffset + 4) !== "PE\0\0") {
+        throw new WindowsJobKeeperArtifactError("Windows Job keeper does not have a valid PE header");
+    }
+    return bytes.readUInt16LE(peOffset + 4);
+}
+function verifyBinary(path, expectedDigest, target) {
+    trustedRegularFile(path, "Windows Job keeper binary");
+    const actualDigest = fileDigest(path);
+    if (actualDigest !== expectedDigest) {
+        throw new WindowsJobKeeperArtifactError(`Windows Job keeper digest mismatch: expected ${expectedDigest}, received ${actualDigest}`);
+    }
+    const expectedMachine = target === "x86_64" ? 0x8664 : 0xaa64;
+    const actualMachine = readPeMachine(path);
+    if (actualMachine !== expectedMachine) {
+        throw new WindowsJobKeeperArtifactError(`Windows Job keeper PE machine mismatch: expected 0x${expectedMachine.toString(16)}, received 0x${actualMachine.toString(16)}`);
+    }
+}
+function repositoryRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+}
+function defaultManifestPaths() {
+    const root = repositoryRoot();
+    return [
+        resolve(root, "dist/native/windows-job-keeper/manifest.json"),
+        resolve(root, "native/windows-job-keeper/manifest.json"),
+    ];
+}
+export function resolveWindowsJobKeeperArtifact(options) {
+    if (options.platform !== "win32")
+        return null;
+    const target = architecture(options.architecture ?? process.arch);
+    const hasOverride = options.helper_path !== undefined || options.expected_digest !== undefined;
+    if (hasOverride) {
+        if (process.platform === "win32") {
+            throw new WindowsJobKeeperArtifactError("production Windows execution cannot override the packaged Job keeper trust anchor");
+        }
+        if (options.helper_path === undefined || !canonicalDigest(options.expected_digest)) {
+            throw new WindowsJobKeeperArtifactError("simulated Windows execution requires helper_path and a canonical expected_digest");
+        }
+        const path = resolve(options.helper_path);
+        verifyBinary(path, options.expected_digest, target);
+        return {
+            architecture: target,
+            path,
+            digest: options.expected_digest,
+            source_digest: options.expected_digest,
+            protocol_version: WINDOWS_JOB_KEEPER_PROTOCOL_VERSION,
+            manifest_path: null,
+        };
+    }
+    const manifestPath = defaultManifestPaths().find(existsSync);
+    if (manifestPath === undefined) {
+        throw new WindowsJobKeeperArtifactError("packaged Windows Job keeper manifest is unavailable");
+    }
+    trustedRegularFile(manifestPath, "Windows Job keeper manifest");
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch (error) {
+        throw new WindowsJobKeeperArtifactError("Windows Job keeper manifest is not valid JSON", {
+            cause: error,
+        });
+    }
+    const manifest = parseWindowsJobKeeperManifest(parsed);
+    const sourcePath = resolveManifestMember(manifestPath, manifest.source.path, "Windows Job keeper source");
+    if (fileDigest(sourcePath) !== manifest.source.sha256) {
+        throw new WindowsJobKeeperArtifactError("Windows Job keeper source digest mismatch");
+    }
+    const buildScriptPath = resolve(dirname(manifestPath), manifest.toolchain.build_script.path);
+    trustedRegularFile(buildScriptPath, "Windows Job keeper build script");
+    if (fileDigest(realpathSync(buildScriptPath)) !== manifest.toolchain.build_script.sha256) {
+        throw new WindowsJobKeeperArtifactError("Windows Job keeper build script digest mismatch");
+    }
+    const binary = manifest.binaries[target];
+    const binaryPath = resolveManifestMember(manifestPath, binary.path, "Windows Job keeper binary");
+    verifyBinary(binaryPath, binary.sha256, target);
+    return {
+        architecture: target,
+        path: binaryPath,
+        digest: binary.sha256,
+        source_digest: manifest.source.sha256,
+        protocol_version: manifest.protocol_version,
+        manifest_path: realpathSync(manifestPath),
+    };
+}

package/dist/runtime/worker-executor.d.ts

@@ -1,5 +1,6 @@
-import type { ProviderEvent, StepPacket } from "./run-contracts.js";
+import type { ProviderEvent, StepPacket, TerminalOutcome } from "./run-contracts.js";
 import type { ExecutionProvider, WorkerExecution } from "./execution-provider.js";
+import { type ProcessTreeRunOptions, type ProcessTreeRunResult } from "./process-tree.js";
 export interface WorkerExecutorOptions {
     readonly cancellationSignal?: AbortSignal;
     readonly cancellationReason?: string | null;
@@ -7,8 +8,23 @@ export interface WorkerExecutorOptions {
     readonly maxProcessCount?: number;
     readonly processLimitPollMs?: number;
     readonly onProcessStart?: (processId: number) => void | Promise<void>;
+    readonly execution_authority?: WorkerExecutionAuthorityBinding;
+    readonly startedAt?: string;
     readonly now?: () => Date;
 }
+export interface WorkerExecutionAuthorityBinding {
+    readonly cancellation_signal: AbortSignal;
+    readonly launch_environment?: Readonly<Record<string, string>>;
+    executeProcessTree?(command: string, args: readonly string[], options: ProcessTreeRunOptions): Promise<ProcessTreeRunResult>;
+    processStarted(processId: number): void | Promise<void>;
+    processTreeCompleted(observation: {
+        readonly started_at: string;
+        readonly completed_at: string;
+        readonly outcome: TerminalOutcome;
+        readonly process_id: number | null;
+        readonly process_tree_drained: boolean;
+    }): void | Promise<void>;
+}
 export interface WorkerExecutionWithEvents extends WorkerExecution {
     readonly events: readonly ProviderEvent[];
 }

package/dist/runtime/worker-executor.js

@@ -88,17 +88,31 @@ export async function executeWorkerAttempt(packet, provider, options = {}) {
         });
     };
     const launch = provider.createLaunch(packet);
-    const startedAt = now().toISOString();
+    const startedAt = options.startedAt ?? now().toISOString();
     pushEvent({ type: "launch_started", provider: provider.name });
     let processStartObservation = Promise.resolve();
     let processStartFailed = false;
     let processStartError;
-    const processResult = await runProcessTree(launch.command, launch.args, {
+    const cancellationSignals = [
+        options.cancellationSignal,
+        options.execution_authority?.cancellation_signal,
+    ].filter((signal) => signal !== undefined);
+    const cancellationSignal = cancellationSignals.length > 1
+        ? AbortSignal.any(cancellationSignals)
+        : cancellationSignals[0];
+    const executeProcessTree = options.execution_authority?.executeProcessTree
+        ?? runProcessTree;
+    const processResult = await executeProcessTree(launch.command, launch.args, {
         cwd: launch.cwd,
-        env: launch.env,
+        env: options.execution_authority?.launch_environment === undefined
+            ? launch.env
+            : {
+                ...(launch.env ?? process.env),
+                ...options.execution_authority.launch_environment,
+            },
         stdin: launch.stdin ?? undefined,
         timeoutMs: packet.execution.timeout_ms ?? undefined,
-        cancellationSignal: options.cancellationSignal,
+        cancellationSignal,
         cancellationReason: options.cancellationReason,
         cancellationGraceMs: packet.execution.cancellation_grace_ms,
         maxOutputBytes: options.maxOutputBytes,
@@ -107,7 +121,7 @@ export async function executeWorkerAttempt(packet, provider, options = {}) {
         cleanupOnParentExit: true,
         onProcessStart: (processId) => {
             pushEvent({ type: "process_started", process_id: processId });
-            processStartObservation = Promise.resolve(options.onProcessStart?.(processId)).catch((error) => {
+            processStartObservation = Promise.resolve(options.execution_authority?.processStarted(processId)).then(() => options.onProcessStart?.(processId)).then(() => undefined).catch((error) => {
                 processStartFailed = true;
                 processStartError = error;
             });
@@ -172,6 +186,13 @@ export async function executeWorkerAttempt(packet, provider, options = {}) {
         signal: processResult.signal,
     });
     const completedAt = now().toISOString();
+    await options.execution_authority?.processTreeCompleted({
+        started_at: startedAt,
+        completed_at: completedAt,
+        outcome,
+        process_id: processResult.processId,
+        process_tree_drained: processResult.processTreeDrained,
+    });
     const result = {
         run_id: packet.run_id,
         step_id: packet.step_id,

package/dist/runtime/workflow-plan-adapter.d.ts

@@ -1,6 +1,7 @@
 import type { RoleDef, WorkflowPlan, WorkflowStep } from "../schema/types.js";
 import type { ControllerStepDefinition, MaterializeStepPacketInput, WorkflowRetryLoopPolicy } from "./run-controller.js";
 import type { TerminalOutcomeKind } from "./run-contracts.js";
+import { type ExecutableRunPlanPayload, type PlanSourceProvenance, type RunInputContract } from "./executable-run-plan.js";
 export type WorkflowPlanAdapterErrorCode = "invalid_plan" | "missing_role" | "invalid_handoff" | "unsupported_routing";
 export declare class WorkflowPlanAdapterError extends Error {
     readonly code: WorkflowPlanAdapterErrorCode;
@@ -18,6 +19,19 @@ export interface WorkflowPlanAdapterOptions {
     readonly retry_max_delay_ms?: number | null;
     readonly retryable_outcomes?: readonly TerminalOutcomeKind[];
 }
+export interface WorkflowExecutablePlanAdapterOptions {
+    readonly roles: Readonly<Record<string, RoleDef>>;
+    readonly target_key: string;
+    readonly input_contract: RunInputContract;
+    readonly source_provenance: PlanSourceProvenance;
+    readonly global_constraints?: readonly string[];
+    readonly allow_network?: boolean;
+    readonly timeout_ms?: number | null;
+    readonly cancellation_grace_ms?: number;
+    readonly retry_initial_delay_ms?: number;
+    readonly retry_max_delay_ms?: number | null;
+    readonly retryable_outcomes?: readonly TerminalOutcomeKind[];
+}
 export declare function adaptWorkflowRetryLoop(plan: WorkflowPlan, options?: Pick<WorkflowPlanAdapterOptions, "retry_initial_delay_ms" | "retry_max_delay_ms">): WorkflowRetryLoopPolicy | null;
 /**
  * Adapt one compiled workflow plan into Controller definitions. Every
@@ -25,3 +39,8 @@ export declare function adaptWorkflowRetryLoop(plan: WorkflowPlan, options?: Pic
  * no provider transcript or prior-session state is accepted by this API.
  */
 export declare function adaptWorkflowPlan(plan: WorkflowPlan, options: WorkflowPlanAdapterOptions): readonly ControllerStepDefinition[];
+/**
+ * Compile a WorkflowPlan into the immutable, provider-neutral plan payload.
+ * The legacy closure-based adapter above remains unchanged until the S8 cutover.
+ */
+export declare function adaptWorkflowPlanToExecutableRunPlan(plan: WorkflowPlan, options: WorkflowExecutablePlanAdapterOptions): ExecutableRunPlanPayload;