@itookit/dsht 0.3.8 → 0.5.2

package/dist/session/navigator.js

@@ -0,0 +1,158 @@
+/** Workspace/session navigation owns view intent independently of background list refreshes. */
+import { array, object, string } from "../json.js";
+import { sessionLabel } from "../session-title.js";
+import { resolveTarget } from "./navigation.js";
+export class SessionNavigator {
+    host;
+    active;
+    tasks = new Map();
+    listsVersion = 0;
+    revision = 0;
+    constructor(host) {
+        this.host = host;
+    }
+    get intent() { return this.revision; }
+    /** Leaving a view invalidates the request that intended to open it. */
+    cancel() { this.revision++; this.active?.abort(); }
+    reset() { this.revision++; for (const abort of this.tasks.keys())
+        abort.abort(); }
+    async settle() { await Promise.allSettled(this.tasks.values()); }
+    run(caller, navigate, work) {
+        if (navigate)
+            this.cancel();
+        const abort = new AbortController();
+        if (navigate)
+            this.active = abort;
+        const selection = this.host.selection();
+        const signal = AbortSignal.any([abort.signal, this.host.signal(), ...(caller ? [caller] : [])]);
+        const task = Promise.resolve().then(async () => {
+            signal.throwIfAborted();
+            const client = this.host.require();
+            const check = () => {
+                signal.throwIfAborted();
+                if (client !== this.host.client() || navigate && selection !== this.host.selection()) {
+                    throw new Error('Navigation changed while loading');
+                }
+            };
+            check();
+            return work({ client, signal, check });
+        }).finally(() => {
+            abort.abort();
+            this.tasks.delete(abort);
+            if (this.active === abort)
+                this.active = undefined;
+        });
+        this.tasks.set(abort, task);
+        return task;
+    }
+    async load(context) {
+        const version = ++this.listsVersion;
+        const [workspaces, sessions] = await Promise.all([
+            context.client.listWorkspaces(context.signal), context.client.listSessions(undefined, context.signal),
+        ]);
+        context.check();
+        return { workspaces, sessions, version };
+    }
+    publishLists(lists) {
+        if (lists.version === this.listsVersion)
+            this.host.publish({ workspaces: lists.workspaces, sessions: lists.sessions });
+    }
+    refreshLists() {
+        return this.run(undefined, false, async (context) => { this.publishLists(await this.load(context)); });
+    }
+    showPicker(screen, signal) {
+        return this.run(signal, true, async (context) => {
+            const lists = await this.load(context);
+            this.publishLists(lists);
+            context.check();
+            this.host.publish({ screen });
+        });
+    }
+    showChat() {
+        if (this.host.read().sessionId === undefined)
+            return false;
+        this.cancel();
+        this.host.publish({ screen: 'chat' });
+        return true;
+    }
+    enterPath() { this.cancel(); this.host.publish({ screen: 'path' }); }
+    commitWorkspace(workspaceId) {
+        this.host.leave();
+        this.host.publish({ workspaceId, sessionId: undefined, showAllSessions: false, screen: 'sessions' });
+    }
+    pickWorkspace(workspaceId) { this.cancel(); this.commitWorkspace(workspaceId); }
+    switchWorkspace(query, signal) {
+        if (!query)
+            return this.showPicker('workspaces', signal);
+        return this.run(signal, true, async (context) => {
+            const lists = await this.load(context);
+            const workspace = resolveTarget(lists.workspaces, query, 'workspaceId', row => [string(row.title), string(row.path)]);
+            this.publishLists(lists);
+            context.check();
+            this.commitWorkspace(string(workspace.workspaceId));
+        });
+    }
+    switchSession(query, signal) {
+        return this.run(signal, true, async (context) => {
+            const lists = await this.load(context);
+            if (!query || query === 'all') {
+                this.publishLists(lists);
+                context.check();
+                this.host.publish({ screen: query === 'all' || this.host.read().workspaceId ? 'sessions' : 'workspaces', showAllSessions: query === 'all' });
+            }
+            else {
+                const session = resolveTarget(lists.sessions, query, 'sessionId', row => [sessionLabel(row)]);
+                this.publishLists(lists);
+                context.check();
+                this.host.follow(string(session.sessionId));
+            }
+        });
+    }
+    createWorkspace(path, signal) {
+        return this.run(signal, true, async (context) => {
+            const result = object(await context.client.call('workspace/create', { request: { path } }, context.signal));
+            context.check();
+            const lists = await this.load(context);
+            this.publishLists(lists);
+            context.check();
+            this.commitWorkspace(string(object(result.workspace).workspaceId));
+        });
+    }
+    createSession(signal) {
+        return this.run(signal, true, async (context) => {
+            const workspaceId = this.host.read().workspaceId;
+            if (!workspaceId)
+                throw new Error('Select a workspace before creating a session');
+            const result = object(await context.client.call('session/create', { request: { workspaceId } }, context.signal));
+            context.check();
+            this.host.follow(string(result.sessionId));
+        });
+    }
+    get visibleSessions() {
+        const state = this.host.read();
+        const sessions = state.sessions.filter(item => !this.host.client()?.archivedSessionIds.has(string(item.sessionId)));
+        if (state.showAllSessions || !state.workspaceId)
+            return sessions;
+        const workspace = state.workspaces.find(item => item.workspaceId === state.workspaceId);
+        const ids = new Set(array(workspace?.sessionIds ?? []).map(string));
+        return sessions.filter(item => ids.has(string(item.sessionId)));
+    }
+    /** Longest registered path wins, with whole-segment matching for nested workspaces. */
+    adoptLocalWorkspace(directory) {
+        const slashed = (value) => value.replace(/\\/g, '/').replace(/\/+$/, '');
+        const target = slashed(directory);
+        if (!target)
+            return undefined;
+        let best;
+        for (const workspace of this.host.read().workspaces) {
+            const path = slashed(string(workspace.path));
+            if (!path || target !== path && !target.startsWith(`${path}/`))
+                continue;
+            if (!best || path.length > best.length)
+                best = { id: string(workspace.workspaceId), length: path.length };
+        }
+        if (best)
+            this.pickWorkspace(best.id);
+        return best?.id;
+    }
+}

