dsh-ntr 0.3.2 → 0.3.4

package/lib/types/client/activity-pill.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The composer dock's `x轮x步 · xx tok/s` pill on an ACP conversation.
+ *
+ * WHY SHADOW INSTEAD OF A SECOND PILL: the host's `ActivityPill` already states
+ * the two things this conversation has — turn/step counts and a whole-session
+ * decode speed — in the one place a speed belongs. Only its speed is wrong for
+ * ACP: the host divides the tokens a step emitted by `firstTokenTime →
+ * completedTime`, and that window contains every tool wait. Rendering a second
+ * speed beside it would leave two numbers on screen and no way to tell which
+ * is the honest one. So this module takes the host pill's own cell (`list` slot
+ * `conversation.composer.dock`, id `activity`) at a lower priority, renders the
+ * HOST's component, and hands it a patched `sessionStats` whose decode fields
+ * are the plugin's burst aggregate. Style, counts, dialog, aria and locale stay
+ * the host's; only the number changes.
+ *
+ * NON-ACP CONVERSATIONS PASS THROUGH. The shadow is installed only while the
+ * gate confirms the staged conversation runs the ACP preset, but a list entry
+ * is projected into EVERY session's composer. The wrapper therefore renders the
+ * host component with the ORIGINAL projection whenever `acpMode` is not
+ * affirmatively true, making the shadow visually indistinguishable from the
+ * shipped entry there.
+ *
+ * FAIL-OPEN IS STRUCTURAL: if the host entry, its inject face, its locale or
+ * its `performanceUsage` source is missing, no claim is created and the native
+ * pill stays exactly as shipped. If the host component rejects the patched
+ * projection, the slot's error boundary retires this entry and the native
+ * `activity` entry wins again. No CSS hiding and no DOM patching are involved.
+ */
+import type { SessionBurst } from '../protocol.ts';
+import type { AcpStore, UiState } from './store.ts';
+import type { ModelSeatClaim, SeatSlots } from './model-seat.tsx';
+export declare const DOCK_SLOT = "conversation.composer.dock";
+export declare const ACTIVITY_ENTRY_ID = "activity";
+type ActivityProjection = (key: string, selector?: (value: unknown) => unknown) => unknown;
+type ActivityPerformanceHook = (selector?: (value: unknown) => unknown) => unknown;
+type ActivityTranslate = (key: string, params?: Record<string, unknown>) => string;
+/** The standard kit + injected face the shadow renders the host component with. */
+export interface ActivityPillHostProps {
+    sessionId: string;
+    useChat: unknown;
+    useProjection: ActivityProjection;
+    usePerformanceUsage: ActivityPerformanceHook;
+    t?: ActivityTranslate;
+    acp: AcpStore;
+}
+/**
+ * The aggregate the dock should show: the sum of every ACP session backing this
+ * chat (the host pill's counts are whole-chat too), with a live `turn/metrics`
+ * entry preferred per session over its persisted row. `undefined` means "no
+ * measurable burst yet" — the wrapper then hides the speed instead of showing
+ * the host's tool-inclusive number.
+ */
+export declare function activityBurst(ui: Pick<UiState, 'chatSessions' | 'chatSessionsFor' | 'burstStats'>, dshSessionId: string): SessionBurst | undefined;
+/**
+ * Replace ONLY the decode half of the host's session stats.
+ *
+ * `decodeTokens` and `decodeMs` are the two fields the host's `decodeSpeed`
+ * reads (`decodeTokens / (decodeMs / 1000)`), so writing the plugin's aggregate
+ * there makes the host's own formatter, dialog row and aria label display the
+ * plugin's burst rate. Every other field — turns, steps, LLM/tool/TTFT — stays
+ * host-native. With no measurable burst the two decode fields are zeroed: the
+ * host then hides the speed (`decodeMs > 0` guard) while keeping the counts.
+ */
+export declare function patchedActivityStats(native: Record<string, unknown> | undefined, burst: SessionBurst | undefined, acp: boolean): Record<string, unknown> | undefined;
+export interface ActivityPillClaimOptions {
+    slots: SeatSlots;
+    /** Session-scoped face factory (the gate's `chatFace`). */
+    inject(sessionId: unknown, actions?: unknown): unknown;
+    onDiag?(line: string): void;
+    maxClaims?: number;
+}
+/**
+ * Take the dock's `activity` cell for one ACP-mode spell.
+ *
+ * Returns `undefined` on any host shape this bundle cannot serve — an older
+ * host without the `activity` entry (0.1.5 ships `stats`), a slot kind change,
+ * a missing inject/locale, or no `performanceUsage` source. The native pill is
+ * then left untouched; that is the honest failure mode, not a hidden control.
+ */
+export declare function createActivityPillClaim(options: ActivityPillClaimOptions): ModelSeatClaim | undefined;
+export {};

