dsh-ntr 0.3.1 → 0.3.2

package/src/impl.ts

@@ -7,10 +7,10 @@
 
 import { randomUUID } from './ids.ts'
 import type {
-  AcpAgentCatalog, AcpAgentDef, AcpCatalogOption, AcpApprovalDeadlines, AcpConversationChoice, AcpEvent, AcpMcpServerDef, AcpPluginConfig, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentTestResult,
+  AcpAgentCatalog, AcpAgentDef, AcpCatalogOption, AcpApprovalDeadlines, AcpConversationChoice, AcpEvent, AcpIdleRelease, AcpMcpServerDef, AcpPluginConfig, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentTestResult,
   AgentView, ApprovalDeadlineKey, ApprovalDeadlinePatch, ChatSessionView, ChatTranscriptView, DetectedAgentInfo, PermissionOptionView, PermissionOutcome, PermissionTimeoutMode, PluginUpdateState, RpcResult,
 } from './protocol.ts'
-import { DEFAULT_TAG_HALO } from './protocol.ts'
+import { DEFAULT_IDLE_TIMEOUT_MS, DEFAULT_TAG_HALO, IDLE_RELEASE_MS } from './protocol.ts'
 
 export { randomUUID }
 
@@ -175,6 +175,21 @@ export function validateApprovalDeadlines(value: unknown): Partial<Record<Approv
   return out
 }
 
+/**
+ * Validate the idle-release window the settings page writes.
+ *
+ * The window is expressed in MILLISECONDS on the shared ladder
+ * ({@link IDLE_RELEASE_MS}), so a value the slider can produce is always a
+ * value the host runs — the same one-ladder rule the approval deadline card
+ * follows.
+ */
+export function validateIdleReleaseMs(raw: unknown, code: 'bad_config' | 'bad_payload'): number {
+  if (typeof raw !== 'number' || !Number.isInteger(raw) || !IDLE_RELEASE_MS.includes(raw)) {
+    throw new AcpError(code, `acp: idleTimeoutMs must be one of ${IDLE_RELEASE_MS.join(', ')}`)
+  }
+  return raw
+}
+
 /**
  * Validate the mode a write asks for. Three values, and the list is the whole
  * vocabulary: an unanswered ask is either answered for you, kept waiting, or
@@ -523,6 +538,14 @@ export function validateConfig(raw: unknown): AcpPluginConfig {
   // `abort` a zero window would refuse every ask on arrival — the agent stops
   // at every gate — so it becomes the shortest real wait.
   const effectivePermissionTimeoutMs = normalizeApprovalWindow(permissionTimeoutMode, permissionTimeoutMs)
+  // The chat-process idle-release window (the settings page edits it).
+  // Same shape as the per-agent field: 0 = never release, otherwise an
+  // integer number of milliseconds.
+  const idleTimeoutMs = value.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS
+  if (typeof idleTimeoutMs !== 'number' || !Number.isInteger(idleTimeoutMs)
+    || idleTimeoutMs > 86_400_000 || (idleTimeoutMs !== 0 && idleTimeoutMs < 1_000)) {
+    throw new AcpError('bad_config', 'acp: idleTimeoutMs must be 0 (never release) or an integer in [1000, 86400000]')
+  }
   const cancelFallbackMs = value.cancelFallbackMs ?? 15_000
   if (typeof cancelFallbackMs !== 'number' || !Number.isInteger(cancelFallbackMs) || cancelFallbackMs < 0 || cancelFallbackMs > 600_000) {
     throw new AcpError('bad_config', 'acp: cancelFallbackMs must be an integer in [0, 600000] (0 = disable the fallback)')
@@ -564,6 +587,7 @@ export function validateConfig(raw: unknown): AcpPluginConfig {
     turnStallMs,
     turnStallToolMs,
     turnStallTickMs,
+    idleTimeoutMs,
   }
 }
 
@@ -1789,6 +1813,19 @@ export interface AcpManager {
    * applies again. Applies to the running bridges without a restart.
    */
   setApprovalDeadlines?(patch: ApprovalDeadlinePatch, reset?: boolean): Promise<void>