package/dist/session/peek.d.ts

@@ -0,0 +1,38 @@
+import type { HostAccess } from '../transport/host.ts';
+import type { ObjectValue } from '../transport/wire.ts';
+import { Transcript } from './transcript.ts';
+/** One followed session's read-only state. */
+export interface PeekState {
+    /** The transcript as the host has streamed it. */
+    readonly transcript: Transcript;
+    /** True once the stream ended, so a view stops calling it live. */
+    readonly ended: boolean;
+    /** Set when no address form could be followed. */
+    readonly error?: string;
+}
+/** Follows one session address form at a time, read-only. */
+export declare class SessionPeek {
+    private readonly host;
+    private subscription;
+    private state;
+    /** Address forms left to try, in order; a host may refuse the child form for one delivery mode. */
+    private pending;
+    /** Bumped on every open and close, so a cancelled stream's late frame cannot revive the state. */
+    private generation;
+    /** @param host - Transport access this client already holds; the peek borrows it, never owns it. */
+    constructor(host: HostAccess);
+    /** Start following the first address that answers, releasing whatever was followed before.
+     * @param addresses - Address forms to try in order.
+     * @param onChange - Called when the transcript or the state moves.
+     */
+    open(addresses: readonly ObjectValue[], onChange: () => void): void;
+    /** Stop following and release the transcript; safe to call when nothing is open. */
+    close(): void;
+    /** @returns What a view renders, or undefined when nothing is followed. */
+    get snapshot(): PeekState | undefined;
+    /** Follow the next address form, or report that none worked.
+     * @param generation - The open this attempt belongs to; a superseded one stops silently.
+     * @param onChange - Called when the transcript or the state moves.
+     */
+    private next;
+}

package/dist/session/peek.js

