@shardflux/cli 0.16.0 → 0.17.0

package/dist/linux-helper.js

@@ -0,0 +1,88 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { CLI_VERSION } from "./args.js";
+import { writePrivateFile } from "./credentials.js";
+import { runDeviceHelper } from "./device-helper.js";
+export const HELPER_UNIT = 'shardflux-helper.service';
+export const helperUnitPath = (home) => join(home, '.config/systemd/user', HELPER_UNIT);
+const quote = (s) => '"' + s.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%').replaceAll('\n', '\\n').replaceAll('\r', '\\r') + '"';
+/** No credentials in the unit: the helper reads the same private store as shard. */
+export function helperUnit(ctx) {
+    if (!ctx.runtime)
+        throw new Error('An installed shard is required.');
+    let script = ctx.runtime.script;
+    try {
+        script = realpathSync(script);
+    }
+    catch { /* preserve the supplied installed path */ }
+    const env = { HOME: ctx.io.env.HOME, PATH: ctx.io.env.PATH ?? '/usr/local/bin:/usr/bin:/bin', SHARDFLUX_CONFIG_DIR: ctx.store.dir,
+        SHARDFLUX_API_URL: ctx.apiUrl, SHARDFLUX_NO_UPDATE_CHECK: '1',
+        ...Object.fromEntries(['DISPLAY', 'WAYLAND_DISPLAY', 'DBUS_SESSION_BUS_ADDRESS', 'XDG_RUNTIME_DIR', 'CODEX_HOME', 'CLAUDE_CONFIG_DIR'].flatMap(k => ctx.io.env[k] ? [[k, ctx.io.env[k]]] : [])) };
+    return `# Shardflux CLI ${CLI_VERSION}\n[Unit]\nDescription=Shardflux background helper\nAfter=network-online.target\n\n[Service]\nType=simple\nExecStart=${[ctx.runtime.node, script, 'device-helper', '--service'].map(s => quote(s.replaceAll('$', '$$'))).join(' ')}\n${Object.entries(env).map(([k, v]) => `Environment=${quote(`${k}=${v}`)}`).join('\n')}\nRestart=on-failure\nRestartSec=5\nTimeoutStopSec=10\nUMask=0077\n\n[Install]\nWantedBy=default.target\n`;
+}
+export function installLinuxHelper(ctx, deps = {}) {
+    if ((deps.platform ?? process.platform) !== 'linux' || !ctx.runtime || !ctx.io.env.HOME)
+        return false;
+    const run = deps.run ?? (args => spawnSync('systemctl', ['--user', ...args], { env: ctx.io.env, stdio: 'ignore', timeout: 5000 }).status === 0);
+    // Probe before writing: containers without a user manager use the command-lifetime helper.
+    if (!run(['show-environment']))
+        return false;
+    const file = helperUnitPath(ctx.io.env.HOME), text = helperUnit(ctx);
+    const receipt = join(ctx.store.dir, 'linux-helper-started'), digest = createHash('sha256').update(text).digest('hex');
+    let before = '', started = '';
+    try {
+        before = readFileSync(file, 'utf8');
+    }
+    catch { /* first sign-in */ }
+    try {
+        started = readFileSync(receipt, 'utf8');
+    }
+    catch { /* no successful start yet */ }
+    if (before !== text) {
+        writePrivateFile(dirname(file), file, text);
+        if (!run(['daemon-reload']) || !run(['enable', '--now', HELPER_UNIT]))
+            return false;
+        if (before && !run(['restart', HELPER_UNIT]))
+            return false;
+    }
+    else if (!run(['is-active', '--quiet', HELPER_UNIT])) {
+        if (!run(['enable', '--now', HELPER_UNIT]))
+            return false;
+    }
+    else if (started !== digest && !run(['restart', HELPER_UNIT]))
+        return false;
+    // A failed restart must be retried by the next command even though the new unit was already written.
+    if (started !== digest)
+        writePrivateFile(ctx.store.dir, receipt, digest);
+    return true;
+}
+/** The caller owns fallback lifetime; never leave an unmanaged background process behind. */
+export function startLinuxHelper(ctx) {
+    const noop = () => Promise.resolve();
+    if (process.platform !== 'linux' || !ctx.runtime)
+        return noop;
+    try {
+        ctx.apiKey();
+    }
+    catch {
+        return noop;
+    }
+    try {
+        if (installLinuxHelper(ctx))
+            return noop;
+    }
+    catch { /* use the command-lifetime helper */ }
+    const notice = join(ctx.store.dir, 'linux-helper-notice');
+    try {
+        readFileSync(notice);
+    }
+    catch {
+        ctx.io.stderr.write('Shardflux helper runs while shard commands are open on this computer.\n');
+        writePrivateFile(ctx.store.dir, notice, '1\n');
+    }
+    const abort = new AbortController();
+    const work = runDeviceHelper({ ...ctx, signal: AbortSignal.any([ctx.signal, abort.signal]) }, { service: true }).catch(() => undefined);
+    return async () => { abort.abort(); await work; };
+}

