@shardflux/cli 0.17.0 → 0.18.0-next.5

package/dist/t3-mode.js

@@ -3,11 +3,12 @@
  * thread, so the thread is made through T3's own server API, with a short-lived admin session that T3's own CLI
  * issues and revokes, and T3 is brought to the front.
  *
- * - **ACP mode** (a T3 build with ACP providers, 0.0.46+): T3's server runs on this Mac and Shardflux is one of its
- *   providers (`shard acp`, registered by every `shard` run). The thread is launched on the running desktop server
- *   (`server-runtime.json`) over its WebSocket RPC (`orchestration.launchThread`) with the Shardflux provider, which
- *   then gives the thread its own cloud VM. The session is issued by the T3 server the app bundles
- *   (`ELECTRON_RUN_AS_NODE=1 <app>/Contents/MacOS/<exe> <app.asar>/apps/server/dist/bin.mjs auth session issue`).
+ * - **ACP mode** (a T3 build with ACP providers, 0.0.46+): T3's server runs on this computer (macOS or Linux) and
+ *   Shardflux is one of its providers (`shard acp`, registered by every `shard` run). The thread is launched on the
+ *   running desktop server (`server-runtime.json`) over its WebSocket RPC (`orchestration.launchThread`) with the
+ *   Shardflux provider, which then gives the thread its own cloud VM. The session is issued by the T3 server the app
+ *   bundles (`ELECTRON_RUN_AS_NODE=1 <app>/Contents/MacOS/<exe> <app.asar>/apps/server/dist/bin.mjs auth session
+ *   issue`; on Linux the app's `t3code` with its `resources/app.asar`, or T3's own `~/.t3/bin/t3` for an AppImage).
  * - **SSH mode** (stable 0.0.45): T3's server runs in the project VM. `T3_THREAD_SCRIPT` runs there and dispatches
  *   `thread.create` and `thread.turn.start` over loopback (POST /api/orchestration/dispatch).
  *
