DSH plugin PTC runtime: bindings, output, and failures
"Bindings do not arrive" and "failures are indistinguishable" are the two PTC integration traps, and both come from misaligned boundaries. DSH plugin's PTC runtime splits caller input from execution input into two types and treats failure as a result field rather than an exception. Fix those boundaries before debugging programs.
PTC is optional; resolve and run divide the work
resolve() fills defaults, and run() accepts only fully resolved input.(source)
The PTC execution capability seam provides ctx.ptcRuntime through dsh-ptc-runtime. It runs a program against host bindings and reports output, failure, and applicable sandbox facts. The capability is optional and outside the agent loop trunk.
PtcRunRequest carries the program, bindings, cancellation, and optional execution choices. The provider's resolve validates supported choices and applies deployment defaults; run takes a PtcRunSpec with directory and deadline choices settled. Timeout semantics have three tiers:
- omit
timeoutMs— the provider default applies; - pass a number — requests an elapsed budget that the provider validates and caps;
- pass
null— no elapsed deadline.
The provider rejects unsupported choices before execution, so "wrong option" should surface as a resolve throw rather than a mid-run surprise.
Program format and retained state are separate
programFormat governs syntax, stateOwner governs memory, and neither affects the other.(source)
PtcProgramFormat has three values: function-body, repl, and script. Function bodies support top-level await and return; REPL and Script support top-level declarations, await, and trailing expressions but no top-level return. The Node Script provider transforms top-level await and awaits the completion value, and its declaration limits apply to the transformed program.
The completion value becomes PtcRunResult.value. It must be lossless JSON across the runtime boundary; an invalid or oversized value fails the run rather than being replaced by a rendered string.
stateOwner is an in-process object identity marking optional retained memory. Distinct objects are isolated from each other, and stateless providers ignore the field. Consumers must await release(owner) when the owner ends, and that call rejects if cleanup fails. Omitting the owner means single-shot execution.
One hard boundary: retained objects never enter the persisted Session format. So do not build cross-turn memory on stateOwner — it is not a persistence mechanism.
Bindings become global objects with portable names
Each namespace is one global object in the program, and names must pass a portability check.(source)
PtcBindingNamespace is described directly: each namespace becomes one global object of async-callable functions, and PTC passes in tools. Arguments and return values must be lossless JSON; providers enforce their own transport caps, and the seam sets no unified binding byte limit.
Three naming rules are hard:
globalmust match the language-portable identifier subset[A-Za-z_][A-Za-z0-9_]*and must not be a reserved word in any language — the JS-only$toolsis rejected by every backend by design;- names that satisfy the identifier rule but collide with backend-reserved slots (
RESERVED_BINDING_GLOBALS, such asconsoleor__dsh_main__) are rejected too; - binding names are own properties, so
__proto__cannot walk the prototype, and the runtime must build objects with a null prototype.
Optional errorClass turns rejections into program-visible typed errors: the runtime injects a real error constructor at name, rejected member calls become its instances, and memberNameProperty exposes the exact member name. Available member-name property names exclude RESERVED_ERROR_MEMBERS plus double-underscore forms, and every backend enforces the same rules.
Output capture channels and limits
Logs are plain strings, and cross-channel interleaving is not guaranteed by the seam.(source)
Each source channel keeps its own emission order; since channel metadata is outside the seam, how independent channels interleave is the backend's decision. The runtime captures console and stream output, and consumers only render text.
The cap accounting is concrete: implementations cap the serialized outer log array and the combined payload of the completion value or failure message; fixed result framing and consumer presentation whitespace are excluded from that variable payload. Overruns fail explicitly rather than inserting substitute content into the value.
That rule means you cannot rely on "huge output gets truncated into a notice." Either control what the program emits, or accept an output-limit failure.
Failure classes are orthogonal results
The eight kind values describe different facts and never substitute for one another.(source)
| kind | Meaning |
|---|---|
exception | The program threw, or parsing and transformation failed |
timeout | The implementation-owned budget expired |
abort | PtcRunRequest.signal fired |
worker-exit | The execution substrate died without settling, as in OOM |
invalid-output | The completion value is not lossless JSON |
output-limit | Serialized logs, values, or diagnostics exceed configured caps |
protocol | The program emitted invalid or over-budget control traffic |
sandbox-unavailable | The requested constraints could not be established |
The reference's framing is "orthogonal results reported independently": budget exhaustion is not an exception, abort is not a timeout, and a substrate crash is neither. message is human-readable detail suitable for feeding back to the model for self-correction.
One structural convention: the error is a field on a resolved result, never a run() rejection. Only Service Definition misuse rejects. So callers must not wrap program failures in try/catch.
Sandbox facts and execution boundaries
Sandbox facts are independent of terminal state; a successful program does not prove its constraints held.(source)
PtcRunSandbox has three parts: mode (the file-effect mode for this execution), denied (program failure text matched backend diagnostics — not proof of enforcement, and not a complete denial record), and enforcement (the completeness the chosen constraint backend reported, absent under full access).
The reference stresses that these are independent facts, so a successful program never proves every requested restriction was enforced. A provider that does not constrain at all rejects an explicitly supplied policy.
Two capability facts are easy to confuse: isolation describes the execution substrate and makes no security claim, while sandboxMode declares file-policy support and returns undefined from providers offering no constraints. Treating isolation as a security guarantee is a common misread.
Verification: bind a host function that throws
Cover binding visibility, typed errors, and failure classification.(source)
- Register a
toolsnamespace, assert the program can call it, and assert the return value is lossless JSON. - Use a
$toolsnamespace as a negative case and assert rejection already atresolve. - Bind a host function that throws and assert the program receives a rejection rather than the whole run aborting.
- Configure
errorClassand assert a rejected call is an instance of the injected constructor with the member name readable frommemberNameProperty. - Force a timeout and assert
kindistimeoutwhilerundid not reject. - Run again with an already-aborted
signaland assertkindisabort, with in-flight binding calls still the caller's to finish.
If the program crashes outright in step 3, first check whether the bound function returned a non-JSON value — the runtime prefers a descriptive rejection over letting a lossy value corrupt the run.
For integration flow plus timeouts and cancellation, see the PTC runtime overview; for sandbox mode boundaries, see sandbox modes.
One line to close: resolve fills defaults while run takes specs, binding names must be portable, log interleaving belongs to the backend, the eight failures are result fields, and sandbox facts are not a success guarantee.
FAQ
No. DSH plugin returns program failure as a field on the result. DSH plugin's run rejects only on Service Definition misuse; exceptions, timeouts, and aborts all resolve as PtcRunResult.error.
No. DSH plugin requires globals matching a language-portable identifier subset. DSH plugin states that JS-only forms like $tools are rejected by every backend, not just Python ones.
No. DSH plugin treats them as different requests: omission uses the provider default, null means no elapsed deadline, and a number is validated and capped.
No. DSH plugin stops only the program. DSH plugin resolves with an abort failure, while in-flight binding calls must be finished by the caller.
Related Terms
- PtcRunRequest
- PtcRunRequest is one PTC run's caller input: program, bindings, optional cwd, timeout, sandbox policy, and cancellation signal.— packages/ptc-runtime/ptc-runtime/src/types.ts
- PtcBindingNamespace
- PtcBindingNamespace is a group of host functions the runtime exposes as one global object inside the program, such as tools.— packages/ptc-runtime/ptc-runtime/src/types.ts
- PtcRunFailure
- PtcRunFailure is the orthogonal run-failure classification, a kind plus a human-readable message, with eight kind values.— packages/ptc-runtime/ptc-runtime/src/types.ts
- PtcRunSandbox
- PtcRunSandbox is one run's file-constraint facts: mode, whether denial was observed, and enforcement completeness.— packages/ptc-runtime/ptc-runtime/src/types.ts
Sources
- DeepSeek Harness reference - PTC runtime· deepseek-ai
- packages/ptc-runtime/ptc-runtime/src/types.ts· deepseek-ai