@shardflux/cli 0.13.6 → 0.14.1

package/dist/main.js

@@ -15,6 +15,10 @@ import { statSync } from 'node:fs';
 import { SDK_VERSION, Shardflux, ShardfluxAccount, isSessionToken } from '@shardflux/sdk';
 import { CLI_VERSION, CENTER_COMMAND, PROJECT_COMMAND, commandHelp, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
 import { commandCenter } from "./command-center.js";
+import { launchConversationProject } from "./conversation-terminal.js";
+import { runAcp } from "./acp.js";
+import { registerInstalledT3 } from "./t3-provider.js";
+import { runDeviceHelper } from "./device-helper.js";
 import { housekeeping, startupHousekeeping } from "./agent-git-commands.js";
 import { CredentialStore, configDir } from "./credentials.js";
 import { recordInstall } from "./update.js";
@@ -365,6 +369,7 @@ function feedbackHint(info, credentialHint) {
 }
 export async function run(argv, io, opts = {}) {
     const signal = opts.signal ?? new AbortController().signal;
+    await registerInstalledT3(io.env, configDir(io.env), signal);
     const distribution = opts.distribution ?? CLI_DISTRIBUTION;
     const rawKey = io.env.SHARDFLUX_API_KEY;
     // Every credential this command loaded or received: redacted from anything printed on failure.
@@ -626,7 +631,7 @@ export async function run(argv, io, opts = {}) {
             },
         };
         // The update check runs next to the command (not for `version`, which reports it itself).
-        if (!updateCheckDisabled(io.env) && !['version', 'update', 'ssh-proxy'].includes(parsed.command.path[0])) {
+        if (!updateCheckDisabled(io.env) && !['version', 'update', 'ssh-proxy', 'acp', 'device-helper'].includes(parsed.command.path[0])) {
             try {
                 updates = new UpdateCheck({ dir: store.dir, apiUrl, distribution, fetch: base, userAgent });
                 updates.start();
@@ -639,10 +644,11 @@ export async function run(argv, io, opts = {}) {
     catch (err) {
         return report(err);
     }
-    const handler = parsed.command === PROJECT_COMMAND || parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
+    const handler = parsed.command.path[0] === 'acp' ? (ctx) => runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? runDeviceHelper : parsed.command === PROJECT_COMMAND ? launchConversationProject : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
     if (!handler)
         return report(new UsageError(`unknown command "${parsed.command.path.join(' ')}"`));
-    await housekeeping(ctx);
+    if (!['acp', 'device-helper'].includes(parsed.command.path[0]))
+        await housekeeping(ctx);
     const running = handler(ctx, parsed.values, parsed.positionals).then((code) => ({ code }), (err) => ({ err }));
     // On Ctrl-C give the command a moment to clean up (exec sends a cancel), then stop regardless.
     const interrupted = new Promise((resolve) => {
@@ -693,6 +699,12 @@ export async function main(opts = {}) {
             process.exit(130);
         controller.abort(new Error('interrupted'));
     });
+    for (const name of ['SIGTERM', 'SIGHUP'])
+        process.once(name, () => controller.abort(new Error(name)));
+    // A reader that closed its end (ssh after a ProxyCommand session, `| head`) has nothing left to receive.
+    for (const stream of [process.stdout, process.stderr])
+        stream.on('error', (e) => { if (e.code !== 'EPIPE')
+            throw e; });
     const flush = (stream) => new Promise((resolve) => stream.write('', () => resolve()));
     const runtime = { node: process.execPath, script: process.argv[1] ?? '' };
     // The menu bar's update button runs this shard; it finds it here (macOS only, written when it changes).

package/dist/project-sync.d.ts

@@ -35,4 +35,8 @@ export declare function projectReconciler(options: {
     report: (message: string) => void;
     signal?: AbortSignal;
 }): () => Promise<void>;
-export declare function startProjectSync(ctx: Ctx, ws: Workspace, project: ReturnType<typeof projectIdentity>): Promise<ProjectSync>;
+export declare function startProjectSync(ctx: Ctx, ws: Workspace, project: ReturnType<typeof projectIdentity>, options?: {
+    root?: string;
+    agent?: string;
+    seed?: boolean;
+}): Promise<ProjectSync>;

package/dist/project-sync.js

@@ -111,13 +111,14 @@ export function projectReconciler(options) {
     };
     return () => { const next = serial.then(run); serial = next.catch(() => undefined); return next; };
 }
-export async function startProjectSync(ctx, ws, project) {
-    if (ws.labels.agent && ws.labels.agent !== 'main')
-        throw new Error('two-way project sync is only available for the main agent');
-    const root = projectWorkspacePath(project);
+export async function startProjectSync(ctx, ws, project, options = {}) {
+    if (!options.root && ws.labels.agent && ws.labels.agent !== 'main')
+        throw new Error('two-way project sync requires a conversation worktree');
+    const root = options.root ?? projectWorkspacePath(project);
     const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
     await cell.files.mkdir(root, { parents: true });
-    await seedAgentRepository(ctx, ws, project.folder, { root });
+    if (options.seed !== false)
+        await seedAgentRepository(ctx, ws, project.folder, { root });
     const store = new AgentStateStore(ctx.store.dir);
     const key = `${ws.id}:${project.folder}`;
     const states = store.read().project_sync;
@@ -130,7 +131,7 @@ export async function startProjectSync(ctx, ws, project) {
         });
     };
     const report = (message) => { ctx.io.stderr.write(`${message}\n`); };
-    const reconcile = projectReconciler({ folder: project.folder, root, agent: ws.labels.agent ?? 'main', cell, state, save, report, signal: ctx.signal });
+    const reconcile = projectReconciler({ folder: project.folder, root, agent: options.agent ?? ws.labels.agent ?? 'main', cell, state, save, report, signal: ctx.signal });
     const abort = new AbortController();
     const signal = ctx.signal ? AbortSignal.any([ctx.signal, abort.signal]) : abort.signal;
     let stopped = false, dirty = false;

package/dist/t3-provider.d.ts

@@ -0,0 +1,6 @@
+/** Every shard invocation registers the one installed T3 provider without adding terminal noise. */
+export declare function registerInstalledT3(env: Record<string, string | undefined>, dir: string, signal?: AbortSignal): Promise<void>;
+/** A version number alone is insufficient: the installed 0.0.45 desktop lacks the upstream ACP driver. */
+export declare function t3BundleSupportsAcp(app: string): boolean;
+/** Desktop 0.0.45 watches this server settings file, including symlink targets. No encrypted stores. */
+export declare function configureT3Provider(env: Record<string, string | undefined>, dir: string, remove?: boolean, signal?: AbortSignal): Promise<boolean>;

package/dist/t3-provider.js

@@ -0,0 +1,99 @@
+import { readFileSync, realpathSync, openSync, readSync, closeSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { writePrivateFile } from "./credentials.js";
+import { withTargetLock } from "./target-lock.js";
+import { installedTargets } from "./agent-targets.js";
+const ID = 'shardflux';
+const provider = { driver: 'acpRegistry', displayName: 'Shardflux', enabled: true, config: { source: 'local', commandPath: 'shard', commandArgs: ['acp'] } };
+const support = new Map();
+/** Every shard invocation registers the one installed T3 provider without adding terminal noise. */
+export async function registerInstalledT3(env, dir, signal) {
+    if (process.platform !== 'darwin')
+        return;
+    if (!installedTargets(env).targets.includes('t3'))
+        return;
+    try {
+        await configureT3Provider(env, dir, false, signal);
+    }
+    catch { /* User-owned malformed or conflicting settings stay intact. */ }
+}
+/** A version number alone is insufficient: the installed 0.0.45 desktop lacks the upstream ACP driver. */
+export function t3BundleSupportsAcp(app) {
+    const archive = join(app, 'Contents/Resources/app.asar');
+    let fd;
+    try {
+        const stat = statSync(archive), stamp = `${stat.size}:${stat.mtimeMs}`;
+        if (support.get(archive)?.stamp === stamp)
+            return support.get(archive).capable;
+        fd = openSync(archive, 'r');
+        const sizes = Buffer.alloc(16);
+        if (readSync(fd, sizes, 0, 16, 0) !== 16)
+            return false;
+        const headerSize = sizes.readUInt32LE(12);
+        if (headerSize < 1 || headerSize > 16 << 20)
+            return false;
+        const header = Buffer.alloc(headerSize);
+        if (readSync(fd, header, 0, headerSize, 16) !== headerSize)
+            return false;
+        let entry = JSON.parse(header.toString());
+        for (const part of ['apps', 'server', 'dist', 'bin.mjs']) {
+            const child = entry.files?.[part];
+            if (!child)
+                return false;
+            entry = child;
+        }
+        const size = entry.size, offset = Number(entry.offset) + 8 + sizes.readUInt32LE(4);
+        if (!Number.isSafeInteger(size) || !size || size < 1 || size > 64 << 20 || !Number.isSafeInteger(offset) || offset < 16 || offset + size > stat.size)
+            return false;
+        const bytes = entry.unpacked ? readFileSync(join(`${archive}.unpacked`, 'apps/server/dist/bin.mjs')) : Buffer.alloc(size);
+        if (!entry.unpacked && readSync(fd, bytes, 0, size, offset) !== size)
+            return false;
+        const capable = /ProviderDriverKind\.make\(["']acpRegistry["']\)/.test(bytes.toString());
+        support.set(archive, { stamp, capable });
+        return capable;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/** Desktop 0.0.45 watches this server settings file, including symlink targets. No encrypted stores. */
+export async function configureT3Provider(env, dir, remove = false, signal) {
+    return withTargetLock(dir, () => {
+        let file = join(env.T3CODE_HOME || join(env.HOME || homedir(), '.t3'), 'userdata', 'settings.json');
+        let raw = '{}';
+        try {
+            file = realpathSync(file);
+            raw = readFileSync(file, 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            throw new Error('T3 settings must be an object');
+        const doc = parsed;
+        if (doc.providerInstances !== undefined && (!doc.providerInstances || typeof doc.providerInstances !== 'object' || Array.isArray(doc.providerInstances)))
+            throw new Error('T3 providers must be an object');
+        const instances = doc.providerInstances ?? {};
+        const existing = instances[ID];
+        // A user-owned instance with this ID is never silently replaced or removed.
+        if (existing && !(existing.driver === provider.driver && existing.config?.source === 'local' && existing.config.commandPath === 'shard' && JSON.stringify(existing.config.commandArgs) === '["acp"]'))
+            throw new Error('T3 already has a different provider named shardflux');
+        const desired = existing ? { ...existing, config: { ...existing.config, ...provider.config } } : provider;
+        if (remove ? !existing : JSON.stringify(existing) === JSON.stringify(desired))
+            return false;
+        if (remove)
+            delete instances[ID];
+        else
+            instances[ID] = desired;
+        doc.providerInstances = instances;
+        writePrivateFile(dirname(file), file, JSON.stringify(doc, null, 2) + '\n');
+        return true;
+    }, signal);
+}

package/dist/t3-runtime.d.ts

@@ -0,0 +1,6 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+/** T3 v0.0.45 packages/ssh/src/tunnel.ts: identical cache, archive, checksum and completion marker. */
+export declare function t3InstallScript(version: string): string;
+/** Start a supervised guest exec session; only launch is awaited, never download or extraction. */
+export declare function prewarmT3(ctx: Ctx, ws: Workspace, version: string): Promise<void>;

package/dist/t3-runtime.js

@@ -0,0 +1,63 @@
+/** T3 v0.0.45 packages/ssh/src/tunnel.ts: identical cache, archive, checksum and completion marker. */
+export function t3InstallScript(version) {
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version))
+        throw new Error('T3 requires an exact release version');
+    return `set -eu
+T3_ARCHIVE_VERSION='${version}'
+T3_RUNTIME_DIR="$HOME/.t3/runtime/versions/$T3_ARCHIVE_VERSION"
+t3_runtime_ready() {
+  [ -x "$T3_RUNTIME_DIR/t3" ] && [ "$(cat "$T3_RUNTIME_DIR/.install-complete" 2>/dev/null)" = "$T3_ARCHIVE_VERSION" ]
+}
+t3_runtime_ready && exit 0
+mkdir -p "$HOME/.t3/runtime/versions"
+T3_LOCK="$HOME/.t3/runtime/versions/.$T3_ARCHIVE_VERSION.install.lock"
+# A prewarm never waits for T3 or another prewarm. T3's own launcher joins a live installer.
+if ! mkdir "$T3_LOCK" 2>/dev/null; then
+  T3_LOCK_OWNER="$(cat "$T3_LOCK/pid" 2>/dev/null || true)"
+  case "$T3_LOCK_OWNER" in ''|*[!0-9]*) exit 0 ;; esac
+  if kill -0 "$T3_LOCK_OWNER" 2>/dev/null; then exit 0; fi
+  rm -rf "$T3_LOCK"
+  mkdir "$T3_LOCK" 2>/dev/null || exit 0
+fi
+trap 'rm -rf "$T3_LOCK"' EXIT
+printf '%s\\n' "$$" > "$T3_LOCK/pid.tmp"
+mv "$T3_LOCK/pid.tmp" "$T3_LOCK/pid"
+t3_runtime_ready && exit 0
+case "$(uname -s)" in Linux) T3_PLATFORM=linux ;; Darwin) T3_PLATFORM=darwin ;; *) exit 1 ;; esac
+case "$(uname -m)" in arm64|aarch64) T3_ARCH=arm64 ;; x86_64|amd64) T3_ARCH=x64 ;; *) exit 1 ;; esac
+T3_ARCHIVE="t3-$T3_ARCHIVE_VERSION-$T3_PLATFORM-$T3_ARCH.tar.gz"
+T3_STAGING="$(mktemp -d "$HOME/.t3/runtime/versions/.staging-XXXXXX")"
+trap 'rm -rf "$T3_STAGING" "$T3_LOCK"' EXIT
+T3_RELEASE_BASE_URL=https://github.com/pingdotgg/t3code/releases/download
+t3_fetch() {
+  if command -v curl >/dev/null 2>&1; then curl -fsSL --connect-timeout 30 --max-time "$3" "$1" -o "$2"
+  elif command -v wget >/dev/null 2>&1; then wget -q --timeout=30 --tries=1 "$1" -O "$2"
+  else exit 1
+  fi
+}
+t3_fetch "$T3_RELEASE_BASE_URL/v$T3_ARCHIVE_VERSION/SHA256SUMS" "$T3_STAGING/SHA256SUMS" 30
+t3_fetch "$T3_RELEASE_BASE_URL/v$T3_ARCHIVE_VERSION/$T3_ARCHIVE" "$T3_STAGING/$T3_ARCHIVE" 240
+T3_EXPECTED="$(grep " \\*\\{0,1\\}$T3_ARCHIVE$" "$T3_STAGING/SHA256SUMS" | cut -d' ' -f1)"
+if command -v sha256sum >/dev/null 2>&1; then
+  T3_ACTUAL="$(sha256sum "$T3_STAGING/$T3_ARCHIVE" | cut -d' ' -f1)"
+else
+  T3_ACTUAL="$(shasum -a 256 "$T3_STAGING/$T3_ARCHIVE" | cut -d' ' -f1)"
+fi
+if [ -z "$T3_EXPECTED" ] || [ "$T3_ACTUAL" != "$T3_EXPECTED" ]; then
+  printf 'Checksum mismatch for %s.\\n' "$T3_ARCHIVE" >&2; exit 1
+fi
+tar -xzf "$T3_STAGING/$T3_ARCHIVE" -C "$T3_STAGING" --strip-components=1
+rm -f "$T3_STAGING/$T3_ARCHIVE" "$T3_STAGING/SHA256SUMS"
+"$T3_STAGING/t3" --version >/dev/null 2>&1
+printf '%s\\n' "$T3_ARCHIVE_VERSION" > "$T3_STAGING/.install-complete"
+rm -rf "$T3_RUNTIME_DIR"
+mv "$T3_STAGING" "$T3_RUNTIME_DIR"
+`;
+}
+/** Start a supervised guest exec session; only launch is awaited, never download or extraction. */
+export async function prewarmT3(ctx, ws, version) {
+    const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+    const session = await cell.exec.start({ argv: ['sh', '-c', t3InstallScript(version)], user: 'user', timeout_ms: 300_000 }, ctx.signal);
+    if (session.state === 'failed_to_start')
+        throw new Error('T3 runtime prewarm could not start');
+}

package/dist/target-lock.d.ts

@@ -0,0 +1,3 @@
+/** PID ownership is published atomically. A kernel connection wakes waiters on
+ * release or process death, including SIGKILL; there is no polling or deadline. */
+export declare function withTargetLock<T>(dir: string, work: () => T, signal?: AbortSignal): Promise<T>;

package/dist/target-lock.js

@@ -0,0 +1,143 @@
+import { randomUUID } from 'node:crypto';
+import { once } from 'node:events';
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
+import { createConnection, createServer } from 'node:net';
+import { join } from 'node:path';
+const missing = (e) => e.code === 'ENOENT';
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        if (e.code === 'ESRCH')
+            return false;
+        throw e;
+    }
+}
+function removeOwner(lock, name) {
+    // A contender can only remove this owner's unique record. rmdir is atomic
+    // and refuses a replacement owner's nonempty directory.
+    rmSync(join(lock, name), { force: true });
+    try {
+        rmdirSync(lock);
+    }
+    catch (e) {
+        if (!missing(e) && !['ENOTEMPTY', 'EEXIST'].includes(e.code ?? ''))
+            throw e;
+    }
+}
+async function waitForOwner(owner, signal) {
+    signal?.throwIfAborted();
+    await new Promise((resolve, reject) => {
+        const socket = createConnection({ host: '127.0.0.1', port: owner.port });
+        let identity = '';
+        const finish = (error) => {
+            signal?.removeEventListener('abort', abort);
+            socket.destroy();
+            if (error)
+                reject(error instanceof Error ? error : new Error('target update aborted', { cause: error }));
+            else
+                resolve();
+        };
+        const abort = () => finish(signal?.reason ?? new Error('target update aborted'));
+        signal?.addEventListener('abort', abort, { once: true });
+        socket.on('data', bytes => {
+            identity += String(bytes);
+            if (!`${owner.token}\n`.startsWith(identity))
+                finish(new Error('target lock owner identity changed'));
+        });
+        socket.once('end', () => finish());
+        socket.once('error', error => { if (['ECONNREFUSED', 'ECONNRESET'].includes(error.code ?? ''))
+            finish();
+        else
+            finish(error); });
+        if (signal?.aborted)
+            abort();
+    });
+}
+/** PID ownership is published atomically. A kernel connection wakes waiters on
+ * release or process death, including SIGKILL; there is no polling or deadline. */
+export async function withTargetLock(dir, work, signal) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const token = randomUUID(), name = `owner-${token}.json`;
+    const lock = join(dir, 'targets.lock'), candidate = join(dir, `.targets-lock-${token}`);
+    const peers = new Set();
+    let released = false;
+    const server = createServer(socket => {
+        peers.add(socket);
+        socket.once('close', () => peers.delete(socket));
+        socket.on('error', () => socket.destroy());
+        socket.write(`${token}\n`);
+        if (released)
+            socket.end();
+    });
+    let acquired = false;
+    try {
+        server.listen(0, '127.0.0.1');
+        await once(server, 'listening');
+        mkdirSync(candidate, { mode: 0o700 });
+        writeFileSync(join(candidate, name), JSON.stringify({ pid: process.pid, port: server.address().port, token }), { mode: 0o600 });
+        while (!acquired) {
+            signal?.throwIfAborted();
+            try {
+                renameSync(candidate, lock);
+                acquired = true;
+            }
+            catch (e) {
+                if (!['EEXIST', 'ENOTEMPTY'].includes(e.code ?? ''))
+                    throw e;
+                let names;
+                try {
+                    names = readdirSync(lock);
+                }
+                catch (e) {
+                    if (missing(e))
+                        continue;
+                    throw e;
+                }
+                for (const record of names) {
+                    if (!/^owner-[0-9a-f-]+\.json$/.test(record))
+                        throw new Error('targets.lock has no recoverable owner record', { cause: e });
+                    let owner;
+                    try {
+                        owner = JSON.parse(readFileSync(join(lock, record), 'utf8'));
+                    }
+                    catch (e) {
+                        if (missing(e))
+                            continue;
+                        throw e;
+                    }
+                    if (!Number.isSafeInteger(owner.pid) || owner.pid <= 0 || !Number.isInteger(owner.port) || owner.port < 1 || owner.port > 65535 || record !== `owner-${owner.token}.json`)
+                        throw new Error('invalid targets.lock owner', { cause: e });
+                    if (alive(owner.pid))
+                        await waitForOwner(owner, signal);
+                    removeOwner(lock, record);
+                }
+                if (!names.length) {
+                    try {
+                        rmdirSync(lock);
+                    }
+                    catch (e) {
+                        if (!missing(e) && e.code !== 'ENOTEMPTY')
+                            throw e;
+                    }
+                }
+            }
+        }
+        signal?.throwIfAborted();
+        return await work();
+    }
+    finally {
+        released = true;
+        if (acquired)
+            removeOwner(lock, name);
+        rmSync(candidate, { recursive: true, force: true });
+        const closed = new Promise(resolve => server.close(() => resolve()));
+        // A local peer need not answer our FIN. Do not let an unauthenticated
+        // half-open connection retain this process after its lock is released.
+        for (const peer of peers)
+            peer.destroy();
+        await closed;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.13.6",
+  "version": "0.14.1",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork serverless agent workspaces.",
   "license": "Apache-2.0",
@@ -47,7 +47,7 @@
     "smol-toml": "1.9.0",
     "snappyjs": "0.7.0",
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.18.3"
+    "@shardflux/sdk": "^0.19.1"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
@@ -58,7 +58,7 @@
     "typescript-eslint": "8.70.1"
   },
   "optionalDependencies": {
-    "@shardflux/menubar-darwin": "^0.1.3"
+    "@shardflux/menubar-darwin": "^0.2.0"
   },
   "scripts": {
     "build": "node scripts/build.mjs",