@@ -0,0 +1,103 @@
+import { releaseHistoryLayout } from "./history.js";
+import { Transcript } from "./transcript.js";
+/** How much of a followed session the first snapshot asks for; the live tail appends after it. */
+const PEEK_MESSAGES = 120;
+/** Follows one session address form at a time, read-only. */
+export class SessionPeek {
+    host;
+    subscription;
+    state;
+    /** Address forms left to try, in order; a host may refuse the child form for one delivery mode. */
+    pending = [];
+    /** Bumped on every open and close, so a cancelled stream's late frame cannot revive the state. */
+    generation = 0;
+    /** @param host - Transport access this client already holds; the peek borrows it, never owns it. */
+    constructor(host) {
+        this.host = host;
+    }
+    /** Start following the first address that answers, releasing whatever was followed before.
+     * @param addresses - Address forms to try in order.
+     * @param onChange - Called when the transcript or the state moves.
+     */
+    open(addresses, onChange) {
+        this.close();
+        // `close` bumped the generation; this open owns the next one and every callback checks it.
+        const generation = ++this.generation;
+        this.pending = [...addresses];
+        this.next(generation, onChange);
+    }
+    /** Stop following and release the transcript; safe to call when nothing is open. */
+    close() {
+        this.generation += 1;
+        this.subscription?.cancel();
+        this.subscription = undefined;
+        this.pending = [];
+        if (this.state === undefined)
+            return;
+        releaseHistoryLayout(this.state.transcript);
+        this.state.transcript.dispose();
+        this.state = undefined;
+    }
+    /** @returns What a view renders, or undefined when nothing is followed. */
+    get snapshot() { return this.state; }
+    /** Follow the next address form, or report that none worked.
+     * @param generation - The open this attempt belongs to; a superseded one stops silently.
+     * @param onChange - Called when the transcript or the state moves.
+     */
+    next(generation, onChange) {
+        if (generation !== this.generation)
+            return;
+        const address = this.pending.shift();
+        if (address === undefined) {
+            this.state = { transcript: new Transcript(), ended: true, error: 'the host refused every address form' };
+            onChange();
+            return;
+        }
+        const transcript = new Transcript();
+        this.state = { transcript, ended: false };
+        let attempted = false;
+        let subscription;
+        try {
+            subscription = this.host.require().subscribe('session/follow', {
+                request: { address, maxMessages: PEEK_MESSAGES, assistantStream: true },
+            }, {
+                item: value => {
+                    if (generation !== this.generation)
+                        return;
+                    // A peek is a diagnostic surface: a malformed frame ends it with a reason rather than taking
+                    // the whole client down the way a selected session's stream would.
+                    try {
+                        transcript.accept(value);
+                    }
+                    catch {
+                        this.state = { transcript, ended: true, error: 'the session stream sent a frame this client cannot read' };
+                    }
+                    onChange();
+                },
+                end: error => {
+                    // A cancelled stream still reports its end; only the live attempt may act on it.
+                    if (attempted || generation !== this.generation)
+                        return;
+                    attempted = true;
+                    if (error !== undefined && this.pending.length > 0) {
+                        this.next(generation, onChange);
+                        return;
+                    }
+                    this.state = { transcript, ended: true, ...(error === undefined ? {} : { error: errorTextOf(error) }) };
+                    onChange();
+                },
+            });
+        }
+        catch (error) {
+            // Offline, or between connection generations: the view says so instead of failing the caller.
+            this.state = { transcript, ended: true, error: errorTextOf(error) };
+            onChange();
+            return;
+        }
+        this.subscription = subscription;
+    }
+}
+/** One error as displayable text, without importing the whole wire module. */
+function errorTextOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/session/prompt-backfill.d.ts

@@ -0,0 +1,23 @@
+import type { HostAccess } from '../transport/host.ts';
+import { Transcript } from './transcript.ts';
+import type { PromptCache, PromptIndex } from './info.ts';
+interface Selection {
+    sessionId: string;
+    revision: number;
+    record: Transcript;
+    prompts: PromptIndex;
+}
+interface BackfillHost extends Pick<HostAccess, 'require' | 'signal' | 'online'> {
+    current(selection: Selection): boolean;
+    changed(): void;
+}
+export declare class PromptBackfill {
+    private readonly host;
+    private readonly cache;
+    private readonly tasks;
+    constructor(host: BackfillHost, cache: PromptCache);
+    cancel(): void;
+    settle(): Promise<void>;
+    start(selection: Selection): void;
+}
+export {};

package/dist/session/prompt-backfill.js

