@itookit/dsht 0.3.0 → 0.3.2

package/dist/session/math.js

@@ -0,0 +1,82 @@
+/** MathJax compiles TeX locally; terminal output keeps explicit grouping when Unicode cannot express it. */
+import { mathjax } from '@mathjax/src/js/mathjax.js';
+import { TeX } from '@mathjax/src/js/input/tex.js';
+import { liteAdaptor } from '@mathjax/src/js/adaptors/liteAdaptor.js';
+import { RegisterHTMLHandler } from '@mathjax/src/js/handlers/html.js';
+import { STATE } from '@mathjax/src/js/core/MathItem.js';
+import { TextNode } from '@mathjax/src/js/core/MmlTree/MmlNode.js';
+import { SerializedMmlVisitor } from '@mathjax/src/js/core/MmlTree/SerializedMmlVisitor.js';
+import '@mathjax/src/js/input/tex/base/BaseConfiguration.js';
+import '@mathjax/src/js/input/tex/ams/AmsConfiguration.js';
+import { safeText } from "../transport/wire.js";
+RegisterHTMLHandler(liteAdaptor());
+const superscripts = Object.fromEntries([...('0123456789+-=()ni')].map((c, i) => [c, [...'⁰¹²³⁴⁵⁶⁷⁸⁹⁺⁻⁼⁽⁾ⁿⁱ'][i]]));
+const subscripts = Object.fromEntries([...'0123456789+-=()aehijklmnoprstuvx'].map((c, i) => [c, [...'₀₁₂₃₄₅₆₇₈₉₊₋₌₍₎ₐₑₕᵢⱼₖₗₘₙₒₚᵣₛₜᵤᵥₓ'][i]]));
+function script(text, sub) {
+    const alphabet = sub ? subscripts : superscripts;
+    return [...text].every(c => alphabet[c]) ? [...text].map(c => alphabet[c]).join('') : `${sub ? '_' : '^'}(${text})`;
+}
+function readable(node) {
+    if (node instanceof TextNode)
+        return node.getText();
+    const children = node.childNodes.map(readable);
+    const [a = '', b = '', c = ''] = children;
+    let base = node.childNodes[0];
+    while (base && ['TeXAtom', 'mrow', 'inferredMrow', 'mstyle'].includes(base.kind) && base.childNodes.length === 1)
+        base = base.childNodes[0];
+    const grouped = base && !base.isToken && base.childNodes.length > 1 ? `(${a})` : a;
+    switch (node.kind) {
+        case 'mfrac': return `(${a})/(${b})`;
+        case 'msqrt': return `√(${children.join('')})`;
+        case 'mroot': return `root(${b}, ${a})`;
+        case 'msup': return `${grouped}${script(b, false)}`;
+        case 'msub': return `${grouped}${script(b, true)}`;
+        case 'msubsup': return `${grouped}${script(b, true)}${script(c, false)}`;
+        case 'munder': return `${a}_(${b})`;
+        case 'mover': return `${a}^(${b})`;
+        case 'munderover': return `${a}_(${b})^(${c})`;
+        case 'mtable': return `[${children.join('; ')}]`;
+        case 'mtr':
+        case 'mlabeledtr': return children.join(', ');
+        case 'mspace': return ' ';
+        case 'mphantom': return '';
+        case 'math':
+        case 'mrow':
+        case 'inferredMrow':
+        case 'TeXAtom':
+        case 'mstyle':
+        case 'mi':
+        case 'mn':
+        case 'mo':
+        case 'mtext':
+        case 'mtd': return children.join('');
+        default: throw new Error(`Unsupported terminal math node: ${node.kind}`);
+    }
+}
+/** Convert one TeX expression, without extension autoloads, network access or shared macro state.
+ * @param source - TeX without delimiters.
+ * @param display - Block rather than inline mathematics.
+ * @returns Unicode approximation and MathJax-generated MathML, or undefined for invalid TeX.
+ */
+export function renderMath(source, display) {
+    if (source.length > 16 * 1024)
+        return undefined;
+    try {
+        const tex = new TeX({ packages: ['base', 'ams'], maxBuffer: 16 * 1024,
+            formatError(_jax, error) { throw error; } });
+        const document = mathjax.document('', { InputJax: tex });
+        const node = document.convert(source, { display, end: STATE.CONVERT });
+        const html = new SerializedMmlVisitor().visitTree(node);
+        let text;
+        try {
+            text = readable(node);
+        }
+        catch {
+            text = source; /* Valid MathML with no faithful terminal notation retains its TeX. */
+        }
+        return { text: safeText(text), html };
+    }
+    catch {
+        return undefined; /* Incomplete or invalid model-authored TeX remains visible as source. */
+    }
+}

