@itookit/dsht 0.1.0

package/dist/app.js

@@ -0,0 +1,353 @@
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/** Ink terminal interface: startup pickers, transcript, and slash-command composer. */
+import { useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
+import { Box, Text, useApp, useInput, useStdout } from 'ink';
+import { useMouseWheel } from "./mouse.js";
+import { TextInput } from "./input.js";
+import { historyLayout, jumpTarget } from "./history.js";
+import { toolLine } from "./transcript.js";
+import { activeReference, fileMention } from "./references.js";
+import { CostPanel } from "./cost-view.js";
+import { StatusBar } from "./status.js";
+import { navigationCommand, sessionLabel } from "./navigation.js";
+import { array, errorText, object, safeText, string } from "./wire.js";
+const COMMANDS = ['/ws', '/s', '/new', '/older', '/history', '/jump', '/search', '/ssearch', '/wsearch', '/cancel', '/steer', '/allow', '/deny', '/status', '/cost', '/help', '/quit'];
+const HELP = '/ws [name or ID] · /s [title or ID] · /s all · /new · /older · /history [text] · /jump <seq|first|last> · /search text · /ssearch text · /wsearch text · /cancel · /steer text · /allow · /deny · /status · /cost · /quit';
+function Picker({ choices, enabled, canSelect }) {
+    const [selected, setSelected] = useState(0);
+    const current = Math.min(selected, choices.length - 1);
+    useInput((_input, key) => {
+        if (!canSelect())
+            return;
+        if (key.upArrow)
+            setSelected(Math.max(0, current - 1));
+        else if (key.downArrow)
+            setSelected(Math.min(choices.length - 1, current + 1));
+        else if (key.return)
+            choices[current]?.action();
+    }, { isActive: enabled });
+    const start = Math.max(0, current - 7);
+    return _jsxs(Box, { flexDirection: "column", children: [choices.slice(start, start + 12).map((choice, index) => _jsxs(Text, { color: start + index === current ? 'cyan' : undefined, children: [start + index === current ? '❯ ' : '  ', safeText(choice.label)] }, choice.key)), _jsx(Text, { dimColor: true, children: "\u2191 \u2193 select \u00B7 Enter open \u00B7 Ctrl+C stop / exit" })] });
+}
+/** The caller owns starting and stopping the controller around the Ink render lifetime. */
+export function App({ controller }) {
+    const state = useSyncExternalStore(controller.subscribe, controller.snapshot);
+    const { exit } = useApp();
+    const { stdout } = useStdout();
+    const [input, updateInput] = useState('');
+    const draft = useRef('');
+    const [cursor, setCursor] = useState(0);
+    // Input callbacks may run before Ink refreshes the controlled field's listener.
+    const setInput = (value) => { draft.current = value; updateInput(value); setCursor(value.length); };
+    const [scroll, setScroll] = useState(0);
+    const [historyQuery, setHistoryQuery] = useState();
+    const [contentSearch, setContentSearch] = useState(false);
+    const [searchResults, setSearchResults] = useState();
+    const historyAbort = useRef(undefined);
+    useEffect(() => () => historyAbort.current?.abort(), []);
+    const [costExpanded, setCostExpanded] = useState(false);
+    const [statusExpanded, setStatusExpanded] = useState(false);
+    const [help, setHelp] = useState(false);
+    const [answers, setAnswers] = useState({});
+    const [referenceIndex, setReferenceIndex] = useState(0);
+    const [dismissedReference, dismissReference] = useState();
+    const [lookup, setLookup] = useState();
+    const pending = state.pending[0];
+    const token = state.screen === 'chat' && state.online && !state.busy && !pending
+        && (!input.startsWith('/') || input.startsWith('/steer ')) && dismissedReference !== input && cursor === input.length
+        ? activeReference(input) : undefined;
+    const referenceOpen = token !== undefined;
+    const matches = referenceOpen && lookup?.draft === input && lookup.sessionId === state.sessionId ? lookup : undefined;
+    useEffect(() => {
+        if (!referenceOpen)
+            return;
+        const abort = new AbortController();
+        setLookup(undefined);
+        setReferenceIndex(0);
+        void controller.references(activeReference(input).query, abort.signal).then(items => {
+            if (!abort.signal.aborted)
+                setLookup({ draft: input, sessionId: state.sessionId, items });
+        }, error => {
+            if (!abort.signal.aborted)
+                setLookup({ draft: input, sessionId: state.sessionId, items: [], error: errorText(error) });
+        });
+        return () => abort.abort();
+    }, [controller, input, state.sessionId, referenceOpen]);
+    const pickReference = () => {
+        const candidate = matches?.items[referenceIndex];
+        if (!candidate || !token || draft.current !== input)
+            return;
+        const mention = fileMention(candidate, token.quoted);
+        setInput(input.slice(0, -token.prefix.length) + mention + (candidate.kind === 'file' ? ' ' : ''));
+    };
+    const questions = pending?.event === 'user-questions/request' ? array(object(pending.request).questions).map(object) : [];
+    const eventId = pending ? string(pending.eventId) : '';
+    const answered = answers[eventId] ?? [];
+    const question = questions[answered.length];
+    const operate = (fn) => { void controller.perform(fn); };
+    useInput((_value, key) => {
+        if ((key.escape || key.ctrl && _value === 'c') && historyAbort.current) {
+            historyAbort.current.abort();
+            return;
+        }
+        if (key.escape && searchResults) {
+            setSearchResults(undefined);
+            if (controller.running)
+                void controller.interrupt(true);
+            return;
+        }
+        if (key.escape && historyQuery !== undefined) {
+            setHistoryQuery(undefined);
+            if (controller.running)
+                void controller.interrupt(true);
+            return;
+        }
+        if (key.ctrl && _value === 'c') {
+            void controller.interrupt().then(shouldExit => { if (shouldExit)
+                exit(); });
+            return;
+        }
+        if (referenceOpen) {
+            if (key.escape) {
+                dismissReference(input);
+                if (controller.running)
+                    void controller.interrupt(true);
+            }
+            else if (key.tab)
+                pickReference();
+            else if (key.upArrow)
+                setReferenceIndex(value => Math.max(0, value - 1));
+            else if (key.downArrow)
+                setReferenceIndex(value => Math.max(0, Math.min((matches?.items.length ?? 1) - 1, value + 1)));
+            return;
+        }
+        if (key.escape && state.screen === 'chat') {
+            void controller.interrupt(true);
+        }
+        if (key.pageUp)
+            scrollHistory(10);
+        if (key.pageDown)
+            scrollHistory(-10);
+    });
+    const submit = async (raw) => {
+        if (referenceOpen) {
+            pickReference();
+            return;
+        }
+        const value = raw.trim();
+        if (!value)
+            return;
+        if (value === '/quit') {
+            exit();
+            return;
+        }
+        if (value === '/cost') {
+            setCostExpanded(value => !value);
+            setInput('');
+            if (!costExpanded)
+                void controller.perform(() => historyOperation(signal => controller.refreshCosts(signal)));
+            return;
+        }
+        if (value === '/status') {
+            setStatusExpanded(value => !value);
+            setInput('');
+            return;
+        }
+        if (value === '/help') {
+            setHelp(value => !value);
+            setInput('');
+            return;
+        }
+        const accepted = await controller.perform(async () => {
+            const navigation = navigationCommand(value);
+            if (navigation) {
+                setHistoryQuery(undefined);
+                setSearchResults(undefined);
+                if (navigation.kind === 'workspace')
+                    await controller.switchWorkspace(navigation.query);
+                else
+                    await controller.switchSession(navigation.query);
+                setScroll(0);
+            }
+            else if (state.screen === 'path')
+                await controller.createWorkspace(value);
+            else if (value === '/new')
+                await controller.createSession();
+            else if (value === '/history' || value.startsWith('/history ')) {
+                if (state.screen !== 'chat')
+                    throw new Error('Select a session first');
+                setSearchResults(undefined);
+                setContentSearch(false);
+                setHistoryQuery(value.slice(8).trim());
+            }
+            else if (/^\/(?:search|ssearch|wsearch)(?: |$)/.test(value)) {
+                const [command, ...words] = value.split(' ');
+                const query = words.join(' ').trim();
+                if (!query)
+                    throw new Error(`Use ${command} <text>`);
+                await historyOperation(async (signal) => {
+                    if (command === '/search') {
+                        await controller.historyThrough('first', signal);
+                        setSearchResults(undefined);
+                        setContentSearch(true);
+                        setHistoryQuery(query);
+                    }
+                    else {
+                        const result = await controller.searchSessions(query, command === '/ssearch', signal);
+                        setHistoryQuery(undefined);
+                        setSearchResults({ query, ...result });
+                    }
+                });
+            }
+            else if (value === '/jump' || value.startsWith('/jump '))
+                await jumpHistory(jumpTarget(value.slice(5).trim()));
+            else if (value === '/older') {
+                await controller.older();
+                setScroll(value => value + 10);
+            }
+            else if (value === '/cancel')
+                await controller.cancelTurn();
+            else if (value === '/allow')
+                await controller.approve(true);
+            else if (value === '/deny')
+                await controller.approve(false);
+            else if (value.startsWith('/steer '))
+                await controller.prompt(value.slice(7), 'steer');
+            else if (question) {
+                const answer = { id: string(question.id), selected: [], custom: value };
+                const next = [...answered, answer];
+                if (next.length === questions.length)
+                    await controller.answer({ answers: next });
+                setAnswers(previous => ({ ...previous, [eventId]: next }));
+            }
+            else if (pending)
+                throw new Error('Answer the approval with /allow or /deny');
+            else if (value.startsWith('/'))
+                throw new Error('Unknown command. Use /help.');
+            else if (state.screen !== 'chat')
+                throw new Error('Choose a session or type /ws or /s');
+            else {
+                await controller.prompt(value);
+                setScroll(0);
+            }
+        });
+        if (accepted)
+            setInput('');
+    };
+    const choices = state.screen === 'workspaces' ? [
+        ...state.workspaces.map(workspace => ({ key: string(workspace.workspaceId),
+            label: `${string(workspace.title)}  ${string(workspace.path)}`,
+            action: () => controller.pickWorkspace(string(workspace.workspaceId)) })),
+        { key: '@all', label: 'All sessions', action: () => operate(() => controller.switchSession('all')) },
+        { key: '@new', label: '+ Add workspace (host directory)', action: () => controller.enterPath() },
+    ] : [
+        ...(state.workspaceId && !state.showAllSessions ? [{ key: '@new', label: '+ New session', action: () => operate(() => controller.createSession()) }] : []),
+        ...controller.visibleSessions.map(session => ({ key: string(session.sessionId),
+            label: `${session.running ? '● ' : ''}${sessionLabel(session)}  ${session.sessionId}`,
+            action: () => { setScroll(0); operate(() => controller.selectSession(string(session.sessionId))); } })),
+        { key: '@back', label: '← Workspaces', action: () => operate(() => controller.showPicker('workspaces')) },
+    ];
+    const width = Math.max(10, (stdout.columns ?? 80) - 2);
+    const layout = useMemo(() => historyLayout(state.transcript, width), [state.transcript, state.transcript.version, width]);
+    const { lines, first } = layout;
+    const pageSize = Math.max(5, (stdout.rows ?? 30) - (pending ? 17 : 12) - (statusExpanded ? 9 : 0));
+    const previousView = useRef({ transcript: state.transcript, count: lines.length, first });
+    const previous = previousView.current;
+    const prepended = previous.first !== undefined && first !== undefined && first < previous.first;
+    const adjustedScroll = previous.transcript !== state.transcript ? 0
+        : scroll > 0 && !prepended ? Math.max(0, scroll + lines.length - previous.count) : scroll;
+    const maxScroll = Math.max(0, lines.length - pageSize);
+    const position = Math.min(adjustedScroll, maxScroll);
+    useLayoutEffect(() => {
+        previousView.current = { transcript: state.transcript, count: lines.length, first };
+        if (position !== scroll)
+            setScroll(position);
+    }, [state.transcript, lines, position, scroll]);
+    const scrollPosition = useRef(position);
+    scrollPosition.current = position;
+    const loadingPage = useRef(false);
+    const scrollIntent = useRef(0);
+    const mounted = useRef(true);
+    useEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
+    function scrollHistory(delta) {
+        if (state.screen !== 'chat' || historyQuery !== undefined || searchResults !== undefined)
+            return;
+        const intent = ++scrollIntent.current;
+        const next = Math.max(0, Math.min(maxScroll, scrollPosition.current + delta));
+        scrollPosition.current = next;
+        setScroll(next);
+        if (delta <= 0 || next < maxScroll || loadingPage.current || state.busy || !state.online || !state.transcript.ready || !state.transcript.hasMore)
+            return;
+        loadingPage.current = true;
+        const transcript = state.transcript;
+        void controller.perform(() => historyOperation(signal => controller.older(signal))).then(accepted => {
+            if (accepted && mounted.current && controller.state.transcript === transcript && scrollIntent.current === intent) {
+                setScroll(value => value + delta);
+            }
+        }).finally(() => { loadingPage.current = false; });
+    }
+    async function historyOperation(operation) {
+        const abort = new AbortController();
+        historyAbort.current = abort;
+        try {
+            await operation(abort.signal);
+        }
+        finally {
+            if (historyAbort.current === abort)
+                historyAbort.current = undefined;
+        }
+    }
+    async function openSearchSession(sessionId, query) {
+        await historyOperation(async (signal) => {
+            await controller.selectSession(sessionId);
+            await controller.waitForHistory(signal);
+            await controller.historyThrough('first', signal);
+            setSearchResults(undefined);
+            setContentSearch(true);
+            setHistoryQuery(query);
+        });
+    }
+    async function jumpHistory(target) {
+        if (state.screen !== 'chat')
+            throw new Error('Select a session first');
+        ++scrollIntent.current;
+        if (target === 'last') {
+            setHistoryQuery(undefined);
+            setScroll(0);
+            return;
+        }
+        const abort = new AbortController();
+        historyAbort.current = abort;
+        try {
+            await controller.historyThrough(target, abort.signal);
+            abort.signal.throwIfAborted();
+            const current = historyLayout(controller.state.transcript, width);
+            const seq = target === 'first' ? current.messages[0]?.seq : target;
+            const row = seq === undefined ? undefined : current.offsets.get(seq);
+            if (row === undefined)
+                throw new Error('No visible message at this sequence; use /history to choose a record');
+            setHistoryQuery(undefined);
+            setScroll(Math.max(0, current.lines.length - pageSize - row));
+        }
+        finally {
+            if (historyAbort.current === abort)
+                historyAbort.current = undefined;
+        }
+    }
+    useMouseWheel(direction => scrollHistory(direction * 3));
+    const end = Math.max(pageSize, lines.length - position);
+    const visible = lines.slice(Math.max(0, end - pageSize), end);
+    const workspace = state.workspaces.find(item => item.workspaceId === state.workspaceId);
+    return _jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { borderStyle: "round", borderColor: "cyan", paddingX: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, color: "cyan", children: "DeepSeek Harness \u00B7 HTTP TUI" }), _jsxs(Text, { dimColor: true, children: [controller.base, " \u00B7 ", state.status, state.busy ? ' · Working…' : ''] }), _jsx(Text, { wrap: "truncate-end", children: toolLine(`${workspace ? string(workspace.title) : 'All workspaces'}${state.sessionId ? ` / ${controller.sessionName}` : ''}`, Math.max(1, width - 4)) })] }), state.error && _jsx(Text, { color: "red", children: state.error }), searchResults ? _jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsxs(Text, { bold: true, children: ["Session search \u00B7 ", safeText(searchResults.query)] }), searchResults.hasMore && _jsx(Text, { color: "yellow", children: "Host returned only the first 20 global matches; workspace results may be incomplete. Refine your query." }), !searchResults.items.length && _jsx(Text, { children: "No sessions in the returned results" }), _jsx(Picker, { choices: [...searchResults.items.map(item => ({ key: string(item.sessionId),
+                                label: toolLine(`${item.sessionId} · ${item.snippet}`, width - 2),
+                                action: () => operate(() => openSearchSession(string(item.sessionId), searchResults.query)),
+                            })), { key: 'close', label: '← Back', action: () => setSearchResults(undefined) }], enabled: !input && !state.busy, canSelect: () => !draft.current && !controller.state.busy })] }) : state.screen === 'workspaces' || state.screen === 'sessions' ? _jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsx(Text, { bold: true, children: state.screen === 'workspaces' ? 'Choose workspace' : state.showAllSessions ? 'Choose session · All workspaces' : 'Choose session' }), _jsx(Picker, { choices: choices, enabled: state.online && !state.busy && !input, canSelect: () => !draft.current && controller.state.online && !controller.state.busy }, `${state.screen}:${state.workspaceId ?? ''}`)] }) : _jsxs(_Fragment, { children: [state.screen === 'chat' && historyQuery === undefined && !searchResults && _jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsx(Text, { children: visible.length ? visible.join('\n') : 'Start a conversation with the host agent.' }), state.transcript.hasMore && _jsx(Text, { dimColor: true, children: "Scroll up or /older to load earlier history" })] }), state.screen === 'chat' && historyQuery !== undefined && _jsxs(Box, { flexDirection: "column", marginY: 1, children: [_jsxs(Text, { bold: true, children: [contentSearch ? 'Search · session history' : 'History · loaded records', " \u00B7 Esc close"] }), _jsx(Picker, { choices: [
+                                    ...layout.messages.filter(message => (contentSearch ? message.text : `${message.seq} ${message.role} ${message.text}`).toLowerCase().includes(historyQuery.toLowerCase())).map(message => ({
+                                        key: String(message.seq), label: toolLine(`#${message.seq} ${message.role} · ${message.text}`, width - 2),
+                                        action: () => operate(() => jumpHistory(message.seq)),
+                                    })),
+                                    { key: 'close', label: '← Back to conversation', action: () => setHistoryQuery(undefined) },
+                                ], enabled: !input && !state.busy, canSelect: () => !draft.current && !controller.state.busy }, `history:${historyQuery}`)] }), pending && _jsxs(Box, { borderStyle: "round", borderColor: "yellow", paddingX: 1, flexDirection: "column", children: [_jsx(Text, { bold: true, color: "yellow", children: question ? 'Question' : 'Approval required' }), _jsx(Text, { children: safeText(question ? string(question.question) : JSON.stringify(pending.request, null, 2)) }), question?.detail && _jsx(Text, { children: safeText(string(question.detail)) }), question?.options && _jsx(Text, { children: array(question.options).map(option => string(object(option).label)).join(' · ') }), _jsx(Text, { dimColor: true, children: question ? 'Type your answer below' : '/allow approves once · /deny rejects' })] })] }), _jsxs(Box, { borderStyle: "round", borderColor: state.online ? 'cyan' : 'gray', paddingX: 1, children: [_jsx(Text, { color: "cyan", children: "\u276F " }), _jsx(TextInput, { value: input, onChange: setInput, onCursorChange: setCursor, onSubmit: () => { void submit(draft.current); }, focus: state.online && !state.busy, placeholder: state.screen === 'path' ? 'Absolute directory path on host' : 'Message, @host-file, or /help' })] }), referenceOpen && _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Host files \u00B7 \u2191 \u2193 select \u00B7 Tab/Enter insert \u00B7 Esc close" }), !matches ? _jsx(Text, { dimColor: true, children: "Searching\u2026" }) : matches.error ? _jsx(Text, { color: "red", children: matches.error })
+                        : matches.items.length === 0 ? _jsx(Text, { dimColor: true, children: "No matching host files" })
+                            : matches.items.slice(Math.max(0, referenceIndex - 5), Math.max(0, referenceIndex - 5) + 6).map((item, index) => _jsxs(Text, { color: index + Math.max(0, referenceIndex - 5) === referenceIndex ? 'cyan' : undefined, children: [index + Math.max(0, referenceIndex - 5) === referenceIndex ? '❯ ' : '  ', item.path, item.kind === 'directory' ? '/' : ''] }, `${item.kind}:${item.path}`))] }), _jsx(Text, { dimColor: true, children: "Enter send \u00B7 Esc cancel \u00B7 Wheel/PgUp/PgDn scroll \u00B7 Ctrl+C stop / exit" }), input.startsWith('/') && !input.includes(' ') && _jsx(Text, { dimColor: true, children: COMMANDS.filter(command => command.startsWith(input)).join('  ') }), help && _jsxs(_Fragment, { children: [_jsx(Text, { dimColor: true, children: HELP }), _jsx(Text, { dimColor: true, children: "Editing: Ctrl+A/E start/end \u00B7 Ctrl+K/U kill right/left \u00B7 Ctrl+W kill word \u00B7 Ctrl+Y restore" })] }), costExpanded && _jsx(CostPanel, { controller: controller }), _jsx(StatusBar, { controller: controller, expanded: statusExpanded, revision: state.version })] });
+}

