@itookit/dsht 0.3.4 → 0.3.8

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/shell/controller.d.ts

@@ -0,0 +1,67 @@
+/** One local command and the output retained for it. */
+export interface ShellBlock {
+    id: number;
+    command: string;
+    /** Retained output lines, oldest first. */
+    lines: string[];
+    /** Lines dropped from the front because the block exceeded its budget. */
+    dropped: number;
+    /** Durable sequence that was newest when the command started; the block is shown after it. */
+    anchor: number;
+    status: 'running' | 'exited';
+    /** Exit code, once the command ended; null when a signal ended it. */
+    code?: number | null;
+    signal?: string | null;
+    startedAt: number;
+    endedAt?: number;
+}
+/** What one shell controller needs from its owner. */
+export interface ShellHost {
+    /** Repaint after output or a status change. */
+    publish(): void;
+    /** Client working directory the command runs in. */
+    cwd(): string;
+    /** Environment for the child, already stripped of client credentials. */
+    env(): NodeJS.ProcessEnv;
+    /** Newest durable sequence of the selected session, so a block stays where it happened. */
+    anchor(): number;
+}
+/** Owns the `!` commands of this client process: one at a time, bounded, killable. */
+export declare class ShellController {
+    private readonly host;
+    readonly enabled: boolean;
+    private readonly blocks;
+    private readonly bytes;
+    private nextId;
+    private task;
+    private abort;
+    private lastPublish;
+    constructor(host: ShellHost, /** Whether `!` is allowed at all. */ enabled?: boolean);
+    /** Runs in creation order, oldest first; the newest is what the transcript shows at its end. */
+    get runs(): readonly ShellBlock[];
+    /** Whether a command is still running. */
+    get running(): boolean;
+    /** Start one command.
+     *
+     * One command runs at a time: a second `!` while the first is live is refused rather than queued,
+     * because the transcript shows a single result block and the reader can stop the first with Ctrl+C.
+     * @param command - Command line typed after `!`.
+     * @returns The block created for it.
+     */
+    start(command: string): ShellBlock;
+    /** Stop the running command: its process group gets SIGTERM, then SIGKILL after a grace period.
+     * @returns Whether a run was stopped.
+     */
+    cancel(): boolean;
+    /** One run's retained output, with dropped lines made explicit.
+     * @param id - Run to read; defaults to the newest.
+     * @returns The text, or undefined when the run is unknown.
+     */
+    output(id?: number): string | undefined;
+    /** Stop the running command and wait for it, so no child outlives this client. */
+    stop(): Promise<void>;
+    /** Append one output line, trimming the block to its budgets from the front. */
+    private append;
+    /** Repaint, at most once per interval unless the change is a status change. */
+    private publish;
+}

package/dist/shell/controller.js

