DSH plugin PTC runtime: timeouts, cancellation and sandbox

The PTC runtime is not “run some code”; it is “run a program in an execution world with host bindings, a budget, and reported sandbox facts”. ctx.ptcRuntime has two actions: resolve(request) fills caller input into a complete PtcRunSpec, and run(spec) executes it and returns a PtcRunResult. Program failure is a field on the result, not an exception; sandbox facts are reports, not proof.

DeepSeek Harness: Three core objects

Separate request, spec, and result so validation and execution do not blur together. The relationship:(source)

resolve validates supported choices and applies deployment defaults. Omitting timeout uses the provider default, a numeric request is capped, and null requests no deadline. Providers reject unsupported choices before execution instead of failing mid-run.

run receives complete input: cwd exists and timeoutMs is either positive or null. Implementations do not repeat default resolution on every execution.

DeepSeek Harness: Designing bindings

Bindings are host functions exposed to the program, not an arbitrary object channel; arguments and return values must be lossless JSON. Design points:(source)

1. One global per namespace — each PtcBindingNamespace is exposed under global, with functions below it. Expected: the program calls them like normal async functions.
2. Portable names only — [A-Za-z_][A-Za-z0-9_]*, not a reserved word. Expected: the same namespace list works on JS and Python backends.
3. Own properties, even for odd names — __proto__ and constructor are ordinary keys, constructed with a null prototype. Expected: no prototype collision.
4. Optional typed errors — an errorClass lets the program see a real error constructor and member name. Expected: rejections are structured.
5. Lossless values — arguments and resolutions cross a JSON boundary without loss. Expected: non-cloneable values fail explicitly instead of becoming strings.

If a binding needs a complex object, split it into JSON-expressible fields; do not rely on a backend’s serializer happening to accept it.

DeepSeek Harness: Failure taxonomy and result handling

PTC failures are orthogonal outcomes: a timeout is not an exception, an abort is not a timeout, and a substrate death is neither. Eight kinds:(source)

• exception — the program threw or failed to parse/transform.
• timeout — an implementation-owned budget expired.
• abort — the request signal fired.
• worker-exit — the execution substrate died, such as OOM.
• invalid-output — the completion value was not lossless JSON.
• output-limit — serialized logs, value, or diagnostics exceeded a cap.
• protocol — invalid or over-budget control traffic.
• sandbox-unavailable — required confinement could not be established.

Do not rethrow error as an exception; it is the field the caller renders or feeds back to the model. Logs are plain strings; each channel preserves its own order, while interleaving across channels is backend-dependent.

DeepSeek Harness: Three integration options

You do not have to write a runtime to use PTC; choose by isolation and persistence needs. Three options:(source)

1. Use the published Node provider — best for most local execution, with sandbox and persistent REPL behavior. Expected: no custom process isolation.
2. Implement a stateless provider — a fresh environment per request, ignoring stateOwner. Expected: simple, good for one-shot computation.
3. Implement a retained-state provider — isolate memory by stateOwner and call release(owner) when the owner ends. Expected: reuse within one owner, but retained objects never enter the persistent session format.

Every implementation terminates and awaits active executions during disposal. Cleanup failure should reject release or shutdown.

DeepSeek Harness: Security boundaries

Sandbox facts are reports, not guarantees; a successful program does not prove every restriction was enforced. Four points:(source)

1. Read sandbox.mode and denied — mode, observed denial, and enforcement completeness are independent facts. Expected: no “no error” conclusion about privilege.
2. isolation is not a security claim — it describes the substrate. Expected: do not use it as compliance evidence.
3. No proxy configuration — Workflow workers and the Node PTC process do not inherit proxy variables. Expected: model scripts cannot read a proxy URL with credentials; direct egress must configure its own proxy and stay inside the sandbox.
4. Distinguish program failure from contract misuse — program failure is in error; only Service Definition misuse rejects. Expected: user code errors are not reported as framework crashes.

DeepSeek Harness: A minimal call skeleton

The caller only needs resolve and run; program failure is read from result.error. Skeleton:(source)

const spec = ctx.ptcRuntime.resolve({
  program,
  bindings: [{ global: 'tools', functions: { readFile } }],
  cwd,
  timeoutMs: 30_000,
})
const result = await ctx.ptcRuntime.run(spec)
if (result.error) return { ok: false, kind: result.error.kind }
return { ok: true, value: result.value, logs: result.logs }

resolve may throw for an unsupported choice; that is a caller contract error. A program failure inside run is result.error; do not mix the two.

Implementation checklist

Before writing run, settle four decisions or the implementation will churn on error handling and state leaks. Checklist:

1. Language and programFormat — async function body or REPL, which decides top-level await and return. Expected: programs do not fail at parse time for the wrong format.
2. Binding namespaces — which host functions, which global names, and whether typed errors are needed. Expected: names follow the portable identifier rule.
3. Budget and isolation — default timeout, numeric cap, meaning of null, and whether sandboxing exists. Expected: resolve can produce a complete PtcRunSpec.
4. Resource release — how each run’s state is isolated and how release(owner) terminates active execution. Expected: cleanup failure rejects explicitly.

DeepSeek Harness FAQ

How is PTC different from a normal tool call? A tool call is one function invocation. PTC lets the model write a program that composes multiple calls against host bindings while sharing one execution’s directory, budget, and sandbox facts.

Can a PTC program persist state? stateOwner retains state inside the process, but it is not part of the persistent session format; state does not survive process exit.

What happens to in-flight binding calls after a timeout? The runtime stops the program, but the caller owns settlement of in-flight binding calls. Do not treat timeout as “all side effects stopped”.

The short version: keep validation, execution, result, and sandbox separate; mixing them is how program failures get misreported as framework crashes.