package/dist/linux-terminal.d.ts

@@ -0,0 +1,11 @@
+import type { Ctx } from './commands.js';
+import type { Values } from './args.js';
+/** Linux terminals use the existing native Codex harness; explicit app routes keep Cloud. */
+export declare function linuxTerminalSession(ctx: Pick<Ctx, 'io' | 'json'>, values: Values, platform?: NodeJS.Platform): boolean;
+export declare const shellWord: (s: string) => string;
+export declare function linuxTerminalCommand(argv: string[], env: Record<string, string | undefined>): {
+    command: string;
+    args: string[];
+} | null;
+/** Invoked before cloud work: the new terminal owns the attach, credentials and any prompts. */
+export declare function openLinuxTerminal(ctx: Ctx, ref: string, app?: string): Promise<number>;

package/dist/linux-terminal.js

@@ -0,0 +1,42 @@
+import { accessSync, constants } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+/** Linux terminals use the existing native Codex harness; explicit app routes keep Cloud. */
+export function linuxTerminalSession(ctx, values, platform = process.platform) {
+    return platform === 'linux' && (values.in === 'terminal' || (values.in === undefined && !!ctx.io.stdin.isTTY && !ctx.json));
+}
+export const shellWord = (s) => `'${s.replaceAll("'", "'\\''")}'`;
+export function linuxTerminalCommand(argv, env) {
+    const executable = (name) => name.includes('/') ? [name] : (env.PATH ?? '').split(':').filter(Boolean).map(p => join(p, name));
+    const exists = (name) => executable(name).some(p => { try {
+        accessSync(p, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    } });
+    // The shell keeps the window open on an attach error so the user can read and retry it.
+    const attach = ['sh', '-c', `${argv.map(shellWord).join(' ')}; status=$?; if [ "$status" -ne 0 ]; then printf '\nPress Enter to close.'; read answer; fi; exit "$status"`];
+    for (const command of [...new Set([env.TERMINAL?.trim(), 'x-terminal-emulator', 'gnome-terminal'].filter((s) => !!s))]) {
+        if (exists(command))
+            return { command, args: [command === 'gnome-terminal' ? '--' : '-e', ...attach] };
+    }
+    return null;
+}
+/** Invoked before cloud work: the new terminal owns the attach, credentials and any prompts. */
+export async function openLinuxTerminal(ctx, ref, app) {
+    const words = ['agents', 'open', ref, '--in', 'terminal', ...(app ? ['--app', app] : [])];
+    const argv = ctx.runtime ? [ctx.runtime.node, ctx.runtime.script, '--api-url', ctx.apiUrl, ...words] : ['shard', ...words];
+    const choice = linuxTerminalCommand(argv, ctx.io.env);
+    if (choice) {
+        const child = spawn(choice.command, choice.args, { env: ctx.io.env, cwd: process.cwd(), detached: true, stdio: 'ignore' });
+        try {
+            await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+            child.unref();
+            return 0;
+        }
+        catch { /* print a runnable command if the terminal could not start */ }
+    }
+    ctx.io.stdout.write(`${['shard', '--api-url', ctx.apiUrl, ...words].map(shellWord).join(' ')}\n`);
+    return 0;
+}

package/dist/main.js

@@ -13,12 +13,15 @@
 import { homedir, hostname } from 'node:os';
 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 { CLI_VERSION, CENTER_COMMAND, ONBOARDING_COMMAND, PROJECT_COMMAND, commandHelp, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
 import { commandCenter } from "./command-center.js";
-import { launchConversationProject } from "./conversation-terminal.js";
+import { launchProjectCommand } from "./conversation-terminal.js";
 import { runAcp } from "./acp.js";
 import { registerInstalledT3 } from "./t3-provider.js";
+import { refreshForwarderAgent } from "./cli-proxy.js";
 import { runAcpLogin } from "./acp-login.js";
+import { terminalOnboarding } from "./terminal-onboarding.js";
+import { startLinuxHelper } from "./linux-helper.js";
 import { runDeviceHelper } from "./device-helper.js";
 import { housekeeping, startupHousekeeping } from "./agent-git-commands.js";
 import { CredentialStore, configDir } from "./credentials.js";
@@ -660,7 +663,7 @@ export async function run(argv, io, opts = {}) {
             refreshMenubarInBackground({ dir: store.dir, home: io.env.HOME || homedir(), runtime: opts.runtime, env: { ...process.env, ...io.env } });
         }
         // The update check runs next to the command (not for `version`, which reports it itself).
-        if (!updateCheckDisabled(io.env) && !['version', 'update', 'ssh-proxy', 'acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh') {
+        if (!updateCheckDisabled(io.env) && !['version', 'update', 'ssh-proxy', 'acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh' && command !== 'cli-proxy forward') {
             try {
                 updates = new UpdateCheck({ dir: store.dir, apiUrl, distribution, fetch: base, userAgent, registry: npmRegistry(io.env) });
                 updates.start();
@@ -673,11 +676,28 @@ export async function run(argv, io, opts = {}) {
     catch (err) {
         return report(err);
     }
-    const handler = parsed.command.path[0] === 'acp' ? (ctx) => parsed.values.login === true ? runAcpLogin(ctx) : runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? runDeviceHelper : command === 'menubar refresh' ? runMenubarRefresh : parsed.command === PROJECT_COMMAND ? launchConversationProject : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
+    let stopHelper;
+    const startHelper = () => {
+        if (stopHelper)
+            return;
+        try {
+            ctx.apiKey();
+        }
+        catch {
+            return;
+        }
+        stopHelper = startLinuxHelper(ctx);
+    };
+    const handler = parsed.command.path[0] === 'acp' ? (ctx) => parsed.values.login === true ? runAcpLogin(ctx) : runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? (ctx) => runDeviceHelper(ctx, { service: parsed.values.service === true }) : command === 'menubar refresh' ? runMenubarRefresh : parsed.command === PROJECT_COMMAND ? launchProjectCommand : parsed.command === ONBOARDING_COMMAND ? (ctx, values) => terminalOnboarding(ctx, values, { startHelper }) : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
     if (!handler)
         return report(new UsageError(`unknown command "${parsed.command.path.join(' ')}"`));
-    if (!['acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh')
+    // Long-running helpers other programs start (an editor, launchd, the menu bar) skip the per-command housekeeping.
+    if (!['acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh' && command !== 'cli-proxy forward') {
+        // An updated shard restarts this computer's CLIProxyAPI forwarder on itself (a no-op unless the version changed).
+        await refreshForwarderAgent(io.env, ctx.store.dir).catch(() => false);
         await housekeeping(ctx);
+        startHelper();
+    }
     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) => {
@@ -712,6 +732,9 @@ export async function run(argv, io, opts = {}) {
         if (notice)
             io.stderr.write(notice);
     }
+    if (!['acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh' && command !== 'cli-proxy forward')
+        startHelper();
+    await stopHelper?.();
     return code;
 }
 /**
@@ -738,7 +761,7 @@ export async function main(opts = {}) {
     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).
     if (process.platform === 'darwin' && runtime.script)
-        recordInstall(configDir(process.env), runtime, opts.distribution ?? CLI_DISTRIBUTION);
+        recordInstall(configDir(process.env), runtime, opts.distribution ?? CLI_DISTRIBUTION, process.env);
     const code = await run(process.argv.slice(2), { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin, env: process.env }, { signal: controller.signal, runtime, ...(opts.distribution ? { distribution: opts.distribution } : {}) });
     await Promise.all([flush(process.stdout), flush(process.stderr)]);
     process.exit(code);

package/dist/onboarding.d.ts

@@ -26,10 +26,12 @@ type CredentialRow = {
         checked_at: string;
     };
 };
+/** `url`: a page the person opens (the T3 Connect sign-in), instead of a command. */
 type Action = {
     title: string;
     command?: string[];
     retry?: boolean;
+    url?: string;
 };
 export interface Connection {
     id: 'account' | AgentApp | 't3';

package/dist/onboarding.js

@@ -1,7 +1,11 @@
 import { readFile, stat } from 'node:fs/promises';
 import { delimiter, join, resolve, basename } from 'node:path';
 import { homedir } from 'node:os';
+import { ShardfluxApiError } from '@shardflux/sdk';
 import { resolveWorkspace } from "./commands.js";
+import { AgentStateStore } from "./agent-state.js";
+import { describeError } from "./errors.js";
+import { t3PhoneLink } from "./t3-phone.js";
 import { readAgentCredentials, syncAgentCredentials } from "./agent-credentials.js";
 import { getConversation } from "./conversations.js";
 import { codexHealth, readCodexConnector, restartCodexConnector } from "./codex-cloud.js";
@@ -79,15 +83,59 @@ export async function t3Connection(ctx, signedIn, appDirs = applicationDirs(ctx.
             return { ...base, mode: 'provider', state: 'action', fact: error instanceof Error ? error.message : 'T3 Code’s settings could not be updated.', action: { title: 'Check again' } };
         }
     }
-    // Stable T3: an SSH environment per project; the newest one this API set up is the one to add.
+    // Stable T3: an SSH environment per project; the newest one this API set up is the one to add. They are recorded in
+    // agents.json (targets.json keeps T3 out of its manifest); a manifest entry from an older CLI still counts.
+    const recorded = new AgentStateStore(ctx.store.dir).t3Environments(ctx.apiUrl).at(-1);
     const manifest = await jsonFile(join(ctx.store.dir, 'targets.json'));
     const entries = Array.isArray(manifest?.entries) ? manifest.entries : [];
-    const host = entries.filter(e => e.api_url === ctx.apiUrl && Array.isArray(e.targets) && e.targets.includes('t3') && typeof e.host === 'string').map(e => e.host).at(-1);
-    if (host)
-        return { ...base, mode: 'ssh', state: 'verified', fact: `In T3 Code: Add environment → SSH → ${host}` };
+    const legacy = entries.filter(e => e.api_url === ctx.apiUrl && Array.isArray(e.targets) && e.targets.includes('t3') && typeof e.host === 'string').at(-1);
+    const host = recorded?.host ?? legacy?.host;
+    const workspaceKey = recorded?.workspace ?? (typeof legacy?.workspace === 'string' ? legacy.workspace : undefined);
+    if (host) {
+        const desktop = `In T3 Code: Add environment → SSH → ${host}`;
+        const phone = await t3Phone(ctx, workspaceKey);
+        if (!phone)
+            return { ...base, mode: 'ssh', state: 'verified', fact: desktop };
+        return { ...base, mode: 'ssh', ...phone, fact: phone.state === 'verified' ? `${desktop}. On your phone: ${phone.fact}` : phone.fact };
+    }
     // An SSH environment is per project (shardflux-<project>-main): it is set up once a project is picked.
     return { ...base, mode: 'ssh', state: 'info', fact: 'Available after you pick a project.', next: shard(['agents', 'new', '--in', 't3', '--path', '<project>']) };
 }
+/**
+ * The T3 app on the phone (T3 Connect, 0.17.0+): the workspace is linked with the person's one T3 Connect sign-in. The
+ * sign-in is a page to open once; afterwards every project appears in the T3 app by itself. Undefined when the API has
+ * no T3 Connect: the desktop route is the whole card then.
+ */
+async function t3Phone(ctx, key) {
+    if (!key)
+        return undefined;
+    try {
+        const ws = await resolveWorkspace(ctx, key);
+        const cloud = ctx.cloud();
+        const known = (await cloud.t3.status()).links.find(l => l.workspace_id === ws.id);
+        // A workspace connected to T3 before T3 Connect, or one whose link failed, is linked now: it is the person's choice.
+        const { link, signIn, needsLogin } = !known || known.status === 'error' || known.status === 'needs_sign_in'
+            ? await t3PhoneLink(ctx, ws.id) : { link: known, signIn: undefined, needsLogin: false };
+        if (link.status === 'linked')
+            return { state: 'verified', fact: `${link.label} in the T3 app.` };
+        if (signIn) {
+            return { state: 'action', fact: `To use it from the T3 app on your phone, confirm ${signIn.user_code} once.`,
+                action: { title: 'Connect phone', url: signIn.verification_uri } };
+        }
+        if (needsLogin)
+            return { state: 'info', fact: 'Sign in to Shardflux on this Mac to use it from the T3 app.' };
+        return { state: 'pending', fact: `Adding ${link.label} to the T3 app on your phone…` };
+    }
+    catch (error) {
+        // No T3 Connect on this API, or nothing to ask it: the desktop route stands on its own.
+        if (!(error instanceof ShardfluxApiError) || describeError(error).code === 'not_found')
+            return undefined;
+        // Another member's T3 Connect sign-in links this project: it is in their T3 app, not something to fix here.
+        if (error.details?.reason === 't3_linked_by_other_member')
+            return { state: 'info', fact: 'In the T3 app of the member who linked it.' };
+        return { state: 'unknown', fact: 'The T3 app link could not be checked just now.', action: { title: 'Retry', retry: true } };
+    }
+}
 const shard = (words) => ['shard', ...words];
 /** Claude: the account login is ready and Claude itself accepts it right now. */
 export function claudeConnection(row) {
@@ -105,7 +153,7 @@ export function codexConnection(local, synced, connector, health) {
     const enable = { title: 'Connect Codex', command: shard(['agents', 'codex', 'enable']) };
     if (!synced) {
         return local ? { state: 'action', fact: 'Available on web and phone once connected.', action: enable }
-            : { state: 'action', fact: 'Sign in to Codex on this Mac first.', action: { title: 'Sign in to Codex', command: ['codex', 'login'] } };
+            : { state: 'action', fact: 'Sign in to Codex on this computer first.', action: { title: 'Sign in to Codex', command: ['codex', 'login'] } };
     }
     const retry = { title: 'Retry', retry: true, command: shard(['setup', '--inspect', '--apps', 'codex', '--connect', '--retry-codex']) };
     switch (health) {

package/dist/t3-launch.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The CLI side of T3 Code mode (0.17.0+): `shard agents new --in t3 [--prompt…] [--on <ref>]`, `shard ./` and
+ * `--in auto` when T3 is where new conversations open, and `shard agents open t3 <conversation|workspace>`.
+ * --json results (contract shared with the menu bar):
+ *   new:  { target: "t3", mode, project, t3_thread_id, conversation_id, workspace: { workspace_key, id } | null,
+ *           opened: true, focused: false, model, effort, ... }
+ *   open: { opened: true, t3_thread_id, focused: false, ... }
+ * `focused` is false: T3 has no way to show a given thread from outside, so T3 is brought to the front instead.
+ */
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import type { Values } from './args.js';
+import type { AgentApp, T3Install, T3ThreadRequest, T3ThreadResult } from './t3-mode.js';
+/**
+ * A `t3_*` refusal raised once the workspace, conversation or thread exists names them (details.workspace_key,
+ * conversation_id, t3_thread_id), so a client opens what exists instead of starting it again.
+ */
+export declare function withT3Context(error: unknown, ref: {
+    workspace_key?: string | null;
+    conversation_id?: string | null;
+    t3_thread_id?: string | null;
+}): unknown;
+/** The thread to start, when the command carries a first message (`--prompt`, `--prompt-file`, `--image`, `--model`, `--effort`). */
+export declare function t3ThreadRequest(ctx: Ctx, values: Values, app: AgentApp): Promise<T3ThreadRequest | undefined>;
+/**
+ * `agents new --in t3`: with a first message in ACP mode, the thread starts on T3's Shardflux provider (its own VM);
+ * otherwise the project VM is opened as T3's SSH environment (with its phone link), and a first message becomes a
+ * thread on the T3 server in that VM. `--on <ref>` uses that existing workspace instead of the project VM.
+ */
+export declare function launchT3(ctx: Ctx, values: Values, path: string, explicitApp: string | undefined): Promise<number>;
+/** The T3 fields of an SSH-mode result (the thread, when one was started in the VM). */
+export declare function t3Fields(ws: Workspace, project: string, install: T3Install | undefined, started: T3ThreadResult | undefined, conversation?: string | null): Record<string, unknown>;
+/**
+ * `agents open t3 <conversation>` for a conversation that runs on T3's Shardflux provider (ACP mode): T3 is brought to
+ * the front with that thread's id. A conversation of another route opens its VM as T3's SSH environment.
+ */
+export declare function openT3Conversation(ctx: Ctx, conversationId: string, values?: Values): Promise<number>;

package/dist/t3-launch.js

@@ -0,0 +1,133 @@
+import { out, resolveWorkspace, str } from "./commands.js";
+import { CodedError, NotFoundError, UsageError } from "./errors.js";
+import { projectIdentity } from "./project-identity.js";
+import { AgentStateStore } from "./agent-state.js";
+import { readInitialImages, readInitialPrompt } from "./initial-prompt.js";
+import { findAcpThread, openT3, startAcpThread, t3Install, t3NotInstalled, t3OpenFailed } from "./t3-mode.js";
+import { agentReachability } from "./agent-reachability.js";
+import { conversationWorkspace, getConversation } from "./conversations.js";
+import { resolveOn } from "./thread-on-computer.js";
+import { ensureCloudClaude } from "./claude-cloud-login.js";
+import { modelChoice } from "./agent-models.js";
+/**
+ * A `t3_*` refusal raised once the workspace, conversation or thread exists names them (details.workspace_key,
+ * conversation_id, t3_thread_id), so a client opens what exists instead of starting it again.
+ */
+export function withT3Context(error, ref) {
+    if (!(error instanceof CodedError) || !error.code.startsWith('t3_'))
+        return error;
+    const details = { ...error.details, conversation_id: ref.conversation_id ?? error.details?.conversation_id ?? null, workspace_key: ref.workspace_key ?? error.details?.workspace_key ?? null,
+        t3_thread_id: ref.t3_thread_id ?? error.details?.t3_thread_id ?? null };
+    const next = new CodedError(error.code, error.message, error.hint, details);
+    next.stack = error.stack;
+    return next;
+}
+/** The thread to start, when the command carries a first message (`--prompt`, `--prompt-file`, `--image`, `--model`, `--effort`). */
+export async function t3ThreadRequest(ctx, values, app) {
+    const prompt = await readInitialPrompt(ctx, values);
+    const images = await readInitialImages(ctx, values, prompt);
+    if (prompt === undefined) {
+        if (values.model !== undefined || values.effort !== undefined)
+            throw new UsageError('--model and --effort choose how the first message runs: add --prompt or --prompt-file.');
+        return undefined;
+    }
+    // The same choices as every other new thread (agent-models.ts); "default" leaves the agent's own.
+    const choice = modelChoice(values, app);
+    return { app, prompt, ...(choice.model ? { model: choice.model } : {}), ...(choice.effort ? { effort: choice.effort } : {}), ...(images.length ? { images } : {}) };
+}
+/**
+ * `agents new --in t3`: with a first message in ACP mode, the thread starts on T3's Shardflux provider (its own VM);
+ * otherwise the project VM is opened as T3's SSH environment (with its phone link), and a first message becomes a
+ * thread on the T3 server in that VM. `--on <ref>` uses that existing workspace instead of the project VM.
+ */
+export async function launchT3(ctx, values, path, explicitApp) {
+    const install = t3Install(ctx.io.env);
+    if (!install)
+        throw t3NotInstalled();
+    if (explicitApp !== undefined && explicitApp !== 'claude' && explicitApp !== 'codex')
+        throw new UsageError('agent app must be claude or codex');
+    const project = projectIdentity(path);
+    const app = explicitApp ?? new AgentStateStore(ctx.store.dir).app(project.remote ?? project.folder);
+    const request = await t3ThreadRequest(ctx, values, app);
+    const on = str(values.on);
+    if (values.review === true)
+        throw new UsageError('--review starts a Claude reviewer in its terminal; leave out --in t3.');
+    if (on !== undefined) {
+        if (request && install.mode === 'acp') {
+            throw new CodedError('t3_on_not_supported', 'With the Shardflux provider in T3 Code, every thread runs in its own new VM, so it cannot start on an existing workspace.', 'Leave out --on to start the thread in its own VM, or open that workspace in T3 Code with shard agents open t3 <workspace>.', { workspace_key: on, conversation_id: null });
+        }
+        const { ws, conversation } = await onComputer(ctx, on, project.folder);
+        // The thread's agent runs in that VM with the account's logins, as `agents open t3` prepares them.
+        await ensureCloudClaude(ctx, ws);
+        const { openDesktopWorkspace } = await import("./agent-target-commands.js");
+        return openDesktopWorkspace(ctx, ws, 't3', install.version ?? undefined, false, request, install, conversation);
+    }
+    if (request && install.mode === 'acp')
+        return acpThreadOutput(ctx, install, project, request);
+    const { launchProjectWith } = await import("./agent-commands.js");
+    return launchProjectWith(ctx, { ...values, in: 't3' }, [path, app], request, install);
+}
+/**
+ * The computer `--on` names, as for any new thread (thread-on-computer.ts): a workspace key or id, else a conversation
+ * id, key or name (its VM). The T3 server in that VM runs the thread.
+ */
+async function onComputer(ctx, ref, folder) {
+    if (!/^conv_[a-z0-9]{26}$/.test(ref)) {
+        try {
+            const ws = await resolveWorkspace(ctx, ref);
+            return { ws, conversation: ws.labels.shard_conversation || null };
+        }
+        catch (error) {
+            if (!(error instanceof NotFoundError))
+                throw error;
+        }
+    }
+    const target = await resolveOn(ctx, ref, folder);
+    return { ws: await conversationWorkspace(ctx, target), conversation: target.id };
+}
+async function acpThreadOutput(ctx, install, project, request) {
+    const started = await startAcpThread(ctx, install, project.folder, request);
+    new AgentStateStore(ctx.store.dir).saveTarget(project.remote ?? project.folder, 't3');
+    out(ctx, `Started in T3 Code: ${request.prompt.split('\n')[0].slice(0, 80)}${started.conversation_id ? ` (${started.conversation_id})` : ''}\n`, { target: 't3', mode: started.mode, project: project.slug, t3_thread_id: started.t3_thread_id, conversation_id: started.conversation_id, workspace: started.workspace,
+        opened: true, focused: false, model: started.model, effort: started.effort, ...(started.effort_reason ? { effort_reason: started.effort_reason } : {}), app_bundle_id: 'com.t3tools.t3code' });
+    return 0;
+}
+/** The T3 fields of an SSH-mode result (the thread, when one was started in the VM). */
+export function t3Fields(ws, project, install, started, conversation) {
+    return { mode: install?.mode ?? 'ssh', project, t3_thread_id: started?.t3_thread_id ?? null, conversation_id: started?.conversation_id ?? conversation ?? (ws.labels.shard_conversation || null),
+        opened: true, focused: false, model: started?.model ?? null, effort: started?.effort ?? null, ...(started?.effort_reason ? { effort_reason: started.effort_reason } : {}) };
+}
+/**
+ * `agents open t3 <conversation>` for a conversation that runs on T3's Shardflux provider (ACP mode): T3 is brought to
+ * the front with that thread's id. A conversation of another route opens its VM as T3's SSH environment.
+ */
+export async function openT3Conversation(ctx, conversationId, values = {}) {
+    const install = t3Install(ctx.io.env);
+    if (!install)
+        throw t3NotInstalled();
+    const conversation = await getConversation(ctx, conversationId);
+    if (install.mode === 'acp' && conversation.route === 'acp') {
+        let threadId;
+        try {
+            threadId = await findAcpThread(ctx, install, conversationId);
+        }
+        catch (error) {
+            throw withT3Context(error, { conversation_id: conversationId });
+        }
+        try {
+            await openT3(ctx.io.env, install.path);
+        }
+        catch (error) {
+            throw threadId ? t3OpenFailed(error, { t3_thread_id: threadId, conversation_id: conversationId }) : error;
+        }
+        out(ctx, threadId ? `Opened T3 Code (thread ${threadId}).\n` : 'Opened T3 Code.\n', { target: 't3', mode: 'acp', conversation_id: conversationId, t3_thread_id: threadId, opened: true, focused: false, app_bundle_id: 'com.t3tools.t3code' });
+        return 0;
+    }
+    // Its VM as T3's SSH environment, with the checks every `agents open t3` makes: --reachable and the cloud Claude login.
+    let ws = await conversationWorkspace(ctx, conversation);
+    if (values.reachable !== undefined)
+        ws = await ctx.cloud().workspaces.open({ key: ws.key, ...agentReachability(values), wait: false });
+    await ensureCloudClaude(ctx, ws);
+    const { openDesktopWorkspace } = await import("./agent-target-commands.js");
+    return openDesktopWorkspace(ctx, ws, 't3', install.version ?? undefined, false, undefined, install, conversationId);
+}

package/dist/t3-mode.d.ts

@@ -0,0 +1,121 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import { CodedError } from './errors.js';
+import type { InitialImage } from './initial-prompt.js';
+export declare const T3_BUNDLE_ID = "com.t3tools.t3code";
+export type T3Mode = 'acp' | 'ssh';
+export type AgentApp = 'claude' | 'codex';
+export type OpenIn = 'terminal' | 'claude-desktop' | 'web' | 'codex-app' | 't3';
+/** 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 declare const OPEN_IN_TARGETS: Record<AgentApp, readonly OpenIn[]>;
+export interface T3Install {
+    path: string;
+    version: string | null;
+    mode: T3Mode;
+}
+export interface T3Status {
+    installed: boolean;
+    mode: T3Mode | null;
+    connected: boolean;
+    version: string | null;
+    last_used_at: string | null;
+}
+export interface T3ThreadRequest {
+    app: AgentApp;
+    prompt: string;
+    model?: string;
+    effort?: string;
+    images?: readonly InitialImage[];
+}
+/** Why a requested `--effort` reached T3 as none: the model offers no such level, or its levels are not known yet. */
+export type EffortReason = 'not_offered' | 'models_not_known';
+export interface T3ThreadResult {
+    mode: T3Mode;
+    t3_thread_id: string;
+    conversation_id: string | null;
+    workspace: {
+        workspace_key: string;
+        id: string;
+    } | null;
+    model: string | null;
+    effort: string | null;
+    effort_reason?: EffortReason;
+}
+/** Native lookups that tests replace: Spotlight's last-used dates of app bundles, one `mdls` for all of them. */
+export declare const t3Native: {
+    lastUsedMany(paths: readonly string[], env: Record<string, string | undefined>): Record<string, string | null>;
+};
+/** Spotlight takes about 40 ms per call, so the dates are kept for a few minutes (app-usage.json in the config dir). */
+export declare const LAST_USED_TTL_MS: number;
+export declare function lastUsedDates(ctx: Ctx, paths: readonly string[], now?: number): Record<string, string | null>;
+/** The installed T3 Code, preferring a build with ACP providers when several channels are installed. */
+export declare function t3Install(env: Record<string, string | undefined>, platform?: NodeJS.Platform): T3Install | undefined;
+export declare function t3HomeDir(env: Record<string, string | undefined>): string;
+/** The Shardflux provider instance in T3's server settings (read only; every `shard` run writes it, see t3-provider.ts). */
+export declare function t3ProviderRegistered(env: Record<string, string | undefined>): boolean;
+/**
+ * T3 is connected when a new thread can start in it now: in ACP mode the Shardflux provider is in T3's settings and
+ * this computer is signed in; in SSH mode this project has a T3 SSH environment set up from this computer (signed in).
+ * `last_used_at` is looked up only when asked for (`agents targets`).
+ */
+export declare function t3Status(ctx: Ctx, opts?: {
+    project?: string | null;
+    install?: T3Install | null;
+    lastUsed?: boolean;
+}): T3Status;
+export interface OpenInChoice {
+    target: OpenIn;
+    saved: boolean;
+}
+/**
+ * Where each app's new conversations open for `project`: the choice saved with `agents targets --open-in` while it is
+ * available, else T3 when it is connected and the most recently used of the installed desktop apps, else a terminal
+ * (Claude) or the Codex app. Lookups run only when an answer needs them: none for a saved terminal, web or Codex app
+ * choice, and Spotlight only when T3 is installed and connected (cached, see lastUsedDates).
+ */
+export declare function openInFor(ctx: Ctx, project: string | null, known?: {
+    clients?: readonly string[];
+}): Record<AgentApp, OpenInChoice>;
+export declare function openInChoices(ctx: Ctx, project: string | null, known?: {
+    clients?: readonly string[];
+}): Record<AgentApp, OpenIn>;
+/** `--open-in claude=t3,codex=t3`: validated against what is installed, then saved in agents.json. */
+export declare function saveOpenIn(ctx: Ctx, spec: string, status: T3Status, clients: readonly string[]): void;
+/** A T3 thread was started, then a later step failed: the error names the thread so a client opens it, never starts another. */
+export declare function t3OpenFailed(error: unknown, ref: {
+    t3_thread_id: string;
+    conversation_id?: string | null;
+    workspace_key?: string | null;
+}): CodedError;
+export declare const t3NotInstalled: () => CodedError;
+/** The first line of the prompt, as T3 titles a thread before it names it. */
+export declare function t3ThreadTitle(prompt: string): string;
+/**
+ * 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.
+ */
+export declare function openT3(env: Record<string, string | undefined>, appPath: string): Promise<void>;
+/** Starts the thread in the VM's T3 server (T3_THREAD_SCRIPT); the prompt travels on stdin, never in argv. */
+export declare function startSshThread(ctx: Ctx, ws: Workspace, version: string | undefined, projectPath: string, request: T3ThreadRequest): Promise<T3ThreadResult>;
+interface Descriptor {
+    serverVersion?: string;
+    orchestrationProtocolVersion?: number;
+}
+export interface LocalT3Server {
+    origin: string;
+    descriptor: Descriptor;
+    base: string;
+}
+interface T3Session {
+    token: string;
+    sessionId: string;
+}
+/** The running desktop server; T3 is opened (which starts it) when none answers. */
+export declare function localT3Server(ctx: Ctx, install: T3Install, waitMs?: number): Promise<LocalT3Server>;
+/** One Effect RPC request over T3's WebSocket (JSON frames: Request → Exit), authorized by a ticket from the session. */
+export declare function t3Rpc(server: LocalT3Server, session: T3Session, tag: string, payload: unknown, signal: AbortSignal, timeoutMs?: number): Promise<unknown>;
+/** Starts a T3 thread on the Shardflux provider (ACP mode) and brings T3 to the front. */
+export declare function startAcpThread(ctx: Ctx, install: T3Install, folder: string, request: T3ThreadRequest, waitMs?: number): Promise<T3ThreadResult>;
+/** The T3 thread of a Shardflux conversation started in T3 (ACP mode): the one remembered, else a search of recent Shardflux threads. */
+export declare function findAcpThread(ctx: Ctx, install: T3Install, conversationId: string): Promise<string | null>;
+export {};