@shardflux/cli 0.16.0 → 0.18.0-next.4

package/dist/agent-target-commands.js

@@ -5,17 +5,23 @@ import { ensureCloudClaude } from "./claude-cloud-login.js";
 import { spawn } from 'node:child_process';
 import { Readable, Duplex } from 'node:stream';
 import { ShardfluxApiError, WorkspaceTunnels } from '@shardflux/sdk';
+import { conversationWorkspace, getConversation } from "./conversations.js";
 import { out, resolveWorkspace } from "./commands.js";
+import { MODEL_CHOICES } from "./agent-models.js";
 import { AgentTargets, installedTargets, targetLabel } from "./agent-targets.js";
 import { join, relative } from 'node:path';
 import { projectIdentity } from "./project-identity.js";
 import { projectWorkspacePath } from "./agent-repository.js";
-import { UsageError } from "./errors.js";
+import { UsageError, describeError } from "./errors.js";
+import { t3PhoneLink } from "./t3-phone.js";
 import { prepareDesktopRouter } from "./conversation-router.js";
 import { openUrl } from "./browser.js";
 import { agentMachineName, prepareAgentMachine } from "./agent-machine.js";
 import { prewarmT3 } from "./t3-runtime.js";
 import { AgentStateStore } from "./agent-state.js";
+import { workspaceRepositoryPath } from "./agent-repository.js";
+import { openInChoices, openT3, saveOpenIn, startSshThread, t3Install, t3NotInstalled, t3OpenFailed, t3Status } from "./t3-mode.js";
+import { openT3Conversation, t3Fields, withT3Context } from "./t3-launch.js";
 const missing = (e) => e instanceof ShardfluxApiError && e.status === 404;
 const keyOf = (ref) => ref.includes('/') ? ref : `${projectIdentity('./').slug}/${ref}`;
 /** How long opening a Claude conversation this computer just started waits for Claude to publish its Remote Control URL. */
@@ -72,6 +78,8 @@ export async function prepareSsh(ws, ctx, targets, host) {
     return cell;
 }
 async function openApp(target, env) {
+    if (target === 't3')
+        return openT3(env, t3Install(env));
     const child = spawn('open', ['-b', { 'claude-desktop': 'com.anthropic.claudefordesktop', 'codex-app': 'com.openai.codex', t3: 'com.t3tools.t3code' }[target]], { env, stdio: 'ignore' });
     await new Promise((resolve, reject) => {
         const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('app launcher timed out')); }, 10_000);
@@ -212,23 +220,41 @@ async function openLink(url, env) {
 }
 const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
     const detected = installedTargets(ctx.io.env);
+    if (target === 't3' && !detected.targets.includes('t3'))
+        throw t3NotInstalled();
     if (target !== 'web' && !detected.targets.includes(target))
         throw new UsageError(`${target} is not installed on this machine`);
-    let ws = await resolveWorkspace(ctx, keyOf(ref));
+    // A conversation started in T3 (its Shardflux provider) opens its own thread there (0.17.0+).
+    if (target === 't3' && /^conv_[a-z0-9]{26}$/.test(ref))
+        return openT3Conversation(ctx, ref, values);
+    // A conversation id opens that conversation's own session on its computer (claude.ai, the desktop apps).
+    const conversation = /^conv_[a-z0-9]{26}$/.test(ref) ? await getConversation(ctx, ref) : undefined;
+    let ws = conversation ? await conversationWorkspace(ctx, conversation) : await resolveWorkspace(ctx, keyOf(ref));
     if (values.reachable !== undefined)
         ws = await ctx.cloud().workspaces.open({ key: ws.key, ...agentReachability(values), wait: false });
-    if (target !== 'codex-app')
+    // T3 lists both agents and opens without Claude (it shows Claude as signed out); the Claude apps need it.
+    if (target === 't3')
+        await ensureCloudClaude(ctx, ws).catch((error) => {
+            if (!(error instanceof UsageError))
+                throw error;
+            ctx.io.stderr.write(`Claude Code in T3: ${error.message}\n`);
+        });
+    else if (target !== 'codex-app')
         await ensureCloudClaude(ctx, ws);
     if (target === 'web') {
-        const url = await remoteControlUrl(ctx, ws);
+        const url = await remoteControlUrl(ctx, ws, conversation);
         if (!ctx.json && !openUrl(url, ctx.io.env))
             throw new Error(`could not open ${url}`);
-        out(ctx, `${url}\n`, { target, workspace: ws.data, url });
+        out(ctx, `${url}\n`, { target, workspace: ws.data, url, ...(conversation ? { conversation_id: conversation.id } : {}) });
         return 0;
     }
-    return openDesktopWorkspace(ctx, ws, target, detected.versions.t3);
+    return openDesktopWorkspace(ctx, ws, target, detected.versions.t3, false, undefined, undefined, conversation?.id);
 };
