@hy-sde-org/dsh-code-runtime-kernels

@hy-sde-org/dsh-code-runtime-kernels

English | 中文

Persistent Python and JavaScript kernels for DeepSeek Harness — one self-contained plugin that gives the model a first-class run_kernel_code tool with session state that survives across calls. No upstream harness changes are required: it mounts as an ordinary Cordis plugin row (via cordis.patch.yml) and registers one tool on ctx.tools, exactly like the shipped tools.

Two long-lived kernel subprocesses share one host driver:

• Python — a long-lived python3 subprocess running a self-contained kernel (standard library only — no venv, no pip). Module-level variables and one asyncio event loop persist across cells; top-level await works; the last expression is the cell's value.
• JavaScript — a long-lived node subprocess running a self-contained kernel (Node builtins only). A persistent state object plus the process-global object carry values across cells; every cell runs as an async function body, so top-level await and return work; return carries the completion value.

The wire protocol, kernel host driver (spawn + handshake, serialized writes, hostile-peer parsing, SIGINT with SIGTERM/SIGKILL escalation, shutdown-to-exit), session registry, binding validation, and output ledger are shared (src/core/), so both languages behave identically.

Namespace snapshots. After every successfully settled run, the session's kernel namespace is snapshotted to disk (atomic temp-file-and-rename, per-entry + combined byte caps) and a fresh kernel for the session restores it once — so state survives a model cell that kills the kernel, an idle-reaped session, and a full plugin restart. The first run after a restore logs what was revived and what could not be (unpicklable entries are named, never silently dropped). reset: true deletes the snapshot so discarded state cannot sneak back; snapshot: false disables persistence entirely.

This is process confinement, not a security boundary: program source has bash-equivalent trust, exactly like the harness's own process-isolated backends. The driver's job is robustness — a forged frame never crashes the host, an unresponsive kernel is graded up to termination — not isolation.

Mounting

Add the bundle row (or a similar row in any cordis.yml):

- insert:
    - id: hy-sde-kernels
      name: '@hy-sde-org/dsh-code-runtime-kernels'
      config:
        languages: ['python', 'typescript']
        maxWallMs: 600000
        maxOutputBytes: 67108864
        sessionIdleMs: 0
        interruptEscalationMs: 5000
        startupTimeoutMs: 15000
        shutdownGraceMs: 1000
        toolTimeoutMs: 30000

All row ids carry the hy-sde- prefix so they never clash with shipped rows (a duplicate loader id fails the boot). Then the model sees the run_kernel_code tool.

Config

Key	Default	Meaning
languages	['python', 'typescript']	Enabled languages; a call to a disabled language is refused at call time.
pythonPath	python3	Explicit python executable (PATH discovery by default; fails loud at first spawn when absent).
nodePath	node	Explicit node executable (PATH discovery by default).
toolTimeoutMs	30000	Cooperative tool-call timeout (exec.signal becomes the per-run abort).
maxWallMs	600000	Per-run wall-clock budget; interrupt gradates SIGINT → SIGTERM → SIGKILL when the kernel does not respond.
maxOutputBytes	67108864	Combined serialized log-, completion-, and failure-message byte cap (an 'output-limit' failure).
maxOutputLineChars	4096	Per-line output cap (chars): a longer line is clipped with a … marker so one log bomb cannot own the budget.
sessionIdleMs	0	Reap a session whose kernel sits unused for this long (0 disables; state loss is the explicit cost).
interruptEscalationMs	5000	Wait after SIGINT before SIGTERM, then the same again before SIGKILL.
startupTimeoutMs	15000	Wait for the bootstrap ready handshake before failing the kernel.
shutdownGraceMs	1000	Grace for the kernel to exit after an exit frame.
snapshot	true	Namespace persistence: snapshot after each successful run, restore once on a fresh kernel. false disables.
snapshotDir	~/.dsh/code-runtime-kernels/state	Snapshot root; files live under /.snapshot.
snapshotMaxBytes	134217728	Combined byte cap for one snapshot file; entries past it are skipped by name.
snapshotMaxEntryBytes	8388608	Per-entry byte cap; an entry larger than this is skipped and named.
preload	{}	Session "toolbox": { python?: string; typescript?: string } sources run as one hidden first cell of every fresh session kernel (before the snapshot restores, so a restored name shadows a same-named helper). A preload failure fails the triggering run like an exception.
pythonImpl	'stdlib'	Python execution semantics: stdlib (self-contained runner) or ipykernel (a real IPython shell: magics, !cmd, display — the interpreter pointed at by pythonPath must have IPython installed; the kernel fails loud at boot otherwise).
sandboxConfinement	false	Route kernel subprocess spawns through the sandbox seam (structural confine capability, see SandboxProvider in @deepseek-ai/dsh-sandbox) instead of spawning the interpreter directly.
sandboxProvider	—	The confinement capability; required when sandboxConfinement is true (fail closed).
sandboxWorkspaceRoot	process.cwd()	Writable root under workspace-write confinement.
sandboxMode	'workspace-write'	File-effect mode for confined kernels ('read-only' or 'workspace-write').

Device setup for ipykernel mode

The runner does not bundle Python — it spawns pythonPath. To use pythonImpl: 'ipykernel', provision an interpreter with IPython once:

scripts/setup-ipykernel-venv.sh (idempotent; re-run after a Python upgrade)

creates/refreshes ~/.dsh/venvs/code-runtime-kernels-python (override the paths with DSH_KERNEL_VENV / DSH_KERNEL_BASE_PYTHON), then point the plugin row at it:

- id: code-runtime-kernels
  name: '@hy-sde-org/dsh-code-runtime-kernels'
  config:
    pythonPath: /Users//.dsh/venvs/code-runtime-kernels-python/bin/python
    pythonImpl: 'ipykernel'

