dsh-plugin-dev-kb 1.6.0 → 1.8.1

package/kb/site/en/reference/subsystems/terminal.md

@@ -1,188 +1,188 @@
----
-editSource: "docs/subsystems/terminal.md"
-rawMarkdownPath: "en/reference/subsystems/terminal.md"
-outline: [2,3]
----
-
-# Persistent PTY Sessions
-
-Types shared by PTY backends, `ctx.terminals`, and the model-facing consumer. The [persistent PTY Agent Note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) owns the rationale; this page records the cross-package vocabulary from [`packages/terminal/terminal/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/terminal/terminal/src/types.ts).
-
-## Identity and readiness
-
-`TerminalSessionId` is a service-minted branded id. Optional names are owner-local display metadata; authorization compares the exact owning `Agent`, not a name or guessed id.
-
-`TerminalWaitReason` says why one send returned. It is independent from `TerminalSessionStatus`: silence or timeout may return while the top-level shell remains alive, while `session_exit` means that shell exited rather than an arbitrary foreground child.
-
-```ts type-equiv
-/** Why one interactive send returned control to its caller. */
-type TerminalWaitReason = 'stdin_read' | 'inferred_idle' | 'timeout' | 'session_exit'
-```
-
-```ts type-equiv
-/** Top-level PTY process status, independent of a send's wait reason. */
-type TerminalSessionStatus =
-  | { kind: 'running' }
-  | { kind: 'exited'; exitCode: number | null; signal: NodeJS.Signals | null }
-```
-
-## Backend and live session
-
-A backend owns how one registered type starts and detects readiness. `TerminalSessionService` publishes the returned session only after setup succeeds, then owns id authorization and cleanup. A backend that cannot clean partial startup resources rejects with `TerminalBackendCleanupError`, allowing disposal to retain the cleanup failure without replacing the caller's cancellation reason. A backend session owns terminal state and captured-resource quiescence.
-
-```ts type-equiv
-/** Replaceable provider for one PTY session type. */
-interface TerminalBackend {
-  /** Stable type selected by {@link TerminalSpawnRequest.type}. */
-  readonly type: string
-  /** Create an unpublished session or reject after cleaning partial resources; cleanup failure uses {@link TerminalBackendCleanupError}. */
-  spawn(spec: TerminalBackendSpawnSpec): Promise<TerminalBackendSession>
-}
-```
-
-```ts type-equiv
-/** Backend-owned live session retained by {@link TerminalSessionService}. */
-interface TerminalBackendSession {
-  /** Initial bounded terminal output returned from `terminal_open`. */
-  readonly motd: string
-  /** Top-level process id when one exists. */
-  readonly pid?: number
-  /** Start one exclusive send operation. */
-  startSend(request: TerminalSendRequest): TerminalSendOperation
-  /** Read one bounded page from retained scrollback. */
-  read(request: TerminalReadRequest): TerminalReadResult
-  /** Signal the verified foreground process group. */
-  signal(signal: TerminalSignal): Promise<TerminalSignalResult>
-  /** Observe top-level process status. */
-  status(): TerminalSessionStatus
-  /** Idempotently close the captured owned process tree and await quiescence. */
-  close(reason: string): Promise<void>
-}
-```
-
-## Send and retained output
-
-One live session accepts one active send. Its operation exposes a consuming output cursor for generic background jobs and one terminal result for a foreground caller. `TerminalReadResult` separately pages the bounded session scrollback.
-
-```ts type-equiv
-/** Live backend-owned send; exactly one may be active per PTY session. */
-interface TerminalSendOperation {
-  /** Resolves after readiness, timeout, cancellation, or top-level process exit. */
-  done: Promise<TerminalSendResult>
-  /** Consume output produced since the prior call. */
-  readOutput(): TerminalSendRead
-  /** Request `SIGINT`; returns false after the operation settled. */
-  cancel(): boolean
-}
-```
-
-```ts type-equiv
-/** Settled result for one foreground or background send. */
-interface TerminalSendResult {
-  /** Bounded rendered terminal delta remaining at settlement. */
-  viewport: string
-  /** Why the wait returned; this does not imply arbitrary child-process exit. */
-  waitReason: TerminalWaitReason
-  /** Top-level session status observed at settlement. */
-  sessionStatus: TerminalSessionStatus
-  /** Whether output was dropped from the operation or retained scrollback. */
-  truncated: boolean
-}
-```
-
-## Ownership and durability
-
-`TerminalSessionService` attaches one awaited cleanup to the exact owner scope, rejects foreign operations, and keeps sessions alive across backend or tool-plugin reload. PTY state and raw bytes remain process-local. Model input and bounded returned output are durable through the existing `tool/call`, `tool/result`, and task-result paths rather than duplicate PTY session events.
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxterminals--terminalsessionservice"></a>
-
-### `ctx.terminals` — `TerminalSessionService`
-
-In-process registry for replaceable PTY backends and exact-Agent sessions.
-
-```ts cordis-catalog
-/**
- * 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: TerminalBackend): () => void
-
-/**
- * List registered backend types in registration order.
- * @returns fresh backend type names.
- */
-listBackends(): string[]
-
-/**
- * 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: TerminalSpawnRequest, signal?: AbortSignal): Promise<TerminalSpawnResult>
-
-/**
- * Test whether an exact owner has a published session or unpublished spawn.
- * @param owner - exact live owner to inspect.
- * @returns true across the entire spawn-to-close interval, with no publication gap.
- */
-hasOwnerActivity(owner: Agent): boolean
-
-/**
- * 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: TerminalSessionId, request: TerminalSendRequest): TerminalSendOperation
-
-/**
- * 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: TerminalSessionId, request: TerminalReadRequest = {}): TerminalReadResult
-
-/**
- * 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: TerminalSessionId, signal: TerminalSignal): Promise<TerminalSignalResult>
-
-/**
- * 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: TerminalSessionId, reason: string = 'model request'): Promise<boolean>
-
-/**
- * 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): TerminalSessionSnapshot[]
-```
-
-Types: [Agent](./core.md)
-
-Source: [`packages/terminal/terminal/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/terminal/terminal/src/index.ts)
-<!-- END GENERATED cordis-surface -->
+---
+editSource: "docs/subsystems/terminal.md"
+rawMarkdownPath: "en/reference/subsystems/terminal.md"
+outline: [2,3]
+---
+
+# Persistent PTY Sessions
+
+Types shared by PTY backends, `ctx.terminals`, and the model-facing consumer. The [persistent PTY Agent Note](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) owns the rationale; this page records the cross-package vocabulary from [`packages/terminal/terminal/src/types.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/terminal/terminal/src/types.ts).
+
+## Identity and readiness
+
+`TerminalSessionId` is a service-minted branded id. Optional names are owner-local display metadata; authorization compares the exact owning `Agent`, not a name or guessed id.
+
+`TerminalWaitReason` says why one send returned. It is independent from `TerminalSessionStatus`: silence or timeout may return while the top-level shell remains alive, while `session_exit` means that shell exited rather than an arbitrary foreground child.
+
+```ts type-equiv
+/** Why one interactive send returned control to its caller. */
+type TerminalWaitReason = 'stdin_read' | 'inferred_idle' | 'timeout' | 'session_exit'
+```
+
+```ts type-equiv
+/** Top-level PTY process status, independent of a send's wait reason. */
+type TerminalSessionStatus =
+  | { kind: 'running' }
+  | { kind: 'exited'; exitCode: number | null; signal: NodeJS.Signals | null }
+```
+
+## Backend and live session
+
+A backend owns how one registered type starts and detects readiness. `TerminalSessionService` publishes the returned session only after setup succeeds, then owns id authorization and cleanup. A backend that cannot clean partial startup resources rejects with `TerminalBackendCleanupError`, allowing disposal to retain the cleanup failure without replacing the caller's cancellation reason. A backend session owns terminal state and captured-resource quiescence.
+
+```ts type-equiv
+/** Replaceable provider for one PTY session type. */
+interface TerminalBackend {
+  /** Stable type selected by {@link TerminalSpawnRequest.type}. */
+  readonly type: string
+  /** Create an unpublished session or reject after cleaning partial resources; cleanup failure uses `TerminalBackendCleanupError`. */
+  spawn(spec: TerminalBackendSpawnSpec): Promise<TerminalBackendSession>
+}
+```
+
+```ts type-equiv
+/** Backend-owned live session retained by {@link TerminalSessionService}. */
+interface TerminalBackendSession {
+  /** Initial bounded terminal output returned from `terminal_open`. */
+  readonly motd: string
+  /** Top-level process id when one exists. */
+  readonly pid?: number
+  /** Start one exclusive send operation. */
+  startSend(request: TerminalSendRequest): TerminalSendOperation
+  /** Read one bounded page from retained scrollback. */
+  read(request: TerminalReadRequest): TerminalReadResult
+  /** Signal the verified foreground process group. */
+  signal(signal: TerminalSignal): Promise<TerminalSignalResult>
+  /** Observe top-level process status. */
+  status(): TerminalSessionStatus
+  /** Idempotently close the captured owned process tree and await quiescence. */
+  close(reason: string): Promise<void>
+}
+```
+
+## Send and retained output
+
+One live session accepts one active send. Its operation exposes a consuming output cursor for generic background jobs and one terminal result for a foreground caller. `TerminalReadResult` separately pages the bounded session scrollback.
+
+```ts type-equiv
+/** Live backend-owned send; exactly one may be active per PTY session. */
+interface TerminalSendOperation {
+  /** Resolves after readiness, timeout, cancellation, or top-level process exit. */
+  done: Promise<TerminalSendResult>
+  /** Consume output produced since the prior call. */
+  readOutput(): TerminalSendRead
+  /** Request `SIGINT`; returns false after the operation settled. */
+  cancel(): boolean
+}
+```
+
+```ts type-equiv
+/** Settled result for one foreground or background send. */
+interface TerminalSendResult {
+  /** Bounded rendered terminal delta remaining at settlement. */
+  viewport: string
+  /** Why the wait returned; this does not imply arbitrary child-process exit. */
+  waitReason: TerminalWaitReason
+  /** Top-level session status observed at settlement. */
+  sessionStatus: TerminalSessionStatus
+  /** Whether output was dropped from the operation or retained scrollback. */
+  truncated: boolean
+}
+```
+
+## Ownership and durability
+
+`TerminalSessionService` attaches one awaited cleanup to the exact owner scope, rejects foreign operations, and keeps sessions alive across backend or tool-plugin reload. PTY state and raw bytes remain process-local. Model input and bounded returned output are durable through the existing `tool/call`, `tool/result`, and task-result paths rather than duplicate PTY session events.
+
+<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
+
+<a id="cordis-surface"></a>
+
+## Cordis API
+
+Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
+
+<a id="ctxterminals--terminalsessionservice"></a>
+
+### `ctx.terminals` — `TerminalSessionService`
+
+In-process registry for replaceable PTY backends and exact-Agent sessions.
+
+```ts cordis-catalog
+/**
+ * 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: TerminalBackend): () => void
+
+/**
+ * List registered backend types in registration order.
+ * @returns fresh backend type names.
+ */
+listBackends(): string[]
+
+/**
+ * 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: TerminalSpawnRequest, signal?: AbortSignal): Promise<TerminalSpawnResult>
+
+/**
+ * Test whether an exact owner has a published session or unpublished spawn.
+ * @param owner - exact live owner to inspect.
+ * @returns true across the entire spawn-to-close interval, with no publication gap.
+ */
+hasOwnerActivity(owner: Agent): boolean
+
+/**
+ * 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: TerminalSessionId, request: TerminalSendRequest): TerminalSendOperation
+
+/**
+ * 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: TerminalSessionId, request: TerminalReadRequest = {}): TerminalReadResult
+
+/**
+ * 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: TerminalSessionId, signal: TerminalSignal): Promise<TerminalSignalResult>
+
+/**
+ * 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: TerminalSessionId, reason: string = 'model request'): Promise<boolean>
+
+/**
+ * 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): TerminalSessionSnapshot[]
+```
+
+Types: [Agent](./core.md)
+
+Source: [`packages/terminal/terminal/src/index.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/terminal/terminal/src/index.ts)
+<!-- END GENERATED cordis-surface -->

package/kb/site/en/reference/subsystems/token-meter.md

@@ -57,6 +57,44 @@ interface TokenSurfaceNode {
 
 Surface order is authoritative; replacement nodes can have higher durable seqs than later positional nodes. The snapshot is immutable and does not grow when the underlying replay fold advances.
 
+## `ContextPressureProjection`
+
+`ctx.tokenMeter.contextPressure(session)` synchronously reads the latest logged `pressureTokens` and `contextWindow`; the client projection also derives `projectedTokens` from surface changes. These display values do not price a new request; use `measure()` for request pricing.
+
+Source: [`packages/llm/token-meter/src/projection.ts`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/token-meter/src/projection.ts)
+
+```ts type-equiv
+/**
+ * Approximate context occupancy for a status display.
+ *
+ * The fields, when present, are deliberately NOT one atomic request
+ * observation: each is a last-wins record of a different moment. Switching
+ * models can therefore pair a fresh capacity with the previous route's
+ * pressure until the next request reports usage. This is an intentional trade
+ * — the value is a user-facing reference, not a billing or gating input. See
+ * the token-meter README for the full rationale.
+ */
+interface ContextPressureProjection {
+  /**
+   * Provider-reported prompt size of the most recent request: uncached input
+   * plus cache reads and writes. Response output is excluded, so this does not
+   * grow as the current turn streams. Absent until a provider reports usage.
+   */
+  pressureTokens?: number
+  /**
+   * What the NEXT request's prompt would cost: {@link pressureTokens} plus the
+   * heuristic repricing of everything the surface gained or lost since that
+   * sample. Only the delta is estimated, so the figure stays anchored to the
+   * provider while still reacting the moment a compaction shadows a span —
+   * which `pressureTokens` alone cannot do, since compaction reports no usage
+   * of its own. Absent until a provider reports usage.
+   */
+  projectedTokens?: number
+  /** Newest recorded route capacity; absent when no adapter advertised one. */
+  contextWindow?: number
+}
+```
+
 <!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
 
 <a id="cordis-surface"></a>
@@ -72,6 +110,13 @@ Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnp
 Replay owner for one service-wide estimator and isolated per-session folds.
 
 ```ts cordis-catalog
+/**
+ * Read the latest logged provider prompt size and route capacity.
+ * @param session - Session whose committed usage and request capacity are read.
+ * @returns context pressure; fields remain absent until their source events are recorded.
+ */
+contextPressure(session: Session): Pick<ContextPressureProjection, 'pressureTokens' | 'contextWindow'>
+
 /**
  * Measure current request pressure and surface through the durable tail.
  *