-export async function openDesktopWorkspace(ctx, ws, target, t3Version, prewarmed = false) {
+/**
+ * Opens a workspace as a desktop app's SSH environment. For T3 (0.17.0+) a first message becomes a thread on the T3
+ * server in the VM (SSH mode), and T3 is brought to the front with --json too (`opened: true`).
+ */
+export async function openDesktopWorkspace(ctx, ws, target, t3Version, prewarmed = false, thread, install, conversation) {
     if (target !== 't3')
         ws = await prepareDesktopRouter(ctx, ws);
     await prepareAgentMachine(ctx, ws);
@@ -241,13 +267,58 @@ export async function openDesktopWorkspace(ctx, ws, target, t3Version, prewarmed
         : target === 'claude-desktop'
             ? `Restart Claude Desktop to load the connection, then choose ${targetLabel(entry)} in Code's environment dropdown and open ${projectWorkspacePath({ slug: entry.project })}.`
             : `Restart Codex to import ${entry.host} and its remote project. If it has already been imported, enable ${entry.host} in Settings → Connections → SSH.`;
-    if (!ctx.json)
+    let started;
+    if (target === 't3' && thread) {
+        try {
+            started = await startSshThread(ctx, ws, t3Version, workspaceRepositoryPath(ws), thread);
+        }
+        catch (error) {
+            throw withT3Context(error, { workspace_key: ws.key, conversation_id: conversation ?? (ws.labels.shard_conversation || null) });
+        }
+    }
+    if (target === 't3') {
+        // The thread exists once startSshThread returns: a failure to show T3 names it rather than inviting a retry.
+        try {
+            await openT3(ctx.io.env, install ?? t3Install(ctx.io.env));
+        }
+        catch (error) {
+            throw started ? t3OpenFailed(error, { t3_thread_id: started.t3_thread_id, conversation_id: conversation ?? (ws.labels.shard_conversation || null), workspace_key: ws.key }) : error;
+        }
+    }
+    else if (!ctx.json)
         await openApp(target, ctx.io.env);
     new AgentStateStore(ctx.store.dir).saveTarget(ws.labels.repo_remote || ws.labels.shard_project || entry.project, target);
-    out(ctx, `${instructions}\n`, { target, workspace: ws.data, host: entry.host, instructions,
+    if (target === 't3')
+        new AgentStateStore(ctx.store.dir).saveT3Environment({ workspace: ws.key, host: entry.host, api_url: ctx.apiUrl });
+    const phone = target === 't3' ? await linkT3Phone(ctx, ws) : undefined;
+    const threadLine = started ? `Started a thread in T3 Code on ${agentMachineName(ws.key)}${started.model ? ` (${started.model}${started.effort ? `, ${started.effort}` : ''})` : ''}.\n` : '';
+    out(ctx, `${threadLine}${instructions}\n${phone?.line ?? ''}`, { target, workspace: ws.data, host: entry.host, instructions, ...(phone ? { t3_link: phone.link } : {}),
+        ...(target === 't3' ? t3Fields(ws, entry.project, install ?? t3Install(ctx.io.env), started, conversation) : {}),
         app_bundle_id: { 'claude-desktop': 'com.anthropic.claudefordesktop', 'codex-app': 'com.openai.codex', t3: 'com.t3tools.t3code' }[target] });
     return 0;
 }
+/**
+ * The T3 app on the phone reaches this workspace through the account's T3 Connect sign-in (0.17.0+). The sign-in is
+ * asked for once per person; linking continues by itself once it is approved.
+ */
+async function linkT3Phone(ctx, ws) {
+    try {
+        const { link, signIn, needsLogin } = await t3PhoneLink(ctx, ws.id);
+        const line = signIn
+            ? `Phone: to use ${link.label} from the T3 app, open ${signIn.verification_uri} and confirm ${signIn.user_code} (once).\n`
+            : needsLogin ? `Phone: to use ${link.label} from the T3 app, sign in with shard auth login, then run this again.\n`
+                : `Phone: ${link.label} appears in the T3 app's environments.\n`;
+        // --json carries the sign-in shard started with its session too, so the menu bar can show it.
+        return { line, link: signIn ? { ...link, sign_in: { ...link.sign_in, ...signIn } } : needsLogin ? { ...link, needs_login: true } : link };
+    }
+    catch (error) {
+        // An API without T3 Connect leaves the desktop route as it is.
+        if (describeError(error).code === 'not_found')
+            return undefined;
+        ctx.io.stderr.write(`Phone link: ${describeError(error).message}\n`);
+        return undefined;
+    }
+}
 export async function queueT3Prewarm(ctx, ws, version) {
     try {
         await prewarmT3(ctx, ws, version);
@@ -269,30 +340,56 @@ function configuredTargets(targets, e, t3 = false) {
 function targetFiles(targets, entries) {
     return [...new Set(entries.flatMap(e => configuredTargets(targets, e).map(c => c.file)))];
 }
+/**
+ * The project `agents targets` reports T3 for: the agent argument's, else `--path`'s (resolved as `agents new --path`
+ * resolves it: the repository remote, else the folder), else the current folder's when it is one.
+ */
+function targetsProject(ref, path) {
+    if (ref)
+        return keyOf(ref).split('/')[0];
+    if (path !== undefined)
+        return projectIdentity(path).slug;
+    try {
+        return projectIdentity('./').slug;
+    }
+    catch {
+        return null;
+    }
+}
 export const TARGET_HANDLERS = {
     async 'agents targets'(ctx, values, [ref]) {
-        const detected = installedTargets(ctx.io.env);
+        const found = installedTargets(ctx.io.env);
+        // models (0.17.0+): the model and effort choices a new thread can start with; clients never hardcode them.
+        // T3 Code mode (0.17.0+): T3's state for this project (the agent's, else this folder's), and where `shard ./` opens
+        // each app's new conversations (--open-in sets it).
+        const project = targetsProject(ref, typeof values.path === 'string' ? values.path : undefined);
+        const t3 = t3Status(ctx, { project, lastUsed: true });
+        if (typeof values['open-in'] === 'string')
+            saveOpenIn(ctx, values['open-in'], t3, found.clients);
+        const detected = { ...found, t3, open_in: openInChoices(ctx, project, { clients: found.clients }) };
         const targets = new AgentTargets(ctx.io.env, ctx.store.dir);
         const key = ref ? keyOf(ref) : undefined;
         const before = values.remove === true ? await targets.configure(undefined, ctx.apiUrl, [], false, ctx.signal) : [];
         const entries = ref || values.remove === true
             ? await targets.configure(key, ctx.apiUrl, detected.targets.filter((t) => t === 'claude-desktop' || t === 'codex-app' || t === 't3'), values.remove === true, ctx.signal)
             : [];
-        const detection = `${detected.clients.join(', ') || 'No installed agent clients'}\nOpen targets: ${detected.targets.join(', ')}\n`;
+        const detection = `${detected.clients.join(', ') || 'No installed agent clients'}\nOpen targets: ${detected.targets.join(', ')}\n` +
+            (t3.installed ? `T3 Code ${t3.version ?? ''}: ${t3.mode === 'acp' ? 'Shardflux provider' : 'SSH environments'}, ${t3.connected ? 'connected' : 'not connected'}\n`.replace(' :', ':') : '') +
+            `New conversations open in: Claude → ${detected.open_in.claude}, Codex → ${detected.open_in.codex}\n`;
         if (values.remove === true) {
             const removed = before.filter(e => !entries.some(n => n.host === e.host));
-            out(ctx, removed.length ? `Removed ${removed.map(e => `${e.workspace} (${e.host})`).join(', ')} from ${targetFiles(targets, removed).map(f => tilde(targets, f)).join(', ')}\n` : 'No managed targets to remove.\n', { ...detected, entries, removed });
+            out(ctx, removed.length ? `Removed ${removed.map(e => `${e.workspace} (${e.host})`).join(', ')} from ${targetFiles(targets, removed).map(f => tilde(targets, f)).join(', ')}\n` : 'No managed targets to remove.\n', { ...detected, entries, removed, models: MODEL_CHOICES });
             return Promise.resolve(0);
         }
         const entry = key ? entries.find(e => e.workspace === key) : undefined;
         if (!entry) {
-            out(ctx, detection, { ...detected, entries });
+            out(ctx, detection, { ...detected, entries, models: MODEL_CHOICES });
             return Promise.resolve(0);
         }
-        const t3 = detected.targets.includes('t3');
-        const configured = configuredTargets(targets, entry, t3);
+        const t3Installed = detected.targets.includes('t3');
+        const configured = configuredTargets(targets, entry, t3Installed);
         out(ctx, `Configured ${entry.workspace} as SSH host ${entry.host}:\n${configured.map(c => `  ${c.label.padEnd(15)} ${tilde(targets, c.file)}${c.detail ? ` ${c.detail}` : ''}`).join('\n')}\n` +
-            ['claude-desktop', 'codex-app', 't3'].filter(t => t === 't3' ? !t3 : !entry.targets.includes(t)).map(t => `  ${{ 'claude-desktop': 'Claude Desktop', 'codex-app': 'Codex app', t3: 'T3 Code' }[t].padEnd(15)} not installed on this computer\n`).join(''), { ...detected, entries, configured: configured.map(({ target, file, name }) => ({ target, file, name })) });
+            ['claude-desktop', 'codex-app', 't3'].filter(t => t === 't3' ? !t3Installed : !entry.targets.includes(t)).map(t => `  ${{ 'claude-desktop': 'Claude Desktop', 'codex-app': 'Codex app', t3: 'T3 Code' }[t].padEnd(15)} not installed on this computer\n`).join(''), { ...detected, entries, configured: configured.map(({ target, file, name }) => ({ target, file, name })), models: MODEL_CHOICES });
         return Promise.resolve(0);
     },
     'agents open claude-desktop': openTarget('claude-desktop'),

package/dist/agent-targets.d.ts

@@ -1,3 +1,4 @@
+import type { T3LinuxApp } from './t3-linux.js';
 export type DesktopTarget = 'claude-desktop' | 'codex-app' | 't3';
 export interface TargetEntry {
     host: string;
@@ -13,13 +14,24 @@ export declare const targetLabel: (e: Pick<TargetEntry, "agent" | "project">) =>
 export declare function targetIdentity(key: string): Pick<TargetEntry, 'host' | 'workspace' | 'project' | 'agent'>;
 /** Replace only a marked block, retaining every byte outside it. Put Includes before user Host blocks. */
 export declare function managedBlock(text: string, body: string): string;
-/** The installed T3 Code apps (any channel), with their path and version, in the given app folders. */
-export declare function t3Apps(dirs: string[], platform?: NodeJS.Platform): Array<{
+/**
+ * An installed T3 Code: on macOS `path` is the .app bundle; on Linux it is the program its desktop entry runs (the
+ * executable, or the AppImage), and `linux` says how it was installed and how it starts (t3-linux.ts).
+ */
+export interface T3App {
     path: string;
     version: string | null;
-}>;
-/** The app folders scanned for desktop apps: SHARDFLUX_APPLICATIONS_DIRS, else /Applications and ~/Applications. */
-export declare function applicationDirs(env: Record<string, string | undefined>): string[];
+    linux?: T3LinuxApp;
+}
+/** The installed T3 Code apps (any channel), with their path and version, in the given app folders (applicationDirs). */
+export declare function t3Apps(dirs: string[], platform?: NodeJS.Platform, env?: Record<string, string | undefined>): T3App[];
+/**
+ * The folders scanned for desktop apps: SHARDFLUX_APPLICATIONS_DIRS (colon-separated) when set; else /Applications and
+ * ~/Applications on macOS, and on Linux the XDG application folders and the usual AppImage folders (linuxApplicationDirs).
+ */
+export declare function applicationDirs(env: Record<string, string | undefined>, platform?: NodeJS.Platform): string[];
+/** The first `name` app bundle with this bundle id in the app folders (macOS only). */
+export declare function desktopAppPath(dirs: string[], name: string, bundle: string, platform?: NodeJS.Platform): string | undefined;
 export declare function installedTargets(env: Record<string, string | undefined>, platform?: NodeJS.Platform, appDirs?: string[]): {
     targets: string[];
     clients: string[];

package/dist/agent-targets.js

@@ -7,6 +7,7 @@ import { writePrivateFile } from "./credentials.js";
 import { UsageError } from "./errors.js";
 import { projectWorkspacePath } from "./agent-repository.js";
 import { withTargetLock } from "./target-lock.js";
+import { linuxApplicationDirs, linuxT3Apps } from "./t3-linux.js";
 const PERSISTED_TARGETS = ['claude-desktop', 'codex-app'];
 const BEGIN = '# BEGIN Shardflux managed targets';
 const END = '# END Shardflux managed targets';
@@ -36,8 +37,10 @@ export function managedBlock(text, body) {
     const stop = end + END.length + (text[end + END.length] === '\n' ? 1 : 0);
     return text.slice(0, start) + block + text.slice(stop);
 }
-/** The installed T3 Code apps (any channel), with their path and version, in the given app folders. */
-export function t3Apps(dirs, platform = process.platform) {
+/** The installed T3 Code apps (any channel), with their path and version, in the given app folders (applicationDirs). */
+export function t3Apps(dirs, platform = process.platform, env = process.env) {
+    if (platform === 'linux')
+        return linuxT3Apps(dirs, env);
     const found = [];
     if (platform !== 'darwin')
         return found;
@@ -69,23 +72,34 @@ export function t3Apps(dirs, platform = process.platform) {
     }
     return found;
 }
-/** The app folders scanned for desktop apps: SHARDFLUX_APPLICATIONS_DIRS, else /Applications and ~/Applications. */
-export function applicationDirs(env) {
+/**
+ * The folders scanned for desktop apps: SHARDFLUX_APPLICATIONS_DIRS (colon-separated) when set; else /Applications and
+ * ~/Applications on macOS, and on Linux the XDG application folders and the usual AppImage folders (linuxApplicationDirs).
+ */
+export function applicationDirs(env, platform = process.platform) {
     const home = env.HOME || homedir();
-    return env.SHARDFLUX_APPLICATIONS_DIRS !== undefined ? env.SHARDFLUX_APPLICATIONS_DIRS.split(':').filter(Boolean) : ['/Applications', join(home, 'Applications')];
+    if (env.SHARDFLUX_APPLICATIONS_DIRS !== undefined)
+        return env.SHARDFLUX_APPLICATIONS_DIRS.split(':').filter(Boolean);
+    return platform === 'linux' ? linuxApplicationDirs(env) : ['/Applications', join(home, 'Applications')];
 }
-export function installedTargets(env, platform = process.platform, appDirs) {
-    // SHARDFLUX_APPLICATIONS_DIRS (colon-separated) replaces the scanned app folders, like SHARDFLUX_CONFIG_DIR does for config.
-    const dirs = appDirs ?? applicationDirs(env);
-    const hasApp = (name, bundle) => platform === 'darwin' && dirs.map(dir => join(dir, name)).some(path => {
+/** The first `name` app bundle with this bundle id in the app folders (macOS only). */
+export function desktopAppPath(dirs, name, bundle, platform = process.platform) {
+    if (platform !== 'darwin')
+        return undefined;
+    return dirs.map(dir => join(dir, name)).find(path => {
         const info = join(path, 'Contents', 'Info.plist');
         if (!existsSync(info))
             return false;
         const result = spawnSync('/usr/libexec/PlistBuddy', ['-c', 'Print :CFBundleIdentifier', info], { input: '', encoding: 'utf8', timeout: 1000 });
         return result.status === 0 && result.stdout.trim() === bundle;
     });
+}
+export function installedTargets(env, platform = process.platform, appDirs) {
+    // SHARDFLUX_APPLICATIONS_DIRS (colon-separated) replaces the scanned app folders, like SHARDFLUX_CONFIG_DIR does for config.
+    const dirs = appDirs ?? applicationDirs(env, platform);
+    const hasApp = (name, bundle) => desktopAppPath(dirs, name, bundle, platform) !== undefined;
     const versions = {};
-    const t3Bundles = t3Apps(dirs, platform);
+    const t3Bundles = t3Apps(dirs, platform, env);
     const t3 = t3Bundles.length > 0;
     for (const app of t3Bundles)
         if (app.version)
@@ -100,7 +114,9 @@ export function installedTargets(env, platform = process.platform, appDirs) {
     const clients = [hasApp('Claude.app', 'com.anthropic.claudefordesktop') && 'claude-desktop', (hasApp('Codex.app', 'com.openai.codex') || hasApp('ChatGPT.app', 'com.openai.codex')) && 'codex-app', executable('claude') && 'claude', executable('codex') && 'codex'].filter((v) => !!v);
     if (t3)
         clients.push('t3');
-    return { targets: [...(platform === 'darwin' ? clients.filter(c => c.endsWith('-app') || c === 'claude-desktop' || c === 't3') : []), 'web'], clients, versions };
+    // Linux has T3 Code (0.17.0+); Claude Desktop and the Codex app are macOS apps.
+    const desktop = platform === 'darwin' ? clients.filter(c => c.endsWith('-app') || c === 'claude-desktop' || c === 't3') : platform === 'linux' && t3 ? ['t3'] : [];
+    return { targets: [...desktop, 'web'], clients, versions };
 }
 /** All paths are supplied by the invocation; tests use a temporary HOME, never the owner's app stores. */
 export class AgentTargets {

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.16.0";
+export declare const CLI_VERSION = "0.17.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;
@@ -27,9 +27,12 @@ export interface CommandSpec {
     positionals: PositionalSpec[];
     options: Record<string, OptionSpec>;
     examples?: string[];
+    /** Runs, but is left out of the top and group help (a program other tools start, such as a forwarder). */
+    hidden?: boolean;
 }
 export declare const GLOBAL_OPTIONS: Record<string, OptionSpec>;
 export declare const PROJECT_COMMAND: CommandSpec;
+export declare const ONBOARDING_COMMAND: CommandSpec;
 export declare const CENTER_COMMAND: CommandSpec;
 export declare const COMMANDS: CommandSpec[];
 export declare function normalizeWords(words: string[]): string[];
@@ -74,6 +77,7 @@ export type Parsed = {
  */
 export declare function parseCommandLine(argv: readonly string[], options?: {
     tty?: boolean;
+    platform?: NodeJS.Platform;
     isProjectPath?: (path: string) => boolean;
 }): Parsed;
 export declare function usageLine(c: CommandSpec): string;

package/dist/args.js

@@ -12,7 +12,8 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.16.0';
+import { DEFAULT_CHOICE, MODEL_CHOICES } from "./agent-models.js";
+export const CLI_VERSION = '0.18.0-next.4';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -1188,6 +1189,18 @@ const AGENT_OPTIONS = {
     reachable: { type: 'string', value: '<duration>', hidden: true, description: 'Deprecated; ignored. Claude conversations stay reachable without a time limit.' },
     approvals: { type: 'boolean', description: 'Keep the agent’s permission prompts.' },
 };
+/** `Claude fable, opus, sonnet or haiku; Codex …` from the CLI's one list (agent-models.ts), without "default". */
+function choiceIds(kind) {
+    return ['claude', 'codex'].map(app => {
+        const ids = MODEL_CHOICES[app][kind].map(c => c.id).filter(id => id !== DEFAULT_CHOICE);
+        return `${app === 'claude' ? 'Claude' : 'Codex'} ${ids.slice(0, -1).join(', ')} or ${ids.at(-1)}`;
+    }).join('; ');
+}
+/** The model and effort a new thread starts with; `shard agents targets --json` lists the choices (0.17.0+). */
+const MODEL_OPTIONS = {
+    model: { type: 'string', value: '<model>', description: `Model the new thread starts with: ${choiceIds('models')}; default is the agent’s own (0.17.0+).` },
+    effort: { type: 'string', value: '<level>', description: `Reasoning effort the new thread starts with: ${choiceIds('efforts')}; default is the agent’s own (0.17.0+).` },
+};
 /** A new thread on an existing conversation's computer (0.16.0+). */
 const ON_OPTIONS = {
     on: { type: 'string', value: '<conversation|computer>', description: 'Start the thread on the computer of an existing conversation, sharing its packages, caches, services, ports and files, on its own branch: a conversation id, key or name, or its workspace key or id (shard agents computers lists them) (0.16.0+).' },
@@ -1198,6 +1211,7 @@ export const PROJECT_COMMAND = {
     description: 'Opens Claude Code or Codex directly. --resume continues a project conversation. With --json it starts detached and prints the session. Detach with Ctrl-] then d.',
     positionals: [{ name: 'path', required: true }, { name: 'claude|codex' }], options: {
         ...AGENT_OPTIONS,
+        ...MODEL_OPTIONS,
         ...ON_OPTIONS,
         computer: COMPUTER_OPTION,
         new: { type: 'boolean', description: 'Start a new conversation.' },
@@ -1211,10 +1225,17 @@ function projectExample(rest, app) {
     const path = rest.find((r, i) => !r.startsWith('-') && !GLOBAL_VALUE_FLAGS.has(rest[i - 1] ?? '')) ?? './';
     return `shard ${/^[\w./~@:+,=-]+$/.test(path) ? path : `'${path.replaceAll("'", `'\\''`)}'`} ${app}`;
 }
+export const ONBOARDING_COMMAND = { path: ['<onboarding>'], summary: 'Set up Shardflux in your terminal', positionals: [], options: { 'accept-terms': { type: 'boolean', description: 'Accept the Terms of Service and Privacy Policy.' }, apps: { type: 'string', value: '<claude,codex>', description: 'Connect Claude, Codex or both.' } } };
 export const CENTER_COMMAND = { path: ['<center>'], summary: 'Open the cloud agent command center', positionals: [], options: {} };
 const AGENT_COMMANDS = [
+    { path: ['device', 'requests'], summary: 'Review local device requests waiting for approval', positionals: [], options: {} },
+    ...['approve', 'deny'].map((action) => ({ path: ['device', action], summary: `${action} a local device request`, positionals: [{ name: 'id', required: true }], options: action === 'approve' ? { always: { type: 'boolean', description: 'Allow matching requests for this project; never for outside-folder access.' } } : {} })),
     { path: ['conversations', 'try'], summary: 'Try a conversation in a synced local worktree', positionals: [{ name: 'conversation', required: true }], options: { path: { type: 'string', value: '<path>', description: 'Local project checkout.' }, stop: { type: 'boolean', description: 'Stop the device helper’s local sync and ports.' } } },
-    { path: ['agents', 'targets'], summary: 'Detect apps or configure managed desktop connections', positionals: [{ name: 'agent' }], options: { remove: { type: 'boolean', description: 'Remove this agent’s managed entries, or all entries for this API URL.' } } },
+    { path: ['agents', 'targets'], summary: 'Detect apps or configure managed desktop connections', positionals: [{ name: 'agent' }], options: {
+            remove: { type: 'boolean', description: 'Remove this agent’s managed entries, or all entries for this API URL.' },
+            'open-in': { type: 'string', value: '<app=target,…>', description: 'Where new conversations open (0.17.0+): claude=terminal|claude-desktop|web|t3, codex=codex-app|t3, e.g. claude=t3,codex=t3.' },
+            path: { type: 'string', value: '<path>', description: 'Local project folder whose T3 Code state and open_in to report, as agents new --path names it (default the current folder; the agent argument wins) (0.17.0+).' },
+        } },
     ...['claude-desktop', 'codex-app', 'web', 't3'].map(target => ({ path: ['agents', 'open', target], summary: `Open the agent in ${target}`, positionals: [{ name: 'agent' }], options: { reachable: AGENT_OPTIONS.reachable } })),
     { path: ['ssh-proxy'], summary: 'Forward SSH standard IO to a managed workspace', positionals: [{ name: 'host', required: true }], options: {} },
     ...['worktree', 'merge', 'keep', 'discard', 'restore'].map((action) => ({
@@ -1232,12 +1253,13 @@ const AGENT_COMMANDS = [
         } },
     { path: ['agents', 'new'], summary: 'Start a conversation in a fresh VM, or with --on on an existing conversation’s computer; Codex opens a genuine Cloud thread', positionals: [{ name: 'agent' }], options: {
             ...AGENT_OPTIONS,
+            ...MODEL_OPTIONS,
             ...ON_OPTIONS,
             computer: COMPUTER_OPTION,
             app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' },
             path: { type: 'string', value: '<path>', description: 'Local project path for first launch.' },
             name: { type: 'string', value: '<name>', description: 'New agent name; copies the project main workspace with --like.' },
-            in: { type: 'string', value: '<terminal|claude-desktop|codex-app|t3>', description: 'Where to open the new agent (default terminal).' },
+            in: { type: 'string', value: '<terminal|auto|claude-desktop|codex-app|t3>', description: 'Where to open the new agent (default terminal). t3 (0.17.0+): the first message starts a T3 Code thread (with --on, on that computer’s T3 server); auto: where agents targets --open-in says.' },
             like: { type: 'string', value: '<id|key>', description: 'Copy the workspace configuration onto a fresh disk.' },
         } },
     { path: ['agents', 'fork'], summary: 'Fork an agent’s memory and disk', positionals: [{ name: 'agent', required: true }, { name: 'name', required: true }], options: WAIT },
@@ -1248,13 +1270,29 @@ const AGENT_COMMANDS = [
             follow: { type: 'boolean', description: 'Follow output until interrupted.' },
         } },
 ];
+const CLI_PROXY_HELP = 'One CLIProxyAPI for your whole account: your Claude, Codex and other subscription logins live in a small hosted copy that sleeps between requests and wakes on the next one. This computer and every VM reach it at http://127.0.0.1:8317, so Claude Code, Codex and T3 Code keep their settings.';
+const CLI_PROXY_COMMANDS = [
+    { path: ['cli-proxy'], summary: 'Your hosted CLIProxyAPI: its accounts, and where it is reachable', description: CLI_PROXY_HELP, positionals: [], options: {
+            config: { type: 'string', value: '<path>', description: 'This computer’s CLIProxyAPI config file, when none is set up yet (default: found automatically).' },
+        } },
+    { path: ['cli-proxy', 'import'], summary: 'Move CLIProxyAPI from this computer into your account, reachable at 127.0.0.1:8317 everywhere', description: `${CLI_PROXY_HELP} Import brings your config and logins over, stops the local copy (one copy refreshes each login), and connects this computer and your machine template. On a second computer it connects that computer.`, positionals: [], options: {
+            config: { type: 'string', value: '<path>', description: 'Your CLIProxyAPI config file (default: the one the running CLIProxyAPI uses, else the usual locations).' },
+            yes: { type: 'boolean', description: 'Stop the local CLIProxyAPI without asking.' },
+        }, examples: ['shard cli-proxy import', 'shard cli-proxy'] },
+    { path: ['cli-proxy', 'export'], summary: 'Bring your logins back to this computer and stop the hosted CLIProxyAPI', description: 'The hosted copy stops first, so only this computer refreshes your logins from then on. Its logins, as last refreshed, go to the auth folder the import took them from (0600), this computer stops forwarding 127.0.0.1:8317, and the command that starts your local CLIProxyAPI is shown. shard cli-proxy import moves them back.', positionals: [], options: {
+            yes: { type: 'boolean', description: 'Do it without asking.' },
+        } },
+    { path: ['cli-proxy', 'forward'], hidden: true, summary: 'Forward 127.0.0.1:8317 to your hosted CLIProxyAPI (started at login)', positionals: [], options: {} },
+];
 /** Every command: the account plane first (sign in, set up), then the project-key commands. */
 const MENUBAR_COMMANDS = ['start', 'stop', 'status'].map(action => ({
     path: ['menubar', action], summary: `${action === 'start' ? 'Install and start' : action === 'stop' ? 'Stop' : 'Show'} the macOS menu bar app`,
     positionals: [], options: { login: { type: 'string', value: '<on|off>', description: 'Enable or disable launch at login.' } },
 }));
-export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...AGENT_COMMANDS, ...AGENT_CREDENTIAL_COMMANDS, ...MENUBAR_COMMANDS, ...KEY_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
+export const COMMANDS = [...ACCOUNT_COMMANDS.filter((c) => c.path[0] !== 'templates'), ...AGENT_COMMANDS, ...AGENT_CREDENTIAL_COMMANDS, ...CLI_PROXY_COMMANDS, ...MENUBAR_COMMANDS, ...KEY_COMMANDS, ...ACCOUNT_COMMANDS.filter((c) => c.path[0] === 'templates')];
 const GROUPS = {
+    device: 'Local device approvals',
+    'cli-proxy': 'Your hosted CLIProxyAPI, reachable at http://127.0.0.1:8317 on this computer and in every VM',
     menubar: 'macOS menu bar app',
     conversations: 'Project conversations, branches and messages',
     agents: 'Cloud agent sessions and copied credentials',
@@ -1433,6 +1471,8 @@ export function parseCommandLine(argv, options = {}) {
     // `menubar refresh` (0.15.2+, not in help): the background step each command may start (menubar.ts).
     if (argv.length === 2 && argv[0] === 'menubar' && argv[1] === 'refresh')
         return { kind: 'run', command: { path: ['menubar', 'refresh'], summary: '', positionals: [], options: {} }, values: {}, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
+    if (argv[0] === 'device-helper' && argv.length === 2 && argv[1] === '--service')
+        return { kind: 'run', command: { path: ['device-helper'], summary: '', positionals: [], options: {} }, values: { service: true }, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
     if (argv.length === 1 && (argv[0] === 'acp' || argv[0] === 'device-helper'))
         return { kind: 'run', command: { path: [argv[0]], summary: '', positionals: [], options: {} }, values: {}, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
     const terminator = argv.indexOf('--');
@@ -1494,8 +1534,8 @@ export function parseCommandLine(argv, options = {}) {
         const path = rest.find((r, i) => !r.startsWith('-') && !GLOBAL_VALUE_FLAGS.has(rest[i - 1] ?? ''));
         if (path !== undefined && (/^(?:\.|\/|~\/)/.test(path) || options.isProjectPath?.(path)))
             command = PROJECT_COMMAND;
-        else if (path === undefined && !wantsHelp && !head.includes('--version') && !head.includes('-V') && (options.tty || head.includes('--json')))
-            command = CENTER_COMMAND;
+        else if (path === undefined && !wantsHelp && !head.includes('--version') && !head.includes('-V') && ((options.platform ?? process.platform) === 'linux' || options.tty || head.includes('--json')))
+            command = (options.platform ?? process.platform) === 'linux' && !head.includes('--json') ? ONBOARDING_COMMAND : CENTER_COMMAND;
     }
     if (!command) {
         if (words.length === 0) {
@@ -1623,7 +1663,7 @@ export function commandHelp(c) {
 export function groupHelp(prefix) {
     const words = typeof prefix === 'string' ? [prefix] : [...prefix];
     const group = words.join(' ');
-    const cmds = COMMANDS.filter((c) => words.every((w, i) => c.path[i] === w));
+    const cmds = COMMANDS.filter((c) => !c.hidden && words.every((w, i) => c.path[i] === w));
     const w = Math.max(...cmds.map((c) => usageLine(c).length));
     return [`Usage: shard ${group} <command> [options]`, '', `${GROUPS[group] ?? GROUPS[words[0]] ?? ''}.`, '', 'Commands:', ...cmds.map((c) => `  ${usageLine(c).padEnd(w)}  ${c.summary}`), ...(group === 'workspaces' ? ['', 'Also: shard workspaces files <read|write|ls|stat|search|patch> ..., shard workspaces operations <list|get|wait> ... and shard workspaces executions get ...'] : []), '', `Run "shard ${group} <command> --help" for details.`].join('\n') + '\n';
 }
@@ -1641,14 +1681,14 @@ export const EXIT_CODE_HELP = [
 /** The top help's sections: every command's group (first word) is in exactly one (args.test.ts checks). */
 export const HELP_SECTIONS = [
     { title: 'Account (a user session: shard signup or shard auth login)', groups: ['signup', 'verify', 'auth', 'setup', 'env', 'orgs', 'projects', 'api-keys', 'members', 'invitations', 'billing', 'audit', 'account'] },
-    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'machine', 'template', 'agents', 'ssh-proxy'] },
+    { title: 'Cloud agents (shard ./ starts one; a project API key)', groups: ['conversations', 'machine', 'template', 'agents', 'device', 'cli-proxy', 'ssh-proxy'] },
     { title: 'Workspaces for your app (a project API key: SHARDFLUX_API_KEY, else the one shard setup saved)', groups: ['login', 'whoami', 'status', 'usage', 'workspaces', 'files', 'operations', 'executions', 'secrets', 'credentials', 'volumes', 'egress'] },
     { title: 'Templates for your app’s workspaces (not for cloud agents; publish and archive use the session, the rest the API key)', groups: ['templates'] },
     { title: 'Other', groups: ['menubar', 'update', 'feedback', 'version'] },
 ];
 export function topHelp() {
     const w = Math.max(...COMMANDS.map((c) => usageLine(c).length));
-    const sections = HELP_SECTIONS.flatMap((s) => ['', `${s.title}:`, ...s.groups.flatMap((g) => COMMANDS.filter((c) => c.path[0] === g)).map((c) => `  ${usageLine(c).padEnd(w)}  ${c.summary}`)]);
+    const sections = HELP_SECTIONS.flatMap((s) => ['', `${s.title}:`, ...s.groups.flatMap((g) => COMMANDS.filter((c) => c.path[0] === g && !c.hidden)).map((c) => `  ${usageLine(c).padEnd(w)}  ${c.summary}`)]);
     return [
         `shard ${CLI_VERSION} — the Shardflux command line (built on @shardflux/sdk)`,
         '',

package/dist/cli-proxy-forward.d.ts

@@ -0,0 +1,45 @@
+import type { HubInfo } from './cli-proxy-hub.js';
+export declare const REPLAY_LIMIT: number;
+/** The forwarder answers this path itself (paths under /__shardflux/ are reserved by the edge, so no hub route is lost). */
+export declare const IDENTITY_PATH = "/__shardflux/forwarder";
+export interface ForwarderOptions {
+    /** The current hub info, read on every request (cheap: hubInfoSource caches by mtime). */
+    hub: () => HubInfo | null;
+    /** Starts CLIProxyAPI in the hub again (after `port_not_listening`). At most one runs at a time. */
+    repair?: () => Promise<void>;
+    /**
+     * Replaces the hub's callback URLs after the edge answers `callback_invalid` (the API key that created them was
+     * revoked) and gives VMs the new one. At most one runs at a time and at most one a minute; each request is renewed
+     * for once, so a URL that stays invalid is answered as is.
+     */
+    renew?: () => Promise<void>;
+    host?: string;
+    port?: number;
+    /** How long one request may be retried for (default 60 s, plus the time a repair takes). */
+    retryBudgetMs?: number;
+    /** Between attempts to bind a port another process holds (default 5 s). */
+    bindRetryMs?: number;
+    log?: (line: string) => void;
+    sleep?: (ms: number) => Promise<void>;
+    /** Request bodies kept for a retry, in bytes (default REPLAY_LIMIT); a larger body streams and is not retried. */
+    replayLimit?: number;
+}
+/** The hub info file, re-read when it changes (a replaced callback URL takes effect on the next request). */
+export declare function hubInfoSource(dir: string): () => HubInfo | null;
+export declare class CliProxyForwarder {
+    #private;
+    constructor(opts: ForwarderOptions);
+    get address(): {
+        host: string;
+        port: number;
+    } | null;
+    /**
+     * Listens on host:port. While another program holds the port (also one listening on all interfaces, which a
+     * loopback bind would not notice), logs once and tries again every bindRetryMs (until close()); resolves once
+     * listening.
+     */
+    listen(): Promise<void>;
+    /** Closes the idle keep-alive connections to the edge (the next request opens a fresh one). */
+    dropIdleConnections(): void;
+    close(): Promise<void>;
+}