ChatGPTClaudeGrok / X / CursorGemini

DSH plugin PTC runtime: bindings, output, and failures

Plugin DevelopmentPublished 2026-11-12Author: DeepSeek Plugin Market
DSH pluginDeepSeek HarnessPTC runtimeBindingsFailure classes
DSH plugin PTC runtime: resolve versus run, portable binding globals, output capture limits, and eight orthogonal PtcRunFailure kinds.

"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:

  1. omit timeoutMs — the provider default applies;
  2. pass a number — requests an elapsed budget that the provider validates and caps;
  3. 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:

  1. global must 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 $tools is rejected by every backend by design;
  2. names that satisfy the identifier rule but collide with backend-reserved slots (RESERVED_BINDING_GLOBALS, such as console or __dsh_main__) are rejected too;
  3. 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)

kindMeaning
exceptionThe program threw, or parsing and transformation failed
timeoutThe implementation-owned budget expired
abortPtcRunRequest.signal fired
worker-exitThe execution substrate died without settling, as in OOM
invalid-outputThe completion value is not lossless JSON
output-limitSerialized logs, values, or diagnostics exceed configured caps
protocolThe program emitted invalid or over-budget control traffic
sandbox-unavailableThe 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)

  1. Register a tools namespace, assert the program can call it, and assert the return value is lossless JSON.
  2. Use a $tools namespace as a negative case and assert rejection already at resolve.
  3. Bind a host function that throws and assert the program receives a rejection rather than the whole run aborting.
  4. Configure errorClass and assert a rejected call is an instance of the injected constructor with the member name readable from memberNameProperty.
  5. Force a timeout and assert kind is timeout while run did not reject.
  6. Run again with an already-aborted signal and assert kind is abort, 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.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Does a throwing PTC program make DSH plugin run reject?

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.

Can a DSH plugin binding namespace be named $tools?

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.

Is omitting DSH plugin timeoutMs the same as null?

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.

Does aborting a DSH plugin run wait for binding calls?

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