@turns/dev 0.0.1

package/README.md

@@ -0,0 +1,74 @@
+# Turns CLI
+
+`turns` uploads native agent transcripts directly from this machine to the
+current user's Durable Object on turns.dev. Transcript rows are secret-filtered
+on the machine immediately before the WebSocket boundary; local transcript
+files are never rewritten.
+
+Install the CLI with Node.js 22.18 or newer:
+
+```sh
+npm install --global @turns/dev
+```
+
+## Commands
+
+```text
+turns                         upload sessions for the current directory once
+turns upload [directory]      watch one directory
+turns install                 install the all-directory user daemon
+turns status                  report daemon state
+turns uninstall               remove the daemon
+turns login                   replace saved credentials through the browser
+turns logout                  remove saved credentials
+```
+
+The server is selected with `--server URL` or `TURNS_ORIGIN`. Its normalized
+origin is saved in `~/.config/turns/credentials.json` and reused by later
+invocations and daemon starts. On Linux the other persistent files are:
+
+- `~/.config/turns/machine-id`
+- `~/.local/state/turns/native-upload-state.json`
+- `~/.config/systemd/user/turns.service`
+
+The credential file contains a seven-day access token and a signed refresh
+token. The CLI refreshes the access token at least once every 24 hours. A new
+machine opens a one-time turns.dev URL, waits on an authentication WebSocket,
+and saves the resulting pair with mode `0600`. Set `TURNS_NO_BROWSER=1` to only
+print the URL.
+
+Rows are scanned on their way out for substrings that look like file paths —
+`out/chart.png`, `` `src/app.tsx` ``, `~/shots/a.png` — and each one the
+filesystem confirms is recorded on the session's own log as a resolution: the
+substring, the absolute path, the size, and whether the contents were sent.
+Paths resolve against the session's working directory and are canonicalised
+before the `--allow-directory` prefixes are enforced, so a symlink out of an
+allowed tree is not a way to read the disk.
+
+Only images under 10 MB are uploaded, to `PUT /api/file/{machine}/{path}`. Everything else is recorded as a name, so
+a reader learns what a response was pointing at without the machine shipping
+source files. Nothing is claimed until the filesystem confirms it, which is what
+bounds a deliberately broad matcher: prose that merely looks like a path
+resolves to nothing and is never mentioned to the server, and no directory is
+ever scanned.
+
+An explicit file browse may upload up to 199 MB to the same private R2 prefix.
+The daemon streams the file from disk and the Worker hands that request stream
+straight to R2, so neither process retains the complete file in memory.
+
+The systemd unit uses `KillMode=process`: restarting the uploader leaves its
+detached agent-anchor processes running so in-flight harness turns continue.
+For a foreground daemon restricted to one or more directory trees, repeat
+`--allow-directory`. Both transcript discovery and agent launches enforce the
+canonical prefix, including protection against symlinks that escape it:
+
+```sh
+turns daemon run --server https://turns.example --allow-directory /srv/agents
+```
+
+Against local Wrangler development, use the configured `DEV_USER` directly:
+
+```sh
+turns daemon run --server http://127.0.0.1:8787 \
+  --dev-user antimatter15 --allow-directory /tmp/turns-driver-workspaces
+```

package/dist/agent-anchor-client.js

