dsh-ntr 0.1.5 → 0.2.0

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

@@ -2,11 +2,11 @@
  * React surface for ACP: the settings configuration section.
  *
  * Scope is deliberately narrow — this is a CONFIGURATION surface. Runtime
- * interaction lives in the conversation: permission asks are answered in the
- * chat composer through the host approval chain. The ledger card answers
- * whatever did NOT reach the conversation — a host without the chain, a
- * session with no chat identity behind it, or an ask whose native route
- * degraded to unavailable (see `permissionLedgerCard`).
+ * interaction lives in the conversation: every permission ask with a chat
+ * identity is answered on a card above that conversation's composer
+ * (`permission-dock.tsx`). The ledger card here is the cross-session mirror —
+ * asks whose conversation is not open, or which have no chat identity at all —
+ * and is where those are answered (see `permissionLedgerCard`).
  *
  * Each configured agent is one compact row (status + current model + badges)
  * that expands into the full connection form and model catalog. The row stays
@@ -15,7 +15,7 @@
  * All business state lives in the injected AcpStore.
  */
 import type { AcpStore, UiState } from './store.ts';
-import type { AcpAgentDef, AgentSavePayload, AgentView, DetectedAgentInfo } from '../protocol.ts';
+import type { AcpAgentDef, AcpApprovalDeadlines, AgentSavePayload, AgentView, DetectedAgentInfo, PermissionTimeoutMode } from '../protocol.ts';
 interface WithStore {
     acp: AcpStore;
 }
