@turns/dev 0.0.1

package/dist/native-record-compaction.js

@@ -0,0 +1,84 @@
+/**
+ * One value budget for every row this machine sends, native or live.
+ *
+ * A stored row's value has to survive the Durable Object's SQLite column limit,
+ * which is well under the socket's message ceiling: a value that clears the
+ * frame check and then fails the insert is not a dropped row, it is a batch the
+ * uploader retries forever. Both producers compact through here so no harness's
+ * multi-megabyte tool output can reach that state.
+ */
+/** Largest value this machine ever sends for one row. */
+export const MAX_NATIVE_VALUE_BYTES = 450_000;
+function headUtf8(value, cap) {
+    const bytes = Buffer.from(value);
+    return bytes.byteLength <= cap ? value : bytes.subarray(0, cap).toString('utf8');
+}
+/** Trim long strings, deep arrays, and inline binary out of one parsed record. */
+export function sanitizeNativeValue(value, stringCap, arrayCap, depth = 0) {
+    if (typeof value === 'string') {
+        const bytes = Buffer.byteLength(value);
+        const binary = value.includes('data:') && value.includes(';base64,');
+        if (!binary && bytes <= stringCap)
+            return value;
+        const head = headUtf8(value, binary ? Math.min(stringCap, 8_000) : stringCap);
+        return `${head}\n[turns.dev omitted ${Math.max(0, bytes - Buffer.byteLength(head)).toLocaleString()} bytes${binary ? ' of inline binary data' : ''}]`;
+    }
+    if (Array.isArray(value)) {
+        const held = value.slice(0, arrayCap).map((item) => sanitizeNativeValue(item, stringCap, arrayCap, depth + 1));
+        if (value.length > arrayCap)
+            held.push(`[turns.dev omitted ${value.length - arrayCap} array entries]`);
+        return held;
+    }
+    if (!value || typeof value !== 'object' || depth > 16)
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, held]) => [key, sanitizeNativeValue(held, stringCap, arrayCap, depth + 1)]));
+}
+/** Compact one record's serialized form to fit `MAX_NATIVE_VALUE_BYTES`. */
+export function compactNativeRaw(raw) {
+    const bytes = Buffer.byteLength(raw);
+    const containsBinary = raw.includes('data:') && raw.includes(';base64,');
+    if (bytes <= MAX_NATIVE_VALUE_BYTES && !containsBinary)
+        return raw;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return JSON.stringify({
+            type: 'turns.native.omitted',
+            text: `[turns.dev omitted an unparsable ${bytes.toLocaleString()}-byte native record]`,
+        });
+    }
+    let compacted = JSON.stringify(sanitizeNativeValue(parsed, 64_000, 250));
+    if (Buffer.byteLength(compacted) > MAX_NATIVE_VALUE_BYTES) {
+        compacted = JSON.stringify(sanitizeNativeValue(parsed, 4_000, 80));
+    }
+    if (Buffer.byteLength(compacted) <= MAX_NATIVE_VALUE_BYTES)
+        return compacted;
+    const record = parsed && typeof parsed === 'object' ? parsed : {};
+    return JSON.stringify({
+        type: record.type || 'turns.native.omitted',
+        role: record.role,
+        timestamp: record.timestamp || record.ts || record.created_at || record.createdAt,
+        text: `[turns.dev omitted an oversized ${bytes.toLocaleString()}-byte native record]`,
+    });
+}
+/**
+ * Compact one live frame's value. Live frames are not always JSON (stderr lines
+ * arrive raw), so an unparsable value keeps its readable head rather than being
+ * replaced wholesale the way a native record is.
+ */
+export function compactRuntimeValue(value) {
+    const raw = String(value);
+    const bytes = Buffer.byteLength(raw);
+    if (bytes <= MAX_NATIVE_VALUE_BYTES && !(raw.includes('data:') && raw.includes(';base64,')))
+        return raw;
+    try {
+        JSON.parse(raw);
+    }
+    catch {
+        const head = headUtf8(raw, MAX_NATIVE_VALUE_BYTES - 200);
+        return `${head}\n[turns.dev omitted ${Math.max(0, bytes - Buffer.byteLength(head)).toLocaleString()} bytes of an oversized live frame]`;
+    }
+    return compactNativeRaw(raw);
+}