@@ -0,0 +1,88 @@
+/** Bounded background recall indexing, owned by one selected record and connection lifetime. */
+import { setTimeout as delay } from 'node:timers/promises';
+import { object } from "../json.js";
+import { Transcript } from "./transcript.js";
+const PAGE_LIMIT = 200;
+export class PromptBackfill {
+    host;
+    cache;
+    tasks = new Set();
+    constructor(host, cache) {
+        this.host = host;
+        this.cache = cache;
+    }
+    cancel() { for (const task of this.tasks)
+        task.abort.abort(); }
+    async settle() { await Promise.allSettled([...this.tasks].map(task => task.promise)); }
+    start(selection) {
+        this.cancel();
+        const abort = new AbortController();
+        const signal = AbortSignal.any([abort.signal, this.host.signal()]);
+        const task = { abort, promise: Promise.resolve() };
+        // Register before dispatch, including before any reentrant host callback.
+        this.tasks.add(task);
+        task.promise = Promise.resolve().then(async () => {
+            const check = () => {
+                signal.throwIfAborted();
+                if (!this.host.online() || !this.host.current(selection))
+                    throw new Error('Session changed while indexing prompts');
+            };
+            check();
+            const client = this.host.require();
+            const deadline = Date.now() + client.timeoutMs;
+            const { record, prompts, sessionId } = selection;
+            while (!record.ready) {
+                check();
+                if (Date.now() >= deadline)
+                    throw new Error('Session snapshot timed out');
+                await delay(20, undefined, { signal });
+            }
+            check();
+            const adopt = () => {
+                const cached = this.cache.get(sessionId);
+                if (!cached?.complete)
+                    return false;
+                prompts.prepend(cached.prompts);
+                prompts.settle();
+                prompts.markComplete();
+                this.host.changed();
+                return true;
+            };
+            if (adopt())
+                return;
+            const throughSeq = record.readThrough;
+            let beforeSeq = record.beforeSeq, hasMore = record.hasMore;
+            for (let page = 0; hasMore && beforeSeq !== undefined && page < PAGE_LIMIT; page++) {
+                check();
+                const result = object(await client.call('session/page', { request: {
+                        address: { kind: 'session', sessionId }, throughSeq, beforeSeq, maxMessages: 80,
+                    } }, signal));
+                check();
+                const temporary = new Transcript();
+                try {
+                    temporary.accept({ type: 'snapshot', cursor: throughSeq, assistantStream: { revision: 0 }, records: result.records, hasMore: result.hasMore });
+                    const next = temporary.beforeSeq;
+                    if (temporary.hasMore && (next === undefined || next >= beforeSeq))
+                        throw new Error('Host history page did not advance');
+                    prompts.prepend(temporary.promptsSince(-1).prompts);
+                    // Bound each admitted page, even when the next request fails or never returns.
+                    prompts.settle();
+                    beforeSeq = next;
+                    hasMore = temporary.hasMore;
+                }
+                finally {
+                    temporary.dispose();
+                }
+                if (adopt())
+                    return;
+            }
+            if (!hasMore) {
+                prompts.markComplete();
+                this.cache.put(sessionId, { prompts: prompts.durableItems, complete: prompts.exhausted });
+            }
+            this.host.changed();
+        }).catch(() => {
+            // Cancellation or unavailable history leaves older prompts reachable through lazy paging.
+        }).finally(() => { this.tasks.delete(task); });
+    }
+}

package/dist/session/references.d.ts

@@ -1,23 +1,5 @@
-/** A path relative to the remote session's working directory. */
-export interface FileReference {
-    path: string;
-    kind: 'file' | 'directory';
-}
-/** Find the unfinished reference at the end of the draft; email addresses do not trigger it.
- * @param text - Complete composer draft.
- * @returns The replaceable token and host query, or undefined outside a reference.
- */
-export declare function activeReference(text: string): {
-    prefix: string;
-    query: string;
-    quoted: boolean;
-} | undefined;
-/** Encode a candidate in Harness prompt syntax; directories keep completion open.
- * @param candidate - Remote path and entry kind.
- * @param quoted - Preserve an explicitly opened quote.
- * @returns Mention text, or undefined for paths the mention grammar cannot encode.
- */
-export declare function fileMention(candidate: FileReference, quoted?: boolean): string | undefined;
+import { type FileReference } from '../references.ts';
+export type { FileReference } from '../references.ts';
 /** Validate remote candidates and omit paths that cannot be inserted safely.
  * @param value - Decoded fileReferences/list result.
  * @returns Ordered file and directory candidates.

package/dist/session/references.js

@@ -1,31 +1,6 @@
 /** Independent adapter for Harness path-only @ references; no file bytes are read. */
 import { array, object, string } from "../transport/wire.js";
