/** Select program syntax and own temporary or retained Node processes. */ import { stripTypeScriptTypes } from 'node:module' import { isAbsolute } from 'node:path' import type { Context } from '@deepseek-ai/cordis' import type { PtcProgramFormat, PtcRunRequest, PtcRunResult, PtcRunSpec } from '@deepseek-ai/dsh-ptc-runtime' import { assertNever } from '@deepseek-ai/dsh-util-values' import { clampTimeout } from '@deepseek-ai/dsh-timeout' import type { ResolvedConfig } from './config.ts' import { validateBindings } from './bindings.ts' import type { PolicyProcesses } from './policy-processes.ts' import { ProgramWorker } from './worker.ts' /** Syntax, state retention and model guidance selected during provider construction. */ export interface ExecutionMode { /** Child evaluator selected independently of process lifetime. */ readonly format: PtcProgramFormat /** Whether caller-owned objects retain processes between runs. */ readonly retainsState: boolean /** Model-facing syntax, output and recovery rules. */ readonly executionInstructions: string /** * Erase TypeScript in the selected syntax without executing the program. * @param program - Model-written TypeScript source. * @returns JavaScript accepted by the selected evaluator. */ stripTypes(program: string): string } /** * Select program semantics and create their shared process owner. * @param ctx - Provider lifecycle and execution services. * @param config - Validated configuration with loader defaults. * @param processes - Policy invalidation and process cleanup coordination. * @returns Mode selection and temporary or retained execution through one process implementation. */ export function createExecution(ctx: Context, config: ResolvedConfig, processes: PolicyProcesses): NodeExecution { return new NodeExecution(ctx, config, processes, resolveMode(config)) } /** Temporary processes and optional object-owned reuse share one process implementation. */ class NodeExecution { private readonly owners = new WeakMap() private readonly workers = new Set() /** * Own process instances and optional owner lookup for one provider. * @param ctx - Provider lifecycle and execution services. * @param config - Validated limits and selected executable. * @param processes - Provider-owned policy invalidation and cleanup. * @param mode - Program syntax and TypeScript erasure. */ constructor( private readonly ctx: Context, private readonly config: ResolvedConfig, private readonly processes: PolicyProcesses, readonly mode: ExecutionMode, ) {} /** Stop every owned process, retaining failed cleanup for a later retry. */ async dispose(): Promise { const results = await Promise.allSettled([...this.workers].map(async (worker) => { await worker.dispose() this.workers.delete(worker) })) const failed = results.find(result => result.status === 'rejected') if (failed?.status === 'rejected') throw failed.reason } /** * Resolve the common file policy, directory and deadline defaults. * @param request - Program, bindings, owner, directory and elapsed budget. * @returns Resolved inputs with the selected file policy. */ resolve(request: PtcRunRequest): PtcRunSpec { const sandboxPolicy = request.sandboxPolicy ?? this.ctx.sandboxPolicy.resolve() const cwd = request.cwd ?? sandboxPolicy.workspaceRoot if (!isAbsolute(cwd)) throw new Error(`${this.mode.retainsState ? 'persistent PTC' : 'ptc-runtime-node'}: cwd must be absolute`) return { ...request, sandboxPolicy, cwd, timeoutMs: request.timeoutMs === null ? null : clampTimeout(request.timeoutMs, this.config.timeoutMs, this.config.maxTimeoutMs, this.mode.retainsState ? 'persistent PTC timeoutMs' : 'ptc-runtime-node: timeoutMs') } } /** * Evaluate in a temporary process or reuse an enabled state owner's process. * @param spec - Resolved request; concurrent calls for one owner are rejected. * @returns Captured logs, JSON completion, or a structured execution failure. */ async run(spec: PtcRunSpec): Promise { if (spec.sandboxPolicy === undefined) throw new Error('ptc-runtime-node: run requires a resolved sandbox policy') if (!isAbsolute(spec.cwd) || (spec.timeoutMs !== null && (!Number.isFinite(spec.timeoutMs) || spec.timeoutMs <= 0 || spec.timeoutMs > this.config.maxTimeoutMs))) throw new Error('ptc-runtime-node: run requires resolved cwd and timeout') const bindings = validateBindings(spec) const owner = this.mode.retainsState ? spec.stateOwner : undefined let worker = owner === undefined ? undefined : this.owners.get(owner) worker?.assertIdle() if (worker && !worker.closed && (worker.policy.mode !== spec.sandboxPolicy.mode || worker.policy.workspaceRoot !== spec.sandboxPolicy.workspaceRoot || worker.policy.sessionId !== spec.sandboxPolicy.sessionId)) { throw new Error('persistent PTC: release the retained environment before changing its sandbox policy') } // Retained processes keep their launch-time directory grants until release. if (!worker || worker.closed) { if (worker) this.workers.delete(worker) // Direct callers can own mutable policy arrays; the retained process owns its grant snapshot. worker = new ProgramWorker(this.ctx, this.config, { ...spec.sandboxPolicy, ...spec.sandboxPolicy.additionalWritableRoots === undefined ? {} : { additionalWritableRoots: [...spec.sandboxPolicy.additionalWritableRoots] }, }, this.processes, this.mode, owner !== undefined) this.workers.add(worker) if (owner !== undefined) this.owners.set(owner, worker) } try { return await worker.run(spec, bindings) } finally { if (owner === undefined && worker.cleanupComplete) this.workers.delete(worker) } } /** * Release retained state and await its process cleanup. * @param owner - Exact object supplied to run. * @returns Completion after the owned process and output streams stop. */ async release(owner: object): Promise { const worker = this.owners.get(owner) if (!worker) return await worker.dispose() if (this.owners.get(owner) === worker) this.owners.delete(owner) this.workers.delete(worker) } } const STRIP_PREFIX = 'async function __dsh_program__() {\n' const STRIP_SUFFIX = '\n}' const RETAINED_STATE_INSTRUCTIONS = 'Timeout and cancellation results say whether retained variables were preserved or cleared. Restart, sandbox changes, output overflow, or process failure clears them. Recreate missing variables and resources; conversation history does not restore state. Earlier mutations and tool effects are not rolled back. Approved sandbox escalations use a fresh environment and discard its variables afterward. Do not redeclare existing let, const, or class names; reuse mutable bindings or choose new names. Await tools and cleanup before returning; unfinished tools reject. After completion, timeout, or cancellation, new tool calls are rejected and captured output is discarded; background work may still change state. Await child-process completion before returning; raw output belongs to the active evaluation.' function resolveMode(config: ResolvedConfig): ExecutionMode { const outputInstructions = 'Use inspect(...values) to display output. Do not use console.' switch (config.executionMode) { case 'per-call': return { format: 'function-body', retainsState: false, executionInstructions: 'The program is the body of an async TypeScript function; only erasable syntax is accepted, with no enum or namespaces. Type annotations are advisory. Top-level await and return are supported. ' + outputInstructions + ' Each call runs in a fresh Node process. Node APIs are available through await import(...). Relative paths use the supplied working directory; process.env starts empty. Direct filesystem access follows this execution\'s sandbox policy.', stripTypes(program) { const stripped = stripTypeScriptTypes(STRIP_PREFIX + program + STRIP_SUFFIX) return stripped.slice(STRIP_PREFIX.length, stripped.length - STRIP_SUFFIX.length) }, } case 'persistent-in-memory': return { format: 'repl', retainsState: true, executionInstructions: 'The program contains TypeScript REPL statements; only erasable syntax is accepted, with no enum or namespaces. Type annotations are advisory. Top-level declarations and await are supported; top-level return is not supported. ' + outputInstructions + ' Variables, functions, and imported modules remain in memory for this Agent across calls. Use await import(...) for modules. Direct filesystem access follows the environment\'s launch-time sandbox policy; process.env starts empty. ' + RETAINED_STATE_INSTRUCTIONS, stripTypes: stripTypeScriptTypes, } case 'vm-script': { const lifetime = config.scriptPersistence ? 'Variables, functions, and imported modules remain in memory for this Agent across calls.' : 'Each call runs in a fresh Node process.' const filePolicy = config.scriptPersistence ? 'Direct filesystem access follows the environment\'s launch-time sandbox policy; process.env starts empty.' : 'Direct filesystem access follows this execution\'s sandbox policy; process.env starts empty.' const asynchronousFailure = 'Await asynchronous work: an uncaught callback exception or unhandled rejection terminates the process' + (config.scriptPersistence ? ' and clears its variables.' : '.') const recovery = config.scriptPersistence ? ' ' + RETAINED_STATE_INSTRUCTIONS + ' If a native top-level let, const, or class initializer throws, its name may remain permanently uninitialized; use a new name or restart the environment.' : '' return { format: 'script', retainsState: config.scriptPersistence, executionInstructions: 'The program contains TypeScript script statements; only erasable syntax is accepted, with no enum or namespaces. Type annotations are advisory. Top-level declarations and await are supported; top-level return is not supported. ' + outputInstructions + ' The final expression is awaited if it is a Promise. ' + lifetime + ' Use await import(...) for modules. Relative paths use the supplied working directory. ' + filePolicy + ' ' + asynchronousFailure + ' Values from bindings and imports can belong to another realm; use Array.isArray for arrays and the supplied binding error classes for failures, because instanceof Array or Error may be false.' + recovery, stripTypes: stripTypeScriptTypes, } } /* v8 ignore next -- Loader validates the closed execution-mode union before selection. */ default: return assertNever(config.executionMode) } }