173 lines
11 KiB
TypeScript
173 lines
11 KiB
TypeScript
/** 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<object, ProgramWorker>()
|
|
private readonly workers = new Set<ProgramWorker>()
|
|
|
|
/**
|
|
* 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<void> {
|
|
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<PtcRunResult> {
|
|
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<void> {
|
|
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)
|
|
}
|
|
}
|