Tool surface

run_kernel_code takes:

Parameter	Meaning
language	python or typescript.
code	Program source: for typescript an async-function body (top-level await/return work); for python a module (top-level await works, the last expression is the completion value — a top-level return is invalid Python and is reported as an exception).
session	Optional non-empty id; calls sharing one id keep kernel state. Omit for a one-shot run in fresh state.
reset	Discard the session's prior kernel state before this run (one reset instead of many retries).

It resolves the seam's result envelope — value (JSON completion), logs, executionCount, and error { kind, message } — so the vocabulary matches the harness's own run_code (exception / timeout / abort / worker-exit / invalid-output / output-limit), but with the persistent-session fields this plugin owns (session, reset, executionCount).

Semantics

• Sessions. A call with a non-empty session runs in that session's kernel; executionCount reports the running count. reset: true shuts the old kernel down before a fresh one answers.
• One-shot. Without session, a fresh kernel is spawned, exactly one program runs, and the kernel is shut down.
• Persistence. Python: module-level variables and loop state survive across cells. JavaScript: state (a long-lived shared object) and sloppy-mode global assignments survive; const/let/function/class at cell top level are per-cell (async body), so persistent definitions go on state. A cell completes return for a completion value, or with no return for a no-value run; non-lossless completions (cycles, BigInt, sets) are 'invalid-output'.
• Snapshots. After each successful run the namespace is saved (Python: pickle + marshal for bytecode, per-name loss reporting; JavaScript: V8 binary serialization, so Map/Set/Date/cyclic values survive but function-valued keys are named as lost). A fresh kernel for the session restores the last snapshot once — the restoring run's logs carry [dsh-kernels] restored N names from snapshot (could not restore: …). reset: true deletes the snapshot first, so it never resurrects discarded state. Python bytecode is marshal-format-dependent: restoring across a Python minor-version upgrade should be expected to lose function/class entries (named in the notice), not data.
• Toolbox. With preload set, every fresh session kernel runs the language's source as one hidden first cell before the snapshot restores: helpers behave like any other session state (they ride snapshots; a restored name shadows a same-named helper). Its output is hidden from the model; a preload failure fails the run it triggered.
• Budgets and failure kinds. Wall-clock expiry → 'timeout'; cancellation or a kernel that had to die → 'abort'; thrown exceptions → 'exception'; non-JSON completions → 'invalid-output'; combined output overflow → 'output-limit'; kernel death → the session registry replaces the kernel and retries once. All are result FIELDS, never rejections of the tool.

Model experience

The system-prompt guide tells the model to prefer run_kernel_code over scratch files for computation with intermediate results, to omit session for one-offs, to reuse a session id for related calls, and to pass reset: true when a session's state is corrupted or unwanted. The terminal card presentation shows language + session on each call and the captured output + failure line on completion.

Known limitations

• A busy synchronous cell resists SIGINT. A while (true) {}/while True: loop never yields to the event loop, so the interrupt handler cannot run and the escalation ladder (SIGTERM then SIGKILL) is what actually stops it — costing the kernel's state, hence the session. Cells that yield (async await on timers/I/O/tool calls) cancel cleanly and the kernel survives (the wall-clock/timeout tests cover this split).
• State can be poisoned. A buggy program can corrupt the session's state at any time; reset: true is the intended recovery primitive (it also deletes the snapshot, so the corruption cannot come back).
• No security boundary. Kernel code has bash-equivalent trust, matching the harness's own process backends — and so do snapshot files (pickle/marshal are not safe to read from untrusted input). Keep snapshotDir user-private; a planted snapshot executes as the host.
• Snapshot granularity is per-name. Python: data, modules, importable callables, and __main__-defined functions/classes are saved by value; user-class instances, closures over non-picklables, and entries past the caps are named as lost on the next restore. JavaScript: state and sloppy-mode global assignments are saved per key; a function anywhere inside a key's value discards that whole key (named).
• Snapshots are not free. Each successful run pickles/serializes and writes the namespace. Large namespaces mean larger latencies; tune the caps (snapshotMaxBytes, snapshotMaxEntryBytes) or disable with snapshot: false if state is ephemeral.
• Idle kernels hold a process. With sessionIdleMs: 0 (default), session kernels stay alive until reset or plugin teardown; a reaped session resumes from its snapshot on the next call with the same id.
• ipykernel mode needs a real IPython. Install ipykernel into the interpreter named by pythonPath (e.g. a venv) — the runner fails loud at boot with a clear message otherwise, and cells then run through the IPython shell (magics %…, !cmd, display), with snapshots and binding proxies working exactly as in stdlib mode.
• Confinement binds snapshots to the workspace. A confined kernel cannot write outside sandboxWorkspaceRoot, so snapshotDir must live under it (validated at construction; disable snapshot if the namespace is ephemeral). Confinement is process-level file-effect enforcement (bwrap / landlock-run / seatbelt via the seam), not a security boundary — model code still runs as your user.
• TS preloads persist via state. The TypeScript kernel evaluates each cell as an async-function body, so a function/class declaration in a preload stays cell-local; define toolbox helpers on state (e.g. state.helper = …).

Development

pnpm check (tsc), pnpm test (vitest; real python3/node subprocesses), pnpm build (tsc → ESModules under dist/), pnpm pack smoke. Layout: shared host driver in src/core/ (protocol, kernel host, session registry, ledger), languages in src/python/runner.ts (embedded source, staged per spawn) and src/nodejs/runner.ts (compiled file, spawned with node --no-warnings), the plugin/tool in src/index.ts. Tests: tests/kernels.spec.ts drives both kernels through KernelManager; tests/tool.spec.ts mounts the plugin on a real Cordis context and executes run_kernel_code through ctx.tools.execute.