+  /**
+   * The idle-release window in force for chat processes, plus the built-in
+   * default a reset returns to. `undefined` on a host half from before the
+   * card existed, which hides the settings tab instead of showing a number
+   * this browser invented.
+   */
+  idleRelease?(): AcpIdleRelease | undefined
+  /**
+   * Write the idle-release window (in ms), or drop the persisted
+   * override with `reset` so the built-in default applies again. Applies to
+   * the running bridges without a restart.
+   */
+  setIdleRelease?(idleTimeoutMs: number | undefined, reset?: boolean): Promise<void>
   detectAgents?(): Promise<DetectedAgentInfo[]>
   saveAgent?(def: AcpAgentDef): Promise<void>
   deleteAgent?(agentId: string): Promise<void>
@@ -1861,6 +1898,21 @@ export interface AcpManager {
    * without it the live (non-released) session is picked.
    */
   setChatSessionMode?(dshSessionId: string, modeId: string, agentId?: string): Promise<void>
+  /**
+   * Bring one chat conversation's released session back on a fresh process on
+   * the user's explicit gesture (`session/chat-resume`, the released-session
+   * banner's button). Same recovery the next prompt performs lazily, minus
+   * the create path; no-op when the session is already live.
+   */
+  resumeChatSession?(dshSessionId: string): Promise<void>
+  /**
+   * Adopt the ACP side of a branched conversation (`session/chat-fork-adopt`):
+   * the browser has already asked the HOST to fork the DSH session tree, and
+   * this runs the agent's own `session/fork` of the parent's live ACP session,
+   * then binds the child to it. All-or-nothing — nothing is bound on failure,
+   * so the child stays an ordinary copied-history conversation.
+   */
+  adoptForkedSession?(childDshSessionId: string, parentDshSessionId: string): Promise<{ sessionId: string; acpSessionId: string }>
   /**
    * Point one DSH chat conversation at an ACP agent — the plugin's own
    * conversation↔agent mapping, never a DSH model route (see
@@ -2055,6 +2107,26 @@ export async function dispatchRpc(manager: AcpManager, endpoint: string, payload
         await manager.setChatSessionMode?.(dshSessionId, modeId, optionalStr(body, 'agentId', 64))
         return ok({ done: true })
       }
+      case 'session/chat-resume': {
+        // The released-session banner's explicit resume: the recovery the next
+        // prompt performs lazily, on the user's gesture instead. Addressed by
+        // DSH chat session id, like the rest of the conversation surfaces.
+        const dshSessionId = str(body, 'dshSessionId', 128)
+        await manager.resumeChatSession?.(dshSessionId)
+        return ok({ done: true })
+      }
+      case 'session/chat-fork-adopt': {
+        // The second half of a branched conversation: bind the DSH session the
+        // host's `sessions.fork` just created to the agent's own `session/fork`
+        // of the parent's live ACP session. Both ids are validated before the
+        // optional call — the same shape rule as `session/chat-list` above.
+        // The adopted ids ride the answer (the protocol's ChatForkAdoptResult);
+        // a manager without the method keeps the plain `done` shape.
+        const dshSessionId = str(body, 'dshSessionId', 128)
+        const parentDshSessionId = str(body, 'parentDshSessionId', 128)
+        const adopted = await manager.adoptForkedSession?.(dshSessionId, parentDshSessionId)
+        return ok(adopted ?? { done: true })
+      }
       case 'session/chat-bind': {
         // Point one chat conversation at an ACP agent. The plugin's own
         // conversation↔agent mapping — NOT a DSH model route (see
@@ -2141,6 +2213,16 @@ export async function dispatchRpc(manager: AcpManager, endpoint: string, payload
         await manager.setApprovalDeadlines?.(patch, body.reset === true)
         return ok({ deadlines: manager.approvalDeadlines?.() })
       }
+      case 'ui/idle-release':
+        // Absent on a host half from before the tab existed: the browser then
+        // renders nothing rather than a number it cannot trust.
+        return ok({ idleRelease: manager.idleRelease?.() })
+      case 'ui/idle-release-set': {
+        const reset = body.reset === true
+        const idleTimeoutMs = reset ? undefined : validateIdleReleaseMs(body.idleTimeoutMs, 'bad_payload')
+        await manager.setIdleRelease?.(idleTimeoutMs, reset)
+        return ok({ idleRelease: manager.idleRelease?.() })
+      }
       case 'agent/set-exposed-models': {
         const agentId = str(body, 'agentId', 64)
         const raw = body.exposedModels

package/src/index.ts

@@ -91,6 +91,7 @@ export function apply(ctx: Context, config?: unknown): void {
       turnStallMs: resolved.turnStallMs,
       turnStallToolMs: resolved.turnStallToolMs,
       turnStallTickMs: resolved.turnStallTickMs,
+      idleTimeoutMs: resolved.idleTimeoutMs,
     },
   )
   const adapter = new AcpLlmAdapter(manager)
@@ -126,6 +127,13 @@ export function apply(ctx: Context, config?: unknown): void {
     ? rawConfig.permissionTimeoutMode
     : undefined
   manager.setConfiguredApprovalDeadlines(configuredDeadlines, configuredMode)
+
+  // The idle-release baseline the settings page's pick outranks. Only the
+  // raw value counts: `validateConfig` fills a default in, so the
+  // validated number cannot tell "the file says 10 minutes" from
+  // "the file says nothing, so 30 minutes applies".
+  const configuredIdleTimeoutMs = typeof rawConfig.idleTimeoutMs === 'number' ? rawConfig.idleTimeoutMs : undefined
+  manager.setConfiguredIdleRelease(configuredIdleTimeoutMs)
   // Boot hook kept only so this entry point's shape does not change:
   // `bootstrapCatalogs` is intentionally empty — boot never spawns an agent,
   // in any environment and for any `probeModelsOnBoot` value. Catalogs fill

package/src/protocol.ts

@@ -187,6 +187,18 @@ export interface AcpPluginConfig {
    * deployment baseline that override falls back to. See {@link AcpApprovalDeadlines}.
    */
   permissionTimeoutMs?: number
+  /**
+   * How long a chat process may sit idle before it is released (parked, then
+   * resumed by the next message). In MILLISECONDS; default 1800000 (30 min).
+   *
+   * This is the HOST DEFAULT: an agent that names its own
+   * {@link AcpAgentDef.idleTimeoutMs} keeps its own. Editable from the
+   * settings page (「进程管理」 → `ui/idle-release-set`), which persists an
+   * override in the plugin's own state file and applies it to the running
+   * bridges without restarting anything; the value here is the deployment
+   * baseline that override falls back to. See {@link AcpIdleRelease}.
+   */
+  idleTimeoutMs?: number
   /**
    * LEGACY: the old conversation-route window, kept so an existing
    * `cordis.patch.yml` still says what it meant. Folded into
@@ -490,6 +502,14 @@ export interface SessionView {
    * recover") when the agent declares the `loadSession` capability.
    */
   released?: boolean
+  /**
+   * The agent-side session has history while the local buffer is empty: the
+   * record was restored from disk after a host restart (the `session/load`
+   * replay has not landed), or a resume cleared the buffer ahead of the
+   * replay. The ACP view then says history replays on restore instead of
+   * claiming "nothing yet".
+   */
+  hasHistory?: boolean
   /** Highest transcript seq included in this snapshot (for gap detection). */
   seq: number
 }
