@turns/dev 0.0.6 → 0.0.8

package/README.md

@@ -39,14 +39,19 @@ never prunes saved upload cursors, so it cannot make the sessions it filtered
 out replay from their first byte the next time the daemon starts.
 
 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:
+origin is saved and reused by later invocations and daemon starts. On Linux,
+Turns uses the XDG config/state directories and installs this user service:
 
 - `~/.config/turns/machine-id`
 - `~/.local/state/turns/native-upload-state.json`
 - `~/.local/state/turns/letta-sessions/*.json` (Letta conversation-to-project associations)
 - `~/.config/systemd/user/turns.service`
 
+On macOS, credentials and daemon state live under
+`~/Library/Application Support/turns/`, and `turns install` creates the per-user
+LaunchAgent `~/Library/LaunchAgents/dev.turns.cli.plist`. Its output is written
+to `~/Library/Application Support/turns/daemon.log`.
+
 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,
@@ -72,8 +77,9 @@ 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.
+The systemd unit uses `KillMode=process`, and the macOS LaunchAgent uses
+`AbandonProcessGroup`: 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
 `--directory`. Both transcript discovery and agent launches enforce the
 canonical prefix, including protection against symlinks that escape it:

package/dist/daemon.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { spawnSync } from 'node:child_process';
@@ -36,6 +37,7 @@ export function canonicalDaemonCliEntry(cliDirectory = HERE) {
 }
 export const SYSTEMD_SERVICE_NAME = 'turns.service';
 export const LEGACY_SYSTEMD_SERVICE_NAME = 'turns-native-uploader.service';
+export const MAC_LAUNCH_AGENT_LABEL = 'dev.turns.cli';
 function systemdQuote(value) {
     return `"${String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%')}"`;
 }