package/dist/path-resolution.js

@@ -0,0 +1,298 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * Turning the paths an agent writes into things a reader can open.
+ *
+ * An agent describes its work the way it would to a colleague sitting beside
+ * it — "wrote the plot to `out/chart.png`", "see ./src/app.tsx" — and every one
+ * of those names is meaningless on another computer. This machine is the only
+ * party that can say what they pointed at, so it says so on the record: each
+ * resolution is appended to the session's own log as its own row, carrying the
+ * substring, the absolute path, the size, and whether the contents came too.
+ *
+ * Only images travel eagerly, and only small ones. A transcript that mentions a
+ * picture is nearly always one somebody wants to see the picture in; a
+ * transcript that mentions a source file is one they want to know the path of.
+ */
+/**
+ * Substrings that might name a file.
+ *
+ * Deliberately broad — anything with a path separator, a home-relative prefix,
+ * a drive letter, or a bare name carrying an extension. Breadth is safe because
+ * nothing is claimed until the filesystem confirms it: a candidate that names no
+ * readable file is dropped without ever being mentioned to the server, and one
+ * that no message's text contains is attached to nothing when the session is
+ * rendered. A path is nearly always written inside markdown, backticks, quotes
+ * or parentheses, and all of those fall away on their own.
+ *
+ * What is scanned is a whole JSON row, so the envelope's own words — a kind of
+ * `transcript.line`, a store called `session.jsonl` — look like candidates too.
+ * They are: they cost one `stat` each per session, resolve to nothing or to a
+ * file no sentence mentions, and are dropped at one of those two gates.
+ */
+const PATH_CANDIDATE = /(?<![\w:\\/.@+-])(?:[A-Za-z]:\\|~\/|\.{1,2}\/|\/)?(?:[\w.@+-]+[/\\])*[\w.@+-]*\w\.[A-Za-z0-9]{1,12}(?![\w])/gu;
+/** Extensions a browser will render inline, and the type each is served as. */
+const IMAGE_CONTENT_TYPES = new Map([
+    ['.apng', 'image/apng'],
+    ['.avif', 'image/avif'],
+    ['.bmp', 'image/bmp'],
+    ['.gif', 'image/gif'],
+    ['.heic', 'image/heic'],
+    ['.ico', 'image/x-icon'],
+    ['.jpeg', 'image/jpeg'],
+    ['.jpg', 'image/jpeg'],
+    ['.png', 'image/png'],
+    ['.svg', 'image/svg+xml'],
+    ['.webp', 'image/webp'],
+]);
+/** Kept in step with `MAX_FILE_BYTES` on the server, which rejects more. */
+export const MAX_FILE_BYTES = 10 * 1024 * 1024;
+/** Resolutions recorded for one session, matching the reducer's own ceiling. */
+export const MAX_RESOLVED_PATHS = 256;
+/** Candidates considered in one row, so a pasted log cannot become a scan. */
+export const MAX_PATH_CANDIDATES_PER_ROW = 64;
+export function agentImageContentType(file) {
+    return IMAGE_CONTENT_TYPES.get(path.extname(file).toLowerCase()) || '';
+}
+/**
+ * Destinations the reader's browser could already fetch are not ours to resolve.
+ *
+ * A single-letter prefix is not read as a scheme, so a Windows `C:\...` path
+ * stays a path — URL schemes are two characters or more.
+ */
+function couldNameLocalFile(candidate) {
+    if (!candidate || candidate.length > 1024)
+        return false;
+    if (candidate.startsWith('#') || candidate.startsWith('//'))
+        return false;
+    return !/^[a-zA-Z][a-zA-Z0-9+.-]+:/u.test(candidate);
+}
+/**
+ * Every substring of one outbound row that might name a file.
+ *
+ * The row is the redacted JSON line, so what is scanned is escaped text: a
+ * candidate carrying a quote or a backslash cannot be told apart from the
+ * escaping around it and is skipped rather than guessed at. Windows paths are
+ * the notable casualty, and they are the reason this is stated rather than
+ * silently true.
+ */
+export function pathCandidates(row) {
+    const found = [];
+    for (const match of String(row || '').matchAll(PATH_CANDIDATE)) {
+        const candidate = match[0];
+        if (candidate.includes('\\') || !couldNameLocalFile(candidate))
+            continue;
+        if (found.includes(candidate))
+            continue;
+        found.push(candidate);
+        if (found.length >= MAX_PATH_CANDIDATES_PER_ROW)
+            break;
+    }
+    return found;
+}
+/**
+ * Candidate filesystem paths for one substring.
+ *
+ * Markdown percent-encodes a space, so `shots/a%20b.png` and `shots/a b.png`
+ * are the same file written two ways and both are tried. A leading `~` is the
+ * agent's own shorthand for its home directory and is expanded here rather
+ * than being handed to the filesystem as a literal directory name.
+ */
+export function candidateFilePaths(candidate, workingDirectory) {
+    const raw = String(candidate || '').trim();
+    if (!raw)
+        return [];
+    const forms = new Set([raw]);
+    try {
+        const decoded = decodeURIComponent(raw);
+        if (decoded !== raw)
+            forms.add(decoded);
+    }
+    catch { }
+    const resolved = [];
+    for (const form of forms) {
+        const expanded = form === '~' || form.startsWith('~/') ? path.join(os.homedir(), form.slice(1)) : form;
+        if (path.isAbsolute(expanded))
+            resolved.push(path.normalize(expanded));
+        else if (workingDirectory)
+            resolved.push(path.resolve(workingDirectory, expanded));
+    }
+    return [...new Set(resolved)];
+}
+/**
+ * What one substring names on this machine, or nothing.
+ *
+ * This is the filter that makes a broad regex safe: a candidate becomes a
+ * resolution only once the filesystem confirms a readable regular file, inside
+ * whatever the daemon was allowed to read. Everything else was just prose that
+ * happened to look like a path.
+ */
+export function resolvePathCandidate(candidate, workingDirectory, { allowedDirectories = [] } = {}) {
+    for (const attempt of candidateFilePaths(candidate, workingDirectory)) {
+        let file;
+        let stat;
+        try {
+            // Canonicalise before the allowlist test: a symlink out of an allowed
+            // tree must not become a way to read the rest of the disk.
+            file = fs.realpathSync(attempt);
+            stat = fs.statSync(file);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        if (allowedDirectories.length && !insideAllowedDirectory(file, allowedDirectories))
+            continue;
+        return { file, bytes: stat.size, contentType: agentImageContentType(file) };
+    }
+    return null;
+}
+/** Whether the machine should send the contents alongside the name. */
+export function shouldUploadEagerly(resolved) {
+    return Boolean(resolved.contentType) && resolved.bytes > 0 && resolved.bytes <= MAX_FILE_BYTES;
+}
+function insideAllowedDirectory(file, allowedDirectories) {
+    return allowedDirectories.some((allowed) => {
+        const relative = path.relative(allowed, file);
+        return relative !== '' && !relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative);
+    });
+}
+function uploadHeaders(options) {
+    return options.devUser
+        ? { 'x-turns-dev-user': options.devUser, 'x-turns-dev-role': 'uploader' }
+        : { authorization: `Bearer ${options.token}` };
+}
+/**
+ * Put bytes in the account's private prefix, under the path they came from.
+ *
+ * The path is the object's identity rather than a description of it, so a
+ * listing the machine composed for a directory is stored the same way a file
+ * read off the disk is: whoever fetches it addresses the same path back. It is
+ * addressed by machine and path alone — the session that happened to prompt the
+ * upload is not part of what was stored, and nothing records it.
+ */
+export async function uploadFileBytes({ baseUrl, options, machine, absolutePath, contentType, body, fetchImpl = fetch, }) {
+    const url = new URL(`/api/file/${encodeURIComponent(machine)}/${encodeURIComponent(absolutePath)}`, String(baseUrl));
+    const response = await fetchImpl(url, {
+        method: 'PUT',
+        headers: {
+            ...uploadHeaders(options),
+            'content-type': contentType,
+            'content-length': String(body.byteLength),
+        },
+        body,
+    });
+    if (!response.ok)
+        throw new Error(`File upload failed (${response.status}) for ${absolutePath}.`);
+    return true;
+}
+/** Stream one on-disk file to R2 without retaining its body in the daemon. */
+export async function uploadFileStream({ baseUrl, options, machine, absolutePath, contentType, bytes, fetchImpl = fetch, }) {
+    const url = new URL(`/api/file/${encodeURIComponent(machine)}/${encodeURIComponent(absolutePath)}`, String(baseUrl));
+    const body = fs.createReadStream(absolutePath);
+    try {
+        const response = await fetchImpl(url, {
+            method: 'PUT',
+            headers: {
+                ...uploadHeaders(options),
+                'content-type': contentType,
+                'content-length': String(bytes),
+            },
+            body,
+            // Node requires this opt-in for a streaming request body.
+            duplex: 'half',
+        });
+        if (!response.ok)
+            throw new Error(`File upload failed (${response.status}) for ${absolutePath}.`);
+        return true;
+    }
+    finally {
+        body.destroy();
+    }
+}
+/** Send one resolved file to the account's private prefix. */
+export async function uploadResolvedFile({ baseUrl, options, machine, resolved, fetchImpl = fetch, }) {
+    const body = new Uint8Array(fs.readFileSync(resolved.file));
+    // The file changed under the stat. The next pass over a rewritten transcript
+    // resolves it again; sending a body whose length disagrees would not.
+    if (body.byteLength !== resolved.bytes)
+        return false;
+    return uploadFileBytes({
+        baseUrl,
+        options,
+        machine,
+        absolutePath: resolved.file,
+        contentType: resolved.contentType,
+        body,
+        fetchImpl,
+    });
+}
+/**
+ * Resolve what one session's rows mentioned, and record it.
+ *
+ * Every substring a session has already resolved is remembered, so prose quoted
+ * back in a later row — a compaction summary, a resumed transcript — costs a set
+ * lookup rather than another stat. Work runs on one chain per session so a burst
+ * of rows cannot open a burst of file reads, and a failure is reported once and
+ * dropped: rows are the product here, and a picture that did not make it must
+ * never hold up the transcript that named it.
+ */
+export function createPathResolver({ options, machine, baseUrl, appendResolutions, redactor = null, fetchImpl = fetch, }) {
+    const seen = new Map();
+    const chains = new Map();
+    const resolveBatch = async (sessionId, workingDirectory, candidates) => {
+        const resolutions = [];
+        for (const candidate of candidates) {
+            const resolved = resolvePathCandidate(candidate, workingDirectory, {
+                allowedDirectories: options.allowedDirectories || [],
+            });
+            if (!resolved)
+                continue;
+            let uploaded = false;
+            if (shouldUploadEagerly(resolved)) {
+                uploaded = await uploadResolvedFile({ baseUrl, options, machine, resolved, fetchImpl });
+            }
+            resolutions.push({
+                text: candidate,
+                path: resolved.file,
+                bytes: resolved.bytes,
+                ...(resolved.contentType ? { contentType: resolved.contentType } : {}),
+                ...(uploaded ? { uploaded: true } : {}),
+            });
+        }
+        if (resolutions.length)
+            await appendResolutions(sessionId, resolutions);
+    };
+    return {
+        /** Offer the candidates one acknowledged batch of rows mentioned. */
+        enqueue(sessionId, workingDirectory, candidates) {
+            if (!sessionId || !candidates?.length)
+                return chains.get(sessionId) || Promise.resolve();
+            let known = seen.get(sessionId);
+            if (!known) {
+                known = new Set();
+                seen.set(sessionId, known);
+            }
+            const fresh = candidates.filter((candidate) => candidate && !known.has(candidate));
+            if (!fresh.length)
+                return chains.get(sessionId) || Promise.resolve();
+            for (const candidate of fresh) {
+                if (known.size >= MAX_RESOLVED_PATHS)
+                    break;
+                known.add(candidate);
+            }
+            const chain = (chains.get(sessionId) || Promise.resolve()).then(() => resolveBatch(sessionId, workingDirectory, fresh).catch((error) => {
+                const message = error?.message || String(error);
+                process.stderr.write(`Path resolution failed: ${redactor ? redactor.redactText(message) : message}\n`);
+            }));
+            chains.set(sessionId, chain);
+            return chain;
+        },
+        /** A reset replays the whole transcript, so its substrings are offered again. */
+        forget(sessionId) {
+            seen.delete(sessionId);
+        },
+    };
+}

