@shardflux/cli 0.15.2 → 0.17.0

package/dist/agent-commands.js

@@ -1,3 +1,5 @@
+import { linuxTerminalSession, openLinuxTerminal } from "./linux-terminal.js";
+import { repositoryName } from "./files-mirror.js";
 import { prepareSetupCache } from "./setup-cache.js";
 import { launchCodexCloud, openCodexConversation } from "./codex-cloud.js";
 import { agentReachability } from "./agent-reachability.js";
@@ -22,10 +24,12 @@ import { progress } from "./progress.js";
 import { rememberLaunch } from "./agent-live.js";
 import { prepareAgentMachine } from "./agent-machine.js";
 import { installedTargets } from "./agent-targets.js";
+import { openInFor } from "./t3-mode.js";
 import { openClaudeDesktopSession, openDesktopWorkspace, queueT3Prewarm } from "./agent-target-commands.js";
 import { submitInitialPrompt, prepareInitialCodexProject } from "./initial-prompt.js";
 import { conversationWorkspace, conversationsUnavailable, getConversation, listConversations, resumeConversation } from "./conversations.js";
 import { conversationTerminal } from "./conversation-terminal.js";
+import { CHOICE_PENDING, choiceReport, hasChoice, launchChoice, modelChoice, runFlags } from "./agent-models.js";
 const active = (session) => session.state === 'running' || session.state === 'starting';
 /** `<slug>-<6 hex of sha256(identity)>`: the same repository gets the same key on every machine. */
 export function disambiguatedSlug(slug, identity) {
@@ -47,7 +51,9 @@ export async function projectTemplate(ctx, remote) {
         throw error;
     }
 }