package/lib/types/client/branch-action.d.ts

@@ -21,7 +21,14 @@
  * rather than risking a fork cut at a point the user is not looking at.
  */
 import type { ComponentType } from 'react';
-import type { AcpChatInjected } from './acp-ui.tsx';
+import type { AcpChatInjected, AcpHostForkFace } from './acp-ui.tsx';
+/**
+ * Resolves the runtime's `sessions.fork` primitive, binding it to the service
+ * instance so that internal `this` accesses (such as `this.list.getSnapshot()`)
+ * resolve correctly when called through `face.fork(...)`.
+ * Returns `undefined` if the service or `fork` method is absent or not a function.
+ */
+export declare function resolveHostFork(sessionsService: unknown): AcpHostForkFace | undefined;
 /**
  * The host's own branch-button icon, picked per host generation. The icon
  * exports MOVED between shipped hosts — desktop 0.2.1-rc.2 has

package/lib/types/client/model-seat.d.ts

@@ -122,7 +122,13 @@ export interface SeatEntry {
     options?: {
         priority?: number;
         registrant?: string;
+        id?: string;
+        order?: number;
     };
+    /** Entry-owned inject face; needed when the claim reuses a shipped occupant. */
+    inject?: (...args: unknown[]) => unknown;
+    /** Locale namespace the occupant's `t` is bound to; needed for the same reuse. */
+    locale?: string;
 }
 /** The slot-registry face this module uses (structural: the registry is not a dependency of this bundle). */
 export interface SeatSlots {
@@ -142,6 +148,12 @@ export interface SeatSlots {
  */
 export interface SeatRegisterOptions {
     name: string;
+    /** List-slot cell to shadow; omitted for single/keyed registers. */
+    id?: string;
+    /** Display position within the list; only meaningful with `id`. */
+    order?: number;
+    /** Locale namespace the occupant's `t` is bound to. */
+    locale?: string;
     priority?: number;
     /**
      * The session-scoped face factory the renderer calls with the scope binding's
@@ -218,6 +230,15 @@ export interface PermissionSeatClaimOptions {
 export interface SeatClaimOptions {
     slots: SeatSlots;
     slotKey: string;
+    /**
+     * List-slot cell id to hold. Omitted for single/keyed seats; a list slot
+     * needs it because its winner view is one entry PER id, not one per slot.
+     */
+    entryId?: string;
+    /** Display order for the installed list entry (same cell, so usually the shipped order). */
+    order?: number;
+    /** Locale namespace the installed occupant resolves `t` against. */
+    locale?: string;
     basePriority: number;
     occupant(): unknown;
     inject?(sessionId: unknown, actions?: unknown): unknown;

package/lib/types/client/store.d.ts

@@ -254,6 +254,16 @@ export interface UiState {
     chatSessions: ChatSessionView[];
     /** The DSH chat session id {@link chatSessions} was loaded for. */
     chatSessionsFor?: string;
+    /**
+     * Live burst aggregate per ACP session id, from `turn/metrics`. Absent means
+     * no measured burst yet; a row's persisted `burst` is the reload seed.
+     */
+    burstStats: Record<string, {
+        outputTokens: number;
+        burstMs: number;
+        turnId: string;
+        final: boolean;
+    }>;
     /**
      * The agent tag's halo preference (settings-editable display choice). The
      * tag reads it per render; the host answer in `resync` is the authority and

package/lib/types/impl.d.ts

@@ -248,6 +248,14 @@ export declare function childEnv(parent: NodeJS.ProcessEnv, extra: Record<string
  * anything unusable is skipped silently.
  */
 export declare function parseCatalogOptions(configOptions: unknown): AcpAgentCatalog;
+/**
+ * Whether a payload names ONE model selector without relying on category
+ * alone. When an agent publishes several `category: 'model'` options and none
+ * is explicitly the `model` id, the category is not trustworthy enough to
+ * reject the user's pick — callers must fail open instead of reporting
+ * `model_unavailable`.
+ */
+export declare function hasUnambiguousModelSelector(configOptions: unknown): boolean;
 /**
  * Fold one per-session option answer's SHAPE into an agent-level catalog.
  *
@@ -446,10 +454,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';
 } | {
@@ -468,19 +508,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. */
@@ -552,7 +598,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;
@@ -664,7 +719,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>;

package/lib/types/protocol.d.ts

@@ -485,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;
@@ -523,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;
@@ -554,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;
     /**
@@ -639,6 +659,8 @@ export interface ChatSessionView {
      * 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. */

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.2",
+  "version": "0.3.4",
   "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",