Tianyi Cui
e385c11e8e
- pty-local: a pre-write inspection rejection no longer releases a canceled send while its foreground SIGINT is in flight; the interrupt path retains the slot and its post-signal tail resumes polling. Regression pins the failure-shaped cancellation and a close-during-write release. - pty-local: SEND_ACTIVE names which provider operation is draining; README states the never-settling-provider outcome (slot retained, close recovers). - subprocess-local: resolveExecutable rejects relative paths containing separators instead of expanding them per PATH entry with a misleading not-found error; seam JSDoc pins the rule for every provider. - subprocess-local: LocalTerminalHandle documents why the seam's in-flight-join promise holds without operation tracking. - lsp-local: the oversized-source diagnostic reports the observed byte lower bound; README documents that processId: null trades away server-side orphan cleanup after a hard-killed harness. - pty/subprocess seams: cross-reference the twin five-member signal unions. - pty-local: TODO markers for send-state consolidation and initialize-race relocation.
@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
typeand return an unpublishedPtyBackendSession; failed or cancelled setup must clean partial resources, and a failed cleanup rejects withPtyBackendCleanupErrorso 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 optionalnameis 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.waitReasonandsessionStatusare independent.session_exitdescribes 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.