dsh-ntr 0.3.1 → 0.3.3

package/lib/types/impl.d.ts

@@ -5,7 +5,7 @@
  * fakes.
  */
 import { randomUUID } from './ids.ts';
-import type { AcpAgentCatalog, AcpAgentDef, AcpApprovalDeadlines, AcpConversationChoice, AcpEvent, AcpMcpServerDef, AcpPluginConfig, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentTestResult, AgentView, ApprovalDeadlineKey, ApprovalDeadlinePatch, ChatSessionView, ChatTranscriptView, DetectedAgentInfo, PermissionOptionView, PermissionOutcome, PermissionTimeoutMode, PluginUpdateState, RpcResult } from './protocol.ts';
+import type { AcpAgentCatalog, AcpAgentDef, 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';
 export { randomUUID };
 /** Structured failure the RPC layer converts to `{ok:false, error}` and `apply()` surfaces at boot. */
 export declare class AcpError extends Error {
@@ -82,6 +82,15 @@ export declare function validateApprovalDeadlineMs(raw: unknown, label: string,
  * reset the number. `reset` is not a deadline and is dropped here.
  */
 export declare function validateApprovalDeadlines(value: unknown): Partial<Record<ApprovalDeadlineKey, number>>;
+/**
+ * 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 declare function validateIdleReleaseMs(raw: unknown, code: 'bad_config' | 'bad_payload'): number;
 /**
  * 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
@@ -437,10 +446,42 @@ export declare function describeUnhandledUpdate(kind: string, update: Record<str
  * injected context too (goal/subagent/skill material), and that turn carries no
  * user intent to send anywhere.
  */
+export interface PromptImageContent {
+    type: 'image';
+    data: string;
+    mimeType: string;
+    uri?: string;
+}
+export interface PromptTextContent {
+    type: 'text';
+    text: string;
+}
+export type PromptContentBlock = PromptTextContent | PromptImageContent;
+/** Helper: guess MIME type from file extension or URL */
+export declare function guessImageMimeType(pathOrUrl?: string): string | undefined;
+/** Helper: parse Data URI */
+export declare function parseImageDataUrl(url: string): {
+    data: string;
+    mimeType: string;
+} | undefined;
+export declare function isLocalFilePath(str: string): boolean;
+export declare function normalizeFileUrlToPath(uri: string): string;
+/**
+ * Detect image MIME type by examining binary magic numbers.
+ * Supports Buffer, Uint8Array, and base64 strings.
+ */
+export declare function detectImageMimeFromMagic(raw: Buffer | Uint8Array | string | undefined): string | undefined;
+export declare function resolveImageAttachmentFromContext(id: string, context?: unknown, attachmentMeta?: unknown, rootContext?: unknown): unknown;
+/**
+ * Extract an image payload (Base64 data + MIME type) from an image block and optional context.
+ */
+export declare function resolveImageContent(block: unknown, context?: unknown): PromptImageContent | undefined;
 export type ForwardPromptSelection = {
     kind: 'prompt';
     text: string;
     id?: string;
+    images?: PromptImageContent[];
+    content?: PromptContentBlock[];
 } | {
     kind: 'no-user-input';
 } | {
@@ -459,19 +500,25 @@ export type ForwardPromptSelection = {
  * (tests, headless callers) and counts as user input.
  *
  * @param messages - the request's ordered messages, exactly as the host built them.
- * @returns the last real user message's text, or why there is none to forward.
+ * @param context - optional host context or attachment resolver for reading attachments.
+ * @returns the last real user message's text and any image content blocks, or why there is none to forward.
  */
 export declare function selectForwardPrompt(messages: readonly {
     role: string;
-    content?: Array<{
+    content?: string | Array<{
         type?: string;
         text?: string;
-    }>;
+        [k: string]: unknown;
+    }> | {
+        type?: string;
+        text?: string;
+        [k: string]: unknown;
+    };
     source?: {
         kind?: string;
     };
     id?: string;
-}[]): ForwardPromptSelection;
+}[], context?: unknown): ForwardPromptSelection;
 /** Structural read of ACP `ToolCall.kind`; anything unexpected stays `undefined` (= effect unknown). */
 export declare function permissionToolKind(toolCall: unknown): string | undefined;
 /** Structural read of ACP `ToolCall.locations[].path` — where an edit claims it will write. */
@@ -543,7 +590,16 @@ export interface RosterPresetRow {
  * @returns the status, or `undefined` when the roster is unreadable.
  */
 export declare function acpPresetStatusFromRoster(rows: readonly RosterPresetRow[] | undefined, id: string): AcpPresetStatus | undefined;
-/** Bounded append-only log of raw ACP session updates with monotone seq. */
+/**
+ * Bounded log of raw ACP session updates with monotone seq.
+ *
+ * Consecutive ticks of the same state-only kind share one entry (the entry is
+ * replaced in place, not appended): chatty agents emit a usage / phase tick
+ * every few hundred milliseconds, and letting each occupy the ring evicts the
+ * conversation itself. This costs nothing on the live path — `append` still
+ * allocates a fresh seq and the bridge broadcasts that frame — but replay via
+ * `since` only sees the newest tick of each run.
+ */
 export declare class Transcript {
     private readonly max;
     private readonly entries;
@@ -655,7 +711,7 @@ export interface AcpManager {
     startSession(agentId: string, cwd: string | undefined): Promise<{
         sessionId: string;
     }>;
-    prompt(sessionId: string, text: string): Promise<{
+    prompt(sessionId: string, prompt: string | PromptContentBlock[]): Promise<{
         turnId: string;
     }>;
     cancel(sessionId: string): Promise<void>;
@@ -698,6 +754,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>;
@@ -770,6 +839,24 @@ 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

package/lib/types/protocol.d.ts

@@ -178,6 +178,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
@@ -473,6 +485,17 @@ export type AcpEvent = {
     sessionId: string;
     turnId: string;
     text: string;
+} | {
+    type: 'turn/metrics';
+    /** ACP session id (the store keys live burst state by it). */
+    sessionId: string;
+    /** DSH chat session id (routing/context only). */
+    dshSessionId: string;
+    turnId: string;
+    /** Session aggregate INCLUDING the current turn when measurable. */
+    outputTokens: number;
+    burstMs: number;
+    final: boolean;
 } | {
     type: 'turn/end';
     sessionId: string;
@@ -511,6 +534,13 @@ export type PermissionOutcome = {
 } | {
     outcome: 'cancelled';
 };
+/** Plugin-side measurable burst aggregate for one ACP session (not host turn timings). */
+export interface SessionBurst {
+    /** Sum of estimated output tokens over measurable turns. */
+    outputTokens: number;
+    /** Sum of within-burst chunk gaps over those turns; tool/approval/long pauses excluded. */
+    burstMs: number;
+}
 /** Derived session snapshot for replay/reconnect (source of truth stays in the transcript). */
 export interface SessionView {
     sessionId: string;
@@ -542,6 +572,8 @@ export interface SessionView {
             currency: string;
         };
     };
+    /** Measurable burst aggregate over this session's turns; absent until measured. */
+    burst?: SessionBurst;
     running: boolean;
     closed: boolean;
     /**
@@ -550,6 +582,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;
 }
@@ -613,8 +653,38 @@ 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'];
+    /** Measurable burst aggregate over this session's turns; absent until measured. */
+    burst?: SessionView['burst'];
     /** 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[];
@@ -770,6 +840,60 @@ export interface TagHaloSetPayload {
 }
 /** 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 declare const IDLE_RELEASE_MS: readonly number[];
+/**
+ * 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 declare const DEFAULT_IDLE_TIMEOUT_MS = 1800000;
+/**
+ * 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.
@@ -868,6 +992,27 @@ export interface ChatConfigSetPayload {
     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;

package/lib/types/tps.d.ts

@@ -0,0 +1,17 @@
+/** ACP `usage_update` is context occupancy, not request tokens; this is the plugin's 4-chars/token OUTPUT estimate (tool args excluded). */
+export declare const OUTPUT_CHARS_PER_TOKEN = 4;
+export declare const BURST_GAP_MS = 1000;
+export interface TurnTpsSnapshot {
+    outputTokens: number;
+    burstMs: number;
+}
+export declare class TurnTpsTracker {
+    private readonly gapMs;
+    private lastProseAt;
+    private outputChars;
+    private burstMs;
+    constructor(gapMs?: number);
+    onProse(text: string, at: number): void;
+    onBreak(): void;
+    snapshot(): TurnTpsSnapshot;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ntr",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Interactive Agent Client Protocol (ACP) client for the DSH web UI: attach any ACP-capable agent and stream its session.",
   "repository": "https://github.com/GDWhisper/dsh-ntr.git",
   "type": "module",
@@ -72,6 +72,7 @@
         "@deepseek-ai/dsh-client-connection",
         "@deepseek-ai/dsh-client-ui-conversation",
         "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-ui-primitives",
         "@deepseek-ai/dsh-client-ui-settings",
         "@deepseek-ai/dsh-client-ui-sidebar",
         "@deepseek-ai/dsh-client-ui-slots"