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

<!-- 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)