package/dist/auth.d.ts

@@ -0,0 +1,16 @@
+import { Client } from './client.ts';
+/** Fatal authentication failure requiring a new startup token. */
+export declare class AuthenticationRequired extends Error {
+}
+/** Private, atomic cookie files, separated by the complete HTTP origin. */
+export declare class CookieStore {
+    readonly directory: string;
+    constructor(directory?: string);
+    /** Read an unexpired cookie, rejecting unsafe permissions or malformed storage. */
+    load(origin: string): Promise<string | undefined>;
+    /** Atomically save a persistent host cookie with owner-only POSIX permissions. */
+    save(origin: string, cookie: string, expiresAt: number): Promise<void>;
+    private path;
+}
+/** Reuse a validated cookie first; only authentication rejection permits token fallback. */
+export declare function login(client: Client, token: string | undefined, store: CookieStore): Promise<void>;

package/dist/auth.js

@@ -0,0 +1,108 @@
+/** Origin-scoped cookie persistence; launch tokens are never written to disk. */
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, rename, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { HttpError } from "./client.js";
+/** Fatal authentication failure requiring a new startup token. */
+export class AuthenticationRequired extends Error {
+}
+/** Private, atomic cookie files, separated by the complete HTTP origin. */
+export class CookieStore {
+    directory;
+    constructor(directory = process.env.DSHT_AUTH_DIR
+        ?? join(process.env.XDG_STATE_HOME ?? join(homedir(), '.local', 'state'), 'dsht', 'auth')) {
+        this.directory = directory;
+    }
+    /** Read an unexpired cookie, rejecting unsafe permissions or malformed storage. */
+    async load(origin) {
+        let handle;
+        try {
+            handle = await open(this.path(origin), 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('Cookie file must be owned by the current user with permissions 0600');
+            }
+            const raw = await handle.readFile('utf8');
+            let saved;
+            try {
+                saved = JSON.parse(raw);
+            }
+            catch {
+                throw new Error('Invalid cookie file JSON. Remove the origin cookie file and log in again.');
+            }
+            if (saved === null || typeof saved !== 'object' || !('version' in saved) || saved.version !== 1
+                || !('origin' in saved) || saved.origin !== origin || !('cookie' in saved) || typeof saved.cookie !== 'string'
+                || !('expiresAt' in saved) || typeof saved.expiresAt !== 'number' || !Number.isSafeInteger(saved.expiresAt)) {
+                throw new Error('Invalid saved cookie. Remove the origin cookie file and log in again.');
+            }
+            return saved.expiresAt > Date.now() ? saved.cookie : undefined;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    /** Atomically save a persistent host cookie with owner-only POSIX permissions. */
+    async save(origin, cookie, expiresAt) {
+        await mkdir(this.directory, { recursive: true, mode: 0o700 });
+        const stat = await lstat(this.directory);
+        if (!stat.isDirectory() || process.platform !== 'win32' && ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.())) {
+            throw new Error('Cookie directory must be owned by the current user with permissions 0700');
+        }
+        const temporary = join(this.directory, `${randomUUID()}.tmp`);
+        const handle = await open(temporary, 'wx', 0o600);
+        try {
+            try {
+                await handle.writeFile(JSON.stringify({ version: 1, origin, cookie, expiresAt }) + '\n');
+            }
+            finally {
+                await handle.close();
+            }
+            await rename(temporary, this.path(origin));
+        }
+        finally {
+            try {
+                await unlink(temporary);
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+        }
+    }
+    path(origin) {
+        return join(this.directory, `${createHash('sha256').update(origin).digest('hex')}.json`);
+    }
+}
+/** Reuse a validated cookie first; only authentication rejection permits token fallback. */
+export async function login(client, token, store) {
+    const cookie = await store.load(client.base.origin);
+    if (cookie) {
+        client.restoreCookie(cookie);
+        try {
+            await client.call('session/list', { _request: {} });
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof HttpError) || error.status !== 401)
+                throw error;
+        }
+    }
+    if (!token)
+        throw new AuthenticationRequired('Login required: export DSH_TOKEN, or export DSH_URL as the URL printed by dsh web');
+    await client.authenticate(token);
+    const session = client.persistentCookie;
+    if (session)
+        await store.save(client.base.origin, session.cookie, session.expiresAt);
+}
+function isMissing(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { jsx as _jsx } from "react/jsx-runtime";
+/** Standalone executable entry; connects to an existing host and never launches Harness. */
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { CostLedger, DEFAULT_PRICES, pricesFrom } from "./cost.js";
+import { parseArgs } from 'node:util';
+import { render } from 'ink';
+import { App } from "./app.js";
+import { sessionLabel } from "./navigation.js";
+import { CookieStore, login } from "./auth.js";
+import { Client } from "./client.js";
+import { Controller } from "./controller.js";
+import { endpoint } from "./endpoint.js";
+import { errorText, safeText, string } from "./wire.js";
+const HELP = `Usage: dsht [options] [list workspaces|list sessions]
+
+With no command, choose a workspace and session interactively.
+
+  --url <url>           Host URL, or the dsh web URL with ?token= (DSH_URL)
+  --workspace <id>      Filter list sessions by workspace
+  --session <id>        Open a session directly
+  --auth-dir <path>     Private cookie directory (or DSHT_AUTH_DIR)
+  --json               Print machine-readable list output
+  --help               Show this help
+
+The default host is http://127.0.0.1:3080.
+First login: export DSH_TOKEN, or export DSH_URL as the URL printed by dsh web.
+Cookies are saved per server origin and reused on later starts. Tokens are never saved.
+/cost shows session, today and three-day CNY estimates.
+DSHT_CONFIG_DIR overrides the prices.json directory; DSHT_STATE_DIR overrides usage storage.
+Examples:
+  npx @itookit/dsht
+  dsht list workspaces --json
+  dsht list sessions --workspace <id> --json
+`;
+async function main() {
+    const { values, positionals } = parseArgs({ allowPositionals: true, options: {
+            url: { type: 'string', default: process.env.DSH_URL ?? 'http://127.0.0.1:3080' },
+            workspace: { type: 'string' }, session: { type: 'string' }, 'auth-dir': { type: 'string' }, json: { type: 'boolean' }, help: { type: 'boolean' },
+        } });
+    if (values.help) {
+        process.stdout.write(HELP);
+        return;
+    }
+    const list = positionals[0] === 'list' && ['workspaces', 'sessions'].includes(positionals[1] ?? '') && positionals.length === 2;
+    if (positionals.length && !list)
+        throw new Error('Unknown command. Use --help.');
+    if (!list && (values.json || values.workspace))
+        throw new Error('--json and --workspace apply to list commands');
+    if (list && values.session)
+        throw new Error('--session applies to interactive mode');
+    const { url, token } = endpoint(values.url, process.env.DSH_TOKEN);
+    const store = new CookieStore(values['auth-dir']);
+    if (list) {
+        const client = new Client(url);
+        try {
+            await login(client, token, store);
+            if (positionals[1] === 'workspaces' || values.workspace)
+                await client.connect();
+            const items = positionals[1] === 'workspaces' ? await client.listWorkspaces() : await client.listSessions(values.workspace);
+            if (values.json)
+                process.stdout.write(`${JSON.stringify({ items }, null, 2)}\n`);
+            else {
+                const lines = items.map(item => positionals[1] === 'workspaces'
+                    ? `${string(item.workspaceId)}\t${string(item.title)}\t${string(item.path)}`
+                    : `${string(item.sessionId)}\t${sessionLabel(item)}\t${item.running ? 'running' : 'idle'}`);
+                process.stdout.write(`${safeText(lines.join('\n'))}${lines.length ? '\n' : ''}`);
+            }
+        }
+        finally {
+            await client.close();
+        }
+        return;
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        throw new Error('Interactive mode requires a terminal. Use list workspaces or list sessions for scripts.');
+    const config = process.env.DSHT_CONFIG_DIR ?? join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'dsht');
+    await mkdir(config, { recursive: true, mode: 0o700 });
+    const pricePath = join(config, 'prices.json');
+    try {
+        await writeFile(pricePath, JSON.stringify(DEFAULT_PRICES, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST'))
+            throw error;
+    }
+    const prices = pricesFrom(JSON.parse(await readFile(pricePath, 'utf8')));
+    const costDirectory = join(process.env.DSHT_STATE_DIR ?? join(process.env.XDG_STATE_HOME ?? join(homedir(), '.local', 'state'), 'dsht'), 'cost', createHash('sha256').update(new URL(url).origin).digest('hex'));
+    const costs = new CostLedger(prices, costDirectory);
+    await costs.load();
+    const controller = new Controller(url, token, values.session, undefined, client => login(client, token, store), costs);
+    const app = render(_jsx(App, { controller: controller }), { exitOnCtrlC: false });
+    const terminate = () => app.unmount();
+    process.once('SIGTERM', terminate);
+    controller.start();
+    try {
+        await app.waitUntilExit();
+    }
+    finally {
+        process.off('SIGTERM', terminate);
+        await controller.stop();
+    }
+}
+main().catch(error => { process.stderr.write(`${errorText(error)}\n`); process.exitCode = 1; });

package/dist/client.d.ts

@@ -0,0 +1,61 @@
+import { type Json, type ObjectValue } from './wire.ts';
+/** HTTP failure remains distinct from host business errors. */
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number, endpoint: string);
+}
+/** Host business failure, including the original machine-readable details. */
+export declare class RemoteError extends Error {
+    readonly code: string;
+    readonly details: Json | undefined;
+    constructor(value: unknown);
+}
+/** A logical stream owns its callback registration until cancellation or termination. */
+export interface Subscription {
+    cancel(): void;
+}
+interface Listener {
+    item(value: Json | undefined): void;
+    end(error?: Error): void;
+}
+/** A single authenticated host connection; close before reconnecting or exiting. */
+export declare class Client {
+    readonly timeoutMs: number;
+    readonly base: URL;
+    private cookie;
+    private expiresAt;
+    private socket;
+    private listeners;
+    private lifetime;
+    constructor(base: string, timeoutMs?: number);
+    /** Exchange a startup token only at GET / and retain the server's cookie expiration. */
+    authenticate(token: string): Promise<void>;
+    /** Restore one origin-scoped cookie read by the caller's credential store. */
+    restoreCookie(cookie: string): void;
+    /** Session-only cookies are not eligible for persistent storage. */
+    get persistentCookie(): {
+        cookie: string;
+        expiresAt: number;
+    } | undefined;
+    /** Invoke an exact endpoint once. Mutations are never automatically retried.
+     * @param endpoint - Namespace/method endpoint.
+     * @param args - Host parameter names and JSON values.
+     * @param signal - Optional caller cancellation, combined with client close and timeout.
+     * @returns The decoded result value; HTTP, remote, and cancellation errors reject.
+     */
+    call(endpoint: string, args?: ObjectValue, signal?: AbortSignal): Promise<Json | undefined>;
+    /** Connect the physical mux. A disconnected instance may reconnect with its cookie. */
+    connect(): Promise<void>;
+    /** Subscribe on the existing mux; each subscription has a fresh stream identity. */
+    subscribe(endpoint: string, args: ObjectValue, listener: Listener): Subscription;
+    /** List workspaces by consuming and cancelling the authoritative opening baseline. */
+    listWorkspaces(): Promise<ObjectValue[]>;
+    /** List visible sessions, optionally filtering by the workspace's accounted IDs. */
+    listSessions(workspaceId?: string): Promise<ObjectValue[]>;
+    /** Close all streams, abort in-flight HTTP, and await the physical socket's closure. */
+    close(): Promise<void>;
+    private signal;
+    private fail;
+    private finish;
+}
+export {};