@@ -30,22 +30,61 @@ export declare function payloadEquals(payload: AgentSavePayload, current: AcpAge
 /**
  * The settings panel's permission-ledger rule.
  *
- * A pending ask ALWAYS gets an answerable card here, whatever `approvalRouted`
- * says. That flag reports that the host HAS an approval service — it does not
- * promise THIS ask reached the conversation. An ask lands in `ui.permissions`
- * only on the ledger path (`AgentBridge.handlePermissionRequest` broadcasts
- * `permission/request` there and nowhere else), so a pending entry is by
- * definition a question the conversation is not showing. The previous rule
- * (`approvalRouted` → a read-only count, no buttons) hid the only answer
- * entry exactly when the native route had degraded to unavailable, and the
- * ask then hung until its timeout.
- *
- * `fellBackFromConversation` is the case the card has to explain: the host
- * can route asks, and this one still did not make it.
+ * Pending asks are shown in the conversation card while that conversation is
+ * open; this card is the cross-session mirror for the ones it cannot show —
+ * asks belonging to another conversation, and `/acp` RPC-only asks with no
+ * chat identity at all. It therefore appears whenever ANY ask is pending: a
+ * pending entry with no conversation card would otherwise have no answer
+ * surface anywhere.
  */
-export declare function permissionLedgerCard(ui: Pick<UiState, 'approvalRouted' | 'permissions'>): {
+export declare function permissionLedgerCard(ui: Pick<UiState, 'permissions'>): {
     visible: boolean;
-    fellBackFromConversation: boolean;
+};
+/**
+ * The shortest REAL wait — the first rung above 不等待.
+ *
+ * Hand-copied from the host half (`APPROVAL_DEADLINE_MIN_WAIT_MS` in
+ * `src/impl.ts`): the browser half may not import the host module, so the
+ * equivalence is pinned by a test instead (see `tests/acp-view.spec.ts`).
+ */
+export declare const DEADLINE_MIN_WAIT_MS = 30000;
+/**
+ * The window the card shows under a mode.
+ *
+ * 不等待 (`0`) is the **auto** mode's rung: it answers with the option the
+ * agent's own kinds imply, so the agent CONTINUES. `abort` has no such rung —
+ * refusing every ask the instant it arrives stops the agent at every gate it
+ * meets, which is not a timeout but a wall. So under `abort` the window floors
+ * to the shortest real wait, and the card never shows a zero it cannot run.
+ *
+ * `undefined` (the `wait` mode) stays undefined: there is no window at all.
+ */
+export declare function deadlineValueFor(mode: PermissionTimeoutMode, ms: number | undefined): number | undefined;
+/**
+ * The rung the slider shows for a window. Exact hits keep their rung; anything
+ * else takes the nearest one. A tie goes to the SHORTER wait: the thumb must
+ * never promise more patience than the window has.
+ */
+export declare function deadlineSliderIndex(ms: number, mode?: PermissionTimeoutMode): number;
+/**
+ * The facts the card has to show, decided from what the host reported.
+ *
+ * The card carries TWO controls, and they are orthogonal: one window (how
+ * long) and one mode (what happens). An override can sit on either of them,
+ * so each is decided on its own.
+ *
+ * `overridden` is what gates the reset button. A baseline that AGREES with the
+ * running value is not an override, and offering a reset for it would be a
+ * button that does nothing (observed live).
+ */
+export declare function approvalDeadlineFacts(deadlines: AcpApprovalDeadlines): {
+    /** The config-file window the card's window outranks — undefined when
+     *  nothing is being outranked. */
+    baseline: number | undefined;
+    /** The config-file mode the card's mode outranks, when it differs. */
+    modeBaseline: PermissionTimeoutMode | undefined;
+    /** A reset is only honest when something is actually being outranked. */
+    overridden: boolean;
 };
 /** Settings configuration section for ACP agents. */
 export declare function AcpSettingsSection(props: WithStore): import("react").JSX.Element;

package/lib/types/client/permission-dock.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pending ACP permission asks for the staged DSH conversation, rendered as
+ * composer-width entries above the composer card (`conversation.input.dock`).
+ * The slot itself spans the conversation column; the dock mirrors the host's
+ * InputBar width formula so the cards line up with the input box.
+ *
+ * The host broadcasts every ask as `permission/request`, carrying the DSH chat
+ * session id when the ask belongs to a conversation. This dock is the primary
+ * answer surface: it renders exactly the asks whose `dshSessionId` is the
+ * conversation it was mounted for, and nothing otherwise. There is no
+ * ACP-mode gate — the frame set itself is the gate, so an ordinary
+ * conversation shows this card if and only if it actually has an ask.
+ *
+ * The ask's description and options are the agent's own: buttons appear in the
+ * agent's order with the agent's names (including "Always Allow"), and
+ * `kind` is not rendered. A separate cancel button answers with no option,
+ * which the host forwards as `cancelled`. No Enter/Escape handlers: the
+ * composer owns its keyboard, and these are ordinary focusable buttons.
+ *
+ * Multiple asks stack in ARRIVAL order, oldest first: the question ignored
+ * longest stays at the top. The list is capped in height by CSS and scrolls.
+ * Asks without a chat identity never appear here — they stay in the
+ * settings-panel ledger, the cross-session mirror.
+ */
+import type { AcpStore } from './store.ts';
+export interface PermissionDockProps {
+    /** Injected face: the store plus the chat session id this dock belongs to. */
+    acp: AcpStore;
+    sessionId: string;
+}
+export declare function PermissionDock({ acp, sessionId }: PermissionDockProps): import("react").JSX.Element | null;

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

@@ -5,7 +5,7 @@
  *
  * Deliberately framework-free: React binds through `useSyncExternalStore`.
  */
-import type { AcpApprovalDeadlines, AcpConversationChoice, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentSavePayload, AgentTestResult, AgentView, ChatSessionView, ApprovalDeadlineKey, DetectedAgentInfo, SessionView } from '../protocol.ts';
+import type { AcpApprovalDeadlines, AcpConversationChoice, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentSavePayload, AgentTestResult, AgentView, ChatSessionView, DetectedAgentInfo, PermissionTimeoutMode, SessionView } from '../protocol.ts';
 /** One slash command the ACP agent declared, whole row (the menu draws name, description and `input.hint`). */
 export type AgentCommand = NonNullable<ChatSessionView['availableCommands']>[number];
 /** The unary RPC face (narrowed `ctx.connection.rpc.call`). */
@@ -84,16 +84,49 @@ export type Block = {
     tone: 'info' | 'error';
     text: string;
 };
+/**
+ * One permission ask waiting for a human. Every field is copied VERBATIM from
+ * the host's `permission/request` frame: the host owns what the ask is called
+ * (`toolName` / `reason`), which options the agent offered (order included),
+ * and whether the ask carries a deadline. The browser does not derive a title
+ * from `toolCall` and does not second-guess the agent's option labels.
+ */
 export interface PendingPermission {
     requestId: string;
+    /** ACP session id. */
     sessionId: string;
-    title: string;
+    /** DSH chat session id; absent for `/acp` RPC-only sessions (settings-only ask). */
+    dshSessionId?: string;
+    toolName: string;
+    reason?: string;
     options: Array<{
         optionId: string;
         name: string;
         kind: string;
     }>;
+    timeoutMode: PermissionTimeoutMode;
+    /** Epoch ms; absent in `wait` mode. */
+    deadlineAt?: number;
 }
+/** Returned by {@link deadlineRemainingLabel} once the deadline has passed. */
+export declare const PERMISSION_DEADLINE_EXPIRED = "expired";
+/**
+ * The asks that belong to one DSH chat conversation. An ask without a
+ * `dshSessionId` belongs to no conversation (an `/acp` RPC-only session), so it
+ * is deliberately absent from every conversation's dock and stays in the
+ * settings-panel ledger.
+ */
+export declare function permissionsForSession(permissions: readonly PendingPermission[], dshSessionId: string): PendingPermission[];
+/**
+ * Compact countdown for one ask, or `undefined` when there is nothing to count
+ * down (`wait` mode, or a frame without a deadline). Pure so the formatting is
+ * testable without a clock: the dock passes `Date.now()` on its tick.
+ *
+ * Past the deadline the answer is {@link PERMISSION_DEADLINE_EXPIRED} rather
+ * than a negative number — the host has already armed the expiry, and a card
+ * counting backwards would claim a deadline that no longer exists.
+ */
+export declare function deadlineRemainingLabel(deadlineAt: number | undefined, now: number, mode: PermissionTimeoutMode): string | undefined;
 /**
  * One observed ACP transcript, keyed by ACP session id. This is the ACP view
  * tab's data source: the native chat plane can only render text/reasoning
@@ -164,17 +197,6 @@ export interface UiState {
      * that never answers, …) reads as a dead button.
      */
     probeErrors: Record<string, string>;
-    /**
-     * Host reports that it HAS the native approval chain (permission asks are
-     * answered in the chat composer). This is a capability report, not a
-     * per-ask promise: an individual ask still falls back to the settings-panel
-     * ledger when the service is unavailable this time, or when the session has
-     * no chat identity behind it (`AgentBridge.askNativeApproval`). The panel
-     * therefore answers ANY pending ask, whatever this flag says — see
-     * `permissionLedgerCard` in panel.tsx. False on an older host or when the
-     * approval service is missing, in which case the ledger is the only path.
-     */
-    approvalRouted: boolean;
     /**
      * ACP agent sessions backing the chat session the composer control sits in.
      * Only meaningful together with {@link chatSessionsFor}: the control reads it
@@ -556,6 +578,14 @@ export declare class AcpStore {
     /** Mirror the running flag onto a transcript the ACP view is showing. */
     private markWatchedRunning;
     setConfigOption(configId: string, value: string): Promise<void>;
+    /**
+     * Answer one ask (`optionId` absent = cancel it). A failure is reported
+     * through the store's notice — the settings panel renders that — AND
+     * rethrown, so the conversation dock can pin the message next to the card
+     * that failed instead of leaving it on a settings page the user may not
+     * have open. Callers that cannot show it (the settings panel) swallow it
+     * after the notice.
+     */
     respondPermission(requestId: string, optionId?: string): Promise<void>;
     stopAgent(agentId: string): Promise<void>;
     /**
@@ -572,7 +602,7 @@ export declare class AcpStore {
      */
     setTagHalo(halo: AcpTagHalo): Promise<void>;
     /**
-     * Write one approval deadline (settings card), or drop the persisted override
+     * Write the approval deadline (settings card), or drop the persisted override
      * with `reset` so the `cordis.patch.yml` baseline applies again.
      *
      * The host answer — the same route returns the deadlines now in force — is the
@@ -580,7 +610,14 @@ export declare class AcpStore {
      * merged with a value this browser did not know about) self-corrects instead
      * of drifting from what runs.
      */
-    setApprovalDeadline(key: ApprovalDeadlineKey, ms: number): Promise<void>;
+    setApprovalDeadline(ms: number): Promise<void>;
+    /**
+     * Write the mode: what an expired deadline DOES (`abort` refuses, `auto`
+     * answers with the option the agent's own kinds imply, `wait` never
+     * expires). Same write path as the window, so the host answer stays
+     * the authority.
+     */
+    setApprovalTimeoutMode(mode: PermissionTimeoutMode): Promise<void>;
     /** Drop the persisted override: the config file (or the built-in default) decides again. */
     resetApprovalDeadlines(): Promise<void>;
     private writeApprovalDeadlines;

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, ChatSessionView, ChatTranscriptView, DetectedAgentInfo, PermissionOptionView, PermissionOutcome, RpcResult } from './protocol.ts';
+import type { AcpAgentCatalog, AcpAgentDef, AcpApprovalDeadlines, AcpConversationChoice, AcpEvent, AcpMcpServerDef, AcpPluginConfig, AcpPresetStatus, AcpTagHalo, AgentCatalogResult, AgentProbeModelsResult, AgentTestResult, AgentView, ApprovalDeadlineKey, ApprovalDeadlinePatch, ChatSessionView, ChatTranscriptView, DetectedAgentInfo, PermissionOptionView, PermissionOutcome, PermissionTimeoutMode, 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 {
@@ -35,6 +35,36 @@ export declare function validateTagHalo(value: unknown): AcpTagHalo;
  * longer would be a mis-typed number rather than a deliberate window.
  */
 export declare const APPROVAL_DEADLINE_MAX_MS = 86400000;
+/**
+ * The shortest REAL wait: the first rung of the card's ladder (30 seconds).
+ *
+ * The floor for a mode that must not wait zero — see
+ * {@link normalizeApprovalWindow}.
+ */
+export declare const APPROVAL_DEADLINE_MIN_WAIT_MS = 30000;
+/**
+ * Make a window legal for the mode it runs under.
+ *
+ * `0` means 不等待 — the ask is settled the moment it arrives instead of
+ * waiting. That is the **auto** mode's business: `auto` answers with the
+ * option the agent's own kinds imply, so the agent CONTINUES, and an
+ * unattended deployment gets a sane default instead of a hang.
+ *
+ * Under `abort` the same zero would refuse every ask the instant it arrived:
+ * the agent stops at every gate it meets, which is not a timeout, it is a
+ * brick wall. So `abort` never offers 不等待, and a window of `0` reaching it
+ * (a config file, a state file written by an older build, a mode switch that
+ * left the window behind) normalizes to the shortest real wait.
+ *
+ * `wait` ignores the window entirely — it never expires.
+ */
+export declare function normalizeApprovalWindow(mode: PermissionTimeoutMode, ms: number): number;
+/**
+ * The order `auto` mode picks an option in, by the kind the agent declared:
+ * the broadest grant first, then the narrow one, then the refusals, then
+ * whatever the agent offered instead. See {@link pickAutoOption}.
+ */
+export declare const AUTO_OPTION_KIND_PRIORITY: readonly ["allow_always", "allow_once", "reject_once", "reject_always"];
 /**
  * Validate ONE approval deadline, shared by every layer that accepts one.
  *
@@ -48,10 +78,32 @@ export declare const APPROVAL_DEADLINE_MAX_MS = 86400000;
 export declare function validateApprovalDeadlineMs(raw: unknown, label: string, code: 'bad_config' | 'bad_payload', hint: string): number;
 /**
  * Validate a settings-page deadline write. Omitted keys are simply absent from
- * the result — the manager merges, so a card that only touched one slider must
- * not reset the other. `reset` is not a deadline and is dropped here.
+ * the result — the manager merges, so a card that only moved the mode must not
+ * reset the number. `reset` is not a deadline and is dropped here.
  */
 export declare function validateApprovalDeadlines(value: unknown): Partial<Record<ApprovalDeadlineKey, 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
+ * refused. Anything else is a typo, not a new mode.
+ */
+export declare function validatePermissionTimeoutMode(raw: unknown, code: 'bad_config' | 'bad_payload'): PermissionTimeoutMode;
+/**
+ * The option an expired deadline answers with in `auto` mode.
+ *
+ * The pick is by the option's KIND, because that is what the agent declared
+ * about the choice it is offering: `allow_always` first (one grant covers the
+ * rest of the run), then `allow_once` (the smaller grant), then the reject
+ * kinds (refuse but let the agent continue), and finally the first option
+ * whatever it is — an agent may offer only a custom kind, and refusing to
+ * answer at all would hang the turn.
+ *
+ * `undefined` means NO option could be read (no options, or none with a usable
+ * id). The caller then degrades to `abort`: guessing an option is worse than
+ * refusing, and hanging is worse than either. OmniTerm dev picks the same way
+ * (`pick_auto_option`, `src/acp/permission.rs`).
+ */
+export declare function pickAutoOption(options: readonly PermissionOptionView[]): PermissionOptionView | undefined;
 /**
  * Validate one agent's `mcpServers` list (the plugin's normalized shape, NOT
  * the ACP wire shape).
@@ -509,6 +561,21 @@ export declare class EventHub {
     subscribe(sink: (event: AcpEvent) => void): () => void;
     broadcast(event: AcpEvent): void;
 }
+/** Everything a `permission/request` frame carries besides the ids the ledger owns. */
+export interface PendingPermissionFields {
+    /** DSH chat session id; absent for `/acp` RPC-only sessions. */
+    dshSessionId?: string;
+    toolCall: unknown;
+    /** Host-derived human name (`permissionToolName`). */
+    toolName: string;
+    /** One-line detail from the agent's declared input, when it has any. */
+    reason?: string;
+    options: PermissionOptionView[];
+    /** What an unanswered ask does when its deadline fires. */
+    timeoutMode: PermissionTimeoutMode;
+    /** Epoch ms of the deadline; absent in `wait` mode (no deadline). */
+    deadlineAt?: number;
+}
 export interface PendingPermission {
     requestId: string;
     sessionId: string;
@@ -518,17 +585,12 @@ export interface PendingPermission {
      * client receives (see `permissionReplayFrames`). Absent on entries created
      * without a view — those still answer, they just cannot be re-shown.
      */
-    view?: {
-        toolCall: unknown;
-        options: PermissionOptionView[];
-    };
+    view?: PendingPermissionFields;
 }
 /** One outstanding ask as a reconnecting client must be re-shown it. */
-export interface PendingPermissionView {
+export interface PendingPermissionView extends PendingPermissionFields {
     requestId: string;
     sessionId: string;
-    toolCall: unknown;
-    options: PermissionOptionView[];
 }
 export declare class PermissionLedger {
     private readonly pending;
@@ -551,6 +613,16 @@ export declare class PermissionLedger {
      */
     pendingViews(): PendingPermissionView[];
 }
+/**
+ * The `permission/request` frame for one ask.
+ *
+ * ONE builder for both the live broadcast and the reconnect replay, so the two
+ * can never drift: a client that reconnects must receive exactly the frame the
+ * live one carried (its conversation card filters on `dshSessionId` and shows
+ * `toolName` / `deadlineAt`, so a replay missing them would silently drop the
+ * ask).
+ */
+export declare function permissionRequestFrame(view: PendingPermissionView): AcpEvent;
 /**
  * Frames that re-establish a freshly connected client's view of the pending
  * permission asks: every outstanding ask re-sent as its original
@@ -558,10 +630,10 @@ export declare class PermissionLedger {
  *
  * Why a replay at all: a `permission/request` is broadcast ONCE, when the ask is
  * created. A client that connects later — page reload, second tab, stream
- * outage — never receives it, and for a ledger ask (the `/acp` RPC path, or a
- * native route that degraded) that card is the ONLY answer entry, so the ask is
- * invisible to exactly the client that needs it. OmniTerm closes the same hole
- * with `PermissionManager::pending_events()` + a `PermissionsSynced` marker on
+ * outage — never receives it, and that card (conversation or settings ledger)
+ * is the ONLY answer entry for the ask, so the ask is invisible to exactly the
+ * client that needs it. OmniTerm closes the same hole with
+ * `PermissionManager::pending_events()` + a `PermissionsSynced` marker on
  * every WS connect.
  *
  * Why the terminator is mandatory: the replay is a snapshot, so an ask resolved
@@ -607,18 +679,18 @@ export interface AcpManager {
     /** Write the halo preference (persisted with the agent registry). */
     setTagHalo?(halo: AcpTagHalo): Promise<void>;
     /**
-     * The approval deadlines in force, with the facts that explain an override
-     * (the `cordis.patch.yml` baseline it outranks, and a `permissionTimeoutMs`
-     * that overrides both). `undefined` on a host half from before the card
-     * existed, which hides the settings card instead of guessing a value.
+     * The approval deadline in force, with the facts that explain an override
+     * (the `cordis.patch.yml` baseline it outranks). `undefined` on a host half
+     * from before the card existed, which hides the settings card instead of
+     * guessing a value.
      */
     approvalDeadlines?(): AcpApprovalDeadlines | undefined;
     /**
-     * Write one or both approval deadlines (omitted keys keep their value), or
-     * drop the persisted override with `reset` so the config-file baseline
+     * Write the approval deadline, or the mode (omitted keys keep their value),
+     * or drop the persisted override with `reset` so the config-file baseline
      * applies again. Applies to the running bridges without a restart.
      */
-    setApprovalDeadlines?(patch: Partial<Record<ApprovalDeadlineKey, number>>, reset?: boolean): Promise<void>;
+    setApprovalDeadlines?(patch: ApprovalDeadlinePatch, reset?: boolean): Promise<void>;
     detectAgents?(): Promise<DetectedAgentInfo[]>;
     saveAgent?(def: AcpAgentDef): Promise<void>;
     deleteAgent?(agentId: string): Promise<void>;
@@ -654,12 +726,6 @@ export interface AcpManager {
      * cache (newly published models appear, withdrawn ones drop out).
      */
     cachedAgentModels?(agentId: string): AgentProbeModelsResult | undefined;
-    /**
-     * True when ACP permission asks are routed to the host's native approval
-     * service (answered in the chat composer) instead of the settings-panel
-     * ledger. Read-only capability report for `agents/list`.
-     */
-    approvalRouting?(): boolean;
     /**
      * ACP agent sessions backing one DSH chat session (looked up by chat session
      * id), so the composer can offer the agent's OWN mode list. Empty when no