@@ -543,8 +563,36 @@ export interface ChatSessionView {
    * agent can never see.
    */
   availableCommands?: SessionView['availableCommands']
+  /**
+   * Context occupancy the agent last reported (`usage_update`): prompt-side
+   * used/size, not request tokens. Absent until the agent reports one; the
+   * browser live-patches this row from the update frames (see AGENTS/ui.md).
+   */
+  usage?: SessionView['usage']
   /** The agent process died; the session awaits a `session/load` resume. */
   released?: boolean
+  /** The agent is running a turn on this session right now. */
+  running?: boolean
+  /**
+   * Whether this session's ACP agent can be forked (`session/fork`) into a
+   * child conversation, as the host computed it. The browser does not derive
+   * this itself — the capability is host knowledge (the agent's
+   * `initialize`), and the row is the one place it is delivered.
+   * `supported: false` carries the reason; no reason on `false` means the
+   * host half predates the field (treat as unsupported).
+   */
+  fork?: ChatSessionForkInfo
+}
+/**
+ * The host's per-row verdict on forking one chat session's ACP session
+ * (`ChatSessionView.fork`). Computed from the agent's LAST KNOWN
+ * `sessionCapabilities.fork` (persisted with the model catalog) plus the
+ * session's own state — the browser never reads capability bits itself.
+ */
+export interface ChatSessionForkInfo {
+  supported: boolean
+  /** Why {@link supported} is false: the agent cannot fork, or the session cannot be forked right now. */
+  reason?: 'unsupported' | 'released' | 'busy'
 }
 export type ChatSessionsListResult = { sessions: ChatSessionView[] }
 
