deepseek-harness/packages/pty/pty/README.md

@deepseek-ai/dsh-pty

English | 中文

Owner-scoped persistent PTY seam. PtyService registers as ctx.pty, mints opaque session ids, routes creation through named backends, fences every operation to the exact live Agent, and awaits backend quiescence when that agent or the service disposes.

Contract

• Backends register one stable type and return an unpublished PtyBackendSession; failed or cancelled setup must clean partial resources, and a failed cleanup rejects with PtyBackendCleanupError so the registry can retain it across cancellation.
• Spawn cancellation preserves the caller's exact abort reason. Service disposal and owner loss remain distinct machine-routable failures after backend setup.
• Owner and service disposal abort unpublished setup through a service-owned signal and await backend settlement plus rollback before returning.
• A rollback-close or backend-reported startup cleanup failure rejects the disposing lifecycle instead of claiming quiescence. Caller-triggered cancellation still receives its exact reason; lifecycle-triggered rollback failure also rejects the pending spawn.
• A backend cleanup failure that follows caller cancellation remains owner activity until owner or service disposal consumes and reports it, so lifecycle policy cannot mistake failed cleanup for quiescence.
• hasOwnerActivity(owner) spans unpublished setup through final close, so lifecycle policy can fence the exact owner without a publication race.
• A successful spawn publishes one PtySessionId. The optional name is owner-local display metadata, never authority.
• One session accepts at most one live send operation. Reads and signals may observe it; another send fails until the operation settles.
• PtySendResult.waitReason and sessionStatus are independent. session_exit describes the top-level PTY process, not an arbitrary foreground command.
• kill() and disposal resolve only after the backend's captured process tree is quiescent. A cleanup failure rejects instead of claiming success and clears the matching backend and registry fences so a later close can retry without disturbing a newer attempt.

The seam contains no node-pty, sandbox, tool-schema, prompt, task, or terminal-rendering policy. Implementations own terminal mechanics; consumers own model presentation and optional background-task registration.

Model Experience

Indirect consumer

What the model sees

Nothing directly. This package registers no prompt or tool; @deepseek-ai/dsh-tool-pty owns visible schemas and result text.

Token effect

None directly. Live session state stays process-local until a consumer returns a bounded result.

KV Cache effect

No direct invalidation; the named consumer owns request-prefix changes.

Known Limitations and Deferred Work

• Sessions are process-local and are not restored after a harness restart.
• Cross-agent sharing is intentionally absent; a future shared-session design needs a separate authority contract.