@itookit/dsht 0.3.7 → 0.5.1

package/dist/controller/trace-log.js

@@ -0,0 +1,144 @@
+/** Append-only diagnostic trace of connection, screen and selection transitions.
+ *
+ * The memory log answers "is retained content growing"; this log answers "why did the client end up
+ * where it is" — every reconnect, picker and selection change is written with the values it moved
+ * between, so a jump that only happens in the field can be read instead of guessed at. Events carry
+ * identifiers and screen names only, never prompt, tool or session text, and a failing log stops
+ * itself instead of breaking the client.
+ */
+import { dirname } from 'node:path';
+import { appendPrivateFile, createPrivateFile, ensureDirectory, readText, writePrivateFile } from "../storage/index.js";
+import { errorText } from "../transport/wire.js";
+/** Events kept; reaching the cap rewrites the file with just these lines. */
+const KEEP_EVENTS = 2000;
+/** First line of the file, so a reader knows what the lines are without reading the source. */
+const HEADER = '# dsht trace: one JSON event per line, oldest first\n';
+/** Events whose `begin` opens a span a later phase closes; only these constrain where a cut may fall. */
+const SPAN_EVENTS = new Set(['command', 'loop', 'generation']);
+/** Phases that close a span opened by `begin`. */
+const CLOSE_PHASES = new Set(['end', 'failed', 'cancelled', 'ended']);
+/** Identifier fields, in priority order, that let a span's `begin` and its close be matched. */
+const SPAN_IDS = ['commandId', 'operationId', 'turnId', 'runId', 'generationId'];
+/** Read the span one line belongs to, if any.
+ *
+ * A line without a known event or phase carries no span: it is an ordinary event whose position in the
+ * file means nothing to a reader, so compaction may cut on either side of it. A span without its own id
+ * — `generation` has none — still pairs by event name, because only one of them is ever open at a time
+ * and dropping that pairing would erase the marker that separates two connections.
+ * @param line - One JSON line of the trace.
+ * @returns The span key and whether it opens or closes, or undefined.
+ */
+function spanOf(line) {
+    let record;
+    try {
+        record = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    const event = record.event;
+    const phase = record.phase;
+    if (typeof event !== 'string' || !SPAN_EVENTS.has(event) || typeof phase !== 'string')
+        return undefined;
+    const open = phase === 'begin';
+    if (!open && !CLOSE_PHASES.has(phase))
+        return undefined;
+    const id = SPAN_IDS.map(field => record[field]).find(value => typeof value === 'string');
+    return { key: `${event}:${id ?? ''}`, open };
+}
+/** The index the newest `keep` lines start at, moved forward past any split lifecycle span.
+ *
+ * A span opened before the cut and closed after it would be kept as a close without its begin, so the
+ * cut moves to just after that close and the check repeats: the newly dropped region may itself open a
+ * span that closes later. A span whose close never appears cannot be split, so it does not move the
+ * cut — that is the in-flight command the file exists to show.
+ * @param lines - Every line this process appended, oldest first.
+ * @param keep - How many of the newest lines the caller wants to keep.
+ * @returns Index of the first line to keep; always at most `lines.length - keep`.
+ */
+export function compactCut(lines, keep = KEEP_EVENTS) {
+    let cut = Math.max(0, lines.length - keep);
+    for (;;) {
+        const open = new Set();
+        for (let index = 0; index < cut; index += 1) {
+            const span = spanOf(lines[index]);
+            if (span === undefined)
+                continue;
+            if (span.open)
+                open.add(span.key);
+            else
+                open.delete(span.key);
+        }
+        if (open.size === 0)
+            return cut;
+        let moved = -1;
+        for (let index = cut; index < lines.length; index += 1) {
+            const span = spanOf(lines[index]);
+            if (span !== undefined && !span.open && open.has(span.key))
+                moved = index + 1;
+        }
+        if (moved === -1)
+            return cut;
+        cut = moved;
+    }
+}
+/** Serialized append-only trace; the file holds at most `KEEP_EVENTS` lines, fewer when a lifecycle span would be split.
+ *
+ * Writes are chained rather than awaited by the caller, because transitions are published from
+ * synchronous state updates. A failed write is remembered and reported on the next event instead of
+ * throwing into the controller.
+ */
+export class TraceLog {
+    path;
+    queue = Promise.resolve();
+    lines = [];
+    directoryEnsured = false;
+    /** Last write failure, when the log stopped growing. */
+    error;
+    constructor(path) {
+        this.path = path;
+    }
+    /** Append one event; an absent path makes this a no-op. */
+    record(event) {
+        if (this.path === undefined)
+            return;
+        const line = `${JSON.stringify({ time: new Date().toISOString(), ...event })}\n`;
+        this.lines.push(line);
+        this.queue = this.queue.then(() => this.append(line))
+            .catch(error => { this.error = errorText(error); });
+    }
+    /** Wait for queued writes, so a shutdown does not lose the last events. */
+    async settle() { await this.queue; }
+    /** Write one line, then bound the file when the cap is reached. */
+    async append(line) {
+        if (!this.directoryEnsured) {
+            await ensureDirectory(dirname(this.path));
+            this.directoryEnsured = true;
+        }
+        // Seeding a header only affects a new file; an existing trace is appended to.
+        await createPrivateFile(this.path, HEADER);
+        await appendPrivateFile(this.path, line);
+        this.error = undefined;
+        if (this.lines.length >= KEEP_EVENTS)
+            await this.compact();
+    }
+    /** Rewrite the file with the header and the newest kept lines, bounding its size.
+     *
+     * Older runs are not read back: `lines` is what this process appended, which bounds both the file
+     * and the read that rewrites it. The cut is pairing-aware, so a kept `begin` is never orphaned from
+     * its close and a kept close never loses its begin.
+     */
+    async compact() {
+        const kept = this.lines.slice(compactCut(this.lines, KEEP_EVENTS));
+        await writePrivateFile(this.path, HEADER + kept.join(''));
+        this.lines = kept;
+    }
+}
+/** Read a trace back, so a test or a diagnostic tool can assert what was recorded.
+ * @param path - Trace file to read.
+ * @returns Every non-empty line, oldest first.
+ */
+export async function readTrace(path) {
+    const text = await readText(path);
+    return text === undefined ? [] : text.split('\n').filter(line => line !== '');
+}

package/dist/controller/verifier.d.ts

@@ -0,0 +1,126 @@
+import type { LoopResult } from './loop.ts';
+/** Identity one verification carries, so a file can never be read as another run's verdict.
+ *
+ * Two clients reviewing the same step would otherwise write and delete the same path, and the
+ * kind/step/attempt triple cannot tell them apart. The sequence is the finer half: one `attempt`
+ * may start several verification tasks (a failure retry, an operator answer), and only the task
+ * that is still awaited may decide the attempt.
+ * @param runId - Identity of one loop run, unique per client run.
+ * @param kind - Protocol kind.
+ * @param step - Step in flight.
+ * @param attempt - Attempt in flight.
+ * @param seq - This verification task's sequence within the run.
+ * @returns The identity string embedded in the verdict file.
+ */
+export declare function verificationId(runId: string, kind: string, step: number, attempt: number, seq: number): string;
+/** Directory holding one run's verdicts, so a whole review can be audited or removed as a group.
+ * @param directory - Workspace directory the review runs in.
+ * @param runId - Identity of the run.
+ * @returns The absolute directory.
+ */
+export declare function verdictDirectory(directory: string, runId: string): string;
+/** Path of the verdict one verification task must write.
+ * @param directory - Workspace directory the review runs in.
+ * @param runId - Identity of the run; part of the path so concurrent runs never collide.
+ * @param kind - Protocol kind.
+ * @param step - Step in flight.
+ * @param attempt - Attempt in flight.
+ * @param seq - This verification task's sequence within the run; part of the name so a retry
+ *   cannot be read as, or overwrite, the task it replaced.
+ * @returns The absolute verdict path.
+ */
+export declare function verdictFile(directory: string, runId: string, kind: string, step: number, attempt: number, seq: number): string;
+/** One round handed to an independent verifier. */
+export interface VerifierRequest {
+    /** Identity of this verification; the verdict file must declare it back. */
+    verificationId: string;
+    /** Protocol kind the verdict must declare, so a stale file cannot score this round. */
+    kind: string;
+    /** Step in flight. */
+    step: number;
+    /** Attempt in flight. */
+    attempt: number;
+    /** Prompt the verifier session receives, built by the protocol. */
+    prompt: string;
+    /** Session title, so a reader can tell verifier sessions apart in the host's list. */
+    title: string;
+    /** Absolute path the verifier must write its verdict to. */
+    file: string;
+    /** Absolute path of the workspace the artifact belongs to.
+     *
+     * Declared per request instead of inferred from the verifier's own working directory: the
+     * reviewed tree and the process that happens to run the check are different things, and only the
+     * caller knows which workspace this round is about.
+     */
+    workspace: string;
+    /** Workspace file the verifier must not change, when the protocol names one. */
+    artifact?: string;
+}
+/** What a host is waiting for when the verifier cannot answer by itself. */
+export interface VerificationHumanRequest {
+    /** `approval` or `question`, as the host reported it. */
+    kind: string;
+    /** One line a reader can act on. */
+    text: string;
+}
+/** Marker a child prints on the line that reports an unanswerable human request.
+ *
+ * The child sees the interaction on its own session and exits; the parent parses the same line back
+ * out of the child's output. One definition keeps both sides from drifting.
+ */
+export declare const NEEDS_HUMAN_MARKER = "dsht-verify-needs-human:";
+/** Render the line the child logs and the parent parses.
+ * @param request - What the host is waiting for.
+ * @returns The marker line.
+ */
+export declare function needsHumanLine(request: VerificationHumanRequest): string;
+/** Read that line back, ignoring every other line the child prints.
+ * @param line - One child output line.
+ * @returns The request, or undefined when the line is not this marker.
+ */
+export declare function parseNeedsHumanLine(line: string): VerificationHumanRequest | undefined;
+/** What one verification produced.
+ *
+ * A missing verdict is not a failed review: the reviewed session produced work and nobody judged it.
+ * The two are kept apart so an outage never spends an attempt and never lets the reviewer pass itself.
+ */
+export type VerifierOutcome = 
+/** An independent verdict was produced and can decide the attempt. */
+{
+    type: 'verified';
+    result: LoopResult;
+    sessionId: string;
+}
+/** The verifier could not judge: no session, no child, no verdict, or a timeout.
+ *
+ * `retryable: false` means the same failure will not fix itself — a remote task may still be
+ * running, or the client is configured wrong — so the controller reports it instead of spending
+ * its retry budget. Absent means the failure is treated as transient.
+ */
+ | {
+    type: 'unavailable';
+    reason: string;
+    sessionId?: string;
+    retryable?: boolean;
+}
+/** The review itself was cancelled, so there is nothing to decide. */
+ | {
+    type: 'cancelled';
+}
+/** The host is waiting for a human; the verifier session's turn was cancelled, not judged. */
+ | {
+    type: 'needs-human';
+    request: VerificationHumanRequest;
+    sessionId: string;
+};
+/** Judge one round independently. */
+export interface VerifierPort {
+    /** Which harness judges: `dsht` for the forked client, a future adapter names itself here. */
+    readonly name: string;
+    /** Run one verification to completion, or to cancellation.
+     * @param request - Round identity, prompt and verdict path.
+     * @param signal - Cancels the run and its child process.
+     * @returns The verdict, or a note explaining why there is none.
+     */
+    verify(request: VerifierRequest, signal: AbortSignal): Promise<VerifierOutcome>;
+}

package/dist/controller/verifier.js

@@ -0,0 +1,75 @@
+/** Independent verification of one scored round, as a capability rather than a mechanism.
+ *
+ * The loop owns when a round is judged; this port owns how. The implementation runs a child `dsht`
+ * against a session of its own and reads the verdict file that session writes, but the controller
+ * only ever sees a port, so a test can decide a round without spawning anything.
+ */
+import { join } from 'node:path';
+/** Identity one verification carries, so a file can never be read as another run's verdict.
+ *
+ * Two clients reviewing the same step would otherwise write and delete the same path, and the
+ * kind/step/attempt triple cannot tell them apart. The sequence is the finer half: one `attempt`
+ * may start several verification tasks (a failure retry, an operator answer), and only the task
+ * that is still awaited may decide the attempt.
+ * @param runId - Identity of one loop run, unique per client run.
+ * @param kind - Protocol kind.
+ * @param step - Step in flight.
+ * @param attempt - Attempt in flight.
+ * @param seq - This verification task's sequence within the run.
+ * @returns The identity string embedded in the verdict file.
+ */
+export function verificationId(runId, kind, step, attempt, seq) {
+    return `${runId}/${kind}/${step}/${attempt}/${seq}`;
+}
+/** Directory holding one run's verdicts, so a whole review can be audited or removed as a group.
+ * @param directory - Workspace directory the review runs in.
+ * @param runId - Identity of the run.
+ * @returns The absolute directory.
+ */
+export function verdictDirectory(directory, runId) {
+    return join(directory, '.dsht', 'verify', runId);
+}
+/** Path of the verdict one verification task must write.
+ * @param directory - Workspace directory the review runs in.
+ * @param runId - Identity of the run; part of the path so concurrent runs never collide.
+ * @param kind - Protocol kind.
+ * @param step - Step in flight.
+ * @param attempt - Attempt in flight.
+ * @param seq - This verification task's sequence within the run; part of the name so a retry
+ *   cannot be read as, or overwrite, the task it replaced.
+ * @returns The absolute verdict path.
+ */
+export function verdictFile(directory, runId, kind, step, attempt, seq) {
+    return join(verdictDirectory(directory, runId), `${kind}-${step}-${attempt}-${seq}.json`);
+}
+/** Marker a child prints on the line that reports an unanswerable human request.
+ *
+ * The child sees the interaction on its own session and exits; the parent parses the same line back
+ * out of the child's output. One definition keeps both sides from drifting.
+ */
+export const NEEDS_HUMAN_MARKER = 'dsht-verify-needs-human:';
+/** Render the line the child logs and the parent parses.
+ * @param request - What the host is waiting for.
+ * @returns The marker line.
+ */
+export function needsHumanLine(request) {
+    return `${NEEDS_HUMAN_MARKER}${JSON.stringify(request)}`;
+}
+/** Read that line back, ignoring every other line the child prints.
+ * @param line - One child output line.
+ * @returns The request, or undefined when the line is not this marker.
+ */
+export function parseNeedsHumanLine(line) {
+    const at = line.indexOf(NEEDS_HUMAN_MARKER);
+    if (at === -1)
+        return undefined;
+    try {
+        const parsed = JSON.parse(line.slice(at + NEEDS_HUMAN_MARKER.length));
+        if (typeof parsed.kind !== 'string' || typeof parsed.text !== 'string')
+            return undefined;
+        return { kind: parsed.kind, text: parsed.text };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cost/index.d.ts

@@ -1,7 +1,7 @@
 /** Cost domain: price tables, record folding, the folded ledger, the scanner and its controller. */
 export { CostController } from './controller.ts';
 export type { CostHost } from './controller.ts';
-export { CostLedger, costText } from './ledger.ts';
+export { CostLedger } from './ledger.ts';
 export { loadPrices } from './config.ts';
 export { candidates, canonicalModel, chargeFor, costDay, DEFAULT_PRICES, isUncorrectedSeed, priceAt, PRICES_REVISION, PRICING_ENGINE_VERSION, pricesDigest, pricesFrom } from './pricing.ts';
 export { costRecords, foldSamples } from './records.ts';

package/dist/cost/index.js

@@ -1,6 +1,6 @@
 /** Cost domain: price tables, record folding, the folded ledger, the scanner and its controller. */
 export { CostController } from "./controller.js";
-export { CostLedger, costText } from "./ledger.js";
+export { CostLedger } from "./ledger.js";
 export { loadPrices } from "./config.js";
 export { candidates, canonicalModel, chargeFor, costDay, DEFAULT_PRICES, isUncorrectedSeed, priceAt, PRICES_REVISION, PRICING_ENGINE_VERSION, pricesDigest, pricesFrom } from "./pricing.js";
 export { costRecords, foldSamples } from "./records.js";

package/dist/cost/ledger.d.ts

@@ -75,4 +75,3 @@ export declare class CostLedger {
  * @param total - Summary from the ledger.
  * @returns Yuan amount and incompleteness marker.
  */
-export declare function costText(total: CostTotal): string;

package/dist/cost/ledger.js

@@ -143,4 +143,3 @@ export class CostLedger {
  * @param total - Summary from the ledger.
  * @returns Yuan amount and incompleteness marker.
  */
-export function costText(total) { return `~¥${total.amount.toFixed(4)}${total.unknown ? '*' : ''}`; }

package/dist/json.d.ts

@@ -0,0 +1,18 @@
+/** Plain JSON shapes and the strict readers for them.
+ *
+ * A dependency-free leaf shared by the wire, the features and the UI contract: the wire validates
+ * what it decodes with these, and the UI reads the host summaries it is handed. Typing those
+ * summaries per feature is what will eventually let the UI stop reading raw objects.
+ */
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export type ObjectValue = {
+    [key: string]: Json;
+};
+/** Require an object from a decoded wire message. */
+export declare function object(value: unknown): ObjectValue;
+/** Require a string field rather than silently accepting protocol drift. */
+export declare function string(value: unknown): string;
+/** Require an array field from the server. */
+export declare function array(value: unknown): Json[];

package/dist/json.js

@@ -0,0 +1,19 @@
+/** Require an object from a decoded wire message. */
+export function object(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Expected a JSON object from the server');
+    }
+    return value;
+}
+/** Require a string field rather than silently accepting protocol drift. */
+export function string(value) {
+    if (typeof value !== 'string')
+        throw new Error('Expected a string from the server');
+    return value;
+}
+/** Require an array field from the server. */
+export function array(value) {
+    if (!Array.isArray(value))
+        throw new Error('Expected an array from the server');
+    return value;
+}

package/dist/references.d.ts

@@ -0,0 +1,25 @@
+/** The composer's `@` mention grammar.
+ *
+ * Both the session domain (validating host candidates) and the composer (finding the unfinished
+ * token and encoding a choice) need the same syntax, so it lives in its own leaf.
+ */
+/** 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;

package/dist/references.js

@@ -0,0 +1,26 @@
+/** 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' ? '"' : ''}`;
+}

package/dist/session/connection-view.d.ts

@@ -1,18 +1,9 @@
 /** What the session domain reads from the connection the controller owns. */
-import type { Telemetry } from './telemetry.ts';
-import type { ObjectValue } from '../transport/wire.ts';
+import type { Json } from '../transport/wire.ts';
 /** Read-only connection facts and actions the session controller needs. */
 export interface ConnectionView {
-    /** Projection store of the current generation. */
-    telemetryView(): Telemetry;
-    /** Cached host running flag for one session, or undefined when never reported. */
-    runningFor(sessionId: string): boolean | undefined;
-    /** When this client first observed the session, for the elapsed-time fallback. */
-    observedAt(sessionId: string): number | undefined;
-    /** Record an observation start for a session this client just opened. */
-    observe(sessionId: string): void;
     /** Fail the current generation, so the controller reopens a snapshot. */
     fail(error: Error): void;
     /** Answer one retained host waterfall through the event-result endpoint. */
-    reply(frame: ObjectValue, outcome: ObjectValue): Promise<void>;
+    reply(eventId: string, outcome: Json): Promise<void>;
 }