@@ -668,6 +716,63 @@ export interface TagHaloSetPayload { halo: AcpTagHalo }
 /** The approval deadline the settings page can edit, by field name. ONE window. */
 export type ApprovalDeadlineKey = 'permissionTimeoutMs'
 
+/**
+ * The idle-release windows the settings page offers, in MILLISECONDS.
+ *
+ * ONE ladder, shared by both halves: the browser snaps its slider to these
+ * values and the host accepts only these values, so a window the slider can
+ * produce is always a window the host runs. The first rung is 1 minute (an
+ * aggressive release), the rest are 5-minute steps up to an hour.
+ */
+export const IDLE_RELEASE_MS: readonly number[] = [
+  60_000, 300_000, 600_000, 900_000, 1_200_000, 1_500_000, 1_800_000, 2_100_000, 2_400_000, 2_700_000, 3_000_000, 3_300_000, 3_600_000,
+]
+
+/**
+ * The built-in idle-release window for chat processes: 30 minutes.
+ *
+ * Lives beside the ladder it is a rung of, so the two cannot drift: a
+ * deployment that names no window of its own runs this, and the settings
+ * page's reset returns to it.
+ */
+export const DEFAULT_IDLE_TIMEOUT_MS = 1_800_000
+
+/**
+ * The idle-release window for chat processes, as the settings page edits it.
+ *
+ * The window is the HOST default: an agent that names its own
+ * {@link AcpAgentDef.idleTimeoutMs} keeps it, and a probe-only process (one
+ * that never hosted a session) still honors the short probe window — see
+ * `AGENTS/protocol.md` §5.
+ */
+export interface AcpIdleRelease {
+  /** The window in force, in ms. */
+  idleTimeoutMs: number
+  /**
+   * The window a RESET returns to: the deployment baseline when the config
+   * file names one, else the built-in default (30 minutes).
+   */
+  defaultIdleTimeoutMs: number
+  /**
+   * The window `cordis.patch.yml` names, when it names one. Reported only
+   * when the file actually names one: the settings card must not say "the
+   * file asks for 30 minutes" about a file that says nothing.
+   */
+  configuredIdleTimeoutMs?: number
+}
+/** `ui/idle-release`: read the idle-release window in force. */
+export type IdleReleaseResult = { idleRelease?: AcpIdleRelease }
+/**
+ * `ui/idle-release-set`: write the idle-release window, or drop the persisted
+ * override with `reset` so the built-in default applies again.
+ */
+export interface IdleReleaseSetPayload {
+  /** The window to run, in ms; omitted when `reset` is true. */
+  idleTimeoutMs?: number
+  /** Drop the persisted override so the built-in default applies again. */
+  reset?: boolean
+}
+
 /**
  * What an EXPIRED approval deadline does. Three modes, and only three — an
  * unanswered ask either gets answered for you, keeps waiting, or is refused.
@@ -752,6 +857,22 @@ export interface ChatEffortSetPayload { dshSessionId: string; effort?: string; a
 /** `session/chat-config-set`: set one of the agent's extra config options. */
 export interface ChatConfigSetPayload { dshSessionId: string; configId: string; value: string | boolean; agentId?: string }
 
+/**
+ * `session/chat-fork-adopt`: bind the DSH chat session a host `sessions.fork`
+ * just created to the SAME agent process, through the agent's own
+ * `session/fork` of the parent conversation's ACP session — the second half of
+ * the two-stage branch (host builds the DSH tree first, the plugin then adopts
+ * the ACP side; see the NTR message-actions plan, §D5/D7).
+ *
+ * On success the child conversation's next message reaches an agent that
+ * actually remembers the parent context. On failure NOTHING is bound: the
+ * child stays an ordinary copied-history conversation and its first message
+ * starts a fresh `session/new` (today's behavior).
+ */
+export interface ChatForkAdoptPayload { dshSessionId: string; parentDshSessionId: string }
+/** `session/chat-fork-adopt` success: the adopted ACP session's ids. */
+export type ChatForkAdoptResult = { sessionId: string; acpSessionId: string }
+
 /** Host-detected agent presence and tested defaults. */
 export interface DetectedAgentInfo {
   id: string