deepseek-harness/packages/workflow/workflow-ptc/README.md

---

description: "Run workflow orchestration through the shared sandboxed PTC Node process runtime, with workflow hooks, subagent routing and caller-owned cancellation."

kind: "package-reference"

@deepseek-ai/dsh-workflow-ptc

English | 中文

Summary

Run JavaScript workflows in fresh Node processes under the calling Session's file sandbox policy. Scripts keep the agent(), parallel(), pipeline(), phase() and log() hooks while subagents perform delegated work. The same execution provider serves PTC and workflows, including the opt-in Ralph loop. Runs have no overall elapsed deadline; cancellation stops the managed process and disposes child agents. The selected sandbox and subprocess providers determine enforcement and cleanup limits.

Table of Contents

• Use this package
• Understand the implementation
• Further Exploration
• Model Experience
• Known Limitations and Deferred Work
• Dev Note

---

Use this package

Mount this engine in a composition that provides subagents, sandbox policy and the Node PTC runtime. It supplies workflow execution for dsh-tool-workflow and for dsh-tool-ralph when explicitly enabled. Ralph remains disabled in shipped defaults. The engine rejects non-TypeScript PTC providers when it loads. Python PTC compositions must disable the workflow-ptc, tool-workflow and any enabled tool-ralph rows.

Minimal configuration

With those dependencies available, mount the engine and its model-facing consumer:

- name: '@deepseek-ai/dsh-workflow-ptc'
- name: '@deepseek-ai/dsh-tool-workflow'

Field	Default	Meaning
provider	spawn	Host-side subagent provider used by agent() calls.
maxConcurrentAgents	0	Concurrent agent() ceiling; 0 resolves from available CPU parallelism.
maxTotalAgents	1000	Total agent() calls one run may start.
maxItemsPerCall	4096	Items accepted by one parallel() or pipeline() call.
syncTimeoutMs	5000	VM timeout for the script's initial synchronous slice, in milliseconds.

An owning consumer may set WorkflowStartRequest.subagentProvider and lower WorkflowStartRequest.maxTotalAgents for one run. Script hooks cannot change either choice. Process heap, output, control and termination limits belong to the Node PTC provider; the engine adds no overall elapsed timer. The generated configuration catalog defines accepted engine fields.

The Node PTC provider's maxPendingCalls also limits workflow concurrency: child startup, result waits and disposal use those slots. Progress batches use at most one additional slot. Leave headroom when setting maxConcurrentAgents.

Results and failures

The script runs with top-level await; meta and args arrive as JSON data. Every agent() call uses the configured subagent provider and the run's fixed parent. The final lossless-JSON return value becomes the run result; an ordinary child failure resolves agent() to null.

Invalid metadata, an unparseable body, an unavailable provider route or a per-run cap above the ceiling is rejected before a run is published. During execution, hook misuse and tripped cooperative caps fail the workflow. Process failures, unavailable required confinement and PTC output or control limits also fail the run.

File policy and cancellation

The engine resolves the calling Session's standing file policy and cwd for PTC execution. The VM retains the documented helper API, but it is not a security boundary: code that reaches Node remains subject to the selected OS file policy. The program-visible environment is empty. Network access is not restricted by the file policy.

The workflow requests timeoutMs: null from PTC. Its initial VM slice still has syncTimeoutMs, and a caller's abort signal still applies, including an enclosing tool deadline. Cancellation immediately aborts the PTC process and pending or active subagents. The caller must dispose every run and await child cleanup; there is no separate workflow cleanup timer.

---

Understand the implementation

Implementation internals — click to expand