@@ -59,6 +61,62 @@ Environment=NODE_NO_WARNINGS=1
 WantedBy=default.target
 `;
 }
+function xmlEscape(value) {
+    return String(value)
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
+}
+export function macLaunchAgentPlist({ cliEntry = canonicalDaemonCliEntry(), execPath = process.execPath, workingDirectory = os.homedir(), logPath = applicationPaths().daemonLog, pathEnvironment = process.env.PATH || '/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin', } = {}) {
+    const arguments_ = [
+        execPath,
+        '--max-old-space-size=256',
+        '--max-semi-space-size=8',
+        '--experimental-strip-types',
+        cliEntry,
+        'daemon',
+        'run',
+    ];
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${MAC_LAUNCH_AGENT_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${arguments_.map((value) => `    <string>${xmlEscape(value)}</string>`).join('\n')}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(workingDirectory)}</string>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>5</integer>
+  <key>AbandonProcessGroup</key>
+  <true/>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>NODE_NO_WARNINGS</key>
+    <string>1</string>
+    <key>PATH</key>
+    <string>${xmlEscape(pathEnvironment)}</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(logPath)}</string>
+</dict>
+</plist>
+`;
+}
 function systemctl(arguments_, { spawnSyncImpl = spawnSync, allowFailure = false } = {}) {
     const result = spawnSyncImpl('systemctl', ['--user', ...arguments_], { encoding: 'utf8', stdio: 'pipe' });
     if (!allowFailure && result.status !== 0) {
@@ -66,6 +124,16 @@ function systemctl(arguments_, { spawnSyncImpl = spawnSync, allowFailure = false
     }
     return result;
 }
+function launchctl(arguments_, { spawnSyncImpl = spawnSync, allowFailure = false } = {}) {
+    const result = spawnSyncImpl('/bin/launchctl', arguments_, { encoding: 'utf8', stdio: 'pipe' });
+    if (!allowFailure && result.status !== 0) {
+        throw new Error(String(result.stderr || result.stdout || `launchctl ${arguments_.join(' ')} failed`).trim());
+    }
+    return result;
+}
+function macLaunchTarget(userId) {
+    return `gui/${userId}/${MAC_LAUNCH_AGENT_LABEL}`;
+}
 export function installLinuxDaemon({ paths = applicationPaths(), spawnSyncImpl = spawnSync, } = {}) {
     fs.mkdirSync(path.dirname(paths.linuxService), { recursive: true, mode: 0o700 });
     const unit = linuxServiceUnit();
@@ -115,20 +183,63 @@ export function linuxDaemonStatus({ spawnSyncImpl = spawnSync } = {}) {
         status: String(result.stdout || result.stderr || 'unknown').trim(),
     };
 }
-export function installDaemon(options = {}) {
-    if (process.platform !== 'linux') {
-        throw new Error('Automatic daemon installation is currently supported on Linux with systemd.');
-    }
-    return installLinuxDaemon(options);
+export function installMacDaemon({ paths = applicationPaths(), spawnSyncImpl = spawnSync, userId = process.getuid?.(), } = {}) {
+    if (userId === undefined)
+        throw new Error('Could not determine the macOS user ID for launchd.');
+    fs.mkdirSync(path.dirname(paths.macLaunchAgent), { recursive: true, mode: 0o700 });
+    fs.mkdirSync(path.dirname(paths.daemonLog), { recursive: true, mode: 0o700 });
+    const target = macLaunchTarget(userId);
+    const temporary = `${paths.macLaunchAgent}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, macLaunchAgentPlist({ workingDirectory: os.homedir(), logPath: paths.daemonLog }), { mode: 0o644 });
+    fs.renameSync(temporary, paths.macLaunchAgent);
+    // A loaded job retains its previous definition. Boot it out after the atomic
+    // replacement so a reinstall always starts the command from the current CLI.
+    launchctl(['bootout', target], { spawnSyncImpl, allowFailure: true });
+    launchctl(['enable', target], { spawnSyncImpl });
+    launchctl(['bootstrap', `gui/${userId}`, paths.macLaunchAgent], { spawnSyncImpl });
+    launchctl(['kickstart', '-k', target], { spawnSyncImpl });
+    return paths.macLaunchAgent;
 }
-export function uninstallDaemon(options = {}) {
-    if (process.platform !== 'linux') {
-        throw new Error('Automatic daemon removal is currently supported on Linux with systemd.');
+export function uninstallMacDaemon({ paths = applicationPaths(), spawnSyncImpl = spawnSync, userId = process.getuid?.(), } = {}) {
+    if (userId === undefined)
+        throw new Error('Could not determine the macOS user ID for launchd.');
+    launchctl(['bootout', macLaunchTarget(userId)], { spawnSyncImpl, allowFailure: true });
+    try {
+        fs.unlinkSync(paths.macLaunchAgent);
+    }
+    catch (error) {
+        if (error?.code !== 'ENOENT')
+            throw error;
     }
-    return uninstallLinuxDaemon(options);
 }
-export function daemonStatus(options = {}) {
-    if (process.platform !== 'linux')
+export function macDaemonStatus({ spawnSyncImpl = spawnSync, userId = process.getuid?.(), } = {}) {
+    if (userId === undefined)
         return { active: false, status: 'unsupported' };
-    return linuxDaemonStatus(options);
+    const result = launchctl(['print', macLaunchTarget(userId)], { spawnSyncImpl, allowFailure: true });
+    if (result.status !== 0)
+        return { active: false, status: 'not running' };
+    const output = String(result.stdout || result.stderr || '');
+    const state = /^\s*state = (.+?)\s*$/mu.exec(output)?.[1] || 'loaded';
+    return { active: state === 'running', status: state };
+}
+export function installDaemon({ platform = process.platform, ...options } = {}) {
+    if (platform === 'linux')
+        return installLinuxDaemon(options);
+    if (platform === 'darwin')
+        return installMacDaemon(options);
+    throw new Error('Automatic daemon installation is supported on Linux with systemd and macOS with launchd.');
+}
+export function uninstallDaemon({ platform = process.platform, ...options } = {}) {
+    if (platform === 'linux')
+        return uninstallLinuxDaemon(options);
+    if (platform === 'darwin')
+        return uninstallMacDaemon(options);
+    throw new Error('Automatic daemon removal is supported on Linux with systemd and macOS with launchd.');
+}
+export function daemonStatus({ platform = process.platform, ...options } = {}) {
+    if (platform === 'linux')
+        return linuxDaemonStatus(options);
+    if (platform === 'darwin')
+        return macDaemonStatus(options);
+    return { active: false, status: 'unsupported' };
 }

package/dist/file-browsing.js

@@ -173,7 +173,7 @@ export function readDirectory(directory) {
     // clock inside the body would make every read produce different bytes.
     return { path: directory, entries, truncated: names.length > MAX_DIRECTORY_ENTRIES };
 }
-export async function browseMachinePath({ requested, machine, baseUrl, options, workingDirectory = '', fetchImpl = fetch, }) {
+export async function browseMachinePath({ requested, machine, baseUrl, options, workingDirectory = '', contentEtag = '', fetchImpl = fetch, }) {
     const resolved = resolveBrowsePath(requested, {
         workingDirectory,
         allowedDirectories: options.allowedDirectories || [],
@@ -209,6 +209,7 @@ export async function browseMachinePath({ requested, machine, baseUrl, options,
         contentType,
         bytes: resolved.stat.size,
         modifiedAt,
+        ...(contentEtag ? { contentEtag } : {}),
         fetchImpl,
     });
     return { path: resolved.path, kind: 'file', bytes: resolved.stat.size, contentType, modifiedAt };

package/dist/file-edits.js

@@ -0,0 +1,82 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { workingDirectoryIsAllowed } from "./directory-policy.js";
+/**
+ * Applying a browser edit to a file this machine holds.
+ *
+ * The server's queue row says what the edit expects (`beforeHash`) and what it
+ * produces (`afterHash`); the bytes themselves are downloaded from the
+ * account's bucket only once the file on disk has been shown to still match
+ * what the editor started from. The replacement is written beside the target
+ * and renamed over it, so a crash mid-write leaves the original untouched, and
+ * the downloaded bytes are verified against `afterHash` before the rename —
+ * corrupt or truncated downloads never reach the file.
+ *
+ * A redelivered edit is settled by content: a file that already hashes to
+ * `afterHash` reports success without touching the disk, which is what lets
+ * the server re-offer an edit whose earlier answer was lost.
+ */
+/** SHA-256 of one file's bytes, streamed so large files cost no memory. */
+export async function hashFileSha256(file) {
+    const hash = crypto.createHash('sha256');
+    await pipeline(fs.createReadStream(file), hash);
+    return hash.digest('hex');
+}
+export async function applyFileEdit({ edit, baseUrl, options, fetchImpl = fetch, }) {
+    const requested = String(edit.path || '').trim();
+    if (!requested || !path.isAbsolute(requested)) {
+        throw new Error(`File edits need an absolute path: ${requested || '(empty)'}`);
+    }
+    let canonical;
+    let stat;
+    try {
+        canonical = fs.realpathSync(requested);
+        stat = fs.statSync(canonical);
+    }
+    catch {
+        throw new Error(`No such file: ${requested}`);
+    }
+    if (!stat.isFile())
+        throw new Error(`Not an editable file: ${canonical}`);
+    // The same allowlist that bounds browsing bounds writing: a file is editable
+    // exactly when the directory holding it could be browsed.
+    if (!workingDirectoryIsAllowed(path.dirname(canonical), options.allowedDirectories || [])) {
+        throw new Error(`Path is outside the daemon allowlist: ${canonical}`);
+    }
+    const current = await hashFileSha256(canonical);
+    if (current === edit.afterHash)
+        return { path: canonical, alreadyApplied: true };
+    if (current !== edit.beforeHash) {
+        throw new Error('The file changed on this machine after the edit was made, so it was not applied.');
+    }
+    const url = new URL(`/api/file-edits/${encodeURIComponent(String(edit.id || ''))}`, String(baseUrl));
+    const response = await fetchImpl(url, {
+        headers: { authorization: `Bearer ${options.token}` },
+    });
+    if (!response.ok || !response.body) {
+        throw new Error(`The edited file could not be downloaded (${response.status}).`);
+    }
+    const temporary = path.join(path.dirname(canonical), `.${path.basename(canonical)}.turns-edit-${process.pid}.tmp`);
+    try {
+        await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(temporary, { mode: 0o600 }));
+        const written = fs.statSync(temporary);
+        if (Number(edit.bytes) !== written.size) {
+            throw new Error('The downloaded edit did not match its recorded size.');
+        }
+        if ((await hashFileSha256(temporary)) !== edit.afterHash) {
+            throw new Error('The downloaded edit did not match its recorded content hash.');
+        }
+        // The temporary file was created 0600 regardless of umask; give the
+        // replacement the permissions the original had before it takes its name.
+        fs.chmodSync(temporary, stat.mode & 0o7777);
+        fs.renameSync(temporary, canonical);
+    }
+    catch (error) {
+        fs.rmSync(temporary, { force: true });
+        throw error;
+    }
+    return { path: canonical, alreadyApplied: false };
+}

package/dist/path-resolution.js

@@ -193,7 +193,7 @@ export async function uploadFileBytes({ baseUrl, options, machine, 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, modifiedAt, fetchImpl = fetch, }) {
+export async function uploadFileStream({ baseUrl, options, machine, absolutePath, contentType, bytes, modifiedAt, contentEtag, fetchImpl = fetch, }) {
     const url = new URL(`/api/file/${encodeURIComponent(machine)}/${encodeURIComponent(absolutePath)}`, String(baseUrl));
     const body = fs.createReadStream(absolutePath);
     try {
@@ -204,6 +204,7 @@ export async function uploadFileStream({ baseUrl, options, machine, absolutePath
                 'content-type': contentType,
                 'content-length': String(bytes),
                 ...(modifiedAt ? { 'x-turns-file-modified-at': modifiedAt } : {}),
+                ...(contentEtag ? { 'x-turns-content-etag': contentEtag } : {}),
             },
             body,
             // Node requires this opt-in for a streaming request body.

package/dist/queue-worker.js

@@ -7,6 +7,7 @@ import { pipeline } from 'node:stream/promises';
 import { anchorId, connectExistingAgentAnchors, launchAgentAnchor, waitForAgentTurn } from "./agent-anchor-client.js";
 import { assertAllowedWorkingDirectory, workingDirectoryIsAllowed } from "./directory-policy.js";
 import { browseMachinePath } from "./file-browsing.js";
+import { applyFileEdit } from "./file-edits.js";
 import { nativeDescriptorAgentSessionId, nativeDescriptorWorkingDirectory } from "./local-session-sources.js";
 import { compactRuntimeValue } from "./native-record-compaction.js";
 import { createSecretRedactor } from "./secret-redaction.js";
@@ -1068,6 +1069,55 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
             });
         }
     };
+    /**
+     * Apply one queued browser edit, and report how it went.
+     *
+     * Edits are serialized through one chain: the server sends every pending
+     * edit for this machine in queue order, and applying them strictly in
+     * arrival order is what lets several edits to one file chain — each one's
+     * before-hash is the previous one's after-hash. After a real application the
+     * file is re-browsed so the stored copy readers open reflects the new bytes.
+     */
+    let fileEditChain = Promise.resolve();
+    const handleFileEdit = (message, replyRpc) => {
+        fileEditChain = fileEditChain.then(async () => {
+            const sessionId = String(message.sessionId || '');
+            const edit = message.edit || {};
+            try {
+                const applied = await applyFileEdit({ edit, baseUrl, options });
+                if (!applied.alreadyApplied) {
+                    await browseMachinePath({
+                        requested: applied.path,
+                        machine,
+                        baseUrl,
+                        options,
+                        // The applied bytes were verified against this hash, so store it
+                        // as their identity: a pane already showing them recognizes the
+                        // refresh instead of being offered its own save as a new version.
+                        contentEtag: String(edit.afterHash || ''),
+                    }).catch((error) => process.stderr.write(`Post-edit refresh failed for ${applied.path}: ${error?.message || error}\n`));
+                }
+                replyRpc.notify({
+                    type: 'session.file.edit.result',
+                    requestId: message.requestId,
+                    sessionId,
+                    editId: String(edit.id || ''),
+                    ok: true,
+                });
+            }
+            catch (error) {
+                replyRpc.notify({
+                    type: 'session.file.edit.result',
+                    requestId: message.requestId,
+                    sessionId,
+                    editId: String(edit.id || ''),
+                    ok: false,
+                    error: redactor.redactText(error?.message || String(error)),
+                });
+            }
+        });
+        return fileEditChain;
+    };
     const heartbeat = setInterval(() => {
         for (const [sessionId, entry] of anchors) {
             if (entry.connection.closed)
@@ -1089,6 +1139,8 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
             void handleInteractionAnswer(message, rpc);
         if (message.type === 'session.file.browse.request')
             void handleFileBrowse(message, rpc);
+        if (message.type === 'session.file.edit.request')
+            void handleFileEdit(message, rpc);
     });
     const registered = new WeakSet();
     const registering = new WeakSet();
@@ -1100,6 +1152,7 @@ export async function watchQueuedPrompts({ rpc, options, machine, getDescriptors
             const ready = await control.request({
                 type: 'machine.register',
                 machineId: machine,
+                machineHostname: os.hostname(),
                 workerId,
                 workerInstanceId,
                 anchorSessionIds: [...anchors.keys()],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turns/dev",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Upload local AI agent sessions to turns.dev",
   "license": "MIT",
   "type": "module",