Tianyi Cui
6da6f04016
New group packages/code-runtime/ with the interface package @deepseek-ai/dsh-code-runtime, per the Code Mode RFC: abstract CodeRuntime service (run() resolves program failures as an error field, rejects only for seam misuse), the CodeRunRequest/CodeBindingNamespace/CodeRunResult/ CodeLogEntry/CodeRunFailure vocabulary, and readonly language/isolation backend descriptors. Registered in the tsconfig maps, packages/README, architecture service map, and the doc-graph service-role classification; catalogs regenerated. The RFC's one forward path token to the worker package becomes an npm-name mention until PR3 creates that directory (verify-package-paths is drift-scoped: the now-existing group made the token checkable). docs/architecture.md ceiling 1630 -> 1640: the doc gained a genuinely new capability-service row; the row itself is already minimal.
94 lines
3.8 KiB
TypeScript
94 lines
3.8 KiB
TypeScript
/**
|
|
* The code-execution seam (`ctx.codeRuntime`): an abstract service defining
|
|
* WHAT a code runtime does — run one model-written program against a set of
|
|
* host-provided async bindings and report `{ value, logs, error? }` — without
|
|
* saying HOW. Implementations subclass {@link CodeRuntime} and register
|
|
* themselves as the `codeRuntime` service; backends may differ by execution
|
|
* substrate (worker thread, separate process, container) and by source
|
|
* language, both declared as readonly descriptors. The design and its
|
|
* consumer (the tool registry's Code Mode) are specified in the Code Mode RFC
|
|
* (docs/rfc/proposed/feature/2026-06-15-code-mode.md).
|
|
*
|
|
* The split mirrors the bash seam (`BashExecutor`): the runtime knows nothing
|
|
* about tools or sessions — it is handed named async functions and a program,
|
|
* and everything tool-shaped stays with the consumer.
|
|
*
|
|
* @module @deepseek-ai/dsh-code-runtime
|
|
*/
|
|
|
|
import { Context, Service } from 'cordis'
|
|
import type { CodeRunRequest, CodeRunResult } from './types.ts'
|
|
|
|
export type {
|
|
CodeBindingFunction,
|
|
CodeBindingNamespace,
|
|
CodeLogEntry,
|
|
CodeRunFailure,
|
|
CodeRunRequest,
|
|
CodeRunResult,
|
|
} from './types.ts'
|
|
|
|
declare module 'cordis' {
|
|
interface Context {
|
|
codeRuntime: CodeRuntime
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Abstract code-execution service. Subclass, implement {@link run} and the
|
|
* two descriptors, and load the subclass as a plugin — it registers as
|
|
* `ctx.codeRuntime` (one implementation per context; loading a second throws,
|
|
* cordis' standard duplicate-service behavior).
|
|
*
|
|
* Semantics every implementation must honor:
|
|
* - {@link run} resolves with an error FIELD for every program outcome —
|
|
* parse/transform failures, thrown exceptions, budget expiry, abort,
|
|
* substrate death ({@link CodeRunFailure}'s taxonomy). It REJECTS only for
|
|
* caller misuse of the seam itself (e.g. a run submitted after disposal).
|
|
* - Binding calls bridge to the caller's {@link CodeBindingFunction}s
|
|
* verbatim; arguments and resolutions must be structured-cloneable, and the
|
|
* runtime treats the program as a hostile peer (arbitrary binding names are
|
|
* own properties, malformed traffic is rejected or ignored, never crashes
|
|
* the host).
|
|
* - Runs are isolated from each other: no state survives from one run to the
|
|
* next through the runtime.
|
|
* - Disposal reaches quiescence: in-flight runs are terminated AND awaited
|
|
* before the service's own teardown completes (no orphan substrate survives
|
|
* `fiber.dispose()`).
|
|
*/
|
|
export abstract class CodeRuntime extends Service {
|
|
/**
|
|
* The source language {@link run} expects `program` to be written in, as a
|
|
* lowercase identifier. Informational, not gating — a consumer that
|
|
* generates language-specific presentation (typed SDK stubs, usage
|
|
* instructions) switches on it and fails loud on a language it cannot
|
|
* present. Well-known value: `'typescript'`.
|
|
*/
|
|
abstract readonly language: string
|
|
|
|
/**
|
|
* The execution substrate, as a lowercase identifier. Informational, not
|
|
* gating — a descriptor so deployments and diagnostics can tell backends
|
|
* apart, not a security claim. Well-known values: `'worker-thread'`,
|
|
* `'process'`, `'container'`.
|
|
*/
|
|
abstract readonly isolation: string
|
|
|
|
constructor(ctx: Context) {
|
|
super(ctx, 'codeRuntime')
|
|
}
|
|
|
|
/**
|
|
* Execute one program against the request's bindings and capture what it
|
|
* emitted. See the class doc for the resolution contract (error is a result
|
|
* field; rejection means seam misuse only).
|
|
* @param request - the program, its bindings, and the abort signal; the
|
|
* request carries everything the runtime acts on, with no hidden defaults.
|
|
* @returns the run's outcome: completion value (when transferable), the
|
|
* ordered log capture, and the failure (if any).
|
|
*/
|
|
abstract run(request: CodeRunRequest): Promise<CodeRunResult>
|
|
}
|
|
|
|
export default CodeRuntime
|