package/dist/question-mcp.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+import net from 'node:net';
+import readline from 'node:readline';
+const anchorSocket = process.env.TURNS_AGENT_ANCHOR_SOCKET || '';
+let nextId = 1;
+function send(value) {
+    process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+function askAnchor(toolName, input) {
+    if (!anchorSocket)
+        return Promise.reject(new Error('The Turns agent anchor socket is unavailable.'));
+    return new Promise((resolve, reject) => {
+        const socket = net.createConnection(anchorSocket);
+        const id = String(nextId++);
+        const timer = setTimeout(() => {
+            socket.destroy();
+            reject(new Error('The question timed out.'));
+        }, 12 * 60 * 60_000);
+        timer.unref?.();
+        socket.once('error', (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+        socket.once('connect', () => socket.write(`${JSON.stringify({ id, type: 'ask_interaction', toolName, input })}\n`));
+        readline.createInterface({ input: socket }).on('line', (line) => {
+            let frame;
+            try {
+                frame = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (String(frame.id ?? '') !== id)
+                return;
+            clearTimeout(timer);
+            socket.end();
+            frame.ok ? resolve(frame.result) : reject(new Error(frame.error || 'The question was rejected.'));
+        });
+    });
+}
+const tools = [
+    {
+        name: 'turns_ask_user_question',
+        description: 'Ask the user one or more questions and wait for their interactive answer.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                question: { type: 'string' },
+                header: { type: 'string' },
+                questions: { type: 'array', items: { type: 'object' } },
+                options: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            label: { type: 'string' },
+                            description: { type: 'string' },
+                        },
+                        required: ['label'],
+                    },
+                },
+                multiSelect: { type: 'boolean' },
+                allowFreeText: { type: 'boolean' },
+                disableFreeText: { type: 'boolean' },
+                disable_free_text: { type: 'boolean' },
+            },
+        },
+    },
+    {
+        name: 'turns_echo',
+        description: 'Return the supplied text unchanged. Useful for verifying that the Turns MCP bridge is connected.',
+        inputSchema: {
+            type: 'object',
+            properties: { text: { type: 'string' } },
+            required: ['text'],
+        },
+    },
+];
+readline.createInterface({ input: process.stdin }).on('line', async (line) => {
+    let frame;
+    try {
+        frame = JSON.parse(line);
+    }
+    catch {
+        return;
+    }
+    if (frame.method === 'initialize')
+        return send({
+            jsonrpc: '2.0',
+            id: frame.id,
+            result: {
+                protocolVersion: frame.params?.protocolVersion || '2025-06-18',
+                capabilities: { tools: { listChanged: false } },
+                serverInfo: { name: 'turns', version: '1' },
+            },
+        });
+    if (frame.method === 'tools/list')
+        return send({ jsonrpc: '2.0', id: frame.id, result: { tools } });
+    if (frame.method === 'tools/call') {
+        try {
+            if (frame.params?.name === 'turns_echo') {
+                const text = String(frame.params?.arguments?.text || '');
+                return send({
+                    jsonrpc: '2.0',
+                    id: frame.id,
+                    result: { isError: false, content: [{ type: 'text', text }] },
+                });
+            }
+            const response = await askAnchor(frame.params?.name, frame.params?.arguments || {});
+            return send({
+                jsonrpc: '2.0',
+                id: frame.id,
+                result: { isError: false, content: [{ type: 'text', text: JSON.stringify(response) }] },
+            });
+        }
+        catch (error) {
+            return send({
+                jsonrpc: '2.0',
+                id: frame.id,
+                result: { isError: true, content: [{ type: 'text', text: error?.message || String(error) }] },
+            });
+        }
+    }
+    if (frame.id !== undefined)
+        send({ jsonrpc: '2.0', id: frame.id, error: { code: -32601, message: 'Method not found' } });
+});