@sema-agent/core/dist/core/runner/prepare-execution-env.js

Stateless, task-oriented AI agent core

import { StubExecutionEnv } from "../stub-env.js";
import { hasDestroy } from "../remote-env.js";
import { announceMalformedCapabilities } from "./env-capability-census.js";
import { settleTeardownLeg } from "./teardown-bounded.js";
export async function prepareExecutionEnv(input) {
    const { deps, spec, internals, resume, placementRootResolved, sessionId, forgetOnThrow, rollback } = input;
    let ownedEnv;
    let ownedEnvObservedAt;
    if (internals?.requestedCwd !== undefined && deps.executionEnvFactory === undefined) {
        await settleTeardownLeg(() => forgetOnThrow(), "forgetOnThrow (cwd-unsupported leg)", (err) => deps.onError?.(err, { phase: "config", sessionId }));
        const e = new Error(`Agent cwd "${internals.requestedCwd}" cannot take effect: this deployment has no executionEnvFactory (a static execution environment cannot be re-rooted per agent). Drop the cwd parameter or deploy a factory.`);
        e.code = "config.cwd_unsupported";
        throw e;
    }
    if (internals?.requestedCwd !== undefined && resume?.workspaceHandle !== undefined) {
        await settleTeardownLeg(() => forgetOnThrow(), "forgetOnThrow (cwd-conflicts-restore leg)", (err) => deps.onError?.(err, { phase: "config", sessionId }));
        throw cwdConflictsRestoreError(internals.requestedCwd);
    }
    try {
        ownedEnv = deps.executionEnvFactory
            ? await deps.executionEnvFactory({
                sessionId, placementRootSessionId: mintPlacementRootSessionId(placementRootResolved),
                taskId: spec.taskId,
                ...(internals?.isolation ? { isolation: internals.isolation } : {}),
                ...(internals?.parentCwd ? { parentCwd: internals.parentCwd } : {}),
            })
            : undefined;
        if (ownedEnv !== undefined)
            ownedEnvObservedAt = Date.now();
    }
    catch (factoryErr) {
        await settleTeardownLeg(() => forgetOnThrow(), "forgetOnThrow (env-factory-throw leg)", (err) => deps.onError?.(err, { phase: "config", sessionId }));
        throw factoryErr;
    }
    const ownedEnvSeat = { current: ownedEnv };
    if (ownedEnv !== undefined) {
        rollback.push(function ownedEnvDestroy() {
            const env = ownedEnvSeat.current;
            return env !== undefined && hasDestroy(env) ? env.destroy() : undefined;
        });
    }
    const executionEnv = ownedEnv ?? deps.executionEnv ?? new StubExecutionEnv();
    announceMalformedCapabilities(executionEnv, deps.onNotice);
    if (internals?.requestedCwd !== undefined) {
        const canon = async (p) => {
            const r = await executionEnv.canonicalPath(p);
            return r.ok ? r.value : p;
        };
        const want = await canon(internals.requestedCwd);
        const rejectCwd = async (message, code) => {
            await settleTeardownLeg(() => forgetOnThrow(), "forgetOnThrow (cwd-reject leg)", (err) => deps.onError?.(err, { phase: "config", sessionId }));
            await settleTeardownLeg(() => (ownedEnv && hasDestroy(ownedEnv) ? ownedEnv.destroy() : undefined), "ownedEnv.destroy (cwd-reject leg)", (err) => deps.onError?.(err, { phase: "config", sessionId }));
            const e = new Error(message);
            e.code = code;
            throw e;
        };
        if (deps.rootPath !== undefined) {
            const root = await canon(deps.rootPath);
            const sep = root.includes("\\") && !root.includes("/") ? "\\" : "/";
            const rootPrefix = root.endsWith(sep) ? root : root + sep;
            if (want !== root && !want.startsWith(rootPrefix)) {
                await rejectCwd(`Agent cwd "${internals.requestedCwd}" is outside this deployment's declared root "${deps.rootPath}" — the cwd must be located within the deployment root.`, "config.cwd_outside_root");
            }
        }
        const got = await canon(executionEnv.cwd);
        if (want !== got) {
            await rejectCwd(`Agent cwd "${internals.requestedCwd}" was not honored by the execution environment (it rooted at "${executionEnv.cwd}") — failing loud instead of running the agent in the wrong tree.`, "config.cwd_not_honored");
        }
    }
    const handsEnabled = ownedEnv !== undefined || deps.executionEnv !== undefined;
    const taskRootInitial = internals?.isolation === "worktree" || internals?.requestedCwd !== undefined || !deps.rootPath ? executionEnv.cwd : deps.rootPath;
    return { executionEnv, ownedEnvSeat, ownedEnvObservedAt, handsEnabled, taskRootInitial };
}
function cwdConflictsRestoreError(requestedCwd) {
    const e = new Error(`RunInternals.requestedCwd ("${requestedCwd}") cannot be combined with a checkpoint workspace restore — ` +
        `the restored workspace's own mount path is authoritative for the task root, so a requested cwd on this leg ` +
        `would be ignored (or worse, probed against an unrestored environment). Drop requestedCwd on resume legs.`);
    e.code = "config.cwd_conflicts_restore";
    return e;
}
function mintPlacementRootSessionId(placementRootResolved) {
    if (placementRootResolved === "") {
        const e = new Error("placement root resolved EMPTY (internals.placementRoot / internals.rootSessionId carries an empty string) — an empty fixed point cannot key a placement lookup; fix the spawning lane instead of defaulting around it.");
        e.code = "config.placement_root_invalid";
        throw e;
    }
    return placementRootResolved;
}