@@ -0,0 +1,319 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+function withTimeout(promise, timeoutMs, label) {
+    let timer;
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms.`)), timeoutMs);
+            timer.unref?.();
+        }),
+    ]).finally(() => clearTimeout(timer));
+}
+function wait(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+export class AgentAnchorConnection {
+    socketPath;
+    socket;
+    lines;
+    nextId;
+    pending;
+    listeners;
+    recentMessages;
+    lastEventCursor;
+    snapshot;
+    closed;
+    constructor(socketPath) {
+        this.socketPath = socketPath;
+        this.socket = null;
+        this.lines = null;
+        this.nextId = 1;
+        this.pending = new Map();
+        this.listeners = new Set();
+        this.recentMessages = [];
+        this.lastEventCursor = 0;
+        this.snapshot = null;
+        this.closed = false;
+    }
+    async connect(timeoutMs = 2_000) {
+        const socket = net.createConnection(this.socketPath);
+        this.socket = socket;
+        socket.setEncoding('utf8');
+        this.lines = readline.createInterface({ input: socket });
+        this.lines.on('line', (line) => this.handleLine(line));
+        this.lines.on('error', (error) => this.handleDisconnect(error));
+        socket.on('error', (error) => this.handleDisconnect(error));
+        socket.on('close', () => this.handleDisconnect(new Error(`Agent anchor disconnected: ${this.socketPath}`)));
+        await withTimeout(new Promise((resolve, reject) => {
+            socket.once('connect', resolve);
+            socket.once('error', reject);
+        }), timeoutMs, `Agent anchor connection ${this.socketPath}`);
+        this.snapshot = await this.request('snapshot', {}, timeoutMs);
+        return this;
+    }
+    handleLine(line) {
+        if (!line.trim())
+            return;
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (message.id !== undefined) {
+            const pending = this.pending.get(message.id);
+            if (!pending)
+                return;
+            this.pending.delete(message.id);
+            if (message.ok === false)
+                pending.reject(new Error(message.error || 'Agent anchor request failed.'));
+            else
+                pending.resolve(message.result);
+            return;
+        }
+        if (message.type === 'anchor_hello' && message.anchor)
+            this.snapshot = message.anchor;
+        const cursor = ++this.lastEventCursor;
+        this.recentMessages.push({ cursor, message });
+        if (this.recentMessages.length > 512)
+            this.recentMessages.shift();
+        for (const listener of this.listeners)
+            listener(message, cursor);
+    }
+    handleDisconnect(error) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.lines?.close();
+        }
+        catch { }
+        try {
+            this.socket?.destroy();
+        }
+        catch { }
+        for (const pending of this.pending.values())
+            pending.reject(error);
+        this.pending.clear();
+        for (const listener of this.listeners)
+            listener({
+                type: 'anchor_disconnect',
+                error: error?.message || String(error),
+            });
+    }
+    request(type, params = {}, timeoutMs = 15_000) {
+        if (this.closed || !this.socket?.writable)
+            return Promise.reject(new Error('Agent anchor is not connected.'));
+        const id = this.nextId++;
+        return withTimeout(new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.socket.write(`${JSON.stringify({ id, type, ...params })}\n`, (error) => {
+                if (!error)
+                    return;
+                this.pending.delete(id);
+                reject(error);
+            });
+        }), timeoutMs, `Agent anchor request ${type}`).finally(() => this.pending.delete(id));
+    }
+    onEvent(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    recentEvents() {
+        return this.recentMessages.map((entry) => entry.message);
+    }
+    eventCursor() {
+        return this.lastEventCursor;
+    }
+    recentEventsAfter(cursor) {
+        return this.recentMessages.filter((entry) => entry.cursor > cursor).map((entry) => ({ ...entry }));
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.lines?.close();
+        }
+        catch { }
+        try {
+            this.socket?.end();
+            this.socket?.unref();
+        }
+        catch { }
+        for (const pending of this.pending.values())
+            pending.reject(new Error('Agent anchor connection closed.'));
+        this.pending.clear();
+        this.listeners.clear();
+    }
+}
+export function agentAnchorDirectory() {
+    return path.resolve(process.env.TURNS_AGENT_ANCHOR_DIR || path.join(os.homedir(), '.local', 'state', 'turns-dev', 'agent-anchors'));
+}
+function anchorEntryPoint() {
+    const configured = process.env.TURNS_AGENT_ANCHOR_BIN;
+    const extension = path.extname(fileURLToPath(import.meta.url));
+    const candidate = path.resolve(configured || path.join(HERE, `agent-anchor${extension}`));
+    if (!fs.existsSync(candidate)) {
+        throw new Error(`The Turns agent anchor was not found at ${candidate}. Set TURNS_AGENT_ANCHOR_BIN.`);
+    }
+    return candidate;
+}
+function socketPathFor(sessionId) {
+    const directory = agentAnchorDirectory();
+    const sessionHash = crypto.createHash('sha256').update(String(sessionId)).digest('hex').slice(0, 12);
+    const nonce = crypto.randomUUID().replaceAll('-', '').slice(0, 12);
+    const socketPath = path.join(directory, `a-${sessionHash}-${nonce}.sock`);
+    if (Buffer.byteLength(socketPath) > 107)
+        throw new Error(`Agent anchor socket path is too long: ${socketPath}`);
+    return socketPath;
+}
+export function anchorId(connection) {
+    return path.basename(connection.socketPath, '.sock');
+}
+export async function launchAgentAnchor(sessionId, timeoutMs = 15_000) {
+    const directory = agentAnchorDirectory();
+    const logDirectory = path.join(directory, 'logs');
+    fs.mkdirSync(logDirectory, { recursive: true, mode: 0o700 });
+    const socketPath = socketPathFor(sessionId);
+    const logPath = path.join(logDirectory, `${path.basename(socketPath, '.sock')}.log`);
+    const logFd = fs.openSync(logPath, 'a', 0o600);
+    const entry = anchorEntryPoint();
+    const child = spawn(process.execPath, [entry, '--socket', socketPath], {
+        cwd: path.dirname(entry),
+        env: { ...process.env, TURNS_AGENT_ANCHOR_DIR: directory },
+        detached: true,
+        stdio: ['ignore', logFd, logFd],
+    });
+    fs.closeSync(logFd);
+    child.unref();
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        if (child.exitCode !== null || child.signalCode !== null) {
+            throw new Error(`Agent anchor exited before opening its socket (${child.signalCode || child.exitCode}). See ${logPath}`);
+        }
+        const connection = new AgentAnchorConnection(socketPath);
+        try {
+            await connection.connect(Math.min(1_500, Math.max(100, deadline - Date.now())));
+            return connection;
+        }
+        catch (error) {
+            lastError = error;
+            connection.close();
+            await wait(100);
+        }
+    }
+    try {
+        process.kill(child.pid, 'SIGTERM');
+    }
+    catch { }
+    throw lastError || new Error(`Timed out starting agent anchor. See ${logPath}`);
+}
+export async function connectExistingAgentAnchors() {
+    const directory = agentAnchorDirectory();
+    let paths = [];
+    try {
+        paths = fs
+            .readdirSync(directory, { withFileTypes: true })
+            .filter((entry) => entry.isSocket?.() || entry.name.endsWith('.sock'))
+            .map((entry) => path.join(directory, entry.name));
+    }
+    catch { }
+    const anchors = [];
+    await Promise.all(paths.map(async (socketPath) => {
+        const connection = new AgentAnchorConnection(socketPath);
+        try {
+            await connection.connect();
+            const snapshot = connection.snapshot || {};
+            if (snapshot.protocol !== 'turns.agent-anchor.v1' || !snapshot.sessionId || !snapshot.agentSessionId) {
+                connection.close();
+                return;
+            }
+            anchors.push({ connection, snapshot });
+        }
+        catch {
+            connection.close();
+            try {
+                fs.unlinkSync(socketPath);
+            }
+            catch { }
+        }
+    }));
+    return anchors;
+}
+export function waitForAgentTurn(connection, messageId, timeoutMs = 12 * 60 * 60_000, snapshot = null, afterEventCursor = null) {
+    let unsubscribe;
+    let settled = false;
+    let resolveCompletion;
+    let rejectCompletion;
+    const resultFromSnapshot = (value) => {
+        const turn = value?.currentTurn;
+        if (turn?.messageId !== messageId || turn.status === 'running' || value?.status === 'running')
+            return null;
+        return (turn.result || {
+            exitCode: turn.status === 'completed' || turn.status === 'interrupted' ? 0 : 1,
+            signal: null,
+            timedOut: false,
+            error: turn.status === 'completed' || turn.status === 'interrupted'
+                ? null
+                : { message: 'Anchored agent turn failed.' },
+        });
+    };
+    const settle = (result, error) => {
+        if (settled)
+            return;
+        settled = true;
+        if (error)
+            rejectCompletion(error);
+        else
+            resolveCompletion(result);
+    };
+    const consume = (message, cursor = null) => {
+        if (message.type === 'anchor_disconnect')
+            return settle(null, new Error(message.error || 'Agent anchor disconnected.'));
+        if (afterEventCursor !== null && cursor !== null && cursor <= afterEventCursor)
+            return;
+        if (String(message.messageId || '') !== String(messageId))
+            return;
+        if (message.type === 'turn_complete')
+            settle(message.result || { exitCode: 0, error: null });
+        if (message.type === 'turn_error')
+            settle(message.result || { exitCode: 1, error: { message: 'Agent turn failed.' } });
+    };
+    const completion = new Promise((resolve, reject) => {
+        resolveCompletion = resolve;
+        rejectCompletion = reject;
+        unsubscribe = connection.onEvent(consume);
+        if (afterEventCursor === null) {
+            for (const message of connection.recentEvents())
+                consume(message);
+        }
+        else {
+            for (const entry of connection.recentEventsAfter(afterEventCursor))
+                consume(entry.message, entry.cursor);
+        }
+        const initial = resultFromSnapshot(snapshot);
+        if (initial)
+            settle(initial);
+        if (!settled)
+            connection
+                .request('snapshot', {}, 5_000)
+                .then((latest) => {
+                const result = resultFromSnapshot(latest);
+                if (result)
+                    settle(result);
+            })
+                .catch(() => { });
+    });
+    return withTimeout(completion, timeoutMs, 'Anchored agent turn').finally(() => unsubscribe?.());
+}