@askdkc/dsh-cli 0.11.3

package/lib/types/dsh-adapter/activity-store.d.ts

@@ -0,0 +1,221 @@
+/**
+ * Session-scoped activity snapshots for the working-status line.
+ *
+ * The line's *semantics* belong to the `dsh-working-activity` plugin: it folds
+ * durable session events and live model frames into a **session projection**
+ * (`workingActivity`) that any client can read — the browser reads it, and so
+ * does this TUI. Consuming the projection is what removes the second tracker
+ * this app used to run: one semantic owner, and a value that arrives already
+ * scoped to a session, so a background session can no longer overwrite the line
+ * of the session on screen.
+ *
+ * Two properties of the transport shape this module:
+ *
+ * 1. **It is event-driven.** A value changes when a committed event folds, never
+ *    on its own. `updatedAt` is the timestamp of the last folded event (session
+ *    time, so it survives a restart) and `live` says whether `line` counts
+ *    elapsed time. A renderer that wants the counter to move must derive it from
+ *    `turnStartedAt` / `phaseStartedAt` instead of re-rendering `line`.
+ * 2. **The value is host data, not plugin API.** The shape below is a local
+ *    structural copy of the plugin's wire value, the same discipline the channel
+ *    port already applies to the activity state: this app must not import the
+ *    plugin's internals to display a line.
+ * @module dsh-tui/dsh-adapter/activity-store
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** The projection key the activity plugin publishes. */
+export declare const ACTIVITY_PROJECTION_KEY = "workingActivity";
+/** Phases the plugin's line can be in (`idle` renders nothing). */
+export type ActivityPhase = 'idle' | 'waiting' | 'thinking' | 'tool' | 'done';
+/**
+ * One session's activity value, as the plugin publishes it.
+ *
+ * Structural copy of `dsh-working-activity`'s `WorkingActivityView`.
+ */
+export interface ActivityView {
+    readonly phase: ActivityPhase;
+    /** The line as the host rendered it at `updatedAt`. */
+    readonly line: string;
+    /** Whether `line` counts elapsed time (a renderer ticks it from the stamps). */
+    readonly live: boolean;
+    /** Tool action verb, when the line describes a running tool. */
+    readonly label?: string;
+    /** Tool detail fragment (path / command / pattern), when there is one. */
+    readonly detail?: string;
+    /** The playful phrase or `⏵` self-narration currently shown, when any. */
+    readonly phrase?: string;
+    /** Tools completed in the current turn. */
+    readonly toolCount: number;
+    /** Wall clock the current phase began. */
+    readonly phaseStartedAt: number;
+    /** Wall clock the current turn began (0 when no turn has started). */
+    readonly turnStartedAt: number;
+    /** Timestamp of the last folded event — the value's freshness signal. */
+    readonly updatedAt: number;
+    /** Language the line was rendered in. */
+    readonly lang: 'zh' | 'en';
+}
+/** The slice of the host projection registry this module uses. */
+export interface ProjectionRegistryLike {
+    onChanged(listener: (session: {
+        readonly id: unknown;
+    }, key: string, value: unknown, seq: number) => void): () => void;
+    snapshot(session: unknown, keys?: readonly string[]): {
+        readonly values: Record<string, unknown>;
+    };
+}
+/**
+ * Narrow one projection value: anything that is not an activity view is
+ * dropped rather than rendered half-formed.
+ * @param value - Raw projection value.
+ * @returns the value as an activity view, or `undefined`.
+ */
+export declare function asActivityView(value: unknown): ActivityView | undefined;
+/**
+ * The latest activity value for the session on screen, with a subscription
+ * for renderers.
+ *
+ * The store is effectively single-current: binding a session ({@link
+ * ActivityStore.seed}) names the session the UI is showing, and every other
+ * id is dropped — values, session objects and read-failure counts alike. A
+ * registry-less store (the UI's fallback, test rigs) has no current session
+ * and keeps today's accept-all behavior.
+ */
+export declare class ActivityStore {
+    private readonly values;
+    /** Session objects seen for each id, so a live value can be re-read. */
+    private readonly sessions;
+    /** Consecutive failed reads per session id; reset by a successful read. */
+    private readonly readFailures;
+    /** Sessions already warned about (see {@link noteReadFailure}): once each. */
+    private readonly warned;
+    private readonly listeners;
+    /** The session the UI is showing (the last {@link seed}); the only id kept. */
+    private currentId;
+    /** Host registry, remembered so a bind can read a baseline on demand. */
+    private registry;
+    /** Warn sink (see {@link noteReadFailure}); injected by the composition root. */
+    private readonly warn;
+    constructor(warn?: (message: string) => void);
+    /** Remember the host registry (see {@link seed} and {@link refreshLive}). */
+    attachRegistry(registry: ProjectionRegistryLike): void;
+    /**
+     * Seed one session from the registry's current snapshot and make it the
+     * current one.
+     *
+     * A value only *arrives* when it changes, so a session opened after its last
+     * change — a resume, or a window reattached to a running agent — would show
+     * nothing until the next event without this read. The bind also defines the
+     * session on screen: every other id is pruned, so a later event — or the
+     * tick — for a session the user switched away from can no longer fill this
+     * store or keep a timer armed.
+     * @param session - Session being bound.
+     */
+    seed(session: unknown): void;
+    /**
+     * Note the session object behind an id, so a live value can be re-read.
+     * Dropped for any id other than the current one (see {@link seed}). */
+    remember(sessionId: string, session: unknown): void;
+    /**
+     * Re-read the current session's value while it is still counting time.
+     *
+     * The host renders the value when it is *read*, so this is what makes the
+     * elapsed seconds advance between committed events — with the host's own copy
+     * and language, since nothing is re-rendered here. A value that has settled
+     * (`live` false: idle, or a finished turn) is deliberately skipped: its text
+     * cannot change on its own. Only the current session can be live (see
+     * {@link seed}), so the tick never polls a session the user left.
+     */
+    refreshLive(): void;
+    /** Whether the current session's value is still counting time (see {@link refreshLive}). */
+    hasLive(): boolean;
+    /** The current value for one session, stable between updates. */
+    get(sessionId: string | undefined): ActivityView | undefined;
+    /**
+     * Record one projection value. Dropped for any id other than the current
+     * one (see {@link seed}).
+     * @param sessionId - Session the value belongs to.
+     * @param view - The published value.
+     */
+    update(sessionId: string, view: ActivityView): void;
+    /** Forget one session (disposed, or left behind by a reset). */
+    clear(sessionId: string): void;
+    /** A read succeeded: this session's consecutive-failure count restarts. */
+    noteReadSuccess(sessionId: string): void;
+    /**
+     * A read failed. The failure is reported to the warn sink ONCE per session
+     * (the sink is the composition root's logger — this module stays free of
+     * cordis types), and after {@link MAX_READ_FAILURES} consecutive failures
+     * the value is cleared so the tick disarms instead of polling a registry
+     * that will never answer.
+     * @param sessionId - Session whose read failed.
+     * @param detail - What the failed read threw.
+     */
+    noteReadFailure(sessionId: string, detail: string): void;
+    /** Drop every id that is not the current one; emit when a value went. */
+    private pruneToCurrent;
+    /** Subscribe to value changes; returns the unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    private emit;
+}
+/**
+ * The change-feed listener for one store.
+ *
+ * Only this plugin's key is read, and only values that narrow to an activity
+ * view are accepted: the feed is host-wide, so every other unit's change and
+ * every malformed value must be dropped here rather than inside a renderer.
+ * @param store - Store to fill.
+ * @returns the listener to hand to `ProjectionRegistry.onChanged`.
+ */
+export declare function createActivityFeed(store: ActivityStore): (session: {
+    readonly id: unknown;
+}, key: string, value: unknown) => void;
+/** How often a value that is still counting time is re-read from the host. */
+export declare const LIVE_TICK_MS = 500;
+/**
+ * Wire one store to the host's projection registry.
+ *
+ * Registration is deferred through `inject` because the plugin that *publishes*
+ * the unit is mounted alongside this one: the registry may not exist yet, and
+ * the unit may not be registered until later still. Both absences are normal —
+ * a composition without the activity plugin simply never fills the store, and
+ * the line falls back to whatever else the UI has.
+ *
+ * The feed is event-driven, so a value only lands when a committed event folds;
+ * its elapsed text would therefore freeze for the length of a long tool. The
+ * host renders a value when it is READ, so a timer re-reads the live ones: the
+ * seconds advance, the copy and language stay the plugin's, and a settled value
+ * (idle, or a finished turn) stops the timer instead of being polled forever.
+ * @param ctx - Host context of the composition root.
+ * @param store - Store to fill.
+ */
+export declare function attachActivityProjection(ctx: Context, store: ActivityStore): void;
+/**
+ * Create the composition root's activity store and wire it to the host.
+ * @param ctx - Host context of the composition root.
+ * @param enabled - Whether the working line is shown at all (cordis.yml
+ *   `activity`; a static, config-time switch — the runtime `/activity` command
+ *   only changes the preset). With the line off, nothing attaches: no feed,
+ *   no registry, and therefore no 500ms tick for a line nobody renders.
+ * @returns the store the UI reads from.
+ */
+export declare function createActivityStore(ctx: Context, enabled: boolean): ActivityStore;
+/**
+ * Read one session's activity value in a component.
+ * @param store - Store to read.
+ * @param sessionId - Session the UI is showing.
+ * @returns the current value, or `undefined` when there is none.
+ */
+export declare function useActivity(store: ActivityStore, sessionId: string | undefined): ActivityView | undefined;
+/**
+ * Seed one session's value from the registry's current snapshot.
+ *
+ * A value only *arrives* when it changes, so a session opened after its last
+ * change — a resume, or a window reattached to a running agent — would show
+ * nothing until the next event without this read.
+ * @param registry - Host projection registry.
+ * @param store - Store to fill.
+ * @param session - Session to read.
+ */
+export declare function seedActivity(registry: ProjectionRegistryLike | undefined, store: ActivityStore, session: unknown): void;
+//# sourceMappingURL=activity-store.d.ts.map

package/lib/types/dsh-adapter/activity-store.d.ts.map

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

package/lib/types/dsh-adapter/activity-store.js

@@ -0,0 +1,359 @@
+/**
+ * Session-scoped activity snapshots for the working-status line.
+ *
+ * The line's *semantics* belong to the `dsh-working-activity` plugin: it folds
+ * durable session events and live model frames into a **session projection**
+ * (`workingActivity`) that any client can read — the browser reads it, and so
+ * does this TUI. Consuming the projection is what removes the second tracker
+ * this app used to run: one semantic owner, and a value that arrives already
+ * scoped to a session, so a background session can no longer overwrite the line
+ * of the session on screen.
+ *
+ * Two properties of the transport shape this module:
+ *
+ * 1. **It is event-driven.** A value changes when a committed event folds, never
+ *    on its own. `updatedAt` is the timestamp of the last folded event (session
+ *    time, so it survives a restart) and `live` says whether `line` counts
+ *    elapsed time. A renderer that wants the counter to move must derive it from
+ *    `turnStartedAt` / `phaseStartedAt` instead of re-rendering `line`.
+ * 2. **The value is host data, not plugin API.** The shape below is a local
+ *    structural copy of the plugin's wire value, the same discipline the channel
+ *    port already applies to the activity state: this app must not import the
+ *    plugin's internals to display a line.
+ * @module dsh-tui/dsh-adapter/activity-store
+ */
+import React from 'react';
+/** The projection key the activity plugin publishes. */
+export const ACTIVITY_PROJECTION_KEY = 'workingActivity';
+/**
+ * Narrow one projection value: anything that is not an activity view is
+ * dropped rather than rendered half-formed.
+ * @param value - Raw projection value.
+ * @returns the value as an activity view, or `undefined`.
+ */
+export function asActivityView(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (typeof record.phase !== 'string' || typeof record.line !== 'string')
+        return undefined;
+    if (!PHASES.has(record.phase))
+        return undefined;
+    return value;
+}
+const PHASES = new Set(['idle', 'waiting', 'thinking', 'tool', 'done']);
+/**
+ * The latest activity value for the session on screen, with a subscription
+ * for renderers.
+ *
+ * The store is effectively single-current: binding a session ({@link
+ * ActivityStore.seed}) names the session the UI is showing, and every other
+ * id is dropped — values, session objects and read-failure counts alike. A
+ * registry-less store (the UI's fallback, test rigs) has no current session
+ * and keeps today's accept-all behavior.
+ */
+export class ActivityStore {
+    values = new Map();
+    /** Session objects seen for each id, so a live value can be re-read. */
+    sessions = new Map();
+    /** Consecutive failed reads per session id; reset by a successful read. */
+    readFailures = new Map();
+    /** Sessions already warned about (see {@link noteReadFailure}): once each. */
+    warned = new Set();
+    listeners = new Set();
+    /** The session the UI is showing (the last {@link seed}); the only id kept. */
+    currentId;
+    /** Host registry, remembered so a bind can read a baseline on demand. */
+    registry;
+    /** Warn sink (see {@link noteReadFailure}); injected by the composition root. */
+    warn;
+    constructor(warn) {
+        this.warn = warn;
+    }
+    /** Remember the host registry (see {@link seed} and {@link refreshLive}). */
+    attachRegistry(registry) {
+        this.registry = registry;
+    }
+    /**
+     * Seed one session from the registry's current snapshot and make it the
+     * current one.
+     *
+     * A value only *arrives* when it changes, so a session opened after its last
+     * change — a resume, or a window reattached to a running agent — would show
+     * nothing until the next event without this read. The bind also defines the
+     * session on screen: every other id is pruned, so a later event — or the
+     * tick — for a session the user switched away from can no longer fill this
+     * store or keep a timer armed.
+     * @param session - Session being bound.
+     */
+    seed(session) {
+        if (session === null || session === undefined)
+            return;
+        this.currentId = String(session.id);
+        this.pruneToCurrent();
+        seedActivity(this.registry, this, session);
+    }
+    /**
+     * Note the session object behind an id, so a live value can be re-read.
+     * Dropped for any id other than the current one (see {@link seed}). */
+    remember(sessionId, session) {
+        if (this.currentId !== undefined && sessionId !== this.currentId)
+            return;
+        this.sessions.set(sessionId, session);
+    }
+    /**
+     * Re-read the current session's value while it is still counting time.
+     *
+     * The host renders the value when it is *read*, so this is what makes the
+     * elapsed seconds advance between committed events — with the host's own copy
+     * and language, since nothing is re-rendered here. A value that has settled
+     * (`live` false: idle, or a finished turn) is deliberately skipped: its text
+     * cannot change on its own. Only the current session can be live (see
+     * {@link seed}), so the tick never polls a session the user left.
+     */
+    refreshLive() {
+        const registry = this.registry;
+        if (registry === undefined)
+            return;
+        for (const [sessionId, value] of [...this.values]) {
+            if (!value.live)
+                continue;
+            const session = this.sessions.get(sessionId);
+            if (session === undefined)
+                continue;
+            seedActivity(registry, this, session);
+        }
+    }
+    /** Whether the current session's value is still counting time (see {@link refreshLive}). */
+    hasLive() {
+        for (const value of this.values.values())
+            if (value.live)
+                return true;
+        return false;
+    }
+    /** The current value for one session, stable between updates. */
+    get(sessionId) {
+        if (sessionId === undefined)
+            return undefined;
+        return this.values.get(sessionId);
+    }
+    /**
+     * Record one projection value. Dropped for any id other than the current
+     * one (see {@link seed}).
+     * @param sessionId - Session the value belongs to.
+     * @param view - The published value.
+     */
+    update(sessionId, view) {
+        if (this.currentId !== undefined && sessionId !== this.currentId)
+            return;
+        if (this.values.get(sessionId) === view)
+            return;
+        this.values.set(sessionId, view);
+        this.emit();
+    }
+    /** Forget one session (disposed, or left behind by a reset). */
+    clear(sessionId) {
+        this.sessions.delete(sessionId);
+        if (!this.values.delete(sessionId))
+            return;
+        this.emit();
+    }
+    /** A read succeeded: this session's consecutive-failure count restarts. */
+    noteReadSuccess(sessionId) {
+        this.readFailures.delete(sessionId);
+    }
+    /**
+     * A read failed. The failure is reported to the warn sink ONCE per session
+     * (the sink is the composition root's logger — this module stays free of
+     * cordis types), and after {@link MAX_READ_FAILURES} consecutive failures
+     * the value is cleared so the tick disarms instead of polling a registry
+     * that will never answer.
+     * @param sessionId - Session whose read failed.
+     * @param detail - What the failed read threw.
+     */
+    noteReadFailure(sessionId, detail) {
+        const failures = (this.readFailures.get(sessionId) ?? 0) + 1;
+        this.readFailures.set(sessionId, failures);
+        if (!this.warned.has(sessionId)) {
+            this.warned.add(sessionId);
+            this.warn?.(`dsh-tui: working-activity projection read failed for session ${sessionId}: ${detail}`);
+        }
+        if (failures >= MAX_READ_FAILURES)
+            this.clear(sessionId);
+    }
+    /** Drop every id that is not the current one; emit when a value went. */
+    pruneToCurrent() {
+        if (this.currentId === undefined)
+            return;
+        let removedValue = false;
+        for (const id of [...this.values.keys()]) {
+            if (id === this.currentId)
+                continue;
+            this.values.delete(id);
+            removedValue = true;
+            this.sessions.delete(id);
+            this.readFailures.delete(id);
+            this.warned.delete(id);
+        }
+        for (const id of [...this.sessions.keys()]) {
+            if (id === this.currentId)
+                continue;
+            this.sessions.delete(id);
+            this.readFailures.delete(id);
+            this.warned.delete(id);
+        }
+        if (removedValue)
+            this.emit();
+    }
+    /** Subscribe to value changes; returns the unsubscribe function. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    emit() {
+        for (const listener of [...this.listeners])
+            listener();
+    }
+}
+/**
+ * The change-feed listener for one store.
+ *
+ * Only this plugin's key is read, and only values that narrow to an activity
+ * view are accepted: the feed is host-wide, so every other unit's change and
+ * every malformed value must be dropped here rather than inside a renderer.
+ * @param store - Store to fill.
+ * @returns the listener to hand to `ProjectionRegistry.onChanged`.
+ */
+export function createActivityFeed(store) {
+    return (session, key, value) => {
+        if (key !== ACTIVITY_PROJECTION_KEY)
+            return;
+        const view = asActivityView(value);
+        if (view === undefined)
+            return;
+        const sessionId = String(session.id);
+        // Values for a session other than the current one are dropped inside
+        // remember/update, so the feed needs no filter of its own.
+        store.remember(sessionId, session);
+        store.update(sessionId, view);
+    };
+}
+/** How often a value that is still counting time is re-read from the host. */
+export const LIVE_TICK_MS = 500;
+/** Consecutive failed reads before a session's value is dropped (see {@link ActivityStore.noteReadFailure}). */
+const MAX_READ_FAILURES = 3;
+/**
+ * Wire one store to the host's projection registry.
+ *
+ * Registration is deferred through `inject` because the plugin that *publishes*
+ * the unit is mounted alongside this one: the registry may not exist yet, and
+ * the unit may not be registered until later still. Both absences are normal —
+ * a composition without the activity plugin simply never fills the store, and
+ * the line falls back to whatever else the UI has.
+ *
+ * The feed is event-driven, so a value only lands when a committed event folds;
+ * its elapsed text would therefore freeze for the length of a long tool. The
+ * host renders a value when it is READ, so a timer re-reads the live ones: the
+ * seconds advance, the copy and language stay the plugin's, and a settled value
+ * (idle, or a finished turn) stops the timer instead of being polled forever.
+ * @param ctx - Host context of the composition root.
+ * @param store - Store to fill.
+ */
+export function attachActivityProjection(ctx, store) {
+    ctx.inject(['sessionProjections'], ((projectionCtx) => {
+        const registry = projectionCtx.sessionProjections;
+        if (registry === undefined)
+            return;
+        store.attachRegistry(registry);
+        const offFeed = registry.onChanged(createActivityFeed(store));
+        let timer;
+        const stopTimer = () => {
+            if (timer === undefined)
+                return;
+            clearInterval(timer);
+            timer = undefined;
+        };
+        /** Arm while something is counting time, disarm the moment nothing is. */
+        const reconcileTimer = () => {
+            if (!store.hasLive()) {
+                stopTimer();
+                return;
+            }
+            if (timer !== undefined)
+                return;
+            timer = setInterval(() => {
+                store.refreshLive();
+            }, LIVE_TICK_MS);
+            timer.unref();
+        };
+        const offStore = store.subscribe(reconcileTimer);
+        reconcileTimer();
+        // The cleanup belongs to the injected fiber, not the outer ctx: a service
+        // re-provide re-runs the callback above, and registering on the outer ctx
+        // would stack feed listeners (the old listener's disposer would only run
+        // when the whole composition root goes down).
+        projectionCtx.effect(() => () => {
+            offStore();
+            stopTimer();
+            offFeed();
+        }, 'dsh-tui activity projection feed');
+    }));
+}
+/**
+ * Create the composition root's activity store and wire it to the host.
+ * @param ctx - Host context of the composition root.
+ * @param enabled - Whether the working line is shown at all (cordis.yml
+ *   `activity`; a static, config-time switch — the runtime `/activity` command
+ *   only changes the preset). With the line off, nothing attaches: no feed,
+ *   no registry, and therefore no 500ms tick for a line nobody renders.
+ * @returns the store the UI reads from.
+ */
+export function createActivityStore(ctx, enabled) {
+    const store = new ActivityStore(message => { ctx.logger.warn(message); });
+    if (enabled)
+        attachActivityProjection(ctx, store);
+    return store;
+}
+/**
+ * Read one session's activity value in a component.
+ * @param store - Store to read.
+ * @param sessionId - Session the UI is showing.
+ * @returns the current value, or `undefined` when there is none.
+ */
+export function useActivity(store, sessionId) {
+    const subscribe = React.useCallback((listener) => store.subscribe(listener), [store]);
+    const read = React.useCallback(() => store.get(sessionId), [store, sessionId]);
+    return React.useSyncExternalStore(subscribe, read);
+}
+/**
+ * Seed one session's value from the registry's current snapshot.
+ *
+ * A value only *arrives* when it changes, so a session opened after its last
+ * change — a resume, or a window reattached to a running agent — would show
+ * nothing until the next event without this read.
+ * @param registry - Host projection registry.
+ * @param store - Store to fill.
+ * @param session - Session to read.
+ */
+export function seedActivity(registry, store, session) {
+    if (registry === undefined || session === null || session === undefined)
+        return;
+    const id = String(session.id);
+    try {
+        const snapshot = registry.snapshot(session, [ACTIVITY_PROJECTION_KEY]);
+        const view = asActivityView(snapshot.values[ACTIVITY_PROJECTION_KEY]);
+        if (view === undefined)
+            store.clear(id);
+        else {
+            store.remember(id, session);
+            store.update(id, view);
+        }
+        store.noteReadSuccess(id);
+    }
+    catch (error) {
+        // An unreadable snapshot is still not worth failing a session bind over,
+        // but it is no longer silent either: warn once per session, and a read
+        // that keeps failing eventually drops the value so the tick disarms.
+        store.noteReadFailure(id, error instanceof Error ? error.message : String(error));
+    }
+}

package/lib/types/dsh-adapter/agent-view.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { PreviewEntry } from './sessions/index.js';
+import type { AgentViewStatus } from './channel.js';
+/** Agent-view row ordering: needs-input first, stopped last. */
+export declare const AGENT_VIEW_STATUS_ORDER: readonly AgentViewStatus[];
+/** How long a row summary may be before the UI truncates it. */
+export declare 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 declare 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 declare function oneLine(text: string): string;
+/** The first non-empty text block of a user/assistant message content. */
+export declare function agentViewTextOf(content: unknown): string | undefined;
+/** True when any of the events is a human user message. */
+export declare function agentViewHasTurns(events: readonly SessionEvent[]): boolean;
+/**
+ * One agent-view row's derived facts, folded incrementally from events.
+ * `hasTurns`, `summary` and `title` only walk events appended since the last
+ * fold — session logs are append-only, so the cache never rescans history.
+ */
+export interface AgentViewFold {
+    hasTurns: boolean;
+    /** The first human prompt (the fallback title's source). */
+    firstPrompt: string;
+    /** Last non-empty assistant text, else last tool-call name, else the
+     *  first prompt — the one-line "what is it doing" summary. */
+    summary: string;
+    /** Where the current summary came from: a tool call wins over a prompt,
+     *  assistant text wins over both. */
+    summaryKind: 'none' | 'prompt' | 'tool' | 'assistant';
+    title: string;
+    /** `time` of the last folded event (the row's updatedAt). */
+    updatedAt: number;
+    /** Whether the last folded turn ended with an error. */
+    lastTurnFailed: boolean;
+}
+/**
+ * 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 declare function foldAgentViewEvents(events: readonly SessionEvent[], start: number, base: AgentViewFold): AgentViewFold;
+/** The trailing exchanges of a live session's in-memory log. */
+export declare function agentViewLivePreview(events: readonly SessionEvent[], limit: number): PreviewEntry[];
+/** A row title when the session never recorded one: the opening prompt's
+ *  opening words, else the working directory's basename. */
+export declare function sessionTitleFallback(fold: AgentViewFold, cwd: string | undefined): string;
+/**
+ * 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 declare function agentViewStatusOf(liveStatus: 'idle' | 'running', fold: AgentViewFold, needsInput: boolean): AgentViewStatus;
+//# sourceMappingURL=agent-view.d.ts.map

package/lib/types/dsh-adapter/agent-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-view.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/agent-view.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAEnD,gEAAgE;AAChE,eAAO,MAAM,uBAAuB,EAAE,SAAS,eAAe,EAE7D,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,wBAAwB,MAAM,CAAA;AAE3C;4DAC4D;AAC5D,eAAO,MAAM,qBAAqB,KAAK,CAAA;AAEvC;iEACiE;AACjE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAcpE;AAED,2DAA2D;AAC3D,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAE1E;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,OAAO,CAAA;IACjB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAA;IACnB;kEAC8D;IAC9D,OAAO,EAAE,MAAM,CAAA;IACf;yCACqC;IACrC,WAAW,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAA;IACrD,KAAK,EAAE,MAAM,CAAA;IACb,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAA;IACjB,wDAAwD;IACxD,cAAc,EAAE,OAAO,CAAA;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,aAAa,GAClB,aAAa,CAkDf;AAED,gEAAgE;AAChE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE,CAanG;AAED;4DAC4D;AAC5D,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAUzF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,IAAI,EAAE,aAAa,EACnB,UAAU,EAAE,OAAO,GAClB,eAAe,CAMjB"}