@itookit/dsht 0.1.0

package/dist/navigation.js

@@ -0,0 +1,36 @@
+/** Shared display names and unambiguous slash-command target resolution. */
+import { safeText, string } from "./wire.js";
+/** Parse the short navigation commands and their equivalent long aliases. */
+export function navigationCommand(value) {
+    const match = /^\/(ws|workspace|workspaces|s|session|sessions)(?:\s+(.+))?$/.exec(value);
+    if (!match)
+        return undefined;
+    return { kind: match[1] === 'ws' || match[1].startsWith('workspace') ? 'workspace' : 'session', query: match[2] };
+}
+/** Resolve the host's title projection, falling back to the session ID. */
+export function sessionLabel(session) {
+    const projections = session.projections;
+    if (projections && typeof projections === 'object' && !Array.isArray(projections)) {
+        const values = projections.values;
+        const title = values && typeof values === 'object' && !Array.isArray(values) ? values.title : undefined;
+        if (typeof title === 'string' && safeText(title).trim())
+            return safeText(title).trim();
+        if (title && typeof title === 'object' && !Array.isArray(title) && typeof title.title === 'string' && safeText(title.title).trim())
+            return safeText(title.title).trim();
+    }
+    return string(session.sessionId);
+}
+/** Match an exact ID or name before a unique ID prefix; never choose an ambiguous target. */
+export function resolveTarget(items, query, id, names) {
+    const target = query.replace(/^(["'])(.*)\1$/, '$2');
+    const exactId = items.find(item => item[id] === target);
+    if (exactId)
+        return exactId;
+    const exactNames = items.filter(item => names(item).includes(target));
+    const matches = exactNames.length ? exactNames : items.filter(item => string(item[id]).startsWith(target));
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1)
+        throw new Error(`Ambiguous target: ${target}. Use a full ID.`);
+    throw new Error(`Target not found: ${target}`);
+}

package/dist/references.d.ts

@@ -0,0 +1,25 @@
+/** 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;
+/** Validate remote candidates and omit paths that cannot be inserted safely.
+ * @param value - Decoded fileReferences/list result.
+ * @returns Ordered file and directory candidates.
+ */
+export declare function fileReferences(value: unknown): FileReference[];

package/dist/references.js

@@ -0,0 +1,40 @@
+/** Independent adapter for Harness path-only @ references; no file bytes are read. */
+import { array, object, string } from "./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' ? '"' : ''}`;
+}
+/** Validate remote candidates and omit paths that cannot be inserted safely.
+ * @param value - Decoded fileReferences/list result.
+ * @returns Ordered file and directory candidates.
+ */
+export function fileReferences(value) {
+    return array(value).map(item => {
+        const row = object(item);
+        if (row.kind !== 'file' && row.kind !== 'directory')
+            throw new Error('Unknown file reference kind');
+        return { path: string(row.path), kind: row.kind };
+    }).filter(row => fileMention(row) !== undefined);
+}

package/dist/status.d.ts

@@ -0,0 +1,26 @@
+import type { Controller } from './controller.ts';
+import { type ObjectValue } from './wire.ts';
+/** Format elapsed wall time, clamping clock skew instead of displaying negative durations.
+ * @param milliseconds - Elapsed duration.
+ * @returns Minute/second display, with hours when needed.
+ */
+export declare function elapsedTime(milliseconds: number): string;
+/** Produce compact metadata lines without inferring missing provider measurements.
+ * @param values - Current host projection values.
+ * @param defaultModel - Host catalog default used before a session selects a route.
+ * @param running - Whether the current route or next route is primary.
+ * @returns Model, approximate context occupancy, and cumulative token buckets.
+ */
+export declare function metricLines(values: ObjectValue, defaultModel: ObjectValue | undefined, running: boolean): string[];
+/** Fit the status summary to one terminal row; details remain available through /status.
+ * @param fields - Priority-ordered status fields, followed by optional details.
+ * @param width - Available terminal columns.
+ * @returns A terminal-safe single line, shortened by display width.
+ */
+export declare function compactStatus(fields: string[], width: number): string;
+/** Render a live clock and selected-session metadata; the timer belongs to this mounted bar. */
+export declare const StatusBar: import("react").NamedExoticComponent<{
+    controller: Controller;
+    expanded?: boolean;
+    revision?: number;
+}>;

package/dist/status.js

@@ -0,0 +1,135 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/** Terminal status from host projections; cumulative usage and estimated context stay distinct. */
+import { memo, useEffect, useState } from 'react';
+import { Box, Text, useStdout } from 'ink';
+import wrapAnsi from 'wrap-ansi';
+import { costText } from "./cost.js";
+import { safeText } from "./wire.js";
+/** Format elapsed wall time, clamping clock skew instead of displaying negative durations.
+ * @param milliseconds - Elapsed duration.
+ * @returns Minute/second display, with hours when needed.
+ */
+export function elapsedTime(milliseconds) {
+    const seconds = Math.max(0, Math.floor(milliseconds / 1000));
+    const minutes = Math.floor(seconds / 60);
+    return `${minutes >= 60 ? `${Math.floor(minutes / 60)}h ` : ''}${minutes % 60}m ${seconds % 60}s`;
+}
+/** Produce compact metadata lines without inferring missing provider measurements.
+ * @param values - Current host projection values.
+ * @param defaultModel - Host catalog default used before a session selects a route.
+ * @param running - Whether the current route or next route is primary.
+ * @returns Model, approximate context occupancy, and cumulative token buckets.
+ */
+export function metricLines(values, defaultModel, running) {
+    const selection = record(values.modelSelection);
+    const current = running ? selection.lastUsed ?? selection.next ?? defaultModel : selection.next ?? selection.lastUsed ?? defaultModel;
+    const model = modelName(current);
+    const next = modelName(selection.next);
+    const pressure = record(values.contextPressure);
+    const used = numeric(pressure.projectedTokens) ?? numeric(pressure.pressureTokens);
+    const capacity = numeric(pressure.contextWindow);
+    const context = used !== undefined && capacity !== undefined && capacity > 0
+        ? `~${Math.min(100, Math.round(used / capacity * 100))}% (${count(used)} / ${count(capacity)})`
+        : 'unknown';
+    const usage = record(values.tokenUsage);
+    const buckets = [usage.uncachedInputTokens, usage.outputTokens, usage.cacheReadTokens, usage.cacheWriteTokens].map(numeric);
+    const total = buckets.every(value => value !== undefined) ? buckets.reduce((a, b) => a + b, 0) : undefined;
+    return [
+        `Model: ${model}${running && next !== 'unknown' && next !== model ? ` · Next: ${next}` : ''}`,
+        `Context: ${context} · Tokens: ${count(total)} total`,
+        `In (uncached): ${count(buckets[0])} · Out: ${count(buckets[1])} · Cache read/write: ${count(buckets[2])}/${count(buckets[3])}`,
+    ];
+}
+/** Fit the status summary to one terminal row; details remain available through /status.
+ * @param fields - Priority-ordered status fields, followed by optional details.
+ * @param width - Available terminal columns.
+ * @returns A terminal-safe single line, shortened by display width.
+ */
+export function compactStatus(fields, width) {
+    const clean = fields.map(value => safeText(value).replace(/[\r\n\t]/g, ' '));
+    const fit = (value, size) => {
+        if (size < 2)
+            return size === 1 ? '…' : '';
+        const wrapped = wrapAnsi(value, size, { hard: true, wordWrap: false, trim: false });
+        return wrapped.includes('\n') ? wrapAnsi(value, size - 1, { hard: true, wordWrap: false, trim: false }).split('\n')[0] + '…' : value;
+    };
+    const joins = (values) => values.filter(Boolean).join(' · ');
+    const fits = (value) => !wrapAnsi(value, Math.max(1, width), { hard: true, wordWrap: false, trim: false }).includes('\n');
+    if (fits(joins(clean)))
+        return joins(clean);
+    const core = clean.slice(0, 5);
+    core[1] = fit(core[1] ?? '', Math.max(8, Math.min(28, Math.floor(width / 3))));
+    core[2] = fit(core[2] ?? '', Math.max(6, Math.min(20, Math.floor(width / 5))));
+    for (let size = Math.floor(width / 3); size >= 6 && !fits(joins(core)); size--) {
+        core[1] = fit(clean[1] ?? '', size);
+        core[2] = fit(clean[2] ?? '', Math.max(5, Math.floor(size * 0.6)));
+    }
+    const extras = clean.slice(5);
+    while (extras.length && !fits(joins([...core, ...extras])))
+        extras.pop();
+    return fit(joins([...core, ...extras]), width);
+}
+/** Render a live clock and selected-session metadata; the timer belongs to this mounted bar. */
+export const StatusBar = memo(function StatusBar({ controller, expanded = false }) {
+    const { stdout } = useStdout();
+    const [now, setNow] = useState(Date.now);
+    const running = controller.running;
+    const since = controller.workingSince;
+    useEffect(() => {
+        setNow(Date.now());
+        if (!running)
+            return;
+        const timer = setInterval(() => setNow(Date.now()), 1000);
+        return () => clearInterval(timer);
+    }, [running, since]);
+    const state = controller.state;
+    const workspace = state.workspaces.find(item => item.workspaceId === state.workspaceId);
+    const view = controller.telemetry.view(state.sessionId);
+    const costs = controller.costs;
+    const sessionCost = costs?.hasSession(state.sessionId) ? costText(costs.total(state.sessionId)) : '?';
+    const todayEstimate = costs ? costText(costs.total(undefined, 1, Date.now())) : '?';
+    const todayCost = costs && (!costs.scannedAt || costs.error) && !todayEstimate.endsWith('*') ? todayEstimate + '*' : todayEstimate;
+    const label = workspace ? `${workspace.title} · ${workspace.path}` : 'none selected';
+    if (!expanded) {
+        const selection = record(view.values.modelSelection);
+        const route = record(running ? selection.lastUsed ?? selection.next ?? state.defaultModel : selection.next ?? selection.lastUsed ?? state.defaultModel);
+        const model = typeof route.model === 'string' ? `${route.model}${typeof route.reasoningEffort === 'string' ? ` (${route.reasoningEffort})` : ''}` : 'model ?';
+        const pressure = record(view.values.contextPressure);
+        const used = numeric(pressure.projectedTokens) ?? numeric(pressure.pressureTokens);
+        const capacity = numeric(pressure.contextWindow);
+        const usage = record(view.values.tokenUsage);
+        const buckets = [usage.uncachedInputTokens, usage.outputTokens, usage.cacheReadTokens, usage.cacheWriteTokens].map(numeric);
+        const total = buckets.every(value => value !== undefined) ? buckets.reduce((a, b) => a + b, 0) : undefined;
+        const compactCount = (value) => value === undefined ? '?' : new Intl.NumberFormat('en', { notation: 'compact', maximumFractionDigits: 1 }).format(value);
+        const activity = running ? `Working ${since === undefined ? '?' : elapsedTime(now - since)}${state.transcript.activeTurnStartedAt === undefined ? '~' : ''}` : 'Idle';
+        const fields = [
+            `${!state.online ? 'Offline · ' : ''}${state.controlError || state.modelError ? '! ' : ''}${activity}`,
+            model, `ws: ${workspace ? workspace.title : '—'}`,
+            `ctx: ${used !== undefined && capacity !== undefined && capacity > 0 ? `~${Math.min(100, Math.round(used / capacity * 100))}%` : '?'}`,
+            `tok: ${compactCount(total)}`,
+            `in/out: ${compactCount(buckets[0])}/${compactCount(buckets[1])}`,
+            `cache: ${compactCount(buckets[2])}/${compactCount(buckets[3])}`,
+            `q:${count(view.queued)} jobs:${count(view.jobs)}`,
+            running ? 'Esc/^C stop' : '^C exit', '/status',
+        ];
+        const width = Math.max(1, (stdout.columns ?? 80) - 2);
+        const fee = costs ? ` · S:${sessionCost} D:${todayCost}` : '';
+        return _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: [compactStatus(fields, Math.max(1, width - fee.length)), fee] });
+    }
+    return _jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, children: [_jsxs(Text, { color: running ? 'yellow' : 'gray', children: [running
+                        ? `Working ${since === undefined ? 'unknown duration' : elapsedTime(now - since)}${state.transcript.activeTurnStartedAt === undefined ? ' (observed)' : ''} · Esc / Ctrl+C stop`
+                        : 'Idle · Ctrl+C exit', !state.online ? ' · disconnected, last known status' : ''] }), state.sessionId && _jsxs(Text, { children: ["Session ID: ", safeText(state.sessionId)] }), _jsxs(Text, { wrap: "truncate-end", children: ["Workspace: ", safeText(label)] }), metricLines(view.values, state.defaultModel, running).map((line, index) => _jsx(Text, { dimColor: true, children: safeText(line) }, index)), costs && _jsxs(Text, { dimColor: true, children: ["Cost (CNY estimate): Session ", sessionCost, " \u00B7 Today ", todayCost] }), _jsxs(Text, { dimColor: true, children: ["Queued: ", count(view.queued), " \u00B7 Active jobs: ", count(view.jobs)] }), state.controlError && _jsx(Text, { color: "yellow", children: safeText(state.controlError) }), state.modelError && _jsxs(Text, { color: "yellow", children: ["Model catalog unavailable: ", safeText(state.modelError)] })] });
+});
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function numeric(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function count(value) { return value === undefined ? '?' : value.toLocaleString('en-US'); }
+function modelName(value) {
+    const model = record(value);
+    if (typeof model.model !== 'string' || typeof model.provider !== 'string')
+        return 'unknown';
+    return safeText(`${model.provider}/${model.model}${typeof model.reasoningEffort === 'string' ? ` (${model.reasoningEffort})` : ''}`);
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,28 @@
+/** Host projection values with per-key watermarks; snapshots never roll back newer updates. */
+import { type ObjectValue } from './wire.ts';
+/** Generation-local projection, inbox and background-job data for every session. */
+export declare class Telemetry {
+    private entries;
+    private queues;
+    private jobs;
+    ready: boolean;
+    /** Replace all control state on a new stream baseline, then accept replacement frames.
+     * @param value - One decoded session/control frame.
+     */
+    accept(value: unknown): 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.
+     */
+    snapshot(id: string, value: unknown): 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;
+    };
+    private entry;
+}

package/dist/telemetry.js

@@ -0,0 +1,97 @@
+/** Host projection values with per-key watermarks; snapshots never roll back newer updates. */
+import { array, object, string } from "./wire.js";
+/** Generation-local projection, inbox and background-job data for every session. */
+export class Telemetry {
+    entries = new Map();
+    queues = new Map();
+    jobs = new Map();
+    ready = false;
+    /** Replace all control state on a new stream baseline, then accept replacement frames.
+     * @param value - One decoded session/control frame.
+     */
+    accept(value) {
+        const frame = object(value);
+        if (frame.type === 'baseline') {
+            const baseline = object(frame.value);
+            this.entries.clear();
+            this.queues.clear();
+            this.jobs.clear();
+            for (const [id, projection] of Object.entries(object(baseline.projections)))
+                this.snapshot(id, projection);
+            for (const [id, items] of Object.entries(object(baseline.queues)))
+                this.queues.set(id, array(items).length);
+            for (const [id, items] of Object.entries(object(baseline.jobs)))
+                this.jobs.set(id, activeJobs(items));
+            this.ready = true;
+            return;
+        }
+        if (!this.ready)
+            throw new Error('Session control update before baseline');
+        const id = string(frame.sessionId);
+        if (frame.type === 'projection') {
+            const entry = this.entry(id);
+            const key = string(frame.key);
+            const seq = sequence(frame.seq);
+            if (seq < (entry.revisions.get(key) ?? entry.baseline))
+                return;
+            if (frame.value === undefined)
+                throw new Error('Missing projection value');
+            entry.values[key] = frame.value;
+            entry.revisions.set(key, seq);
+        }
+        else if (frame.type === 'queue')
+            this.queues.set(id, array(frame.items).length);
+        else if (frame.type === 'jobs')
+            this.jobs.set(id, activeJobs(frame.items));
+        else
+            throw new Error('Unknown session control frame');
+    }
+    /** 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.
+     */
+    snapshot(id, value) {
+        if (value === undefined)
+            return;
+        const baseline = object(value);
+        const seq = sequence(baseline.asOfSeq);
+        const values = object(baseline.values);
+        const entry = this.entry(id);
+        if (seq < entry.baseline)
+            return;
+        for (const key of new Set([...Object.keys(entry.values), ...Object.keys(values)])) {
+            if ((entry.revisions.get(key) ?? -1) > seq)
+                continue;
+            if (Object.hasOwn(values, key))
+                entry.values[key] = values[key];
+            else
+                delete entry.values[key];
+            entry.revisions.delete(key);
+        }
+        entry.baseline = seq;
+    }
+    /** 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) {
+        return { values: id ? this.entries.get(id)?.values ?? {} : {},
+            queued: id ? this.queues.get(id) : undefined, jobs: id ? this.jobs.get(id) : undefined };
+    }
+    entry(id) {
+        let entry = this.entries.get(id);
+        if (!entry) {
+            entry = { baseline: -1, values: Object.create(null), revisions: new Map() };
+            this.entries.set(id, entry);
+        }
+        return entry;
+    }
+}
+function sequence(value) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < -1)
+        throw new Error('Invalid projection watermark');
+    return value;
+}
+function activeJobs(value) {
+    return array(value).filter(item => ['running', 'stopping'].includes(string(object(item).status))).length;
+}

package/dist/transcript.d.ts

@@ -0,0 +1,64 @@
+import { type Json } from './wire.ts';
+interface ToolSummary {
+    name: string;
+    operation?: string;
+}
+/** Fit a tool operation to one terminal row without exposing the result body.
+ * @param text - Tool name, status icon and optional operation.
+ * @param width - Available terminal columns.
+ * @returns A single line with an ellipsis when shortened.
+ */
+export declare function toolLine(text: string, width: number): string;
+/** Render known content blocks and preserve unknown plugin blocks as JSON. */
+export declare function contentText(content: Json | undefined, tools?: ReadonlyMap<string, ToolSummary>, width?: number): string;
+/** A displayed message retains the durable sequence for stable reconciliation. */
+export interface Message {
+    seq: number;
+    role: string;
+    text: string;
+    compact?: boolean;
+}
+/** Opening snapshots replace all state; durable events are deduplicated by sequence. */
+export declare class Transcript {
+    private events;
+    private blocks;
+    private attempt;
+    private nextIndex;
+    private revision;
+    private legacyStream;
+    /** Changes whenever a follow frame or older page can affect the rendered transcript. */
+    version: number;
+    cursor: number;
+    hasMore: boolean;
+    ready: boolean;
+    /** Apply one follow frame; reject stream gaps so callers can reopen a snapshot. */
+    accept(value: unknown): void;
+    /** Add an older page without replacing the live tail. */
+    addPage(value: unknown): void;
+    /** Start of the open durable turn, when its timestamp is present in the retained window. */
+    get activeTurnStartedAt(): number | undefined;
+    /** Earliest retained record, used with the opening cursor for backward paging. */
+    get beforeSeq(): number | undefined;
+    /** Return append-origin conversation only; model-only replacement copies stay hidden. */
+    get messages(): Message[];
+    /** Project history with single-row tool operations at the caller's terminal width.
+     * @param width - Available terminal columns.
+     * @returns Conversation messages with compact tool-only rows.
+     */
+    messagesForWidth(width: number): Message[];
+    /** Text from the active attempt is transient and never duplicated into durable history. */
+    get liveText(): string;
+    /** Whether the active stream contains only tool operations, with no assistant prose. */
+    get liveToolOnly(): boolean;
+    /** Render live tool operations within a terminal row.
+     * @param width - Available terminal columns.
+     * @returns Transient assistant text with clipped tool rows.
+     */
+    liveTextForWidth(width: number): string;
+    private addRecords;
+    /** Older hosts log chunks directly; replay only the unfinished attempt for live display. */
+    private rebuildLegacyStream;
+    private validatePackedTiming;
+    private chunk;
+}
+export {};