mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
192 lines
11 KiB
Markdown
192 lines
11 KiB
Markdown
# Code Runtime
|
|
|
|
English | [中文](code-runtime.zh.md)
|
|
|
|
The code-execution seam — a [capability seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) whose Service Definition ([dsh-code-runtime](../../packages/code-runtime/code-runtime), `ctx.codeRuntime`) runs one model-written program against host-provided async bindings and reports what it printed and returned. Code execution is **one optional capability**, not part of the agent-loop spine — so its vocabulary lives here, not in [core.md](core.md). Backends differ by execution substrate and source language, both readonly descriptors on the service; the worker-thread Service provider and tool-registry Consumer are specified by the [Code Mode foundation](../../.agents/notes/implemented/feature/2026-06-15-code-mode.md) and [typed-return contract](../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md).
|
|
|
|
Source: [`packages/code-runtime/code-runtime/src/types.ts`](../../packages/code-runtime/code-runtime/src/types.ts)
|
|
|
|
## The run: request in, result out
|
|
|
|
A `CodeRunRequest` carries **everything the runtime acts on** — per the "explicit > implicit at package boundaries" rule, defaulting (time budgets, output caps) is the implementation's validated config, never a hidden `??` inside `run()`:
|
|
|
|
```ts type-equiv
|
|
/**
|
|
* One run: the program source plus everything the runtime acts on. Per the
|
|
* explicit-over-implicit convention, defaulting (time budgets, output caps)
|
|
* is the implementation's validated config — a request carries no optional
|
|
* tuning knobs for a hidden `??` to fill in.
|
|
*/
|
|
interface CodeRunRequest {
|
|
/**
|
|
* The program source, in the runtime's {@link ../index.ts | language}. It
|
|
* runs as the body of an async function: top-level `await` and `return`
|
|
* are available, and the completion value becomes
|
|
* {@link CodeRunResult.value}.
|
|
*/
|
|
program: string
|
|
/** Host functions exposed to the program, one global object per namespace. */
|
|
bindings: CodeBindingNamespace[]
|
|
/**
|
|
* Abort the run: the runtime stops the program (hard, even mid-loop) and
|
|
* resolves with a {@link CodeRunFailure} of kind `'abort'`. In-flight
|
|
* binding calls are the CALLER's to settle — the runtime only stops asking.
|
|
*/
|
|
signal?: AbortSignal
|
|
}
|
|
```
|
|
|
|
The result reports an error as a **field**, never a rejection of `run()` — reporting a failed program is the caller's job, not an exception path (matching `BashExecutor.run`'s resolve-on-failure contract):
|
|
|
|
```ts type-equiv
|
|
/**
|
|
* The outcome of one run. An error is a FIELD on a resolved result, never a
|
|
* rejection of `run()` — reporting a failed program is the caller's job, not
|
|
* an exception path.
|
|
*/
|
|
interface CodeRunResult {
|
|
/**
|
|
* The program's completion value (its top-level `return`), when it ran to
|
|
* completion and the value crossed the runtime's lossless-JSON boundary.
|
|
* Invalid or over-limit completions fail the run instead of substituting a
|
|
* rendered string; a failed or value-less run leaves this absent.
|
|
*/
|
|
value?: CodeJsonValue
|
|
/** Text the program emitted, in order, bounded only as part of the outer result. */
|
|
logs: string[]
|
|
/** Present iff the run failed; see {@link CodeRunFailure} for the taxonomy. */
|
|
error?: CodeRunFailure
|
|
}
|
|
```
|
|
|
|
## Bindings: host functions as program globals
|
|
|
|
Each `CodeBindingNamespace` becomes one global object of async callables inside the program (the Code Mode consumer passes one: `tools`). Arguments and resolutions must be lossless JSON and cross without a seam-level byte cap; the runtime may bridge them through structured clone. A namespace may declare a program-visible error class without making the runtime know the consumer's names: the runtime injects the real constructor and turns rejected calls into its instances. A runtime also treats binding names as hostile input (`__proto__` is an ordinary own property, never a prototype collision):
|
|
|
|
```ts type-equiv
|
|
/**
|
|
* Program-visible typed rejection for one binding namespace. The runtime
|
|
* injects a real error constructor under `name`; rejected member calls become
|
|
* its instances and expose the exact member name through
|
|
* `memberNameProperty`. Both strings are runtime data rather than knowledge
|
|
* of a particular consumer such as Code Mode.
|
|
*/
|
|
interface CodeBindingErrorClass {
|
|
/** Constructor global and resulting `Error.name`; same portable identifier rule as {@link CodeBindingNamespace.global}. */
|
|
name: string
|
|
/**
|
|
* Non-empty own property for the member name. The portable exclusion set is
|
|
* `RESERVED_ERROR_MEMBERS` plus dunder-form names (`__x__`, non-empty
|
|
* middle), enforced identically by every backend; any other name —
|
|
* identifiers or not — is accepted everywhere.
|
|
*/
|
|
memberNameProperty: string
|
|
}
|
|
```
|
|
|
|
```ts type-equiv
|
|
/**
|
|
* A named group of {@link CodeBindingFunction}s the runtime exposes to the
|
|
* program as one global object (e.g. `tools`). Function names are arbitrary
|
|
* strings — a runtime must treat names like `__proto__` or `constructor` as
|
|
* ordinary own properties (null-prototype construction), never as prototype
|
|
* collisions.
|
|
*/
|
|
interface CodeBindingNamespace {
|
|
/**
|
|
* The global identifier the program sees. Must match the LANGUAGE-PORTABLE
|
|
* identifier subset `[A-Za-z_][A-Za-z0-9_]*` and no language's reserved
|
|
* words, so the same namespace list works against every backend regardless
|
|
* of `language` — a JS-only spelling like `$tools` is rejected by design,
|
|
* not just by the Python backend. Names that satisfy the identifier rule but
|
|
* name a backend-owned slot (`RESERVED_BINDING_GLOBALS`, e.g. `console`,
|
|
* `__dsh_main__`) are also refused everywhere; see its declaration for the
|
|
* exact set and why each entry is reserved.
|
|
*/
|
|
global: string
|
|
/** The callable members, keyed by the exact name the program calls. */
|
|
functions: Record<string, CodeBindingFunction>
|
|
/** Optional program-visible typed rejection contract for this namespace. */
|
|
errorClass?: CodeBindingErrorClass
|
|
}
|
|
```
|
|
|
|
```ts type-equiv
|
|
/** A lossless JSON value transferable through the dependency-light Service Definition. */
|
|
type CodeJsonValue = null | boolean | number | string | CodeJsonValue[] | { [key: string]: CodeJsonValue }
|
|
```
|
|
|
|
```ts type-equiv
|
|
/**
|
|
* One host-side function exposed to the program as an async callable. The
|
|
* runtime bridges calls to it (possibly across a serialization boundary), so
|
|
* `args` and the resolution value MUST be lossless JSON. A runtime rejects a
|
|
* lossy or non-cloneable value with a descriptive error rather than corrupting
|
|
* the run. No seam-level byte cap applies to a binding resolution. A rejection
|
|
* of this function surfaces inside the program as a rejection of the
|
|
* corresponding call.
|
|
*/
|
|
type CodeBindingFunction = (args: unknown) => Promise<CodeJsonValue>
|
|
```
|
|
|
|
## Captured output and the failure taxonomy
|
|
|
|
Logs are plain strings in emission order. The runtime captures the program's console and stream output, but channel and console-method metadata are not part of the seam because consumers render only the text. Implementations cap the serialized outer log-array plus completion-value or failure-message payload; fixed result-envelope syntax and consumer presentation whitespace are not part of that variable-payload ledger. Overflow is an explicit failure rather than in-band value substitution.
|
|
|
|
Failure kinds are **orthogonal outcomes reported independently** (per [defensive-patterns](../defensive-patterns.md)): a budget expiry is not an exception, an abort is not a timeout, and a substrate death (e.g. OOM) is neither:
|
|
|
|
```ts type-equiv
|
|
/**
|
|
* Why a run failed. The kinds are orthogonal outcomes reported independently
|
|
* (per docs/defensive-patterns.md): a budget expiry is not an exception, an
|
|
* abort is not a timeout, and a substrate death is neither.
|
|
*
|
|
* - `'exception'` — the program threw or failed to parse/transform.
|
|
* - `'timeout'` — an implementation-owned budget expired; the message says which.
|
|
* - `'abort'` — {@link CodeRunRequest.signal} fired.
|
|
* - `'worker-exit'` — the execution substrate died without settling (e.g. OOM).
|
|
* - `'invalid-output'` — the completion value was not lossless JSON.
|
|
* - `'output-limit'` — the serialized outer logs/value/diagnostic exceeded the configured cap.
|
|
*/
|
|
interface CodeRunFailure {
|
|
/** The failure class (see the interface doc for each kind's meaning). */
|
|
kind: 'exception' | 'timeout' | 'abort' | 'worker-exit' | 'invalid-output' | 'output-limit'
|
|
/** Human-readable detail, suitable for feeding back to a model to self-correct. */
|
|
message: string
|
|
}
|
|
```
|
|
|
|
## The service
|
|
|
|
`CodeRuntime` (`ctx.codeRuntime`, abstract — defined in [`packages/code-runtime/code-runtime/src/index.ts`](../../packages/code-runtime/code-runtime/src/index.ts)) is `run(request)` plus two readonly descriptors: `language` (what the program must be written in — `'typescript'` and `'python'` are the well-known values, those `dsh-tools` presents, and only `'typescript'` has a published backend; a consumer generating language-specific presentation switches on it and fails loud on one it cannot present) and `isolation` (the execution substrate — `'worker-thread'`, `'process'`, `'container'`; a diagnostic label, **not a security claim**). Implementations must keep runs isolated from each other (no cross-run state) and dispose to quiescence: in-flight runs are terminated and awaited before teardown completes.
|
|
|
|
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
|
|
|
|
<a id="cordis-surface"></a>
|
|
|
|
## Cordis API
|
|
|
|
Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
|
|
|
|
<a id="ctxcoderuntime--coderuntime-abstract-seam"></a>
|
|
|
|
### `ctx.codeRuntime` — `CodeRuntime` (abstract seam)
|
|
|
|
Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and substrate failures resolve in CodeRunResult; only Service Definition contract misuse rejects. Implementations bridge structured-cloneable bindings, materialize each declared namespace rejection class, treat programs as hostile peers, isolate runs from one another, and terminate and await in-flight runs during disposal.
|
|
|
|
```ts cordis-catalog
|
|
/**
|
|
* 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 Service Definition contract 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>
|
|
```
|
|
|
|
Source: [`packages/code-runtime/code-runtime/src/index.ts:102`](../../packages/code-runtime/code-runtime/src/index.ts)
|
|
<!-- END GENERATED cordis-surface -->
|