@xingular/harness 1.3.1-unstable.2 → 1.3.1-unstable.4

package/dist/sdk/remote/service.js

@@ -0,0 +1,330 @@
+// Remote control of one terminal session (15-remote-control.md). A paired phone becomes a second
+// person at the terminal: it sends prompts, watches, interrupts, and answers decisions, all through
+// the same controller and Terminals methods the terminal uses (INV-RC-3). It reaches nothing else:
+// no commands, no shell, no links, no plugins or accounts (INV-RC-6).
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { DEFAULT_PRODUCT_NAME } from "../core/env.js";
+import { HarnessError } from "../core/errors.js";
+import { hostPart, pickRemoteAddress, remoteAddresses } from "./addresses.js";
+import { Pairing } from "./pairing.js";
+import { listenRemote } from "./server.js";
+import { PAGE_CSS, PAGE_JS, pageHtml, pageManifest } from "./webClient.js";
+const MAX_TEXT = 1_000_000;
+const MAX_HISTORY = 400;
+const text = (value, size = MAX_TEXT) => (typeof value === 'string' ? value.slice(0, size) : '');
+export function projectEvent(event) {
+    const payload = (event.payload ?? {});
+    const runId = event.runId;
+    switch (event.type) {
+        case 'message.delta':
+            return { kind: 'delta', runId, messageId: text(payload.messageId, 200), text: text(payload.text) };
+        case 'message.completed':
+            return { kind: 'message', runId, messageId: text(payload.messageId, 200), role: payload.role === 'user' ? 'user' : 'assistant', text: text(payload.text) };
+        case 'message.steered':
+            return { kind: 'message', runId, messageId: event.id, role: 'user', text: text(payload.text) };
+        case 'tool.started':
+            return { kind: 'tool', runId, id: text(payload.toolCallId, 200), name: text(payload.name, 200), phase: 'start', summary: text(payload.summary, 400) };
+        case 'tool.completed':
+            return { kind: 'tool', runId, id: text(payload.toolCallId, 200), name: text(payload.name, 200), phase: 'end', ok: payload.ok !== false };
+        case 'started':
+            return { kind: 'run', runId, status: 'running' };
+        case 'completed':
+        case 'failed':
+            return { kind: 'run', runId, status: event.type };
+        case 'status.changed':
+            return { kind: 'run', runId, status: text(payload.status, 40) || 'running' };
+        case 'todo.updated': {
+            const items = Array.isArray(payload.items) ? payload.items.slice(0, 50) : [];
+            return { kind: 'todo', runId, items: items.map((item) => ({ text: text(item?.text, 500), status: text(item?.status, 20) })) };
+        }
+        default:
+            return null;
+    }
+}
+/** A pending decision as the phone shows it. The approval's full action text is kept whole. */
+export function projectRequest(request) {
+    const options = Array.isArray(request.options) ? request.options.slice(0, 12).map((option) => {
+        const value = option;
+        return { label: text(value?.label, 200), description: text(value?.description, 600), recommended: value?.recommended === true };
+    }) : [];
+    return {
+        requestId: text(request.requestId, 200),
+        type: request.type === 'question' ? 'question' : 'approval',
+        runId: text(request.runId, 200),
+        target: text(request.target, 400),
+        action: text(request.action, 64_000),
+        rememberable: request.rememberable === true,
+        summary: text(request.summary, 2_000),
+        question: text(request.question, 4_000),
+        options,
+        multiSelect: request.multiSelect === true,
+        batchId: text(request.batchId, 200),
+        batchIndex: typeof request.batchIndex === 'number' ? request.batchIndex : 0
+    };
+}
+/** What the phone may type. Commands and shell escapes belong to the terminal (INV-RC-6). */
+export function checkPrompt(value) {
+    const prompt = typeof value === 'string' ? value : '';
+    if (!prompt.trim())
+        throw new HarnessError('invalid_request', 'Message is empty.');
+    if (prompt.length > MAX_TEXT)
+        throw new HarnessError('too_large', 'This message is too large.');
+    const first = prompt.trimStart()[0];
+    if (first === '/' || first === '!')
+        throw new HarnessError('invalid_request', 'Slash commands and ! shell commands run only at the terminal.');
+    return prompt;
+}
+let naclSource = null;
+function naclScript() {
+    naclSource ??= readFileSync(createRequire(import.meta.url).resolve('tweetnacl/nacl-fast.min.js'), 'utf8');
+    return naclSource;
+}
+export class RemoteControl {
+    session;
+    options;
+    listening = null;
+    address = null;
+    pairing;
+    connections = new Set();
+    revision = 0;
+    waiters = new Set();
+    unlisten = null;
+    pendingLoop = null;
+    pendingRequests = [];
+    starting = null;
+    ended = false;
+    constructor(session, options = {}) {
+        this.session = session;
+        this.options = options;
+        this.pairing = new Pairing(() => this.changed());
+    }
+    changed() {
+        this.revision += 1;
+        for (const wake of this.waiters)
+            wake();
+    }
+    status() {
+        const kinds = [...new Set((this.options.addresses ?? remoteAddresses)().map((address) => address.kind))];
+        const connected = new Set([...this.connections].map((connection) => connection.device.id));
+        return {
+            running: !!this.listening,
+            revision: this.revision,
+            url: this.listening && this.address ? `${this.base()}/#${this.pairing.fragment}` : null,
+            kind: this.listening ? this.address?.kind ?? null : null,
+            kinds,
+            devices: this.pairing.list().map((device) => ({ id: device.id, label: device.label, connected: connected.has(device.id) })),
+            request: this.pairing.request,
+            warning: this.pairing.warning
+        };
+    }
+    /** Returns at once for a changed revision, otherwise after a change or 20 seconds. */
+    async waitStatus(revision) {
+        if (revision === this.revision && !this.ended) {
+            await new Promise((resolve) => {
+                const wake = () => { clearTimeout(timer); this.waiters.delete(wake); resolve(); };
+                const timer = setTimeout(wake, 20_000);
+                timer.unref?.();
+                this.waiters.add(wake);
+            });
+        }
+        return this.status();
+    }
+    base() {
+        const address = this.address;
+        return `http://${hostPart(address)}:${this.listening.port}`;
+    }
+    /** Starts listening, or switches address kind. Starting again with the same kind changes nothing. */
+    async start(choice = 'auto') {
+        if (this.ended)
+            throw new HarnessError('terminal_not_ready', 'This terminal has ended.');
+        if (this.starting)
+            await this.starting.catch(() => undefined);
+        if (this.listening && (choice === 'auto' || choice === this.address?.kind))
+            return this.status();
+        this.starting = this.listen(choice);
+        try {
+            return await this.starting;
+        }
+        finally {
+            this.starting = null;
+        }
+    }
+    async listen(choice) {
+        const address = pickRemoteAddress(choice, (this.options.addresses ?? remoteAddresses)());
+        await this.close(false);
+        const host = this.options.bindHost ?? address.address;
+        this.listening = await listenRemote(host, this.options.port ?? 0, {
+            asset: (path) => this.asset(path),
+            hello: async (body) => ({ f: await this.pairing.hello(body.p, body.f) }),
+            call: (body) => this.call(body),
+            stream: (deviceId, frame, stream) => this.openStream(deviceId, frame, stream)
+        });
+        this.address = this.options.bindHost ? { ...address, address: this.options.bindHost, family: host.includes(':') ? 'IPv6' : 'IPv4' } : address;
+        this.unlisten = this.session.listen((event) => {
+            const projected = projectEvent(event);
+            if (projected)
+                this.broadcast({ type: 'event', event: projected });
+        });
+        this.changed();
+        return this.status();
+    }
+    /** A new pairing link; every paired phone is disconnected. */
+    rotate() {
+        for (const connection of [...this.connections])
+            this.drop(connection, { type: 'unpaired' });
+        this.pairing.rotate();
+        return this.status();
+    }
+    confirm(requestId, allow) {
+        this.pairing.confirm(requestId, allow);
+        return this.status();
+    }
+    /** Stops remote control; phones are told the session is no longer reachable. */
+    async stop() {
+        await this.close(true);
+        this.changed();
+        return this.status();
+    }
+    /** The terminal session ended (INV-RC-5). */
+    async dispose() {
+        if (this.ended)
+            return;
+        await this.close(true);
+        this.ended = true;
+        this.changed();
+    }
+    async close(unpair) {
+        this.unlisten?.();
+        this.unlisten = null;
+        this.pendingLoop?.abort();
+        this.pendingLoop = null;
+        for (const connection of [...this.connections])
+            this.drop(connection, { type: 'ended' });
+        const listening = this.listening;
+        this.listening = null;
+        if (unpair)
+            this.pairing = new Pairing(() => this.changed());
+        await listening?.close();
+    }
+    get productName() {
+        return this.options.productName ?? DEFAULT_PRODUCT_NAME;
+    }
+    asset(path) {
+        if (path === '/')
+            return { type: 'text/html; charset=utf-8', body: pageHtml(this.productName) };
+        if (path === '/app.js')
+            return { type: 'text/javascript; charset=utf-8', body: PAGE_JS };
+        if (path === '/app.css')
+            return { type: 'text/css; charset=utf-8', body: PAGE_CSS };
+        if (path === '/nacl.js')
+            return { type: 'text/javascript; charset=utf-8', body: naclScript() };
+        if (path === '/manifest.webmanifest')
+            return { type: 'application/manifest+json', body: pageManifest(this.productName) };
+        return null;
+    }
+    send(connection, body) {
+        connection.stream.send(this.pairing.sealFor(connection.device, body));
+    }
+    broadcast(body) {
+        for (const connection of this.connections)
+            this.send(connection, body);
+    }
+    drop(connection, last) {
+        try {
+            this.send(connection, last);
+        }
+        catch { }
+        this.connections.delete(connection);
+        connection.stream.end();
+    }
+    openStream(deviceId, frame, stream) {
+        const { device } = this.pairing.openFrom(deviceId, frame);
+        const connection = { device, stream };
+        this.connections.add(connection);
+        this.send(connection, { type: 'pending', requests: this.pendingRequests.map(projectRequest) });
+        this.watchPending();
+        this.changed();
+        return () => {
+            if (this.connections.delete(connection))
+                this.changed();
+            if (!this.connections.size) {
+                this.pendingLoop?.abort();
+                this.pendingLoop = null;
+            }
+        };
+    }
+    /** Follows the controller's decisions while a phone is connected, as the terminal itself does. */
+    watchPending() {
+        if (this.pendingLoop)
+            return;
+        const loop = new AbortController();
+        this.pendingLoop = loop;
+        void (async () => {
+            let revision;
+            while (!loop.signal.aborted) {
+                try {
+                    const snapshot = await this.session.control('terminal.pending.wait', { revision });
+                    if (loop.signal.aborted)
+                        return;
+                    const changed = snapshot.revision !== revision;
+                    revision = snapshot.revision;
+                    this.pendingRequests = snapshot.requests;
+                    if (changed)
+                        this.broadcast({ type: 'pending', requests: snapshot.requests.map(projectRequest) });
+                }
+                catch {
+                    if (loop.signal.aborted)
+                        return;
+                    await new Promise((resolve) => setTimeout(resolve, 1000).unref?.());
+                    revision = undefined;
+                }
+            }
+        })();
+    }
+    async call(body) {
+        const { device, body: request } = this.pairing.openFrom(body.d, body.f);
+        const id = request?.id ?? null;
+        const params = (request?.params && typeof request.params === 'object' ? request.params : {});
+        try {
+            const result = await this.dispatch(device, String(request?.method ?? ''), params);
+            return { f: this.pairing.sealFor(device, { id, result }) };
+        }
+        catch (error) {
+            const shape = error instanceof HarnessError ? { code: error.code, message: error.message } : { code: 'harness_error', message: error instanceof Error ? error.message : String(error) };
+            return { f: this.pairing.sealFor(device, { id, error: shape }) };
+        }
+    }
+    async dispatch(device, method, params) {
+        switch (method) {
+            case 'snapshot': {
+                const events = this.session.history().map(projectEvent).filter((event) => !!event && event.kind !== 'delta');
+                return {
+                    title: this.session.title(),
+                    device: device.label,
+                    events: events.slice(-MAX_HISTORY),
+                    pending: this.pendingRequests.map(projectRequest),
+                    state: this.session.state()
+                };
+            }
+            case 'send':
+                return this.session.send(checkPrompt(params.text));
+            case 'interrupt':
+                return this.session.control('terminal.interrupt', {});
+            case 'approve':
+                return this.session.control('terminal.approve', { requestId: String(params.requestId ?? ''), decision: params.decision, alwaysAllow: params.alwaysAllow === true });
+            case 'answer':
+                return this.session.control('terminal.answer', { requestId: String(params.requestId ?? ''), answer: params.answer });
+            case 'answers':
+                return this.session.control('terminal.answers', { batchId: String(params.batchId ?? ''), answers: params.answers });
+            case 'unpair':
+                this.pairing.forget(device.id);
+                for (const connection of [...this.connections])
+                    if (connection.device === device)
+                        this.drop(connection, { type: 'unpaired' });
+                return {};
+            default:
+                throw new HarnessError('unknown_method', 'The phone asked for something remote control does not offer.');
+        }
+    }
+}