@@ -0,0 +1,126 @@
+/** Local shell runs the reader started with `!`, kept as bounded blocks for inline display.
+ *
+ * A block is the command line plus its retained output. Output is capped by both lines and bytes, so
+ * a runaway command can only fill its block, and only the newest blocks are kept. Nothing here is
+ * durable: no host record, no session state, no file.
+ */
+import { setTimeout as delay } from 'node:timers/promises';
+import { runShell } from "./runner.js";
+/** Output lines one block keeps before it drops the oldest. */
+const BLOCK_LINES = 200;
+/** Output bytes one block keeps before it drops the oldest. */
+const BLOCK_BYTES = 64 * 1024;
+/** Runs kept for display; the newest always survives. */
+const BLOCK_LIMIT = 20;
+/** Fastest repaint cadence while output streams; status changes always publish. */
+const PUBLISH_INTERVAL_MS = 80;
+/** Owns the `!` commands of this client process: one at a time, bounded, killable. */
+export class ShellController {
+    host;
+    enabled;
+    blocks = [];
+    bytes = new WeakMap();
+    nextId = 1;
+    task;
+    abort;
+    lastPublish = 0;
+    constructor(host, /** Whether `!` is allowed at all. */ enabled = true) {
+        this.host = host;
+        this.enabled = enabled;
+    }
+    /** Runs in creation order, oldest first; the newest is what the transcript shows at its end. */
+    get runs() { return this.blocks; }
+    /** Whether a command is still running. */
+    get running() { return this.blocks.some(block => block.status === 'running'); }
+    /** Start one command.
+     *
+     * One command runs at a time: a second `!` while the first is live is refused rather than queued,
+     * because the transcript shows a single result block and the reader can stop the first with Ctrl+C.
+     * @param command - Command line typed after `!`.
+     * @returns The block created for it.
+     */
+    start(command) {
+        if (!this.enabled)
+            throw new Error('Shell commands are disabled (--no-shell or DSHT_NO_SHELL=1)');
+        if (this.task)
+            throw new Error('A shell command is already running; Ctrl+C stops it');
+        const block = { id: this.nextId++, command, lines: [], dropped: 0, status: 'running',
+            startedAt: Date.now(), anchor: this.host.anchor() };
+        this.blocks.push(block);
+        while (this.blocks.length > BLOCK_LIMIT)
+            this.blocks.shift();
+        this.bytes.set(block, 0);
+        const abort = new AbortController();
+        this.abort = abort;
+        this.publish(true);
+        const task = runShell(command, {
+            cwd: this.host.cwd(), env: this.host.env(), signal: abort.signal,
+            onLine: (line, stream) => this.append(block, line),
+        }).then(exit => {
+            block.status = 'exited';
+            block.code = exit.code;
+            block.signal = exit.signal;
+            block.endedAt = Date.now();
+        }, error => {
+            block.status = 'exited';
+            block.code = null;
+            this.append(block, `! ${error instanceof Error ? error.message : String(error)}`);
+        }).finally(() => {
+            if (this.abort === abort)
+                this.abort = undefined;
+            if (this.task === task)
+                this.task = undefined;
+            this.publish(true);
+        });
+        this.task = task;
+        return block;
+    }
+    /** Stop the running command: its process group gets SIGTERM, then SIGKILL after a grace period.
+     * @returns Whether a run was stopped.
+     */
+    cancel() {
+        if (!this.abort)
+            return false;
+        this.abort.abort();
+        return true;
+    }
+    /** One run's retained output, with dropped lines made explicit.
+     * @param id - Run to read; defaults to the newest.
+     * @returns The text, or undefined when the run is unknown.
+     */
+    output(id) {
+        const block = id === undefined ? this.blocks.at(-1) : this.blocks.find(item => item.id === id);
+        if (!block)
+            return undefined;
+        const head = block.dropped > 0 ? [`… ${block.dropped} earlier lines dropped …`] : [];
+        return [...head, ...block.lines].join('\n');
+    }
+    /** Stop the running command and wait for it, so no child outlives this client. */
+    async stop() {
+        this.cancel();
+        await this.task;
+        while (this.running)
+            await delay(20);
+    }
+    /** Append one output line, trimming the block to its budgets from the front. */
+    append(block, line) {
+        block.lines.push(line);
+        let bytes = (this.bytes.get(block) ?? 0) + line.length * 2;
+        while (block.lines.length > BLOCK_LINES || bytes > BLOCK_BYTES) {
+            if (block.lines.length === 1)
+                break;
+            bytes -= block.lines.shift().length * 2;
+            block.dropped++;
+        }
+        this.bytes.set(block, bytes);
+        this.publish(false);
+    }
+    /** Repaint, at most once per interval unless the change is a status change. */
+    publish(force) {
+        const now = Date.now();
+        if (!force && now - this.lastPublish < PUBLISH_INTERVAL_MS)
+            return;
+        this.lastPublish = now;
+        this.host.publish();
+    }
+}

package/dist/shell/index.d.ts

@@ -0,0 +1,5 @@
+/** Shell domain: the local `!` command runner and the bounded blocks it produces. */
+export { ShellController } from './controller.ts';
+export type { ShellBlock, ShellHost } from './controller.ts';
+export { runShell } from './runner.ts';
+export type { ShellExit, ShellRunOptions, ShellStream } from './runner.ts';

package/dist/shell/index.js

@@ -0,0 +1,3 @@
+/** Shell domain: the local `!` command runner and the bounded blocks it produces. */
+export { ShellController } from "./controller.js";
+export { runShell } from "./runner.js";

package/dist/shell/runner.d.ts

@@ -0,0 +1,28 @@
+/** Which pipe one line arrived on. */
+export type ShellStream = 'stdout' | 'stderr';
+/** How one command ended. */
+export interface ShellExit {
+    code: number | null;
+    signal: string | null;
+}
+/** One command's execution contract. */
+export interface ShellRunOptions {
+    /** Working directory; the client's own directory, not the host's. */
+    cwd: string;
+    /** Environment for the child; the caller strips client credentials first. */
+    env: NodeJS.ProcessEnv;
+    /** Cancels the run; the child's process group is terminated. */
+    signal: AbortSignal;
+    /** Receives every complete line, in arrival order across both pipes. */
+    onLine(line: string, stream: ShellStream): void;
+}
+/** Run one command through the operator's shell and stream its lines.
+ *
+ * Both pipes are merged into one line stream in arrival order. A line longer than the assemble
+ * budget is emitted once, truncated, and the remainder is discarded until the next newline, so a
+ * command that never emits one cannot grow the client's memory.
+ * @param command - Command line, exactly as typed after `!`.
+ * @param options - Directory, environment, cancellation and the line sink.
+ * @returns How the command ended.
+ */
+export declare function runShell(command: string, options: ShellRunOptions): Promise<ShellExit>;