-export async function agentPty(cell, app, agent, approvals, term, signal, project, setupHash, cwd, ptyName, onLaunch, deferSetup = false, conversation) {
+/** `place` is the repository or folder name session titles end with ("todo-app"), `task` what a new session is titled
+ * with before the guest names it from its first prompt (a first prompt line or the conversation's title). */
+export async function agentPty(cell, app, agent, approvals, term, signal, place, setupHash, cwd, ptyName, onLaunch, deferSetup = false, conversation, task, launch) {
     const id = `shard-${ptyName || agent}-${app}`;
     // Arrival and changed locks queue the same durable guest job even when the
     // native agent is already alive. Setup never becomes its first user turn.
@@ -68,18 +74,19 @@ export async function agentPty(cell, app, agent, approvals, term, signal, projec
     onLaunch?.();
     let conversationArgs = [];
     if (conversation) {
-        const help = await cell.exec.run(['sf-agent', 'run', app, '--help'], { timeoutMs: 10_000, maxOutputBytes: 8192, signal });
-        if ((help.stdout + help.stderr).includes('-conversation'))
+        const help = await (launch?.help ?? runHelp(cell, app, signal))();
+        if (help.includes('-conversation'))
             conversationArgs = ['--conversation', conversation.id, ...(conversation.session ? ['--resume-session', conversation.session] : [])];
     }
-    const launch = await cell.exec.run(['sf-agent', 'run', app, '--name', agent, '--detach', ...conversationArgs, ...(ptyName ? ['--pty-name', ptyName] : []), ...(approvals ? ['--approvals'] : []), ...(setupHash ? ['--setup', '--setup-deps-hash', setupHash] : [])], {
-        env: { TERM: term, ...(project ? { SF_PROJECT_NAME: project } : {}), ...(setupHash && deferSetup ? { SF_SETUP_DEFERRED: '1' } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
+    // A model and effort choice reaches only a guest whose run accepts it (the caller checked).
+    const started = await cell.exec.run(['sf-agent', 'run', app, '--name', agent, '--detach', ...conversationArgs, ...(ptyName ? ['--pty-name', ptyName] : []), ...(approvals ? ['--approvals'] : []), ...(setupHash ? ['--setup', '--setup-deps-hash', setupHash] : []), ...runFlags(launch?.choice)], {
+        env: { TERM: term, ...(place ? { SF_PROJECT_NAME: place, SF_REPO_NAME: place } : {}), ...(task ? { SF_TASK_TITLE: task } : {}), ...(setupHash && deferSetup ? { SF_SETUP_DEFERRED: '1' } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
     });
-    if (launch.exitCode !== 0)
-        throw new Error(`agent launch failed: ${launch.stderr.trim() || `exit ${launch.exitCode}`}`);
+    if (started.exitCode !== 0)
+        throw new Error(`agent launch failed: ${started.stderr.trim() || `exit ${started.exitCode}`}`);
     let result;
     try {
-        result = JSON.parse(launch.stdout);
+        result = JSON.parse(started.stdout);
     }
     catch {
         throw new Error('agent launcher returned invalid JSON');
@@ -91,7 +98,18 @@ export async function agentPty(cell, app, agent, approvals, term, signal, projec
         throw new Error(`agent exited before attach: ${session.state}`);
     return session;
 }
+/** `sf-agent run <app> --help` of this computer's guest, read at most once per launch. */
+function runHelp(cell, app, signal) {
+    let text;
+    return () => text ??= cell.exec.run(['sf-agent', 'run', app, '--help'], { timeoutMs: 10_000, maxOutputBytes: 8192, signal }).then(r => r.stdout + r.stderr);
+}
+/** The first non-empty line of a prompt or title, bounded; the guest makes it the task part of the session title. */
+export function sessionTask(text) {
+    const line = text?.split(/\r?\n/).map(l => l.replace(/[\s\p{Cc}]+/gu, ' ').trim()).find(Boolean);
+    return line ? [...line].slice(0, 200).join('') : undefined;
+}
 export async function terminal(ctx, ws, app, agent, project, values, setupHash, cwd = workspaceRepositoryPath(ws), conversation) {
+    const ptyName = conversation?.pty ?? ws.labels.agent_pty_name;
     const store = new AgentStateStore(ctx.store.dir);
     if (!ws.ready)
         await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
@@ -101,12 +119,18 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
     const tunnels = attach ? await startAgentConfigTunnels(ctx, ws) : null;
     try {
         if (app === 'codex' && typeof values.initialPrompt === 'string') {
-            await prepareInitialCodexProject(cell, cwd, `shard-${ws.labels.agent_pty_name || agent}-${app}`);
+            await prepareInitialCodexProject(cell, cwd, `shard-${ptyName || agent}-${app}`);
         }
         const credentialFill = await configureCredentialFill(ctx, ws);
+        // This command's --model/--effort, else the conversation's own (a relaunch keeps its model). A computer whose guest
+        // predates the choice starts the agent with its defaults, and this command says so once.
+        const help = runHelp(cell, app, ctx.signal), explicit = modelChoice(values, app);
+        const { choice, applied } = await launchChoice(explicit, conversation?.choice, !!conversation, help);
+        if (hasChoice(explicit) && !applied && !ctx.json)
+            ctx.io.stderr.write(`${CHOICE_PENDING}\n`);
         // A cold launch is remembered before it starts, so the listing can show it before the projection does (agent-live.ts).
         const term = ctx.io.env.TERM && ctx.io.env.TERM !== 'dumb' ? ctx.io.env.TERM : 'xterm-256color';
-        const session = await agentPty(cell, app, agent, values.approvals === true, term, ctx.signal, ws.labels.shard_project || ws.key.split('/')[0], setupHash, cwd, ws.labels.agent_pty_name, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); }, true, conversation);
+        const session = await agentPty(cell, app, agent, values.approvals === true, term, ctx.signal, repositoryName(ws.labels.repo_remote || project), setupHash, cwd, ptyName, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); }, true, conversation && { id: conversation.id, session: conversation.session }, sessionTask(typeof values.initialPrompt === 'string' ? values.initialPrompt : conversation?.title), { ...(choice ? { choice } : {}), help });
         // A new conversation's guest can start the agent before this command reaches it, so the launch above never ran.
         // Remember it either way: listing and `agents open` then read the guest until the projection lists the session.
         rememberLaunch(ctx, ws.id);
@@ -126,7 +150,10 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
         }
         if (!attach) {
             await preparation;
-            ctx.io.stdout.write(json({ workspace: ws.data, session, ...(typeof values.initialPrompt === 'string' ? { initial_prompt: { submitted: true } } : {}) }));
+            // conversation (0.16.0+): which conversation this session is, also when its computer hosts several threads.
+            // model_choice (0.17.0+): the requested model and effort, and whether this thread started with them.
+            ctx.io.stdout.write(json({ workspace: ws.data, session, ...(conversation ? { conversation: { id: conversation.id } } : {}), ...(typeof values.initialPrompt === 'string' ? { initial_prompt: { submitted: true } } : {}),
+                ...(hasChoice(explicit) ? { model_choice: choiceReport(explicit, applied) } : {}) }));
             return 0;
         }
         ctx.io.stderr.write(`Shardflux · ${ws.key}\nDetach: Ctrl-] then d\n`);
@@ -167,7 +194,9 @@ async function syncCredentials(ctx) {
             throw new Error('agent credentials sync failed');
     }
 }
-export const launchProject = async (ctx, values, [path = './', explicitApp]) => {
+export const launchProject = (ctx, values, args) => launchProjectWith(ctx, values, args);
+/** The project VM launch; with `--in t3` a first message becomes a thread on the T3 server in it (SSH mode, 0.17.0+). */
+export async function launchProjectWith(ctx, values, [path = './', explicitApp], thread, install) {
     if (explicitApp && explicitApp !== 'claude' && explicitApp !== 'codex')
         throw new UsageError('agent app must be claude or codex');
     let like = typeof values.like === 'string' ? await resolveWorkspace(ctx, values.like) : undefined;
@@ -179,8 +208,12 @@ export const launchProject = async (ctx, values, [path = './', explicitApp]) =>
     if (target && (!['claude-desktop', 'codex-app', 't3'].includes(target) || !detected?.targets.includes(target)))
         throw new UsageError(`${target} is not an installed desktop target`);
     const app = explicitApp ?? store.app(projectKey, like?.labels.app === 'codex' ? 'codex' : 'claude');
-    if (target === 'codex-app' || (app === 'codex' && !like && values.in === undefined))
+    // A typo in --model or --effort is refused before anything starts; T3 Code reads the same values (0.17.0+).
+    const choice = modelChoice(values, target === 'codex-app' ? 'codex' : app);
+    if (target === 'codex-app' || (app === 'codex' && !like && values.in === undefined && !linuxTerminalSession(ctx, values)))
         return launchCodexCloud(ctx, values, path);
+    if (target === 'claude-desktop' && hasChoice(choice))
+        ctx.io.stderr.write('Claude Desktop starts the session with the model chosen in the app.\n');
     const agent = typeof values.name === 'string' ? values.name : 'main';
     if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(agent))
         throw new UsageError('agent name must match ^[a-z0-9][a-z0-9._-]{0,63}$');
@@ -226,8 +259,13 @@ export const launchProject = async (ctx, values, [path = './', explicitApp]) =>
         await queueT3Prewarm(ctx, ws, detected.versions.t3);
     if (app === 'claude' && !claudeReady)
         await loginClaudeInWorkspace(ctx, ws);
+    // T3 lists both agents; a Codex project still opens when Claude is not signed in (T3 shows Claude as signed out).
     if (target === 't3' && app === 'codex')
-        await ensureCloudClaude(ctx, ws);
+        await ensureCloudClaude(ctx, ws).catch((error) => {
+            if (!(error instanceof UsageError))
+                throw error;
+            ctx.io.stderr.write(`Claude Code in T3: ${error.message}\n`);
+        });
     if (!(await savedMachine(ctx))?.template)
         await syncAgentConfig(ctx, ws);
     // Seed once; two-way sync is scoped to explicit Try locally worktrees.
@@ -241,15 +279,17 @@ export const launchProject = async (ctx, values, [path = './', explicitApp]) =>
                 throw new Error(`project setup could not be queued: ${setup.stderr.trim() || `exit ${setup.exitCode}`}`);
         }
         store.saveTarget(projectKey, target);
-        return openDesktopWorkspace(ctx, ws, target, detected?.versions.t3, true);
+        return openDesktopWorkspace(ctx, ws, target, detected?.versions.t3, true, thread, install);
     }
     await prepareAgentMachine(ctx, ws);
     return await terminal(ctx, ws, app, agent, projectKey, values, prepared?.setupHash);
-};
+}
 export const AGENT_HANDLERS = {
     async 'agents open'(ctx, values, [agent = 'main']) {
         if (values.app !== undefined && values.app !== 'claude' && values.app !== 'codex')
             throw new UsageError('--app must be claude or codex');
+        if (process.platform === 'linux' && !ctx.json && !ctx.io.stdin.isTTY && values.detach !== true && (values.in === undefined || values.in === 'terminal'))
+            return openLinuxTerminal(ctx, agent, typeof values.app === 'string' ? values.app : undefined);
         let resolvedConversation;
         if (/^conv_[a-z0-9]{26}$/.test(agent)) {
             resolvedConversation = await getConversation(ctx, agent);
@@ -258,19 +298,40 @@ export const AGENT_HANDLERS = {
         }
         if (values.in === 'auto') {
             // The menu and other launchers use the same CLI-owned target selection. Never put provider URLs in a client.
-            const ws = await resolveWorkspace(ctx, agent);
+            // A conversation id opens that conversation's own session, also when its computer hosts other threads.
+            const ws = resolvedConversation ? await conversationWorkspace(ctx, resolvedConversation) : await resolveWorkspace(ctx, agent);
             const project = ws.labels.repo_remote || ws.labels.shard_project || ws.key;
             const store = new AgentStateStore(ctx.store.dir);
-            const app = values.app ?? ws.labels.shard_app ?? ws.labels.app ?? store.app(project);
+            const app = values.app ?? resolvedConversation?.harness ?? ws.labels.shard_app ?? ws.labels.app ?? store.app(project);
             const detected = installedTargets(ctx.io.env);
-            const saved = store.read().projects?.[project]?.target ??
+            // open_in (0.17.0+): a choice saved with `agents targets --open-in`, or T3 when it is the default, comes first.
+            // A conversation opens as itself (its id and session), as the fallbacks below open it.
+            const choice = app === 'claude' || app === 'codex' ? openInFor(ctx, ws.labels.shard_project || ws.key.split('/')[0], { clients: detected.clients })[app] : undefined;
+            const chosen = choice && (choice.saved || choice.target === 't3') ? choice.target : undefined;
+            const opened = resolvedConversation?.id ?? ws.key;
+            if (chosen === 't3' || chosen === 'web') {
+                const { HANDLERS } = await import("./handlers.js");
+                return HANDLERS[`agents open ${chosen}`](ctx, { ...values, in: chosen }, [opened]);
+            }
+            if (chosen === 'claude-desktop' && app === 'claude')
+                return openClaudeDesktopSession(ctx, ws, resolvedConversation);
+            if (chosen === 'terminal' && app === 'claude') {
+                if (ctx.json) {
+                    out(ctx, `shard agents open ${opened}\n`, { target: 'terminal', workspace: ws.data, command: ['shard', 'agents', 'open', opened] });
+                    return 0;
+                }
+                const next = { ...values };
+                delete next.in;
+                return AGENT_HANDLERS['agents open'](ctx, next, [opened]);
+            }
+            const saved = chosen === 'codex-app' ? undefined : store.read().projects?.[project]?.target ??
                 (project.startsWith('file://') ? store.read().projects?.[new URL(project).pathname]?.target : undefined);
             // Codex's default open implementation owns Cloud/desktop routing. PAS-XB replaces that path; do not pin
             // the menu to the old per-VM SSH target. An explicit saved desktop target still takes precedence.
             if ((!saved || !detected.targets.includes(saved)) && app === 'codex') {
                 const next = { ...values };
                 delete next.in;
-                return AGENT_HANDLERS['agents open'](ctx, next, [ws.key]);
+                return AGENT_HANDLERS['agents open'](ctx, next, [resolvedConversation?.id ?? ws.key]);
             }
             if (saved && detected.targets.includes(saved)) {
                 const { HANDLERS } = await import("./handlers.js");
@@ -282,16 +343,16 @@ export const AGENT_HANDLERS = {
             // Claude opens where people work (0.15.1+): the conversation in Claude Desktop when it is installed, else Claude
             // Code in a terminal. The browser (claude.ai) only when it is the chosen target (--in web).
             if (detected.clients.includes('claude-desktop')) {
-                return openClaudeDesktopSession(ctx, ws);
+                return openClaudeDesktopSession(ctx, ws, resolvedConversation);
             }
             if (ctx.json) {
                 // An app runs this in the person's terminal (the menu bar opens Terminal with it).
-                out(ctx, `shard agents open ${ws.key}\n`, { target: 'terminal', workspace: ws.data, command: ['shard', 'agents', 'open', ws.key] });
+                out(ctx, `shard agents open ${opened}\n`, { target: 'terminal', workspace: ws.data, command: ['shard', 'agents', 'open', opened] });
                 return 0;
             }
             const next = { ...values };
             delete next.in;
-            return AGENT_HANDLERS['agents open'](ctx, next, [ws.key]);
+            return AGENT_HANDLERS['agents open'](ctx, next, [opened]);
         }
         if (values.in !== undefined && values.in !== 'terminal') {
             const { HANDLERS } = await import("./handlers.js");

package/dist/agent-models.d.ts

@@ -0,0 +1,61 @@
+import type { Values } from './args.js';
+export type ModelApp = 'claude' | 'codex';
+export interface Choice {
+    id: string;
+    label: string;
+}
+/**
+ * `label` is the menu text, `short` the pill text and `description` what the model is for. A model may take fewer
+ * effort levels than its app (its own `efforts`, ids); without it, all of the app's.
+ */
+export interface ModelOption extends Choice {
+    short: string;
+    description?: string;
+    efforts?: string[];
+}
+/**
+ * `default` names what the agent starts with when no flag is sent, as concrete ids, or null where the agent decides at
+ * start: Claude Code resolves its default model and effort from the account's plan and organization, and Codex its
+ * default effort from the model catalog it fetches with the account's login. A Codex Cloud thread starts with
+ * gpt-6.1-sol (services/guest-agent/internal/codexcloud CloudModel), which is also Codex 0.160.0's first model.
+ */
+export interface AppModels {
+    models: ModelOption[];
+    efforts: Choice[];
+    default: {
+        model: string | null;
+        effort: string | null;
+    };
+}
+export declare const DEFAULT_CHOICE = "default";
+/** Claude Code `--model <alias>` and `--effort <level>`; Codex `-m <model>` and `-c model_reasoning_effort=<level>`. */
+export declare const MODEL_CHOICES: Readonly<Record<ModelApp, AppModels>>;
+/** What a thread starts with: absent fields are the agent's own default (no flag). */
+export interface ModelChoice {
+    model?: string;
+    effort?: string;
+}
+/** `--model` and `--effort` for this app, checked against its list. Throws a usage error for anything else. */
+export declare function modelChoice(values: Values, app: ModelApp): ModelChoice;
+export declare const hasChoice: (c: ModelChoice | undefined) => c is ModelChoice;
+/** The guest's `sf-agent run` flags for a choice (sf-agent maps them to the agent's own flags). */
+export declare function runFlags(c: ModelChoice | undefined): string[];
+/** Whether a guest's `sf-agent run --help` lists the model and effort flags (coding templates from train 14). */
+export declare const runAcceptsChoice: (help: string) => boolean;
+/**
+ * The choice a launch passes (this command's, else the conversation's recorded one, so a relaunch keeps its model) and
+ * whether the thread starts with this command's choice: the computer's guest accepts it and, for a conversation, its
+ * record carries it (the guest starts a conversation's agent from the record).
+ */
+export declare function launchChoice(explicit: ModelChoice, recorded: ModelChoice | undefined, conversation: boolean, help: () => Promise<string>): Promise<{
+    choice?: ModelChoice;
+    applied: boolean;
+}>;
+/** Said once when a computer's platform predates the choice: the thread starts with the agent's defaults. */
+export declare const CHOICE_PENDING = "The model and effort choice applies to new threads after the next platform update; this thread uses the defaults.";
+/** The record the JSON output carries for a requested choice. */
+export declare function choiceReport(c: ModelChoice, applied: boolean): {
+    model: string;
+    effort: string;
+    applied: boolean;
+};

package/dist/agent-models.js

@@ -0,0 +1,79 @@
+import { UsageError } from "./errors.js";
+export const DEFAULT_CHOICE = 'default';
+const DEFAULT_MODEL = { id: DEFAULT_CHOICE, label: 'Default', short: 'Default' };
+const LEVELS = { low: 'Low', medium: 'Medium', high: 'High', xhigh: 'Extra high', max: 'Max', ultra: 'Ultra' };
+const levels = (...ids) => [{ id: DEFAULT_CHOICE, label: 'Default' }, ...ids.map(id => ({ id, label: LEVELS[id] }))];
+/** Claude Code `--model <alias>` and `--effort <level>`; Codex `-m <model>` and `-c model_reasoning_effort=<level>`. */
+export const MODEL_CHOICES = {
+    claude: {
+        // The aliases always name the latest model of each family; descriptions are Claude Code's own.
+        models: [DEFAULT_MODEL,
+            { id: 'fable', label: 'Fable', short: 'Fable', description: 'For your toughest challenges' },
+            { id: 'opus', label: 'Opus', short: 'Opus', description: 'Most capable for ambitious work' },
+            { id: 'sonnet', label: 'Sonnet', short: 'Sonnet', description: 'Most efficient for everyday tasks' },
+            { id: 'haiku', label: 'Haiku', short: 'Haiku', description: 'Fastest for quick answers' }],
+        efforts: levels('low', 'medium', 'high', 'xhigh', 'max'),
+        default: { model: null, effort: null },
+    },
+    codex: {
+        // Descriptions are Codex's own model catalog.
+        models: [DEFAULT_MODEL,
+            { id: 'gpt-6.1-sol', label: 'GPT-6.1 Sol', short: 'GPT-6.1 Sol', description: 'Latest workhorse model for coding and everyday work' },
+            { id: 'gpt-6-astra', label: 'GPT-6 Astra', short: 'GPT-6 Astra', description: 'Frontier intelligence for the most demanding work' },
+            { id: 'gpt-6-luna', label: 'GPT-6 Luna', short: 'GPT-6 Luna', description: 'Fast and affordable model for easier tasks', efforts: [DEFAULT_CHOICE, 'low', 'medium', 'high', 'xhigh', 'max'] }],
+        efforts: levels('low', 'medium', 'high', 'xhigh', 'max', 'ultra'),
+        default: { model: 'gpt-6.1-sol', effort: null },
+    },
+};
+const list = (ids) => ids.length > 1 ? `${ids.slice(0, -1).join(', ')} or ${ids.at(-1)}` : ids[0];
+const label = (app) => app === 'claude' ? 'Claude' : 'Codex';
+/** `--model` and `--effort` for this app, checked against its list. Throws a usage error for anything else. */
+export function modelChoice(values, app) {
+    const raw = (name) => {
+        const value = values[name];
+        if (value === undefined)
+            return undefined;
+        if (typeof value !== 'string' || !value.trim())
+            throw new UsageError(`--${name} needs a value.`);
+        return value.trim().toLowerCase();
+    };
+    const model = raw('model'), effort = raw('effort'), choices = MODEL_CHOICES[app];
+    const option = model === undefined ? undefined : choices.models.find(m => m.id === model);
+    if (model !== undefined && !option)
+        throw new UsageError(`${label(app)} models: ${list(choices.models.map(m => m.id))}.`);
+    const allowed = option?.efforts ?? choices.efforts.map(e => e.id);
+    if (effort !== undefined && !allowed.includes(effort)) {
+        throw new UsageError(`${option?.efforts ? option.label : label(app)} effort levels: ${list(allowed)}.`);
+    }
+    return {
+        ...(model && model !== DEFAULT_CHOICE ? { model } : {}),
+        ...(effort && effort !== DEFAULT_CHOICE ? { effort } : {}),
+    };
+}
+export const hasChoice = (c) => !!(c?.model || c?.effort);
+/** The guest's `sf-agent run` flags for a choice (sf-agent maps them to the agent's own flags). */
+export function runFlags(c) {
+    return [...(c?.model ? ['--model', c.model] : []), ...(c?.effort ? ['--effort', c.effort] : [])];
+}
+/** Whether a guest's `sf-agent run --help` lists the model and effort flags (coding templates from train 14). */
+export const runAcceptsChoice = (help) => /-model\b/.test(help) && /-effort\b/.test(help);
+/**
+ * The choice a launch passes (this command's, else the conversation's recorded one, so a relaunch keeps its model) and
+ * whether the thread starts with this command's choice: the computer's guest accepts it and, for a conversation, its
+ * record carries it (the guest starts a conversation's agent from the record).
+ */
+export async function launchChoice(explicit, recorded, conversation, help) {
+    const choice = hasChoice(explicit) ? explicit : recorded;
+    if (!hasChoice(choice))
+        return { applied: true };
+    // A guest that cannot say what it accepts gets no flags: the thread starts either way.
+    const accepted = runAcceptsChoice(await help().catch(() => ''));
+    const kept = !conversation || !hasChoice(explicit) || (recorded?.model === explicit.model && recorded?.effort === explicit.effort);
+    return { ...(accepted ? { choice } : {}), applied: accepted && kept };
+}
+/** Said once when a computer's platform predates the choice: the thread starts with the agent's defaults. */
+export const CHOICE_PENDING = 'The model and effort choice applies to new threads after the next platform update; this thread uses the defaults.';
+/** The record the JSON output carries for a requested choice. */
+export function choiceReport(c, applied) {
+    return { model: c.model ?? DEFAULT_CHOICE, effort: c.effort ?? DEFAULT_CHOICE, applied };
+}

package/dist/agent-state.d.ts

@@ -12,6 +12,16 @@ export declare class AgentStateStore {
     read(): State;
     app(project: string, fallback?: 'claude' | 'codex'): 'claude' | 'codex';
     target(project: string, available: string[]): string;
+    /** T3 Code environments set up from this computer (the SSH route): targets.json keeps T3 out of its manifest. */
+    t3Environments(apiUrl: string): Array<{
+        workspace: string;
+        host: string;
+    }>;
+    saveT3Environment(entry: {
+        workspace: string;
+        host: string;
+        api_url: string;
+    }): void;
     saveTarget(project: string, target: string): void;
     update(change: (state: State) => void): void;
     save(project: string, app: 'claude' | 'codex'): void;

package/dist/agent-state.js

@@ -28,6 +28,19 @@ export class AgentStateStore {
         const target = this.read().projects?.[project]?.target;
         return target && available.includes(target) ? target : available.includes('t3') ? 't3' : 'terminal';
     }
+    /** T3 Code environments set up from this computer (the SSH route): targets.json keeps T3 out of its manifest. */
+    t3Environments(apiUrl) {
+        const list = this.read().t3;
+        return (Array.isArray(list) ? list : []).filter((e) => !!e && typeof e === 'object' && typeof e.workspace === 'string' && typeof e.host === 'string'
+            && e.api_url === apiUrl).map(({ workspace, host }) => ({ workspace, host }));
+    }
+    saveT3Environment(entry) {
+        this.update(doc => {
+            const list = (Array.isArray(doc.t3) ? doc.t3 : []);
+            // The newest last: the onboarding card names the one most recently set up.
+            doc.t3 = [...list.filter(e => !(e.host === entry.host && e.api_url === entry.api_url)), entry];
+        });
+    }
     saveTarget(project, target) {
         this.update(doc => {
             doc.projects ??= {};

package/dist/agent-target-commands.d.ts

@@ -1,8 +1,10 @@
 import { Duplex } from 'node:stream';
 import type { CellClient, Workspace } from '@shardflux/sdk';
+import type { Conversation } from './conversations.js';
 import type { Ctx, Handler, Io } from './commands.js';
 import { AgentTargets } from './agent-targets.js';
 import type { DesktopTarget } from './agent-targets.js';
+import type { T3Install, T3ThreadRequest } from './t3-mode.js';
 /** Optimistic file replacement preserves keys installed by other devices connecting at the same time. */
 export declare function installDeviceKey(cell: CellClient, key: string, signal?: AbortSignal): Promise<void>;
 /** Host trust is established over the authenticated files API, before sending any SSH protocol bytes. */
@@ -13,7 +15,11 @@ export declare function proxyStream(io: Io, ended?: () => void, outputGate?: Pro
  * this computer just started can accept its first prompt before Remote Control registers, so an open of our recent
  * launch probes the guest for up to 30 s; history browsing stays passive.
  */
-export declare function remoteControlUrl(ctx: Ctx, ws: Workspace): Promise<string>;
+/**
+ * The Claude Remote Control URL of a session in `ws`. With several threads on one computer (0.16.0+) a conversation's
+ * own session is chosen by its harness session id; a thread that has not reported one yet is unambiguous only alone.
+ */
+export declare function remoteControlUrl(ctx: Ctx, ws: Workspace, conversation?: Pick<Conversation, 'harness_session_id'>): Promise<string>;
 /** Claude Desktop's own link to a Remote Control session: claude://code/<session id> opens it in its Code tab. */
 export declare function claudeDesktopLink(remoteControl: string): string;
 export declare const CLAUDE_DESKTOP_BUNDLE = "com.anthropic.claudefordesktop";
@@ -21,7 +27,11 @@ export declare const CLAUDE_DESKTOP_BUNDLE = "com.anthropic.claudefordesktop";
  * Opens the conversation itself (its live Remote Control session) in Claude Desktop (0.15.1+), the way `--in auto`
  * opens a Claude conversation when Claude Desktop is installed. --json prints {target, url, app_bundle_id} for apps.
  */
-export declare function openClaudeDesktopSession(ctx: Ctx, ws: Workspace): Promise<number>;
-export declare function openDesktopWorkspace(ctx: Ctx, ws: Workspace, target: DesktopTarget, t3Version?: string, prewarmed?: boolean): Promise<number>;
+export declare function openClaudeDesktopSession(ctx: Ctx, ws: Workspace, conversation?: Pick<Conversation, 'harness_session_id'>): Promise<number>;
+/**
+ * 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 declare function openDesktopWorkspace(ctx: Ctx, ws: Workspace, target: DesktopTarget, t3Version?: string, prewarmed?: boolean, thread?: T3ThreadRequest, install?: T3Install, conversation?: string | null): Promise<number>;
 export declare function queueT3Prewarm(ctx: Ctx, ws: Workspace, version: string): Promise<void>;
 export declare const TARGET_HANDLERS: Record<string, Handler>;