package/dist/sdk/remote/webClient.d.ts

@@ -0,0 +1,4 @@
+export declare function pageHtml(productName: string): string;
+export declare function pageManifest(productName: string): string;
+export declare const PAGE_CSS = "\n:root {\n  --bg: #f6f6f4; --panel: #ffffff; --text: #18181b; --muted: #6b6b73; --line: #e2e2de;\n  --accent: #2b59c3; --accent-text: #ffffff; --user: #e8eefb; --danger: #b42318; --ok: #1f7a3f;\n  --mono: ui-monospace, SFMono-Regular, Menlo, monospace;\n  color-scheme: light dark;\n}\n@media (prefers-color-scheme: dark) {\n  :root { --bg: #111214; --panel: #1b1c1f; --text: #ececee; --muted: #9a9aa3; --line: #2c2d31; --accent: #7aa2ff; --accent-text: #0d0f14; --user: #1f2a44; --danger: #ff7b72; --ok: #5bd08a; }\n}\n* { box-sizing: border-box; }\nhtml, body { margin: 0; height: 100%; }\nbody {\n  background: var(--bg); color: var(--text);\n  font: 16px/1.45 -apple-system, BlinkMacSystemFont, \"Segoe UI\", system-ui, sans-serif;\n  display: flex; flex-direction: column; max-width: 860px; margin: 0 auto;\n  padding: env(safe-area-inset-top) env(safe-area-inset-right) 0 env(safe-area-inset-left);\n}\n.bar { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 10px 16px; border-bottom: 1px solid var(--line); }\n.title { display: flex; flex-direction: column; min-width: 0; }\n.title strong { white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n.muted { color: var(--muted); font-size: 13px; }\n.chip { font-size: 13px; padding: 3px 10px; border-radius: 999px; border: 1px solid var(--line); color: var(--muted); white-space: nowrap; }\n.chip.working { color: var(--accent); border-color: var(--accent); }\n.chip.bad { color: var(--danger); border-color: var(--danger); }\n#log { flex: 1; overflow-y: auto; padding: 12px 16px; -webkit-overflow-scrolling: touch; }\n.msg { margin: 10px 0; white-space: pre-wrap; overflow-wrap: anywhere; }\n.msg.user { margin-left: 15%; background: var(--user); padding: 8px 12px; border-radius: 14px 14px 4px 14px; }\n.msg.assistant { padding: 2px 0; }\n.tool { margin: 4px 0; font: 13px/1.4 var(--mono); color: var(--muted); overflow-wrap: anywhere; }\n.tool.failed { color: var(--danger); }\n#todo { border-top: 1px solid var(--line); padding: 8px 16px; font-size: 14px; max-height: 30vh; overflow-y: auto; }\n#todo li { list-style: none; margin: 2px 0; }\n#todo ul { margin: 0; padding: 0; }\n#cards { padding: 0 16px; }\n.card { background: var(--panel); border: 1px solid var(--line); border-radius: 12px; padding: 12px; margin: 10px 0; }\n.card h2 { font-size: 15px; margin: 0 0 6px; }\n.card pre { font: 13px/1.45 var(--mono); white-space: pre-wrap; overflow-wrap: anywhere; max-height: 40vh; overflow-y: auto; background: var(--bg); padding: 8px; border-radius: 8px; margin: 6px 0; }\n.card .row { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 8px; }\n.card label.option { display: flex; gap: 8px; align-items: flex-start; padding: 8px; border: 1px solid var(--line); border-radius: 8px; margin: 6px 0; }\n.card label.option small { display: block; color: var(--muted); }\n.card input[type=text] { width: 100%; font: inherit; padding: 8px; border-radius: 8px; border: 1px solid var(--line); background: var(--bg); color: var(--text); margin-top: 6px; }\n#notice { margin: 0 16px 8px; padding: 8px 12px; border-radius: 8px; background: var(--panel); border: 1px solid var(--line); font-size: 14px; }\n#notice.bad { border-color: var(--danger); color: var(--danger); }\n.composer { display: flex; gap: 8px; align-items: flex-end; padding: 8px 16px calc(8px + env(safe-area-inset-bottom)); border-top: 1px solid var(--line); background: var(--bg); }\ntextarea { flex: 1; resize: none; font: inherit; padding: 9px 12px; border-radius: 18px; border: 1px solid var(--line); background: var(--panel); color: var(--text); max-height: 40vh; }\nbutton { font: inherit; font-weight: 600; padding: 9px 16px; border-radius: 18px; border: 1px solid var(--accent); background: var(--accent); color: var(--accent-text); }\nbutton.secondary { background: transparent; color: var(--text); border-color: var(--line); }\nbutton.danger { background: transparent; color: var(--danger); border-color: var(--danger); }\nbutton:disabled { opacity: .5; }\n#cover { position: fixed; inset: 0; background: var(--bg); display: flex; align-items: center; justify-content: center; padding: 24px; }\n#cover .panel { max-width: 420px; text-align: center; }\n#cover h1 { font-size: 20px; }\n#cover p { color: var(--muted); }\n[hidden] { display: none !important; }\n";
+export declare const PAGE_JS: string;