@@ -19,13 +20,13 @@ import { spawn, spawnSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { readFileSync, realpathSync } from 'node:fs';
 import { writePrivateFile } from "./credentials.js";
-import { homedir } from 'node:os';
 import { basename, join } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
 import { CodedError, UsageError, describeError } from "./errors.js";
 import { AgentStateStore } from "./agent-state.js";
 import { applicationDirs, desktopAppPath, t3Apps } from "./agent-targets.js";
-import { configureT3Provider, t3BundleSupportsAcp } from "./t3-provider.js";
+import { configureT3Provider, t3BundleSupportsAcp, t3HomeDir } from "./t3-provider.js";
+import { linuxLastUsed, linuxServerCli, linuxSupportsAcp, openLinuxT3 } from "./t3-linux.js";
 import { acpSignedIn } from "./acp-login.js";
 import { AcpModelCache } from "./acp-models.js";
 import { nativeModelOptions } from "./acp-catalog.js";
@@ -36,6 +37,7 @@ import { uploadInitialImages } from "./initial-prompt.js";
 export const T3_BUNDLE_ID = 'com.t3tools.t3code';
 /** Where each app's new conversations can open: Claude in a terminal, Claude Desktop, claude.ai or T3; Codex in the Codex app or T3. */
 export const OPEN_IN_TARGETS = { claude: ['terminal', 'claude-desktop', 'web', 't3'], codex: ['codex-app', 't3'] };
+export const openInTargets = (app, platform = process.platform) => platform === 'linux' && app === 'codex' ? ['terminal', 't3'] : OPEN_IN_TARGETS[app];
 /** T3 0.0.45's built-in defaults (DEFAULT_MODEL_BY_PROVIDER), used only when T3 in the VM has not described its models yet. */
 const T3_DEFAULT_MODEL = { claude: 'claude-fable-5-1', codex: 'gpt-6-astra' };
 const T3_START_WAIT_MS = 30_000;
@@ -46,11 +48,16 @@ const isoDate = (raw) => {
     const parsed = SPOTLIGHT_DATE.test(raw) ? new Date(raw.replace(' ', 'T').replace(' ', '')) : null;
     return parsed && !Number.isNaN(parsed.getTime()) ? parsed.toISOString() : null;
 };
-/** Native lookups that tests replace: Spotlight's last-used dates of app bundles, one `mdls` for all of them. */
+/**
+ * Native lookups that tests replace: Spotlight's last-used dates of app bundles, one `mdls` for all of them (macOS), or
+ * when each program last started, from its access time (Linux, t3-linux.ts).
+ */
 export const t3Native = {
-    lastUsedMany(paths, env) {
+    lastUsedMany(paths, env, platform = process.platform) {
         if (!paths.length)
             return {};
+        if (platform !== 'darwin')
+            return Object.fromEntries(paths.map(path => [path, linuxLastUsed(path)]));
         const r = spawnSync('mdls', ['-name', 'kMDItemLastUsedDate', '-raw', ...paths], { env, encoding: 'utf8', input: '', timeout: 3000 });
         // -raw separates the values with NUL; a bundle Spotlight has no date for prints "(null)".
         const values = r.status === 0 ? r.stdout.split('\0').map(v => v.trim()) : [];
@@ -76,16 +83,16 @@ export function lastUsedDates(ctx, paths, now = Date.now()) {
     catch { /* a cache only */ }
     return dates;
 }
+/** Whether an installed T3 runs the Shardflux provider: its server has the ACP Registry driver (t3-asar.ts, t3-linux.ts). */
+const supportsAcp = (app) => app.linux ? linuxSupportsAcp({ ...app, linux: app.linux }) : t3BundleSupportsAcp(app.path);
 /** The installed T3 Code, preferring a build with ACP providers when several channels are installed. */
-export function t3Install(env, platform = process.platform) {
-    const apps = t3Apps(applicationDirs(env), platform);
-    const acp = apps.find(app => t3BundleSupportsAcp(app.path));
+export function t3Install(env, platform = process.platform, dirs = applicationDirs(env, platform)) {
+    const apps = t3Apps(dirs, platform, env);
+    const acp = apps.find(supportsAcp);
     const app = acp ?? apps[0];
-    return app ? { path: app.path, version: app.version, mode: acp ? 'acp' : 'ssh' } : undefined;
-}
-export function t3HomeDir(env) {
-    return env.T3CODE_HOME || join(env.HOME || homedir(), '.t3');
+    return app ? { path: app.path, version: app.version, mode: acp ? 'acp' : 'ssh', ...(app.linux ? { linux: app.linux } : {}) } : undefined;
 }
+export { t3HomeDir };
 /** The Shardflux provider instance in T3's server settings (read only; every `shard` run writes it, see t3-provider.ts). */
 export function t3ProviderRegistered(env) {
     try {
@@ -137,7 +144,7 @@ export function openInFor(ctx, project, known = {}) {
     const claudeDesktop = () => known.clients ? known.clients.includes('claude-desktop') : desktopAppPath(dirs, 'Claude.app', 'com.anthropic.claudefordesktop') !== undefined;
     const valid = (app) => {
         const value = saved[app];
-        if (typeof value !== 'string' || !OPEN_IN_TARGETS[app].includes(value))
+        if (typeof value !== 'string' || !openInTargets(app).includes(value))
             return undefined;
         return value === 't3' ? (t3() ? value : undefined) : value === 'claude-desktop' ? (claudeDesktop() ? value : undefined) : value;
     };
@@ -171,8 +178,8 @@ export function saveOpenIn(ctx, spec, status, clients) {
         const [app, target, extra] = part.split('=').map(s => s.trim());
         if (app !== 'claude' && app !== 'codex' || !target || extra !== undefined)
             throw new UsageError('--open-in takes app=target pairs, e.g. claude=t3,codex=t3.');
-        if (!OPEN_IN_TARGETS[app].includes(target))
-            throw new UsageError(`--open-in: ${app} opens in ${OPEN_IN_TARGETS[app].join(', ')}.`);
+        if (!openInTargets(app).includes(target))
+            throw new UsageError(`--open-in: ${app} opens in ${openInTargets(app).join(', ')}.`);
         if (target === 't3' && !status.installed)
             throw t3NotInstalled();
         if (!available(target, status, clients))
@@ -203,11 +210,16 @@ export function t3ThreadTitle(prompt) {
     return line.length > 80 ? `${line.slice(0, 79).trimEnd()}…` : line;
 }
 /**
- * Opens T3 Code (or brings it to the front): the install `shard` chose (`open -a <path>`). Every T3 channel shares one
- * bundle id, so `open -b` could start another installed channel.
+ * Opens T3 Code (or brings it to the front): the install `shard` chose. On macOS `open -a <path>` (every T3 channel
+ * shares one bundle id, so `open -b` could start another installed channel); on Linux its desktop entry with
+ * `gtk-launch`, else its program (t3-linux.ts).
  */
-export async function openT3(env, appPath) {
-    const child = spawn('open', ['-a', appPath], { env, stdio: 'ignore' });
+export async function openT3(env, install) {
+    if (!install)
+        throw t3NotInstalled();
+    if (install.linux)
+        return openLinuxT3(env, { path: install.path, version: install.version, linux: install.linux });
+    const child = spawn('open', ['-a', install.path], { env, stdio: 'ignore' });
     await new Promise((resolve, reject) => {
         const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('T3 Code did not open in time')); }, 10_000);
         child.once('error', e => { clearTimeout(timer); reject(e); });
@@ -307,7 +319,7 @@ export async function localT3Server(ctx, install, waitMs = T3_START_WAIT_MS) {
     const found = await runningServer(base, ctx.signal);
     if (found)
         return found;
-    await openT3(ctx.io.env, install.path);
+    await openT3(ctx.io.env, install);
     const deadline = Date.now() + waitMs;
     while (Date.now() < deadline) {
         await delay(500, undefined, { signal: ctx.signal });
@@ -317,7 +329,17 @@ export async function localT3Server(ctx, install, waitMs = T3_START_WAIT_MS) {
     }
     throw t3Unreachable(`T3 Code’s server did not answer within ${Math.round(waitMs / 1000)} s.`);
 }
-function serverCli(install) {
+/**
+ * The server CLI the app bundles: on macOS the bundle's executable with `<app.asar>/apps/server/dist/bin.mjs`; on Linux
+ * the app's own executable the same way, or for an AppImage T3's own launcher (linuxServerCli).
+ */
+function serverCli(install, env) {
+    if (install.linux) {
+        const cli = linuxServerCli({ path: install.path, version: install.version, linux: install.linux }, t3HomeDir(env));
+        if (!cli)
+            throw t3Unreachable(`T3 Code has not written its command line launcher (${join(t3HomeDir(env), 'bin', 't3')}) yet.`, 'Open T3 Code once, then run this again.');
+        return cli;
+    }
     const r = spawnSync('/usr/libexec/PlistBuddy', ['-c', 'Print :CFBundleExecutable', join(install.path, 'Contents', 'Info.plist')], { encoding: 'utf8', input: '', timeout: 2000 });
     const exe = r.status === 0 ? r.stdout.trim() : '';
     if (!exe || exe.includes('/'))
@@ -326,7 +348,7 @@ function serverCli(install) {
 }
 /** Runs the T3 server CLI the app bundles (Electron as Node), the same code the desktop runs as its backend. */
 function t3Cli(ctx, install, args) {
-    const cli = serverCli(install);
+    const cli = serverCli(install, ctx.io.env);
     return new Promise((resolve, reject) => {
         const child = spawn(cli.command, [...cli.args, ...args], { env: { ...ctx.io.env, ELECTRON_RUN_AS_NODE: '1' }, stdio: ['ignore', 'pipe', 'pipe'], signal: ctx.signal });
         let stdout = '', stderr = '';
@@ -601,7 +623,7 @@ export async function startAcpThread(ctx, install, folder, request, waitMs = CON
         const id = objectValue(launched).threadId;
         const t3ThreadId = typeof id === 'string' ? id : threadId;
         // The thread exists from here on: T3 comes to the front first, and a failure after this names the thread.
-        const opened = await openT3(ctx.io.env, install.path).then(() => undefined, (error) => error);
+        const opened = await openT3(ctx.io.env, install).then(() => undefined, (error) => error);
         let conversation = null;
         try {
             conversation = await threadConversation(ctx, server, session, t3ThreadId, realpathSync(folder), known, waitMs);

package/dist/t3-provider.d.ts

@@ -1,6 +1,8 @@
-/** 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. */
+/** Every shard invocation registers the one installed T3 provider without adding terminal noise (macOS and Linux). */
+export declare function registerInstalledT3(env: Record<string, string | undefined>, dir: string, signal?: AbortSignal, platform?: NodeJS.Platform): Promise<void>;
+/** Whether a macOS T3 bundle's server has the ACP Registry driver (its Contents/Resources/app.asar; see t3-asar.ts). */
 export declare function t3BundleSupportsAcp(app: string): boolean;
+/** T3's home, as the desktop resolves it on macOS and Linux: T3CODE_HOME (trimmed), else ~/.t3. */
+export declare function t3HomeDir(env: Record<string, string | undefined>): string;
 /** 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

@@ -1,70 +1,33 @@
-import { readFileSync, realpathSync, openSync, readSync, closeSync, statSync } from 'node:fs';
+import { readFileSync, realpathSync } 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";
+import { t3ArchiveSupportsAcp } from "./t3-asar.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'))
+/** Every shard invocation registers the one installed T3 provider without adding terminal noise (macOS and Linux). */
+export async function registerInstalledT3(env, dir, signal, platform = process.platform) {
+    if (!installedTargets(env, platform).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. */
+/** Whether a macOS T3 bundle's server has the ACP Registry driver (its Contents/Resources/app.asar; see t3-asar.ts). */
 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);
-    }
+    return t3ArchiveSupportsAcp(join(app, 'Contents/Resources/app.asar'));
+}
+/** T3's home, as the desktop resolves it on macOS and Linux: T3CODE_HOME (trimmed), else ~/.t3. */
+export function t3HomeDir(env) {
+    return env.T3CODE_HOME?.trim() || join(env.HOME || homedir(), '.t3');
 }
 /** 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 file = join(t3HomeDir(env), 'userdata', 'settings.json');
         let raw = '{}';
         try {
             file = realpathSync(file);

package/dist/update.js

@@ -264,6 +264,22 @@ export async function update(ctx, values, deps = {}) {
  * runs the code from before the update).
  */
 async function refreshMenubar(ctx, menubar, runtime, run, env) {
+    if (menubar.platform === 'linux') {
+        const { LinuxDesktopManager } = await import("./desktop-linux.js");
+        const desktop = new LinuxDesktopManager({ home: ctx.io.env.HOME, env: ctx.io.env });
+        const before = await desktop.status(ctx.store.dir);
+        if (!before.installed || new AgentStateStore(ctx.store.dir).read().menubar_stopped === true)
+            return { status: 'off' };
+        if (runtime && run && env) {
+            const result = await run([runtime.node, runtime.script, '--api-url', ctx.apiUrl, 'menubar', 'start', '--json'], { ...env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_NO_UPDATE_CHECK: '1' }, ctx.signal);
+            if (result.code !== 0)
+                return { status: 'failed' };
+        }
+        else
+            await desktop.start(ctx.store.dir, ctx.apiUrl);
+        const after = await desktop.status(ctx.store.dir);
+        return after.version !== before.version ? { status: 'restarted', version: after.version } : { status: 'current' };
+    }
     if (menubar.platform !== 'darwin')
         return { status: 'off' };
     if (new AgentStateStore(ctx.store.dir).read().menubar_stopped === true)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.17.0",
+  "version": "0.18.0-next.5",
   "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",
@@ -43,29 +43,17 @@
     "access": "public"
   },
   "dependencies": {
+    "@shardflux/sdk": "0.24.0-next.5",
     "classic-level": "3.0.0",
     "smol-toml": "1.9.0",
     "snappyjs": "0.7.0",
-    "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.23.0"
-  },
-  "devDependencies": {
-    "@eslint/js": "10.0.1",
-    "@types/node": "24.13.6",
-    "eslint": "10.11.0",
-    "playwright": "1.62.1",
-    "typescript": "5.9.3",
-    "typescript-eslint": "8.70.1"
+    "yaml": "2.9.1"
   },
   "optionalDependencies": {
-    "@shardflux/menubar-darwin": "^0.5.0"
-  },
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "eslint .",
-    "test": "node --test test/*.test.ts"
+    "@shardflux/menubar-darwin": "^0.5.0",
+    "@shardflux/desktop-linux-x64": "0.1.0-next.5",
+    "@shardflux/desktop-linux-arm64": "0.1.0-next.5"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts"
-}
+}