package/dist/{navigation.d.ts → session/navigation.d.ts}

@@ -1,5 +1,5 @@
 /** Shared display names and unambiguous slash-command target resolution. */
-import { type ObjectValue } from './wire.ts';
+import { type ObjectValue } from '../transport/wire.ts';
 /** Parse workspace and resume navigation, including their long aliases. */
 export declare function navigationCommand(value: string): {
     kind: 'workspace' | 'session';

package/dist/{navigation.js → session/navigation.js}

@@ -1,5 +1,5 @@
 /** Shared display names and unambiguous slash-command target resolution. */
-import { safeText, string } from "./wire.js";
+import { safeText, string } from "../transport/wire.js";
 /** Parse workspace and resume navigation, including their long aliases. */
 export function navigationCommand(value) {
     const match = /^\/(ws|workspace|workspaces|resume|session|sessions)(?:\s+(.+))?$/.exec(value);

package/dist/{references.js → session/references.js}

@@ -1,5 +1,5 @@
 /** Independent adapter for Harness path-only @ references; no file bytes are read. */
-import { array, object, string } from "./wire.js";
+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.

package/dist/{telemetry.d.ts → session/telemetry.d.ts}

@@ -1,5 +1,5 @@
 /** Host projection values with per-key watermarks; snapshots never roll back newer updates. */
-import { type ObjectValue } from './wire.ts';
+import { type ObjectValue } from '../transport/wire.ts';
 /** One host-owned pending input, removable only while its occurrence remains queued. */
 export interface QueuedInput {
     id: string;

package/dist/{telemetry.js → session/telemetry.js}

@@ -1,5 +1,5 @@
 /** Host projection values with per-key watermarks; snapshots never roll back newer updates. */
-import { array, object, string } from "./wire.js";
+import { array, object, string } from "../transport/wire.js";
 function queuedInputs(value) {
     return array(value).map(value => {
         const item = object(value);

package/dist/{transcript.d.ts → session/transcript.d.ts}

@@ -1,5 +1,5 @@
 import type { HistoryLimits } from './memory.ts';
-import { type Json } from './wire.ts';
+import { type Json } from '../transport/wire.ts';
 interface ToolSummary {
     name: string;
     operation?: string;
@@ -25,6 +25,17 @@ export interface MessagePart {
     text: string;
     /** Closed live reasoning can fold before the assistant message is committed. */
     closed?: boolean;
+    /** Stable identity of a live part, so its rows can be wrapped incrementally as it grows. */
+    key?: string;
+}
+/** The stripe of live work the unfinished attempt is in. */
+export interface LivePhase {
+    /** Which kind of delta last moved the attempt forward. */
+    kind: 'thinking' | 'tool' | 'output';
+    /** Tool name when `kind` is `tool`, so the bar can name what is running. */
+    name?: string;
+    /** Epoch milliseconds when this phase began. */
+    startedAt: number;
 }
 /** A displayed message retains the durable sequence for stable reconciliation. */
 export interface Message {
@@ -61,6 +72,7 @@ export declare class Transcript {
     private oldestSeq;
     private turnMarker;
     private attempt;
+    private phase;
     private nextIndex;
     private revision;
     private legacyStream;
@@ -97,6 +109,12 @@ export declare class Transcript {
     private dropProjections;
     private storeEvent;
     private deleteEvent;
+    /** The stripe of work the live attempt is in: the phase of the block that last took a delta.
+     *
+     * Its age answers "what is it doing, and for how long" without inferring anything from silence.
+     * @returns Phase kind, the tool name when the phase is a tool call, and when the phase began.
+     */
+    get livePhase(): LivePhase | undefined;
     /** Start of the open durable turn, when its timestamp is present in the retained window. */
     get activeTurnStartedAt(): number | undefined;
     /** Cached prompt/reasoning summaries, oldest first; stream deltas never invalidate this index. */
@@ -144,6 +162,10 @@ export declare class Transcript {
      */
     private foldLegacy;
     private validatePackedTiming;
+    /** Drop the live attempt's blocks and the phase derived from them. */
+    private clearBlocks;
+    /** Record the phase a delta moved the attempt into; the status bar shows its age. */
+    private notePhase;
     private chunk;
 }
 export {};

package/dist/{transcript.js → session/transcript.js}

@@ -1,6 +1,6 @@
 /** Human transcript projection from durable events and ephemeral assistant chunks. */
 import sliceAnsi from 'slice-ansi';
-import { array, object, safeText, string } from "./wire.js";
+import { array, object, safeText, string } from "../transport/wire.js";
 function toolSummary(block) {
     let args = {};
     if (typeof block.arguments === 'string' && block.arguments.trimStart().startsWith('{')) {
@@ -77,6 +77,7 @@ export class Transcript {
     oldestSeq;
     turnMarker;
     attempt;
+    phase;
     nextIndex = 0;
     revision = 0;
     legacyStream = false;
@@ -114,7 +115,7 @@ export class Transcript {
                 this.closedBlocks.clear();
                 this.oldestSeq = undefined;
                 this.turnMarker = undefined;
-                this.blocks.clear();
+                this.clearBlocks();
                 this.keysDirty = true;
                 this.projectionRevision++;
                 this.legacyDirty = true;
@@ -157,8 +158,7 @@ export class Transcript {
                     throw new Error('Assistant stream revision gap');
                 this.revision = number(live.revision);
                 if (live.type === 'start') {
-                    this.blocks.clear();
-                    this.closedBlocks.clear();
+                    this.clearBlocks();
                     this.attempt = string(live.attemptId);
                     this.nextIndex = 0;
                 }
@@ -172,7 +172,7 @@ export class Transcript {
                     }
                     else if (live.type === 'end') {
                         this.attempt = undefined;
-                        this.blocks.clear();
+                        this.clearBlocks();
                     }
                     else
                         throw new Error('Unknown assistant stream frame');
@@ -257,8 +257,7 @@ export class Transcript {
         this.events.clear();
         this.sizes.clear();
         this.storedBytes = 0;
-        this.blocks.clear();
-        this.closedBlocks.clear();
+        this.clearBlocks();
         this.transientSeqs.clear();
         this.sortedSeqs = [];
         this.displayed = [];
@@ -296,6 +295,17 @@ export class Transcript {
         this.sizes.delete(seq);
         this.events.delete(seq);
     }
+    /** The stripe of work the live attempt is in: the phase of the block that last took a delta.
+     *
+     * Its age answers "what is it doing, and for how long" without inferring anything from silence.
+     * @returns Phase kind, the tool name when the phase is a tool call, and when the phase began.
+     */
+    get livePhase() {
+        if (this.phase === undefined || this.blocks.size === 0)
+            return undefined;
+        const { kind, name, startedAt } = this.phase;
+        return { kind, ...(name === undefined ? {} : { name }), startedAt };
+    }
     /** Start of the open durable turn, when its timestamp is present in the retained window. */
     get activeTurnStartedAt() {
         return this.turnMarker?.start;
@@ -449,6 +459,7 @@ export class Transcript {
      * @returns Ordered blocks without terminal style escapes.
      */
     liveParts(width) {
+        const attempt = this.liveAttemptKey ?? 'live';
         return [...this.blocks].sort(([a], [b]) => a - b).map(([index, block]) => {
             const closed = this.closedBlocks.has(index);
             const cached = this.liveProjection.get(block);
@@ -457,6 +468,7 @@ export class Transcript {
             const part = {
                 kind: block.type === 'reasoning' ? 'reasoning' : block.type === 'tool-call' ? 'tool' : 'text',
                 text: cached?.width === width ? cached.part.text : contentText([block], undefined, width), closed,
+                key: `${attempt}:${index}`,
             };
             this.liveProjection.set(block, { width, part });
             return part;
@@ -520,8 +532,7 @@ export class Transcript {
     foldLegacy(added) {
         let events;
         if (this.legacyDirty) {
-            this.blocks.clear();
-            this.closedBlocks.clear();
+            this.clearBlocks();
             this.legacyPosition = '';
             this.legacySeq = -1;
             this.legacyDirty = false;
@@ -533,17 +544,14 @@ export class Transcript {
         for (const event of events) {
             this.legacySeq = Math.max(this.legacySeq, number(event.seq));
             if (['step/start', 'step/end', 'turn/end', 'assistant/message', 'assistant/attempt'].includes(string(event.type))) {
-                this.blocks.clear();
-                this.closedBlocks.clear();
+                this.clearBlocks();
                 this.legacyPosition = '';
             }
             else if (event.type === 'assistant/chunk' || string(event.type).startsWith('chunkrow/')) {
                 const data = object(event.data);
                 const nextPosition = `${number(data.turn)}:${number(data.step)}`;
-                if (this.legacyPosition !== nextPosition) {
-                    this.blocks.clear();
-                    this.closedBlocks.clear();
-                }
+                if (this.legacyPosition !== nextPosition)
+                    this.clearBlocks();
                 this.legacyPosition = nextPosition;
                 switch (event.type) {
                     case 'assistant/chunk':
@@ -572,6 +580,15 @@ export class Transcript {
         if (count === 0 || array(data.dt).length !== count - 1)
             throw new Error('Invalid packed history member count');
     }
+    /** Drop the live attempt's blocks and the phase derived from them. */
+    clearBlocks() { this.blocks.clear(); this.closedBlocks.clear(); this.phase = undefined; }
+    /** Record the phase a delta moved the attempt into; the status bar shows its age. */
+    notePhase(kind, name) {
+        const key = kind === 'tool' ? `tool:${name ?? ''}` : kind;
+        if (this.phase?.key === key)
+            return;
+        this.phase = { key, kind, ...(name === undefined ? {} : { name }), startedAt: Date.now() };
+    }
     chunk(chunk) {
         if (chunk.type === 'text-delta' || chunk.type === 'tool-call-delta') {
             for (const [index, block] of this.blocks)
@@ -583,13 +600,14 @@ export class Transcript {
             const block = this.blocks.get(index);
             this.blocks.set(index, { type: chunk.type === 'text-delta' ? 'text' : 'reasoning',
                 text: (block ? string(block.text) : '') + string(chunk.text) });
+            this.notePhase(chunk.type === 'text-delta' ? 'output' : 'thinking');
         }
         else if (chunk.type === 'tool-call-delta') {
             const index = number(chunk.index);
             const block = this.blocks.get(index);
-            this.blocks.set(index, { type: 'tool-call', id: string(chunk.id),
-                name: typeof chunk.name === 'string' ? chunk.name : block?.name ?? '',
-                arguments: '' });
+            const name = typeof chunk.name === 'string' ? chunk.name : typeof block?.name === 'string' ? block.name : '';
+            this.blocks.set(index, { type: 'tool-call', id: string(chunk.id), name, arguments: '' });
+            this.notePhase('tool', name === '' ? undefined : name);
         }
         else if (chunk.type === 'block-end') {
             this.blocks.set(number(chunk.index), object(chunk.block));

package/dist/session/types.d.ts

@@ -0,0 +1,18 @@
+/** Session-domain result types shared by the controller facade and the terminal UI. */
+/** Resolved navigation-removal identity; empty marks a fresh blank, idle session eligible for immediate archival. */
+export interface RemovalTarget {
+    kind: 'workspace' | 'session';
+    id: string;
+    name: string;
+    path?: string;
+    empty?: boolean;
+}
+/** Bounded search results contain navigation summaries, never complete message bodies. */
+export interface HistorySearch {
+    items: {
+        seq: number;
+        role: string;
+        preview: string;
+    }[];
+    truncated: boolean;
+}

package/dist/session/types.js

@@ -0,0 +1,2 @@
+/** Session-domain result types shared by the controller facade and the terminal UI. */
+export {};

package/dist/state.d.ts

@@ -0,0 +1,41 @@
+/** Application state shared by the controller facade and every domain controller. */
+import { Transcript } from './session/transcript.ts';
+import type { HistorySearch, RemovalTarget } from './session/types.ts';
+import type { ObjectValue } from './transport/wire.ts';
+/** State shared by the picker and conversation view. */
+export interface State {
+    version: number;
+    online: boolean;
+    busy: boolean;
+    screen: 'workspaces' | 'sessions' | 'chat' | 'path';
+    status: string;
+    error: string;
+    workspaces: ObjectValue[];
+    sessions: ObjectValue[];
+    showAllSessions: boolean;
+    workspaceId?: string;
+    sessionId?: string;
+    pending: ObjectValue[];
+    controlError?: string;
+    modelError?: string;
+    presetError?: string;
+    presets?: ObjectValue[];
+    defaultModel?: ObjectValue;
+    transcript: Transcript;
+}
+/** The state contract every domain controller writes through. */
+export interface ControllerStore {
+    /** Current immutable state snapshot. */
+    readonly state: State;
+    /** Publish a state patch and notify observers. */
+    update(patch: Partial<State>): void;
+    /** Monotonic selector generation; a changed value discards in-flight session work. */
+    selection(): number;
+    /** Advance the selector generation when the selected workspace or session changes. */
+    bumpSelection(): void;
+}
+/** Build the initial state before any connection exists.
+ * @returns A fresh state whose transcript is empty and disconnected.
+ */
+export declare function initialState(): State;
+export type { HistorySearch, RemovalTarget };

package/dist/state.js

@@ -0,0 +1,9 @@
+/** Application state shared by the controller facade and every domain controller. */
+import { Transcript } from "./session/transcript.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() };
+}

package/dist/storage/directories.d.ts

@@ -0,0 +1,14 @@
+/** Create a directory tree with owner-only permissions, leaving an existing directory as it is.
+ * @param path - Directory path.
+ */
+export declare function ensureDirectory(path: string): Promise<void>;
+/** Create a directory tree and require it to stay owner-only.
+ * @param path - Directory path.
+ * @param label - Name used in the validation error, such as `Cookie directory`.
+ */
+export declare function ensurePrivateDirectory(path: string, label: string): Promise<void>;
+/** List the entry names of one directory.
+ * @param path - Directory path.
+ * @returns Entry names in filesystem order.
+ */
+export declare function listEntries(path: string): Promise<string[]>;

package/dist/storage/directories.js

@@ -0,0 +1,24 @@
+/** Private directory creation and listing for the client's configuration and state. */
+import { lstat, mkdir, readdir } from 'node:fs/promises';
+/** Create a directory tree with owner-only permissions, leaving an existing directory as it is.
+ * @param path - Directory path.
+ */
+export async function ensureDirectory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+}
+/** Create a directory tree and require it to stay owner-only.
+ * @param path - Directory path.
+ * @param label - Name used in the validation error, such as `Cookie directory`.
+ */
+export async function ensurePrivateDirectory(path, label) {
+    await ensureDirectory(path);
+    const stat = await lstat(path);
+    if (!stat.isDirectory() || process.platform !== 'win32' && ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.())) {
+        throw new Error(`${label} must be owned by the current user with permissions 0700`);
+    }
+}
+/** List the entry names of one directory.
+ * @param path - Directory path.
+ * @returns Entry names in filesystem order.
+ */
+export async function listEntries(path) { return readdir(path); }

package/dist/storage/files.d.ts

@@ -0,0 +1,43 @@
+/** Read a UTF-8 file; an absent file is an ordinary result, not a failure.
+ * @param path - Absolute file path.
+ * @returns File contents, or undefined when the file does not exist.
+ */
+export declare function readText(path: string): Promise<string | undefined>;
+/** Read a user-private file, rejecting a symlink, a foreign owner, or group/other access.
+ * @param path - Absolute file path.
+ * @param label - Name used in the validation error, such as `Cookie file`.
+ * @returns File contents, or undefined when the file does not exist.
+ */
+export declare function readPrivateFile(path: string, label: string): Promise<string | undefined>;
+/** Replace a file atomically with owner-only contents, leaving no partial file behind.
+ * @param path - Destination path.
+ * @param contents - Complete file contents.
+ */
+export declare function writePrivateFile(path: string, contents: string): Promise<void>;
+/** Create an owner-only file only when it does not exist.
+ * @param path - Destination path.
+ * @param contents - Complete file contents.
+ * @returns False when the file already existed, leaving it untouched.
+ */
+export declare function createPrivateFile(path: string, contents: string): Promise<boolean>;
+/** Stream bytes into a new owner-only file, removing it unless the write completed.
+ *
+ * The destination is created before the source is requested, so an existing file fails without
+ * contacting the host, and a source or streaming failure removes the partial file.
+ * @param path - Destination path; an existing file is never replaced.
+ * @param source - Produces the byte stream once the destination exists.
+ * @param signal - Cancels the write and removes the partial file.
+ */
+export declare function writeExclusiveStream(path: string, source: () => Promise<AsyncIterable<Uint8Array>>, signal?: AbortSignal): Promise<void>;
+/** Append to an owner-only file, creating it when absent.
+ *
+ * Appending keeps a long-lived diagnostic file cheap to extend; callers that need a bounded file
+ * rewrite it periodically with `writePrivateFile`.
+ * @param path - Destination path.
+ * @param contents - Text to append.
+ */
+export declare function appendPrivateFile(path: string, contents: string): Promise<void>;
+/** Remove a file, treating an already absent file as success.
+ * @param path - File to remove.
+ */
+export declare function removeFile(path: string): Promise<void>;

package/dist/storage/files.js

@@ -0,0 +1,135 @@
+/** Every filesystem read and write the client performs; no other module opens a file. */
+import { constants } from 'node:fs';
+import { open, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+/** Read a UTF-8 file; an absent file is an ordinary result, not a failure.
+ * @param path - Absolute file path.
+ * @returns File contents, or undefined when the file does not exist.
+ */
+export async function readText(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+/** Read a user-private file, rejecting a symlink, a foreign owner, or group/other access.
+ * @param path - Absolute file path.
+ * @param label - Name used in the validation error, such as `Cookie file`.
+ * @returns File contents, or undefined when the file does not exist.
+ */
+export async function readPrivateFile(path, label) {
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || process.platform !== 'win32' && ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.())) {
+            throw new Error(`${label} must be owned by the current user with permissions 0600`);
+        }
+        return await handle.readFile('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Replace a file atomically with owner-only contents, leaving no partial file behind.
+ * @param path - Destination path.
+ * @param contents - Complete file contents.
+ */
+export async function writePrivateFile(path, contents) {
+    const temporary = join(dirname(path), `${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, contents, { mode: 0o600, flag: 'wx' });
+        await rename(temporary, path);
+    }
+    finally {
+        await removeFile(temporary);
+    }
+}
+/** Create an owner-only file only when it does not exist.
+ * @param path - Destination path.
+ * @param contents - Complete file contents.
+ * @returns False when the file already existed, leaving it untouched.
+ */
+export async function createPrivateFile(path, contents) {
+    try {
+        await writeFile(path, contents, { mode: 0o600, flag: 'wx' });
+        return true;
+    }
+    catch (error) {
+        if (isCode(error, 'EEXIST'))
+            return false;
+        throw error;
+    }
+}
+/** Stream bytes into a new owner-only file, removing it unless the write completed.
+ *
+ * The destination is created before the source is requested, so an existing file fails without
+ * contacting the host, and a source or streaming failure removes the partial file.
+ * @param path - Destination path; an existing file is never replaced.
+ * @param source - Produces the byte stream once the destination exists.
+ * @param signal - Cancels the write and removes the partial file.
+ */
+export async function writeExclusiveStream(path, source, signal) {
+    const file = await open(path, 'wx', 0o600);
+    let complete = false;
+    try {
+        await file.writeFile(await source(), { signal });
+        signal?.throwIfAborted();
+        complete = true;
+    }
+    finally {
+        try {
+            await file.close();
+        }
+        finally {
+            if (!complete)
+                await removeFile(path);
+        }
+    }
+}
+/** Append to an owner-only file, creating it when absent.
+ *
+ * Appending keeps a long-lived diagnostic file cheap to extend; callers that need a bounded file
+ * rewrite it periodically with `writePrivateFile`.
+ * @param path - Destination path.
+ * @param contents - Text to append.
+ */
+export async function appendPrivateFile(path, contents) {
+    const handle = await open(path, 'a', 0o600);
+    try {
+        await handle.writeFile(contents);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Remove a file, treating an already absent file as success.
+ * @param path - File to remove.
+ */
+export async function removeFile(path) {
+    try {
+        await unlink(path);
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+}
+/** Recognize one error code without assuming the error's prototype. */
+function isCode(error, code) {
+    return error instanceof Error && 'code' in error && error.code === code;
+}
+/** Whether an operation failed because the path does not exist. */
+function isMissing(error) { return isCode(error, 'ENOENT'); }

package/dist/storage/index.d.ts

@@ -0,0 +1,3 @@
+/** Storage domain: every filesystem operation the client performs. */
+export { appendPrivateFile, createPrivateFile, readPrivateFile, readText, removeFile, writeExclusiveStream, writePrivateFile } from './files.ts';
+export { ensureDirectory, ensurePrivateDirectory, listEntries } from './directories.ts';

package/dist/storage/index.js

@@ -0,0 +1,3 @@
+/** Storage domain: every filesystem operation the client performs. */
+export { appendPrivateFile, createPrivateFile, readPrivateFile, readText, removeFile, writeExclusiveStream, writePrivateFile } from "./files.js";
+export { ensureDirectory, ensurePrivateDirectory, listEntries } from "./directories.js";