@itookit/dsht 0.3.3 → 0.3.7

package/dist/session/navigation.js

@@ -36,15 +36,20 @@ export function resolveTarget(items, query, id, names) {
 }
 /** Classify one session from the host's list summary; nothing is inferred from silence.
  * @param session - Session summary from `session/list`.
- * @returns Running while its agent works, blank before its first turn, otherwise idle.
+ * @param pending - Whether this client holds an unanswered interaction for that session.
+ * @returns Needs-you while an answer is owed, running while its agent works, otherwise idle or blank.
  */
-export function sessionState(session) {
+export function sessionState(session, pending = false) {
+    if (pending)
+        return 'needs';
     if (session.running === true)
         return 'running';
     return session.blank === true ? 'blank' : 'idle';
 }
-/** Leading marker per state: a working clock, a filled idle dot, and an empty unused circle. */
-export const SESSION_MARKERS = { running: '◐', idle: '●', blank: '○' };
+/** Leading marker per state: a question mark, a working clock, a filled dot, and an unused circle. */
+export const SESSION_MARKERS = { needs: '?', running: '◐', idle: '●', blank: '○' };
+/** One word per state, so every screen names the same state the same way. */
+export const STATE_LABELS = { needs: 'needs you', running: 'working', idle: 'ready', blank: 'empty' };
 /** Coarse age of a session's last activity, so the column stays steady between list refreshes.
  * @param time - Epoch milliseconds of the last activity, when the summary reported one.
  * @param now - Current epoch milliseconds.
@@ -65,20 +70,74 @@ export function activityAge(time, now) {
 /** Status cell for one session row: its state marker and the age of its last activity.
  * @param session - Session summary from `session/list`.
  * @param now - Current epoch milliseconds.
+ * @param pending - Whether this client holds an unanswered interaction for that session.
  * @returns Marker with an optional age, without a trailing space when unknown.
  */
-export function sessionStatus(session, now) {
+export function sessionStatus(session, now, pending = false) {
     const age = activityAge(typeof session.updatedAt === 'number' ? session.updatedAt : undefined, now);
-    return `${SESSION_MARKERS[sessionState(session)]}${age === '' ? '' : ` ${age}`}`;
+    return `${SESSION_MARKERS[sessionState(session, pending)]}${age === '' ? '' : ` ${age}`}`;
 }
+/** States a workspace rollup reports, most actionable first. */
+export const ROLLUP_STATES = ['needs', 'running', 'idle'];
 /** Count the sessions of one workspace by the state each reports.
+ *
+ * Blank sessions are counted by neither a badge nor a word: a session that never sent a turn is the
+ * absence of activity, and listing it beside real work only makes the rollup harder to read.
  * @param sessions - Sessions whose `sessionIds` belong to the workspace.
- * @returns One `marker count` cell per state that occurs, running first, or an empty string.
+ * @param pending - Session IDs this client holds an unanswered interaction for.
+ * @returns One count per state that occurs, most actionable first, or an empty list.
  */
-export function workspaceStatus(sessions) {
-    const counts = { running: 0, idle: 0, blank: 0 };
-    for (const session of sessions)
-        counts[sessionState(session)] += 1;
-    return ['running', 'idle', 'blank'].filter(state => counts[state] > 0)
-        .map(state => `${SESSION_MARKERS[state]} ${counts[state]}`).join('  ');
+export function workspaceCounts(sessions, pending = new Set()) {
+    const counts = { needs: 0, running: 0, idle: 0 };
+    for (const session of sessions) {
+        const id = session.sessionId;
+        const state = sessionState(session, typeof id === 'string' && pending.has(id));
+        if (state !== 'blank')
+            counts[state] += 1;
+    }
+    return ROLLUP_STATES.filter(state => counts[state] > 0).map(state => ({ state, count: counts[state] }));
+}
+/** Render one rollup as separately coloured cells.
+ *
+ * Each cell after the first carries the separator that joins it to the previous one, so a caller can
+ * colour the cells independently without losing the text {@link workspaceStatus} would produce.
+ * @param counts - Counts from {@link workspaceCounts}.
+ * @param style - `words` spells each state out; `badges` keeps only the marker and the count.
+ * @returns The cells in the order given, with their separators.
+ */
+export function workspaceSegments(counts, style = 'words') {
+    const separator = style === 'words' ? ' · ' : ' ';
+    return counts.map(({ state, count }, index) => ({ state,
+        text: `${index === 0 ? '' : separator}${style === 'words' ? `${SESSION_MARKERS[state]} ${count} ${STATE_LABELS[state]}` : `${SESSION_MARKERS[state]}${count}`}` }));
+}
+/** Render one rollup as plain text, the same way every screen and test reads it.
+ * @param counts - Counts from {@link workspaceCounts}.
+ * @param style - `words` spells each state out; `badges` keeps only the marker and the count.
+ * @returns The joined cell text, empty when nothing was counted.
+ */
+export function workspaceStatus(counts, style = 'words') {
+    return workspaceSegments(counts, style).map(segment => segment.text).join('');
+}
+/** Marker key for the compact rollup, which has no room for the words. */
+export const ROLLUP_LEGEND = `${SESSION_MARKERS.idle} ${STATE_LABELS.idle} · ${SESSION_MARKERS.running} ${STATE_LABELS.running} · ${SESSION_MARKERS.needs} ${STATE_LABELS.needs}`;
+/** Secondary path text for one workspace row.
+ *
+ * The title is usually the last path segment, so repeating it wastes the row; the parent directory
+ * is what distinguishes two checkouts. A title that does not name the last segment keeps the full
+ * path, because dropping it would hide where the workspace actually lives.
+ * @param path - Registered host directory.
+ * @param title - Workspace title as the row already shows it.
+ * @returns The path to show beside the row, or an empty string when nothing is left.
+ */
+export function workspaceDetail(path, title) {
+    if (!path)
+        return '';
+    const trimmed = path.replace(/\/+$/u, '');
+    const cut = trimmed.lastIndexOf('/');
+    const base = cut < 0 ? trimmed : trimmed.slice(cut + 1);
+    if (base !== title)
+        return path;
+    if (cut > 0)
+        return trimmed.slice(0, cut);
+    return cut === 0 ? '/' : '';
 }

package/dist/session/transcript.d.ts

@@ -1,5 +1,6 @@
 import type { HistoryLimits } from './memory.ts';
-import { type Json } from '../transport/wire.ts';
+import type { PromptRecord } from './info.ts';
+import { type Json, type ObjectValue } from '../transport/wire.ts';
 interface ToolSummary {
     name: string;
     operation?: string;
@@ -19,6 +20,21 @@ export declare function toolLine(text: string, width: number): string;
  * @returns Blocks joined by newlines.
  */
 export declare function contentText(content: Json | undefined, tools?: ReadonlyMap<string, ToolSummary>, width?: number, reasoning?: 'row' | 'full'): string;
+/** One durable `user/message` event as a recallable prompt.
+ *
+ * Injected context and every other record type return undefined. This is the single place the rule
+ * lives, so a prompt parsed straight from a wire record (the cost scan's pages) is identical to one
+ * the transcript folded into its own window.
+ * @param seq - Durable sequence of the record.
+ * @param event - Decoded wire event, when the record carried one.
+ * @returns The prompt text, or undefined when the record is not a user prompt.
+ */
+export declare function eventPrompt(seq: number, event: ObjectValue | undefined): PromptRecord | undefined;
+/** User prompts in one raw history page, oldest first.
+ * @param records - One HTTP history page's records.
+ * @returns Prompts with their durable sequences, in page order.
+ */
+export declare function recordPrompts(records: unknown): PromptRecord[];
 /** Semantic content stays separate from terminal rows, styles, and fold state. */
 export interface MessagePart {
     kind: 'text' | 'reasoning' | 'tool' | 'success' | 'error';
@@ -144,6 +160,26 @@ export declare class Transcript {
     get thoughts(): ThoughtEntry[];
     /** Latest loaded user prompt summary, sharing the durable thought index. */
     get latestPrompt(): string;
+    /** User prompts newer than `afterSeq`, oldest first, with the newest sequence scanned.
+     *
+     * Recall folds its tail this way instead of projecting messages, so a stream frame never rebuilds
+     * the row layout at a second width just to notice a new prompt. The watermark is returned even when
+     * the scanned records contributed no prompt, because an assistant-only turn must not make the next
+     * frame rescan it.
+     * @param afterSeq - Newest sequence already folded into the caller's index.
+     * @returns Prompts with an increasing sequence, and the watermark the caller should adopt.
+     */
+    promptsSince(afterSeq: number): {
+        prompts: PromptRecord[];
+        through: number;
+    };
+    /** User prompts strictly older than `beforeSeq`, oldest first, from the retained window.
+     * @param beforeSeq - Sequence the caller's index has already reached.
+     * @returns Loaded prompts that can refill an evicted prefix without a page request.
+     */
+    promptsBefore(beforeSeq: number): PromptRecord[];
+    /** One `user/message` record as a prompt; injected context and other records return undefined. */
+    private userPrompt;
     /** Number of semantic records and unfinished legacy chunks held by the client. */
     get retainedRecordCount(): number;
     /** Earliest loaded record, used with the opening cursor for backward paging. */

package/dist/session/transcript.js

@@ -59,6 +59,40 @@ export function contentText(content, tools, width = 100, reasoning = 'full') {
 }
 /** Event types that contribute a displayed message; other retained events only affect live state. */
 const DISPLAY_EVENTS = new Set(['user/message', 'assistant/message', 'tool/result']);
+/** One durable `user/message` event as a recallable prompt.
+ *
+ * Injected context and every other record type return undefined. This is the single place the rule
+ * lives, so a prompt parsed straight from a wire record (the cost scan's pages) is identical to one
+ * the transcript folded into its own window.
+ * @param seq - Durable sequence of the record.
+ * @param event - Decoded wire event, when the record carried one.
+ * @returns The prompt text, or undefined when the record is not a user prompt.
+ */
+export function eventPrompt(seq, event) {
+    if (!event || event.type !== 'user/message' || event.surfaceOp !== 'append')
+        return undefined;
+    const data = object(event.data);
+    if (data.source && object(data.source).kind !== 'user')
+        return undefined;
+    return { seq, text: contentText(data.content) };
+}
+/** User prompts in one raw history page, oldest first.
+ * @param records - One HTTP history page's records.
+ * @returns Prompts with their durable sequences, in page order.
+ */
+export function recordPrompts(records) {
+    const prompts = [];
+    for (const raw of array(records)) {
+        const event = object(object(raw).event);
+        const seq = event.seq;
+        if (typeof seq !== 'number' || !Number.isSafeInteger(seq))
+            continue;
+        const prompt = eventPrompt(seq, event);
+        if (prompt)
+            prompts.push(prompt);
+    }
+    return prompts;
+}
 /** Opening snapshots replace all state; durable events are deduplicated by sequence. */
 export class Transcript {
     sizes = new Map();
@@ -397,6 +431,45 @@ export class Transcript {
     }
     /** Latest loaded user prompt summary, sharing the durable thought index. */
     get latestPrompt() { void this.thoughts; return this.thoughtIndex.prompt; }
+    /** User prompts newer than `afterSeq`, oldest first, with the newest sequence scanned.
+     *
+     * Recall folds its tail this way instead of projecting messages, so a stream frame never rebuilds
+     * the row layout at a second width just to notice a new prompt. The watermark is returned even when
+     * the scanned records contributed no prompt, because an assistant-only turn must not make the next
+     * frame rescan it.
+     * @param afterSeq - Newest sequence already folded into the caller's index.
+     * @returns Prompts with an increasing sequence, and the watermark the caller should adopt.
+     */
+    promptsSince(afterSeq) {
+        const keys = this.sortedKeys();
+        let start = keys.length;
+        while (start > 0 && keys[start - 1] > afterSeq)
+            start--;
+        const prompts = [];
+        for (let index = start; index < keys.length; index++) {
+            const prompt = this.userPrompt(keys[index]);
+            if (prompt)
+                prompts.push(prompt);
+        }
+        return { prompts, through: Math.max(afterSeq, keys.at(-1) ?? afterSeq) };
+    }
+    /** User prompts strictly older than `beforeSeq`, oldest first, from the retained window.
+     * @param beforeSeq - Sequence the caller's index has already reached.
+     * @returns Loaded prompts that can refill an evicted prefix without a page request.
+     */
+    promptsBefore(beforeSeq) {
+        const prompts = [];
+        for (const seq of this.sortedKeys()) {
+            if (seq >= beforeSeq)
+                break;
+            const prompt = this.userPrompt(seq);
+            if (prompt)
+                prompts.push(prompt);
+        }
+        return prompts;
+    }
+    /** One `user/message` record as a prompt; injected context and other records return undefined. */
+    userPrompt(seq) { return eventPrompt(seq, this.events.get(seq)); }
     /** Number of semantic records and unfinished legacy chunks held by the client. */
     get retainedRecordCount() { return this.events.size; }
     /** Earliest loaded record, used with the opening cursor for backward paging. */

package/dist/state.d.ts

@@ -1,5 +1,5 @@
 /** Application state shared by the controller facade and every domain controller. */
-import { Transcript } from './session/transcript.ts';
+import { SessionInfo } from './session/info.ts';
 import type { HistorySearch, RemovalTarget } from './session/types.ts';
 import type { ObjectValue } from './transport/wire.ts';
 /** State shared by the picker and conversation view. */
@@ -21,7 +21,8 @@ export interface State {
     presetError?: string;
     presets?: ObjectValue[];
     defaultModel?: ObjectValue;
-    transcript: Transcript;
+    /** Record, prompt index, composer, view and interaction state of the selected session. */
+    session: SessionInfo;
 }
 /** The state contract every domain controller writes through. */
 export interface ControllerStore {

package/dist/state.js

@@ -1,9 +1,9 @@
 /** Application state shared by the controller facade and every domain controller. */
-import { Transcript } from "./session/transcript.js";
+import { SessionInfo } from "./session/info.js";
 /** Build the initial state before any connection exists.
  * @returns A fresh state whose transcript is empty and disconnected.
  */
 export function initialState() {
     return { version: 0, online: false, busy: false, screen: 'workspaces', status: 'Connecting…',
-        error: '', workspaces: [], sessions: [], showAllSessions: false, pending: [], transcript: new Transcript() };
+        error: '', workspaces: [], sessions: [], showAllSessions: false, pending: [], session: new SessionInfo() };
 }