@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/agent-view.js

@@ -0,0 +1,153 @@
+/**
+ * Agent view derivation helpers — pure functions over
+ * session events that the channel folds into {@link AgentViewRow}s. Kept in
+ * their own module so the focused regression (`scripts/verify-agent-view.mjs`)
+ * can import them without spinning up a composition.
+ *
+ * @module dsh-cli/agent-view
+ */
+/** Agent-view row ordering: needs-input first, stopped last. */
+export const AGENT_VIEW_STATUS_ORDER = [
+    'needs-input', 'working', 'failed', 'completed', 'idle', 'stopped',
+];
+/** How long a row summary may be before the UI truncates it. */
+export const AGENT_VIEW_SUMMARY_LIMIT = 160;
+/** The row name's budget: the fallback name is the first prompt compressed
+ *  to this many cells, keeping the session list compact. */
+export const AGENT_VIEW_NAME_LIMIT = 28;
+/** Collapse every whitespace run (including newlines) into one space so a
+ *  multi-paragraph reply always renders as a single row line. */
+export function oneLine(text) {
+    return text.replace(/\s+/gu, ' ').trim();
+}
+/** The first non-empty text block of a user/assistant message content. */
+export function agentViewTextOf(content) {
+    if (typeof content === 'string') {
+        const trimmed = content.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    if (!Array.isArray(content))
+        return undefined;
+    for (const block of content) {
+        if (block === null || typeof block !== 'object')
+            continue;
+        const record = block;
+        if (record['type'] !== 'text')
+            continue;
+        const text = record['text'];
+        if (typeof text === 'string' && text.trim().length > 0)
+            return text.trim();
+    }
+    return undefined;
+}
+/** True when any of the events is a human user message. */
+export function agentViewHasTurns(events) {
+    return events.some(event => event.type === 'user/message');
+}
+/**
+ * Fold events `[start, end)` into `base` and return the combined result.
+ * @param events - The append-only session log.
+ * @param start - First index to fold (the previously folded length).
+ * @param base - The fold the cache already holds.
+ * @returns The extended fold.
+ */
+export function foldAgentViewEvents(events, start, base) {
+    const fold = { ...base };
+    for (let i = start; i < events.length; i += 1) {
+        const event = events[i];
+        fold.updatedAt = event.time;
+        switch (event.type) {
+            case 'user/message': {
+                fold.hasTurns = true;
+                const text = agentViewTextOf(event.data.content);
+                if (fold.firstPrompt.length === 0 && text !== undefined)
+                    fold.firstPrompt = oneLine(text);
+                // The prompt stands in for the summary only until the session
+                // starts doing something (a tool call or assistant text replaces it).
+                if (fold.summaryKind === 'none' && text !== undefined) {
+                    fold.summary = oneLine(text);
+                    fold.summaryKind = 'prompt';
+                }
+                break;
+            }
+            case 'assistant/message': {
+                const text = agentViewTextOf(event.data.message.content);
+                if (text !== undefined) {
+                    fold.summary = oneLine(text);
+                    fold.summaryKind = 'assistant';
+                }
+                break;
+            }
+            case 'tool/call': {
+                // The current activity beats the prompt it was answering; assistant
+                // text beats a tool call.
+                if (fold.summaryKind === 'none' || fold.summaryKind === 'prompt') {
+                    fold.summary = String(event.data.name);
+                    fold.summaryKind = 'tool';
+                }
+                break;
+            }
+            case 'session/title': {
+                const title = event.data.title;
+                if (typeof title === 'string' && title.trim().length > 0)
+                    fold.title = oneLine(title);
+                break;
+            }
+            case 'turn/end': {
+                const reason = event.data.reason;
+                fold.lastTurnFailed = reason?.kind === 'error';
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return fold;
+}
+/** The trailing exchanges of a live session's in-memory log. */
+export function agentViewLivePreview(events, limit) {
+    const entries = [];
+    for (let i = events.length - 1; i >= 0 && entries.length < limit; i -= 1) {
+        const event = events[i];
+        if (event.type === 'user/message') {
+            const text = agentViewTextOf(event.data.content);
+            if (text !== undefined)
+                entries.push({ role: 'user', text, at: event.time });
+        }
+        else if (event.type === 'assistant/message') {
+            const text = agentViewTextOf(event.data.message.content);
+            if (text !== undefined)
+                entries.push({ role: 'assistant', text, at: event.time });
+        }
+    }
+    return entries.reverse();
+}
+/** A row title when the session never recorded one: the opening prompt's
+ *  opening words, else the working directory's basename. */
+export function sessionTitleFallback(fold, cwd) {
+    const source = fold.firstPrompt.length > 0 ? fold.firstPrompt : fold.summary;
+    if (source.length > 0) {
+        const clipped = source.length <= AGENT_VIEW_NAME_LIMIT
+            ? source
+            : `${source.slice(0, AGENT_VIEW_NAME_LIMIT - 1)}…`;
+        return clipped;
+    }
+    const base = (cwd ?? '').length > 0 ? (cwd ?? '').split('/').filter(Boolean).at(-1) ?? '' : '';
+    return base.length > 0 ? base : 'untitled';
+}
+/**
+ * The agent-view state for a live agent: a parked approval wins over a
+ * running turn, a failed last turn over completion, and a conversation-less
+ * idle agent stays plain idle.
+ */
+export function agentViewStatusOf(liveStatus, fold, needsInput) {
+    if (needsInput)
+        return 'needs-input';
+    if (liveStatus === 'running')
+        return 'working';
+    if (fold.lastTurnFailed)
+        return 'failed';
+    if (fold.hasTurns)
+        return 'completed';
+    return 'idle';
+}

package/lib/types/dsh-adapter/approvals.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Approval store — the UI-side answerer half of the DSH approval seam
+ * (`ctx.approval`). The harness's permission layer asks
+ * `ApprovalService.request()`, which dispatches an `approval/request`
+ * waterfall; the listener registered in plugin.ts parks the request here,
+ * surfaces one ask at a time to the TUI permission prompt, and settles the
+ * harness promise when the user decides, the
+ * asker's abort signal fires, or the plugin tears down.
+ *
+ * Queue semantics mirror QuestionStore: parallel tool calls can trigger
+ * several asks before any answer is given, so asks are drained FIFO.
+ * Outcomes are the protocol's closed set — `'allowed-once'` and
+ * `'rejected'` from the panel, `'cancelled'` on abort/teardown; there is
+ * no allow-always or feedback channel in the protocol.
+ */
+import { compositionRoot } from './host-access.js';
+import { type AdapterRuntimeOptions } from '../adapter/kernel/runtime.js';
+import type { ApprovalOutcome, ApprovalRequest } from '@deepseek-ai/dsh-user-approval';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** What the TUI renders while an approval is pending. */
+export interface ApprovalSnapshot {
+    /** Stable key so the panel remounts (fresh focus state) per request. */
+    readonly key: string;
+    readonly toolName: string;
+    /** The asker's human-readable explanation, when given. */
+    readonly reason?: string;
+    /** The gated command, recovered from the paired tool/call event. */
+    readonly command?: string;
+    /**
+     * The request is not anchored to a live tool call of this session (no or
+     * unknown callId, the paired call already settled, or the callId is
+     * already in flight or consumed by another ask — a genuine approval is
+     * asked exactly once per call). A duplicate callId marks EVERY ask on it
+     * (the pre-existing one included — attacker-first order) so the verdict
+     * can never invert onto the genuine ask). The approval waterfall is an in-process event
+     * any plugin can dispatch, so the panel renders a loud warning instead of
+     * presenting the text as the agent's own pending command. Verdicts that
+     * depend on the session log are re-checked while the ask is queued or on
+     * the panel, so they may also appear late — once a same-callId sibling
+     * ask is allowed and its tool/result lands (P-4). The in-flight dedup
+     * verdict, by contrast, is determined at park() and needs no result to
+     * land.
+     */
+    readonly external?: true;
+    /**
+     * The asking agent's session id — `String(channel.agentId)` for the
+     * attached session, something else for a background session's ask (the
+     * agent view parks those too, so unattended sessions surface as
+     * "needs input" instead of hanging on a fail-closed answer).
+     */
+    readonly agentId: string;
+}
+/** Host-only registration used by the TUI plugin bootstrap. */
+export declare function bindApprovalStore(ctx: Parameters<typeof compositionRoot>[0], store: ApprovalStore): void;
+/** Host-only lookup used by the presentation Port bridge. */
+export declare function getApprovalStore(ctx: Parameters<typeof compositionRoot>[0]): ApprovalStore | undefined;
+/**
+ * Approval store: parks asks from the harness's approval seam, surfaces
+ * one at a time to the TUI, and settles each ask when the user decides or
+ * the ask is withdrawn. The TUI subscribes for re-renders and decides via
+ * {@link ApprovalStore.decide}.
+ */
+export declare class ApprovalStore {
+    private readonly runtime;
+    constructor(runtime?: AdapterRuntimeOptions);
+    private readonly queue;
+    private active;
+    private readonly listeners;
+    private seq;
+    /**
+     * Cached snapshot: useSyncExternalStore requires a stable reference while
+     * nothing changed (a fresh object per call would loop re-renders).
+     */
+    private snapshotCache;
+    /**
+     * Length of the session log at the last liveness evaluation of the active
+     * ask. Events only append, so an unchanged length means no verdict can
+     * have flipped — re-checks below this guard are skipped.
+     */
+    private externalCheckedAtEvents;
+    private notifyQueued;
+    /**
+     * CallIds whose approval ask already settled (decided or cancelled).
+     * Together with the in-flight set this closes the park-after-decide gap:
+     * the first ask leaves the queue while its tool is still executing (the
+     * callId still reads live), so a twin parked in that window would dodge
+     * both the in-flight dedup and the liveness check. A consumed callId
+     * never legitimately comes back: the permission layer asks once per call.
+     * Fails toward the badge — a hypothetical genuine re-ask after a cancel
+     * shows the warning, never the reverse. Evicted when the paired
+     * tool/result lands (after that the liveness check marks the twin
+     * anyway), keeping the set bounded to in-flight tool executions.
+     * Keys are agent-scoped (`agentId::callId`): the store outlives agent
+     * switches (/resume, /new) and low-entropy callIds (provider fallback
+     * `call-<index>`) repeat across sessions — a bare-callId key would badge
+     * the next session's genuine ask with the previous session's residue.
+     */
+    private readonly consumedCallIds;
+    /**
+     * Subscribe to store changes (useSyncExternalStore contract).
+     * @param listener - Called after every mutation that changes the snapshot.
+     * @returns An unsubscribe function removing the listener.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * The approval the TUI should render now, or null when idle. Re-checks the
+     * active ask's source badge against the current session log (see
+     * {@link refreshActiveExternal}) so a badge that flips while the ask is on
+     * the panel surfaces without waiting for another store mutation.
+     * @returns The cached snapshot; the reference is stable between mutations.
+     */
+    getSnapshot(): ApprovalSnapshot | null;
+    /**
+     * Session ids of every agent with a parked ask (active plus queued) — the
+     * agent view's "needs input" signal. Deduplicated, in park order.
+     * @returns One id per asking agent, or an empty array when none waits.
+     */
+    pendingAgentIds(): readonly string[];
+    /**
+     * The first parked ask's detail for one agent — the agent view's row
+     * summary while it needs input (the question it is blocked on).
+     * @param agentId - The asking session's id.
+     * @returns The ask's reason / gated command / tool name, or undefined
+     *   when the agent has no parked ask.
+     */
+    pendingAgentDetail(agentId: string): Pick<ApprovalSnapshot, 'toolName'> & Partial<Pick<ApprovalSnapshot, 'reason' | 'command'>> | undefined;
+    private emit;
+    /** Notify on a microtask so a re-check triggered inside getSnapshot
+     * (during a React render) never fires listeners synchronously mid-render. */
+    private scheduleNotify;
+    /** Rebuild the cached snapshot after any mutation of active. */
+    private rebuildSnapshot;
+    /**
+     * Re-run the source-badge verdict for the active ask (P-4).
+     *
+     * The external flag computed at park() is only a point-in-time verdict. A
+     * forger can dispatch a second request carrying the SAME callId as a
+     * genuinely pending one — both look live at park time; once the first is
+     * allowed and its tool/result lands, the twin surfaces with a callId that
+     * no longer has an unresolved call and must not keep the unmarked panel
+     * data. Re-checked when an ask becomes active (promotion), whenever the
+     * snapshot is read (the result usually lands AFTER the twin was promoted),
+     * and on every session `tool/result` notification (see
+     * {@link noteSessionEvent}). The session log only appends, so the verdict
+     * can only flip live→external, never back — the badge may appear late but
+     * never falsely.
+     */
+    private refreshActiveExternal;
+    /**
+     * Session-event notification inlet (wired by plugin.ts to the
+     * `session/event` firehose). React does not know the session log
+     * appended: a badge flip that only happens inside getSnapshot() surfaces
+     * solely when something ELSE re-renders the panel (a streaming spinner,
+     * say) — a silent render loop leaves the unmarked panel on screen. A
+     * landed `tool/result` is the only event type that can flip the active
+     * verdict live→external, so everything else is dropped here; the internal
+     * length memo then skips the recheck whenever the event belongs to a
+     * different session than the active ask's. The notification the SDK
+     * fires arrives after the event is already in the live session log, so the
+     * recheck sees the settled result.
+     * @param agentId - The emitting session's id (DSH shares agent/session identity).
+     * @param event - The appended session event.
+     */
+    noteSessionEvent(agentId: string, event: SessionEvent): void;
+    /**
+     * Whether another ask with this callId is already parked (active or
+     * queued). A genuine approval is raised once per gated tool call — the
+     * permission layer asks, waits, and never re-asks for the same callId —
+     * so a second ask reusing an in-flight callId is a forged twin dispatched
+     * through the in-process waterfall. This is a DETERMINISTIC verdict: it
+     * needs no tool/result to land, unlike {@link isLiveToolApproval}, whose
+     * twin-reveal window (result lands only after the first ask is allowed
+     * and the tool runs) is exactly when promotion-time rechecks still see no
+     * result. Derived from the live active+queue set on each park(), so
+     * settled asks free their callId automatically.
+     */
+    private isCallIdInFlight;
+    /**
+     * Answerer entry point — called by the `approval/request` waterfall
+     * listener for every ask in this process: the attached session's and any
+     * background session's alike, so an unattended session surfaces as
+     * "needs input" instead of failing closed with nobody to answer it.
+     * @param req - The approval request (agent, tool, callId, reason, signal).
+     * @returns A promise settling with the user's decision, or `'cancelled'`
+     *   when the ask is withdrawn or the plugin tears down.
+     */
+    park(req: ApprovalRequest): Promise<ApprovalOutcome>;
+    /** Advance to the next queued ask, if any. The promoted ask's source
+     * badge is re-checked against the log that has kept appending since it
+     * was parked (P-4: a same-callId twin parked while live may surface long
+     * after its call settled). */
+    private startNext;
+    /**
+     * The user decided on the current approval; settles it and drains the
+     * next queued ask if any. No-op when nothing is pending.
+     * @param outcome - `'allowed-once'` or `'rejected'`.
+     */
+    decide(outcome: 'allowed-once' | 'rejected'): void;
+    /**
+     * Settle the active and all queued asks (plugin teardown). The panel
+     * unmounts as the snapshot clears.
+     * @param outcome - The outcome every pending ask resolves with.
+     */
+    settleAll(outcome: ApprovalOutcome): void;
+    /**
+     * Record a settling ask's callId as consumed (see {@link consumedCallIds}).
+     * @param pending - The ask leaving the active/queue set.
+     */
+    private noteConsumed;
+    /**
+     * A same-callId duplicate just parked: every pending ask on that callId is
+     * now source-ambiguous. The forged-first order parks the fake ask clean
+     * (isLive true, no duplicate visible yet) and the genuine follow-up would
+     * carry the only badge — an inverted verdict. Flip them all, then rebuild
+     * + notify so an on-screen panel updates immediately. refreshActiveExternal
+     * early-returns on an existing external verdict, so the marking is
+     * monotonic and never erased. Deliberately badges instead of cancelling:
+     * cancelling both would hand the attacker a force-cancel primitive
+     * against genuine approvals.
+     * @param agentId - The agent domain owning the duplicated call id.
+     * @param callId - The duplicated call id (non-undefined by construction).
+     */
+    private markCallIdAmbiguous;
+}
+//# sourceMappingURL=approvals.d.ts.map

package/lib/types/dsh-adapter/approvals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvals.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/approvals.ts"],"names":[],"mappings":"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"}