feat: add persistent PTY sessions

website/.vitepress/config/api-sidebar.json

@@ -62,6 +62,10 @@
       "text": "ctx.permission",
       "link": "/zh-CN/api/harness/permission"
     },
+    {
+      "text": "ctx.pty",
+      "link": "/zh-CN/api/harness/pty"
+    },
     {
       "text": "ctx.sandbox",
       "link": "/zh-CN/api/harness/sandbox"

website/zh-CN/api/harness/pty.md

@@ -0,0 +1,178 @@
+<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->
+
+# ctx.pty
+
+`PtyService` — provided by `@deepseek-ai/dsh-pty`.
+
+In-process registry for replaceable PTY backends and exact-Agent sessions.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/pty/pty/src/index.ts#L95)
+
+### ctx.pty.registerBackend(backend)
+
+```ts website-api
+/**
+ * Register one backend type for this effect scope.
+ * @param backend - provider with a non-empty unique type.
+ * @returns disposer that removes exactly this contribution.
+ */
+registerBackend(backend: PtyBackend): () => void
+```
+
+Register one backend type for this effect scope.
+
+- `backend` — provider with a non-empty unique type.
+
+**Returns** disposer that removes exactly this contribution.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/pty/pty/src/index.ts#L114)
+
+### ctx.pty.listBackends()
+
+```ts website-api
+/**
+ * List registered backend types in registration order.
+ * @returns fresh backend type names.
+ */
+listBackends(): string[]
+```
+
+List registered backend types in registration order.
+
+**Returns** fresh backend type names.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/pty/pty/src/index.ts#L132)
+
+### ctx.pty.spawn(owner, request, signal?)
+
+```ts website-api
+/**
+ * Create and publish one owner-scoped session after backend setup succeeds.
+ * @param owner - exact registered Agent that owns access and cleanup.
+ * @param request - backend type plus optional owner-local name and cwd.
+ * @param signal - cancellation of unpublished setup.
+ * @returns published identity, metadata, status, and MOTD.
+ */
+async spawn(owner: Agent, request: PtySpawnRequest, signal?: AbortSignal): Promise<PtySpawnResult>
+```
+
+Create and publish one owner-scoped session after backend setup succeeds.
+
+- `owner` — exact registered Agent that owns access and cleanup.
+- `request` — backend type plus optional owner-local name and cwd.
+- `signal` — cancellation of unpublished setup.
+
+**Returns** published identity, metadata, status, and MOTD.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/pty/pty/src/index.ts#L143)
+
+### ctx.pty.startSend(owner, id, request)
+
+```ts website-api
+/**
+ * Start one exclusive interactive send.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param request - explicit text, submit behavior, and cancellation.
+ * @returns live operation handle for foreground await or task registration.
+ */
+startSend(owner: Agent, id: PtySessionId, request: PtySendRequest): PtySendOperation
+```
+
+Start one exclusive interactive send.
+
+- `owner` — exact session owner.
+- `id` — target PTY identity.
+- `request` — explicit text, submit behavior, and cancellation.
+
+**Returns** live operation handle for foreground await or task registration.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/pty/pty/src/index.ts#L198)
+
+### ctx.pty.read(owner, id, request?)
+
+```ts website-api
+/**
+ * Read one bounded scrollback page from an owned session.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param request - optional newest-relative offset and line count.
+ * @returns bounded retained text and pagination metadata.
+ */
+read(owner: Agent, id: PtySessionId, request: PtyReadRequest = {}): PtyReadResult
+```
+
+Read one bounded scrollback page from an owned session.
+
+- `owner` — exact session owner.
+- `id` — target PTY identity.
+- `request` — optional newest-relative offset and line count.
+
+**Returns** bounded retained text and pagination metadata.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/pty/pty/src/index.ts#L218)
+
+### ctx.pty.signal(owner, id, signal)
+
+```ts website-api
+/**
+ * Deliver an allowed signal through an owned backend session.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param signal - allowed POSIX signal name.
+ * @returns delivered foreground process-group identity.
+ */
+signal(owner: Agent, id: PtySessionId, signal: PtySignal): Promise<PtySignalResult>
+```
+
+Deliver an allowed signal through an owned backend session.
+
+- `owner` — exact session owner.
+- `id` — target PTY identity.
+- `signal` — allowed POSIX signal name.
+
+**Returns** delivered foreground process-group identity.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/pty/pty/src/index.ts#L229)
+
+### ctx.pty.kill(owner, id, reason?)
+
+```ts website-api
+/**
+ * Close one owned session and remove it only after quiescent backend cleanup.
+ * @param owner - exact session owner.
+ * @param id - target PTY identity.
+ * @param reason - diagnostic cleanup reason.
+ * @returns true for a newly closed session, false when the same close is already in flight.
+ */
+async kill(owner: Agent, id: PtySessionId, reason = 'model request'): Promise<boolean>
+```
+
+Close one owned session and remove it only after quiescent backend cleanup.
+
+- `owner` — exact session owner.
+- `id` — target PTY identity.
+- `reason` — diagnostic cleanup reason.
+
+**Returns** true for a newly closed session, false when the same close is already in flight.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/pty/pty/src/index.ts#L240)
+
+### ctx.pty.list(owner)
+
+```ts website-api
+/**
+ * List fresh snapshots for exactly one owner.
+ * @param owner - exact owner whose sessions are visible.
+ * @returns owner-visible snapshots in publication order.
+ */
+list(owner: Agent): PtySessionSnapshot[]
+```
+
+List fresh snapshots for exactly one owner.
+
+- `owner` — exact owner whose sessions are visible.
+
+**Returns** owner-visible snapshots in publication order.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/pty/pty/src/index.ts#L263)