package/dist/shell/runner.js

@@ -0,0 +1,108 @@
+/** Running one local shell command for the reader, and nothing else.
+ *
+ * `!cmd` executes on the machine this client runs on — the operator's laptop or a jump host — never
+ * on the host the agent works in. The host's shell belongs to the model's own tools; this module is
+ * a separate, local facility, and it is the only place in `src/` allowed to spawn a process.
+ */
+import { spawn } from 'node:child_process';
+/** Longest single output line kept while it is still being assembled. */
+const MAX_LINE_CHARS = 8 * 1024;
+/** How long a cancelled command may ignore SIGTERM before it is killed. */
+const KILL_GRACE_MS = 2_000;
+/** The interactive shell to run under, falling back to `sh` when `$SHELL` is unusable. */
+function shellPath() {
+    const chosen = process.env.SHELL;
+    return chosen !== undefined && chosen !== '' ? chosen : '/bin/sh';
+}
+/** Terminate one child's whole process group, so pipelines and background children die with it.
+ *
+ * The child is spawned detached, which gives it its own group; signalling the group is what makes
+ * cancellation behave like Ctrl+C in a terminal instead of leaving orphans holding the pipes.
+ * @param child - The spawned shell.
+ * @param signal - Signal to send the group.
+ */
+function signalGroup(child, signal) {
+    const pid = child.pid;
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            child.kill(signal);
+        }
+        catch { /* already gone */ }
+    }
+}
+/** Run one command through the operator's shell and stream its lines.
+ *
+ * Both pipes are merged into one line stream in arrival order. A line longer than the assemble
+ * budget is emitted once, truncated, and the remainder is discarded until the next newline, so a
+ * command that never emits one cannot grow the client's memory.
+ * @param command - Command line, exactly as typed after `!`.
+ * @param options - Directory, environment, cancellation and the line sink.
+ * @returns How the command ended.
+ */
+export function runShell(command, options) {
+    return new Promise(resolve => {
+        const child = spawn(shellPath(), ['-c', command], {
+            cwd: options.cwd, env: options.env, detached: true, stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const carry = { stdout: '', stderr: '' };
+        const discarding = { stdout: false, stderr: false };
+        let settled = false;
+        let graceTimer;
+        /** Emit one assembled line, keeping the partial remainder for the next chunk. */
+        const feed = (stream, chunk) => {
+            carry[stream] += chunk;
+            for (;;) {
+                const newline = carry[stream].indexOf('\n');
+                if (newline < 0)
+                    break;
+                const line = carry[stream].slice(0, newline);
+                carry[stream] = carry[stream].slice(newline + 1);
+                if (discarding[stream])
+                    discarding[stream] = false;
+                else
+                    options.onLine(line.replace(/\r$/, ''), stream);
+            }
+            if (carry[stream].length > MAX_LINE_CHARS) {
+                if (!discarding[stream]) {
+                    options.onLine(`${carry[stream].slice(0, MAX_LINE_CHARS)}…`, stream);
+                    discarding[stream] = true;
+                }
+                carry[stream] = '';
+            }
+        };
+        const flush = (stream) => {
+            if (carry[stream] !== '' && !discarding[stream])
+                options.onLine(carry[stream].replace(/\r$/, ''), stream);
+            carry[stream] = '';
+        };
+        const finish = (exit) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(graceTimer);
+            options.signal.removeEventListener('abort', onAbort);
+            flush('stdout');
+            flush('stderr');
+            resolve(exit);
+        };
+        const onAbort = () => {
+            signalGroup(child, 'SIGTERM');
+            graceTimer = setTimeout(() => { signalGroup(child, 'SIGKILL'); }, KILL_GRACE_MS);
+        };
+        child.stdout?.setEncoding('utf8');
+        child.stderr?.setEncoding('utf8');
+        child.stdout?.on('data', (chunk) => feed('stdout', chunk));
+        child.stderr?.on('data', (chunk) => feed('stderr', chunk));
+        child.on('error', error => { options.onLine(`! ${error.message}`, 'stderr'); finish({ code: null, signal: null }); });
+        child.on('close', (code, signal) => finish({ code, signal }));
+        if (options.signal.aborted)
+            onAbort();
+        else
+            options.signal.addEventListener('abort', onAbort, { once: true });
+    });
+}

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() };
 }