-/** Find the unfinished reference at the end of the draft; email addresses do not trigger it.
- * @param text - Complete composer draft.
- * @returns The replaceable token and host query, or undefined outside a reference.
- */
-export function activeReference(text) {
-    const quoted = /(?:^|\s)(@"([^"]*))$/u.exec(text);
-    if (quoted)
-        return { prefix: quoted[1], query: quoted[2], quoted: true };
-    const plain = /(?:^|\s)(@([^\s"]*))$/u.exec(text);
-    if (plain)
-        return { prefix: plain[1], query: plain[2], quoted: false };
-    return undefined;
-}
-/** Encode a candidate in Harness prompt syntax; directories keep completion open.
- * @param candidate - Remote path and entry kind.
- * @param quoted - Preserve an explicitly opened quote.
- * @returns Mention text, or undefined for paths the mention grammar cannot encode.
- */
-export function fileMention(candidate, quoted = false) {
-    const path = candidate.path + (candidate.kind === 'directory' ? '/' : '');
-    if (/[\u0000-\u001f\u007f-\u009f"]/u.test(path))
-        return undefined;
-    if (!quoted && !/\s/u.test(path))
-        return `@${path}`;
-    return `@"${path}${candidate.kind === 'file' ? '"' : ''}`;
-}
+import { fileMention } from "../references.js";
 /** Validate remote candidates and omit paths that cannot be inserted safely.
  * @param value - Decoded fileReferences/list result.
  * @returns Ordered file and directory candidates.

package/dist/session/runtime.d.ts

@@ -0,0 +1,26 @@
+/** Per-session host runtime mirrors that are not connection state.
+ *
+ * `running` and the observation start change while the network stays perfectly healthy
+ * (`ready → running → waiting → running`), so they belong to the session runtime rather than to the
+ * connection. Both maps are keyed by `sessionId` and cleared at each connection generation.
+ */
+import type { ControlFrame } from '../transport/events.ts';
+import { Telemetry } from './telemetry.ts';
+export declare class SessionRuntime {
+    /** Host projection values for every session of the current generation. */
+    telemetry: Telemetry;
+    private readonly running;
+    private readonly observed;
+    /** Cached host running flag for one session, or undefined when never reported. */
+    runningFor(sessionId: string): boolean | undefined;
+    /** When this client first observed the session running, for the elapsed-time fallback. */
+    observedAt(sessionId: string): number | undefined;
+    /** Remember when a session this client just opened was first seen. */
+    observe(sessionId: string): void;
+    /** Apply one host running-state notification for a session. */
+    accept(sessionId: string, running: boolean): void;
+    /** Apply one normalized projection/queue/job frame. */
+    acceptControl(frame: ControlFrame): void;
+    /** Drop every generation-scoped mirror, including the projection store. */
+    reset(): void;
+}

package/dist/session/runtime.js

@@ -0,0 +1,28 @@
+import { Telemetry } from "./telemetry.js";
+/** Projection capabilities this client consumes; the host retains every other key. */
+const RETAINED_PROJECTIONS = new Set(['title', 'modelSelection', 'contextPressure', 'tokenUsage', 'sessionStats', 'agentPreset']);
+export class SessionRuntime {
+    /** Host projection values for every session of the current generation. */
+    telemetry = new Telemetry(RETAINED_PROJECTIONS);
+    running = new Map();
+    observed = new Map();
+    /** Cached host running flag for one session, or undefined when never reported. */
+    runningFor(sessionId) { return this.running.get(sessionId); }
+    /** When this client first observed the session running, for the elapsed-time fallback. */
+    observedAt(sessionId) { return this.observed.get(sessionId); }
+    /** Remember when a session this client just opened was first seen. */
+    observe(sessionId) { if (!this.observed.has(sessionId))
+        this.observed.set(sessionId, Date.now()); }
+    /** Apply one host running-state notification for a session. */
+    accept(sessionId, running) {
+        if (running && !this.running.get(sessionId))
+            this.observed.set(sessionId, Date.now());
+        if (!running)
+            this.observed.delete(sessionId);
+        this.running.set(sessionId, running);
+    }
+    /** Apply one normalized projection/queue/job frame. */
+    acceptControl(frame) { this.telemetry.accept(frame); }
+    /** Drop every generation-scoped mirror, including the projection store. */
+    reset() { this.running.clear(); this.observed.clear(); this.telemetry = new Telemetry(RETAINED_PROJECTIONS); }
+}

package/dist/session/state.d.ts

@@ -0,0 +1,20 @@
+/** State and publication capabilities owned by the session domain. */
+import type { NavigationState } from './navigator.ts';
+import type { SessionInfo } from './info.ts';
+import type { PendingInteraction } from './types.ts';
+export interface SessionState extends NavigationState {
+    online: boolean;
+    status: string;
+    lastFailure: string;
+    pending: PendingInteraction[];
+    session: SessionInfo;
+}
+/** The connection and application derive online/pending; session actions cannot overwrite them. */
+export type SessionUpdate = Partial<Omit<SessionState, 'online' | 'pending' | 'session'>>;
+export interface SessionStore {
+    readonly state: Readonly<SessionState>;
+    update(patch: SessionUpdate): void;
+    selection(): number;
+    bumpSelection(): void;
+    busy(): boolean;
+}

package/dist/session/state.js

@@ -0,0 +1 @@
+export {};

package/dist/session/telemetry.d.ts

@@ -1,42 +1,50 @@
-/** Host projection values with per-key watermarks; snapshots never roll back newer updates. */
-import { type ObjectValue } from '../transport/wire.ts';
-/** One host-owned pending input, removable only while its occurrence remains queued. */
-export interface QueuedInput {
-    id: string;
-    placement: 'queued' | 'steering' | 'context';
-    text: string;
+/** Host projection values with per-key watermarks; snapshots never roll back newer updates.
+ *
+ * The wire shape is decoded by `transport/events.ts`; this class only applies semantic control frames
+ * to its own maps, so a host field rename never reaches the session domain.
+ */
+import type { ControlFrame, ProjectionSnapshot, ProjectionValue, QueuedInput } from '../transport/events.ts';
+export type { QueuedInput } from '../transport/events.ts';
+export interface TelemetrySnapshot {
+    readonly values: Readonly<Record<string, ProjectionValue>>;
+    readonly queued?: number;
+    readonly jobs?: number;
+}
+/** The public reader has no projection acceptance or baseline replacement capability. */
+export interface TelemetryReader {
+    readonly ready: boolean;
+    view(id?: string): TelemetrySnapshot;
+    pending(id?: string): readonly Readonly<QueuedInput>[];
 }
 /** Generation-local projection, inbox and background-job data for every session. */
 export declare class Telemetry {
     private readonly retainedKeys?;
     private entries;
     private queues;
+    private readonly views;
+    readonly reader: TelemetryReader;
     private jobs;
     ready: boolean;
     /** Optionally retain only projection capabilities consumed by this client. */
     constructor(retainedKeys?: ReadonlySet<string> | undefined);
     /** Replace all control state on a new stream baseline, then accept replacement frames.
-     * @param value - One decoded session/control frame.
+     * @param frame - One normalized session/control frame.
      */
-    accept(value: unknown): void;
+    accept(frame: ControlFrame): void;
     /** Merge a complete follow snapshot without restoring absent or older projection values.
      * @param id - Session identity.
-     * @param value - Projection baseline, when supplied by the host.
+     * @param baseline - Projection baseline, when supplied by the host.
      */
-    snapshot(id: string, value: unknown): void;
+    snapshot(id: string, baseline: ProjectionSnapshot | undefined): void;
     /** Read current values for one session; missing capabilities remain absent.
      * @param id - Selected session identity, if any.
      * @returns Projection values and known queue/job counts.
      */
-    view(id?: string): {
-        values: ObjectValue;
-        queued?: number;
-        jobs?: number;
-    };
+    view(id?: string): TelemetrySnapshot;
     /** Read the selected session's authoritative pending inputs; absence means no observed queue.
      * @param id - Session identity.
      * @returns Pending inputs in host order.
      */
-    pending(id?: string): readonly QueuedInput[];
+    pending(id?: string): readonly Readonly<QueuedInput>[];
     private entry;
 }