The workflow engine owns orchestration; the PTC provider owns process launch, OS confinement, framed transport and managed process cleanup. ### Design concept One self-contained guest program runs the existing VM and workflow helpers inside a PTC Node process. Host bindings connect that program to `ctx.subagents` and workflow observers. The engine captures the runtime and subagent services when a run starts, so an accepted run retains its dependencies through engine unload. ### Source map | File | Role | |---|---| | [`src/index.ts`](src/index.ts) | Engine configuration, request validation and run creation | | [`src/host.ts`](src/host.ts) | PTC execution, child ownership, settlement and disposal | | [`src/guest.ts`](src/guest.ts) | Guest adapter over PTC host bindings | | [`src/guest-source.ts`](src/guest-source.ts) | Self-contained guest program source | | [`src/runtime.ts`](src/runtime.ts) | VM evaluation, helper contracts and combinators | | [`src/realm.ts`](src/realm.ts) | Lossless-JSON materialization across VM realms | | [`src/meta.ts`](src/meta.ts) | Metadata validation and normalization | | — | No runtime invariant companion is published; the workflow service owns event pairing and PTC owns managed-process observations. | ### Values and child ownership The guest materializes outbound values as lossless JSON before PTC transport. Exotic prototypes, functions, symbols, cycles, sparse arrays, non-finite numbers and nested `undefined` are rejected. Child results cross back as JSON; same-process observer events retain their own cloning and callback-containment rules. The host tracks pending provider starts separately from published children. A shared abort signal closes both paths; a child that becomes ready after cancellation is disposed. Each published child's disposal is shared by all cleanup paths. In-flight host bindings remain the workflow adapter's responsibility after PTC stops the program. ### Cancellation and outcomes The first accepted terminal outcome owns the run result. Cancellation stops the process immediately rather than waiting for a guest acknowledgement. Process settlement and child cleanup remain separate obligations; public disposal waits for both. Existing workflow start/end pairing and child lifecycle projection remain intact.

---

Further Exploration

Use these references for the shared execution guarantees and workflow contracts.

• Workflow subsystem — request, result and event definitions.
• Workflow service — caller-owned runs and cleanup.
• Node PTC runtime — file policy, process limits and deployment choices.
• workflow tool — model-facing scripted orchestration.
• Ralph tool — opt-in fixed fresh-agent iteration.
• Workflow sandbox reuse — execution ownership and tradeoffs.

---

Model Experience

Child-agent requests

What the model sees

Every script agent() call sends its prompt verbatim and optional model or structured-output schema to a subagent provider. Each child sees that provider's own context; phase and log narration stays on observer events.

Token effect

Each child consumes its own model context. Cooperative concurrency, total-agent and item caps limit ordinary script fan-out; child histories do not join the parent history directly.

KV Cache effect

Independent of the parent request cache and of sibling children. Each child can reuse only a byte-identical prefix under its own provider, model, prompt and schema.

Parent tool result, indirectly

What the model sees

The tool consumer presents the final JSON value and child count, or a workflow failure. Intermediate child outputs remain available to the script. Script parsing, helper misuse, child infrastructure failures and PTC execution failures produce errors; ordinary child failure produces null for the script to handle.

Token effect

The engine adds no direct parent tokens. PTC bounds the outer program result, and the tool consumer owns its model-facing rendering and retention.

KV Cache effect

Append-only; newly visible content follows the reusable request prefix.

Known Limitations and Deferred Work

These limits qualify workflow execution and cleanup.

• File confinement and cleanup inherit provider limits — the Node PTC and subprocess providers define enforcement completeness and the managed process range.
• Workflow caps are cooperative — helper counters limit ordinary scripts; they are not host-enforced security quotas or descendant token budgets.
• No overall elapsed deadline — a run can remain active until it completes, fails or is cancelled. Caller deadlines still apply.
• Child cleanup follows provider contracts — the adapter awaits disposal and pending starts without a separate abandonment timer.
• The VM is not a security boundary — withheld globals guide script authors; OS policy governs code that reaches Node.
• Cross-realm errors fail instanceof Error inside scripts — branch on stable fields such as name and code.

Dev Note

Working context for maintainers — click to expand

None.