@shardflux/cli 0.15.2 → 0.17.0

package/dist/codex-cloud.d.ts

@@ -1,11 +1,14 @@
 import type { CodexCloudTask } from '@shardflux/sdk';
 import type { Ctx, Handler } from './commands.js';
 import type { Values } from './args.js';
+import type { ModelChoice } from './agent-models.js';
 import type { Conversation } from './conversations.js';
 import type { InitialImage } from './initial-prompt.js';
 /** Only provider-returned task ids enter the registered Codex deep-link route. */
 export declare function openCodexThread(task: CodexCloudTask, env: Ctx['io']['env']): Promise<void>;
 export declare function submitCloudInitialPrompt(ctx: Ctx, c: Conversation, prompt: string, workspaceKey: string): Promise<void>;
+/** Prints the Cloud thread (and its link) and opens it in the Codex app; --json prints it instead. */
+export declare function printCloudThread(ctx: Ctx, c: Conversation, task: CodexCloudTask, submitted?: boolean, choice?: ModelChoice): Promise<void>;
 /** How long the account's Codex remote device may take to come up before it counts as stuck. */
 export declare const CODEX_STARTING_LIMIT_MS: number;
 export type CodexConnectorView = {

package/dist/codex-cloud.js

@@ -2,7 +2,8 @@ import { spawn } from 'node:child_process';
 import { CodedError, UsageError } from "./errors.js";
 import { json } from "./format.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
-import { createConversation, resumeConversation } from "./conversations.js";
+import { createConversation, getConversation, recordedChoice, resumeConversation } from "./conversations.js";
+import { CHOICE_PENDING, choiceReport, hasChoice, modelChoice } from "./agent-models.js";
 import { AgentStateStore } from "./agent-state.js";
 import { ensureProjectGit } from "./project-git.js";
 import { gitRunner } from "./agent-git.js";
@@ -32,15 +33,25 @@ export async function submitCloudInitialPrompt(ctx, c, prompt, workspaceKey) {
         throw new CodedError('initial_prompt_failed', `Created ${workspaceKey}, but the initial prompt could not be confirmed. Open that conversation before starting another.`, undefined, { workspace_key: workspaceKey, conversation_id: c.id, submitted: null });
     }
 }
-async function output(ctx, c, task, submitted = false) {
+/** Prints the Cloud thread (and its link) and opens it in the Codex app; --json prints it instead. */
+export async function printCloudThread(ctx, c, task, submitted = false, choice) { return output(ctx, c, task, submitted, choice); }
+async function output(ctx, c, task, submitted = false, choice) {
     const url = threadLink(task);
+    // model_choice (0.17.0+): an admitted thread's record keeps the model and effort only when Cloud started it with them.
+    const applied = hasChoice(choice) ? await cloudChoiceApplied(ctx, c, choice) : true;
     if (ctx.json) {
-        ctx.io.stdout.write(json({ conversation: c, cloud: task, url, ...(submitted ? { initial_prompt: { submitted: true } } : {}) }));
+        ctx.io.stdout.write(json({ conversation: c, cloud: task, url, ...(submitted ? { initial_prompt: { submitted: true } } : {}), ...(hasChoice(choice) ? { model_choice: choiceReport(choice, applied) } : {}) }));
         return;
     }
+    if (!applied)
+        ctx.io.stderr.write(`${CHOICE_PENDING}\n`);
     ctx.io.stdout.write(`${c.key}\n${task.desktop_url}\n`);
     await openCodexThread(task, ctx.io.env);
 }
+async function cloudChoiceApplied(ctx, c, choice) {
+    const kept = recordedChoice(await getConversation(ctx, c.id));
+    return kept.model === choice.model && kept.effort === choice.effort;
+}
 /** How long the account's Codex remote device may take to come up before it counts as stuck. */
 export const CODEX_STARTING_LIMIT_MS = 5 * 60_000;
 /** When a connector generation started: its UUIDv7 time. */
@@ -112,11 +123,12 @@ export async function launchCodexCloud(ctx, values, path, images = []) {
         throw new UsageError('New Codex conversations open in Codex Cloud. Omit --in or use --in codex-app.');
     if (values.like !== undefined)
         throw new UsageError('Choose the project directory with --path; new Codex conversations use its latest machine template.');
+    const choice = modelChoice(values, 'codex');
     const project = projectIdentity(path);
     await ensureProjectGit(ctx, project.folder);
     await gitRunner(project.folder, { ...process.env, ...ctx.io.env }, ctx.signal)(['rev-parse', 'HEAD']);
     await ensureCodexCloud(ctx);
-    const created = await createConversation(ctx, path, 'codex', 'codex-cloud', typeof values.name === 'string' ? values.name : undefined);
+    const created = await createConversation(ctx, path, 'codex', 'codex-cloud', typeof values.name === 'string' ? values.name : undefined, choice);
     const c = created.conversation;
     // --computer: the conversation VM's desktop is on before Codex starts, so the thread gets the computer tools.
     if (values.computer === true)
@@ -130,7 +142,7 @@ export async function launchCodexCloud(ctx, values, path, images = []) {
     const submitted = typeof values.initialPrompt === 'string';
     if (submitted)
         await submitCloudInitialPrompt(ctx, c, values.initialPrompt, created.workspace.key);
-    await output(ctx, c, task, submitted);
+    await output(ctx, c, task, submitted, choice);
     return 0;
 }
 export async function openCodexConversation(ctx, c) {

package/dist/command-center-actions.js

@@ -11,7 +11,9 @@ import { agentName as gitAgentName } from "./agent-git.js";
 import { randomUUID } from 'node:crypto';
 import { prepareAgentMachine } from "./agent-machine.js";
 import { OperationFailedError } from '@shardflux/sdk';
-import { launchConversationProject } from "./conversation-terminal.js";
+import { launchConversationProject, launchProjectCommand } from "./conversation-terminal.js";
+import { startThreadOn } from "./thread-on-computer.js";
+import { launchT3 } from "./t3-launch.js";
 /** L9 can register target-specific handlers after detecting the installed applications. */
 export async function availableTargets(ctx) {
     const { HANDLERS } = await import("./handlers.js");
@@ -34,6 +36,28 @@ export async function agentAction(ctx, action, values, args) {
 }
 export const CENTER_HANDLERS = {
     async 'agents new'(ctx, values, [ref]) {
+        const fresh = !ref && values.name === undefined && values.like === undefined;
+        // T3 Code mode (0.17.0+): --in t3 starts the first message as a T3 thread (--on: on that computer's T3 server);
+        // --in auto opens where open_in says.
+        if (fresh && values.in === 't3')
+            return launchT3(ctx, values, str(values.path) ?? './', str(values.app));
+        if (fresh && values.in === 'auto') {
+            const next = { ...values };
+            delete next.in;
+            return launchProjectCommand(ctx, next, [str(values.path) ?? './', ...(str(values.app) ? [str(values.app)] : [])]);
+        }
+        if (values.in === 'auto') {
+            values = { ...values };
+            delete values.in;
+        }
+        // A thread on an existing conversation's computer (0.16.0+).
+        if (values.on !== undefined) {
+            if (ref || values.like !== undefined)
+                throw new UsageError('--on starts a thread on that conversation’s computer; omit the agent argument and --like.');
+            return startThreadOn(ctx, values, str(values.path) ?? './');
+        }
+        if (values.review === true)
+            throw new UsageError('--review needs --on <conversation>.');
         if ((values.prompt !== undefined || values['prompt-file'] !== undefined || values.image !== undefined) && (ref || values.name !== undefined || values.like !== undefined || values.in !== undefined)) {
             throw new UsageError('An initial prompt needs a new conversation: use agents new --path <folder> --app claude|codex.');
         }

package/dist/commands.d.ts

@@ -31,6 +31,11 @@ export interface Ctx {
     wake: boolean;
     /** Bound on lifecycle waits per cell call, wakes included (--wake-timeout / SHARDFLUX_WAKE_TIMEOUT_MS). */
     wakeTimeoutMs: number;
+    /**
+     * The wake bound was given (--wake-timeout or SHARDFLUX_WAKE_TIMEOUT_MS; 0.16.0+): it is kept as given. Otherwise a
+     * resume queued for capacity is waited for until its deadline, its place shown on stderr.
+     */
+    wakeTimeoutExplicit?: boolean;
     signal: AbortSignal;
     /** --timing: print the SDK's timing of the command's open, wait or wake (stderr; a `timing` field with --json). */
     timing: boolean;
@@ -127,4 +132,21 @@ export declare function ttlSeconds(values: Values, b: {
     max: number;
     range: string;
 }): number | undefined;
+type ThreadRow = import('@shardflux/sdk').Agent & {
+    conversation_id?: string | null;
+    conversation_key?: string;
+};
+/**
+ * Each session's own conversation: the one whose harness session it is, else the computer's only live conversation.
+ * Rows that cannot be told apart keep no conversation rather than another thread's.
+ */
+export declare function withConversations(rows: import('@shardflux/sdk').Agent[], conversations: {
+    id: string;
+    key: string;
+    workspace_id: string;
+    harness_session_id: string | null;
+    state: string;
+    ended_at?: string | null;
+}[] | null): ThreadRow[];
 export declare const KEY_HANDLERS: Record<string, Handler>;
+export {};

package/dist/commands.js

@@ -12,7 +12,7 @@ import { agentConfigLikeSecrets, syncAgentConfig } from "./agent-config-sync.js"
 import { randomUUID } from 'node:crypto';
 import { access, readFile, writeFile } from 'node:fs/promises';
 import { basename, dirname, resolve as resolvePath } from 'node:path';
-import { EXECUTION_ID, ExecStartError, FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH, NotSupportedForModeError, SDK_VERSION, ShardfluxApiError, ShardfluxProtocolError, newExecutionId, exitCodePosix } from '@shardflux/sdk';
+import { EXECUTION_ID, ExecStartError, capacityOf, FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH, NotSupportedForModeError, SDK_VERSION, ShardfluxApiError, ShardfluxProtocolError, newExecutionId, exitCodePosix } from '@shardflux/sdk';
 import { parse as parseYaml } from 'yaml';
 import { CLI_VERSION, SECRET_NAME, UUID, parseDuration, parseEnvPairs, parsePositiveInt } from "./args.js";
 import { ExecSessionRunningError, ExecutionFailedError, ExecutionPendingError, InterruptedError, NotFoundError, UsageError } from "./errors.js";
@@ -32,7 +32,15 @@ export const str = (v) => (typeof v === 'string' ? v : undefined);
  * The workspace's cell client as this invocation configures it: the CLI's agent label, wake on use unless turned off,
  * and the wake timeout (an OperationTimeoutError past it exits 5).
  */
-const cellOf = (ctx, ws) => ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs, ...(ctx.wake ? {} : { wake: null }) });
+const cellOf = (ctx, ws) => ws.cell({
+    agentLabel: ctx.agentLabel,
+    transitionTimeoutMs: ctx.wakeTimeoutMs,
+    ...(!ctx.wake
+        ? { wake: null }
+        : ctx.wakeTimeoutExplicit
+            ? { wake: (timeoutMs, signal) => ws.wake({ timeoutMs, ...(signal ? { signal } : {}), agentLabel: ctx.agentLabel, untilCapacityDeadline: false }) }
+            : {}),
+});
 export const strs = (v) => (Array.isArray(v) ? v : typeof v === 'string' ? [v] : []);
 const MAX_SECRET_VALUE_BYTES = 65_536;
 /** `files patch --content-file`: a patch request is at most 7 MiB; larger files go through `files write`. */
@@ -357,10 +365,17 @@ async function writeNew(path, text, force) {
         throw new UsageError(`${path} exists; pass --force to overwrite it`);
     await writeFile(path, text);
 }
+/**
+ * An explicit `--timeout` is kept as given (0.16.0+): without one, a wait whose start is queued for capacity keeps waiting
+ * until the start's deadline (the SDK's `untilCapacityDeadline`), printing where it stands on stderr.
+ */
+function capacityWait(values) {
+    return values !== undefined && str(values.timeout) !== undefined ? { untilCapacityDeadline: false } : {};
+}
 /** Waits with the SDK's backoff; Ctrl-C reports the operation that keeps running. */
-async function waitOperation(ctx, operationId, timeoutMs) {
+async function waitOperation(ctx, operationId, timeoutMs, values) {
     try {
-        return await ctx.cloud().workspaces.waitForOperation(operationId, { timeoutMs, signal: ctx.signal });
+        return await ctx.cloud().workspaces.waitForOperation(operationId, { timeoutMs, signal: ctx.signal, ...capacityWait(values) });
     }
     catch (err) {
         if (ctx.signal.aborted)
@@ -782,7 +797,28 @@ function reportExecution(ctx, ref, r, opts) {
 }
 function lifecycleText(verb, w, op) {
     const finished = op.state === 'succeeded' || op.state === 'failed' || op.state === 'canceled';
-    return `${verb} ${w.key !== undefined ? `${w.key} (${w.id})` : w.id}: operation ${op.id} ${op.kind} ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''}\n${finished ? durableText(op) : `wait with: shard operations wait ${op.id}\n`}`;
+    // A start queued for capacity (0.16.0+): its place in the queue.
+    const position = capacityOf(op)?.queuePosition;
+    const why = [op.state_reason, position ? `position ${position} in the queue` : null].filter(Boolean).join('; ');
+    return `${verb} ${w.key !== undefined ? `${w.key} (${w.id})` : w.id}: operation ${op.id} ${op.kind} ${op.state}${why ? ` (${why})` : ''}\n${finished ? durableText(op) : `wait with: shard operations wait ${op.id}\n`}`;
+}
+/**
+ * Each session's own conversation: the one whose harness session it is, else the computer's only live conversation.
+ * Rows that cannot be told apart keep no conversation rather than another thread's.
+ */
+export function withConversations(rows, conversations) {
+    if (!conversations)
+        return rows;
+    const live = conversations.filter(c => c.state !== 'done' && c.state !== 'archived' && !c.ended_at);
+    return rows.map(a => {
+        const session = a.id.slice(a.workspace_id.length + 1);
+        const bound = live.filter(c => c.workspace_id === a.workspace_id);
+        // An API that names the session's conversation (0.16.0+) decides; older ones are matched here by the same rule.
+        const named = a.conversation_id;
+        const c = (named ? conversations.find(c => c.id === named) : undefined)
+            ?? conversations.find(c => c.workspace_id === a.workspace_id && c.harness_session_id === session) ?? (bound.length === 1 ? bound[0] : undefined);
+        return c ? { ...a, conversation_id: c.id, conversation_key: c.key } : a;
+    });
 }
 /** The project-key commands; handlers.ts adds the account plane's. */
 function agentGrace(text) {
@@ -807,6 +843,9 @@ export const KEY_HANDLERS = {
             ...(str(values.limit) ? { limit: parsePositiveInt(str(values.limit), 'limit', 200) } : {}),
         };
         const rows = [];
+        // Which conversation each session belongs to (0.16.0+): several threads can share one computer. Read alongside
+        // the sessions; an API without conversations leaves the rows as they are.
+        const threads = import("./conversations.js").then(m => m.listConversations(ctx)).catch(() => null);
         let cursor = str(values.cursor);
         let next;
         do {
@@ -820,7 +859,8 @@ export const KEY_HANDLERS = {
             rows.splice(0, rows.length, ...await withLiveAgents(ctx, rows, { ...(state ? { state } : {}), labels }));
         // LAST MESSAGE (0.13.4+): the session's latest message, from an API that reports it.
         const message = (a) => !a.last_message ? '-' : a.last_message.length > 60 ? `${a.last_message.slice(0, 59)}…` : a.last_message;
-        out(ctx, rows.length ? table(['WORKSPACE', 'APP', 'STATE', 'TITLE', 'LAST MESSAGE'], rows.map(a => [a.workspace_key, a.app, a.state, a.title, message(a)])) : 'No agent sessions.\n', { data: rows, next_cursor: next });
+        const enriched = withConversations(rows, await threads);
+        out(ctx, rows.length ? table(['CONVERSATION', 'COMPUTER', 'APP', 'STATE', 'TITLE', 'LAST MESSAGE'], enriched.map(a => [a.conversation_key?.split('/').at(-1) ?? '-', a.workspace_key, a.app, a.state, a.title, message(a)])) : 'No agent sessions.\n', { data: enriched, next_cursor: next });
         if (!ctx.json && next)
             ctx.io.stderr.write(`more: shard agents list --cursor ${next}\n`);
         return 0;
@@ -1090,7 +1130,7 @@ export const KEY_HANDLERS = {
             ...(mode ? { mode } : {}),
             ...(computerUse !== undefined ? { computerUse } : {}),
             agentLabel: ctx.agentLabel,
-            wait: values.wait === false ? false : { timeoutMs, signal: ctx.signal },
+            wait: values.wait === false ? false : { timeoutMs, signal: ctx.signal, ...capacityWait(values) },
         }));
         const op = ws.activeOperation;
         if (ws.ready && ws.mode === 'processful' && ws.labels.shard_project)
@@ -1653,7 +1693,7 @@ export const KEY_HANDLERS = {
         });
         const op = ws.activeOperation;
         if (values.wait !== false && !ws.ready && op) {
-            await waitOperation(ctx, op.id, timeoutMs);
+            await waitOperation(ctx, op.id, timeoutMs, values);
             ws = await ctx.cloud().workspaces.get(ws.id);
         }
         const human = ws.ready
@@ -1849,7 +1889,7 @@ export const KEY_HANDLERS = {
         let ws = opened.workspace;
         const op = opened.operation;
         if (values.wait !== false && !ws.ready && op) {
-            await waitOperation(ctx, op.id, timeoutMs);
+            await waitOperation(ctx, op.id, timeoutMs, values);
             ws = await cloud.workspaces.get(ws.id);
         }
         const human = ws.ready
@@ -1875,7 +1915,7 @@ export const KEY_HANDLERS = {
         const label = str(values.label);
         let op = await draft.captureState(label === undefined ? {} : { label });
         if (values.wait === true)
-            op = await waitOperation(ctx, op.id, waitTimeout(values));
+            op = await waitOperation(ctx, op.id, waitTimeout(values), values);
         const checkpoint = typeof op.result?.checkpoint_id === 'string' ? `state ${op.result.checkpoint_id}\n` : '';
         out(ctx, `Capturing a state of the ${slug} draft: operation ${op.id} ${op.kind} ${op.state}\n${checkpoint}${op.state === 'succeeded' ? '' : `wait with: shard operations wait ${op.id}\n`}`, op);
         return 0;
@@ -1902,7 +1942,7 @@ export const KEY_HANDLERS = {
         let ws = await draft.openTestInstance({ ...(state ? { stateId: state } : {}), ...(instanceKey ? { key: instanceKey } : {}), ...(c ? { caps: c } : {}), agentLabel: ctx.agentLabel, wait: false });
         const op = ws.activeOperation;
         if (values.wait !== false && !ws.ready && op) {
-            await waitOperation(ctx, op.id, timeoutMs);
+            await waitOperation(ctx, op.id, timeoutMs, values);
             ws = await ctx.cloud().workspaces.get(ws.id);
         }
         const human = ws.ready
@@ -1931,7 +1971,7 @@ export const KEY_HANDLERS = {
             throw new UsageError('refusing to discard without --yes (the draft is deleted and its live test instances end)');
         let op = await ctx.cloud().templates.draft(slug).discard();
         if (values.wait === true)
-            op = await waitOperation(ctx, op.id, waitTimeout(values));
+            op = await waitOperation(ctx, op.id, waitTimeout(values), values);
         out(ctx, `Discarding the ${slug} draft: operation ${op.id} ${op.kind} ${op.state}\n`, op);
         return 0;
     },
@@ -2344,7 +2384,7 @@ export const KEY_HANDLERS = {
         const timeoutMs = waitTimeout(values);
         const op = values.durable === true
             ? await waited(ctx, `operation ${id} continues server side.`, () => ctx.cloud().workspaces.waitForDurable(id, { timeoutMs, signal: ctx.signal }))
-            : await waitOperation(ctx, id, timeoutMs);
+            : await waitOperation(ctx, id, timeoutMs, values);
         out(ctx, operationDetail(op), op);
         return 0;
     },
@@ -2488,7 +2528,7 @@ async function resolveSecret(ctx, values, ref) {
 }
 /** `--wait`: the SDK's own wait (the call resolves once the operation finished; one trace covers request and wait). */
 function lifecycleOptions(ctx, values, timeoutMs) {
-    return values.wait === true ? { wait: { timeoutMs, signal: ctx.signal } } : {};
+    return values.wait === true ? { wait: { timeoutMs, signal: ctx.signal, ...capacityWait(values) } } : {};
 }
 async function lifecycle(ctx, values, ref, verb, start, processfulOnly) {
     const timeoutMs = waitTimeout(values);

package/dist/conversation-commands.js

@@ -1,5 +1,6 @@
 import { out, str } from "./commands.js";
 import { UsageError } from "./errors.js";
+import { FilesMirror, humanBytes, listMirrorConversations, workspaceHub } from "./files-mirror.js";
 export function conversationClient(ctx) {
     const key = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
     const session = Boolean(ctx.io.env.SHARDFLUX_SESSION_TOKEN?.trim()) || ctx.store.profile(ctx.apiUrl).session !== undefined;
@@ -32,5 +33,10 @@ export const CONVERSATION_HANDLERS = {
         out(ctx, `${r.title}: ${r.landed.how}\n`, r);
         return 0;
     },
+    async 'files pull'(ctx, _values, [conversation, path]) {
+        const r = await new FilesMirror(ctx, workspaceHub(ctx)).pull(conversation, path, () => listMirrorConversations(ctx));
+        out(ctx, r.already ? `${r.local_path} is already downloaded.\n` : `Downloaded ${r.path} (${humanBytes(r.bytes)}) to ${r.local_path}\n`, r);
+        return 0;
+    },
     async 'conversations move'(ctx, _values, [id, to]) { const r = await conversationClient(ctx).conversations.move(id, to, { signal: ctx.signal }); out(ctx, `Move scheduled for the end of the turn.\n`, r); return 0; },
 };

package/dist/conversation-local.js

@@ -1,5 +1,5 @@
 import { setTimeout as delay } from 'node:timers/promises';
-import { getConversation, resolveConversation, conversationWorkspace, localConversations } from "./conversations.js";
+import { conversationEnded, getConversation, resolveConversation, conversationWorkspace, localConversations } from "./conversations.js";
 import { ensureConversationWorktree, devicePort } from "./device-bridge.js";
 import { startProjectSync } from "./project-sync.js";
 import { projectIdentity } from "./project-identity.js";
@@ -48,7 +48,7 @@ export const CONVERSATION_HANDLERS = {
         try {
             while (!ctx.signal.aborted) {
                 const next = await getConversation(ctx, c.id);
-                if (next.state === 'done' || next.state === 'archived' || next.workspace_id !== c.workspace_id)
+                if (conversationEnded(next) || next.workspace_id !== c.workspace_id)
                     break;
                 await delay(1000, undefined, { signal: ctx.signal }).catch(() => undefined);
             }

package/dist/conversation-stash.js

@@ -182,7 +182,7 @@ export async function mirrorProjectConversations(ctx, state = new ConversationMi
         const c = all.find(c => c.id === record.conversation.id);
         if (!c || record.handed_off || !c.harness_session_id)
             continue;
-        const revision = JSON.stringify([c.workspace_id, c.harness_session_id, c.state, c.durable, c.last_activity_at, c.summary]);
+        const revision = JSON.stringify([c.workspace_id, c.harness_session_id, c.state, c.durable, c.last_activity_at, c.summary, c.ended_at]);
         if (state.mirrored.get(c.id) === revision)
             continue;
         let retry = state.retries.get(c.id);
@@ -220,8 +220,9 @@ export async function mirrorProjectConversations(ctx, state = new ConversationMi
             await mirrorConversation(ctx, { ...record, conversation: c }, source, skipped);
             retry.failures = 0;
             retry.retryAt = 0;
-            // An ended record may precede its VM tombstone; retry until the handoff receipt is written.
-            if (c.state !== 'done' && c.state !== 'archived')
+            // An ended record may precede its VM tombstone; retry until the handoff receipt is written. A finished turn is
+            // `done` while its VM lives: mirrored once per revision, and again when it ends.
+            if (c.state !== 'archived' && !(c.state === 'done' && c.ended_at))
                 state.mirrored.set(c.id, revision);
         }
         catch (e) {

package/dist/conversation-terminal.d.ts

@@ -4,5 +4,10 @@ import type { Values } from './args.js';
 import type { Conversation } from './conversations.js';
 /** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
 export declare function conversationTerminal(ctx: Ctx, ws: Workspace, c: Conversation, project: string, values: Values): Promise<number>;
+/**
+ * `shard ./` (and `agents new --in auto`): new conversations open where `agents targets` says (open_in, 0.17.0+): T3
+ * Code mode, Claude Desktop or claude.ai for Claude (the conversation's Remote Control session), else this terminal.
+ */
+export declare const launchProjectCommand: Handler;
 /** Select a durable conversation, then use the harness's native terminal for all interaction. */
 export declare const launchConversationProject: Handler;

package/dist/conversation-terminal.js

@@ -1,7 +1,9 @@
+import { linuxTerminalSession } from "./linux-terminal.js";
 import { randomUUID } from 'node:crypto';
 import { AgentStateStore } from "./agent-state.js";
 import { projectIdentity, projectLabels } from "./project-identity.js";
-import { createConversation, conversationName, conversationWorkspace, conversationsUnavailable, listConversations, localConversations, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
+import { createConversation, conversationName, conversationWorkspace, conversationsUnavailable, listConversations, localConversations, recordedChoice, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
+import { modelChoice } from "./agent-models.js";
 import { terminal } from "./agent-commands.js";
 import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
@@ -15,15 +17,47 @@ import { localResumeTerminal } from "./conversation-local-resume.js";
 import { agentReachability } from "./agent-reachability.js";
 import { promptWithImages, readInitialImages, readInitialPrompt, uploadInitialImages } from "./initial-prompt.js";
 import { launchCodexCloud, openCodexConversation } from "./codex-cloud.js";
+import { startThreadOn } from "./thread-on-computer.js";
+import { openInChoices } from "./t3-mode.js";
+import { launchT3 } from "./t3-launch.js";
+import { openClaudeDesktopSession, remoteControlUrl } from "./agent-target-commands.js";
+import { openUrl } from "./browser.js";
+import { out } from "./commands.js";
 /** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
 export async function conversationTerminal(ctx, ws, c, project, values) {
     if (c.route === 'codex-cloud')
         return openCodexConversation(ctx, c);
     await restoreConversationBinding(ctx, c, ws);
-    return terminal(ctx, ws, c.harness, conversationName(c), project, values, undefined, c.worktree_path, { id: c.id, session: c.harness_session_id });
+    // A thread on another conversation's computer has its own PTY there, never the VM's own (0.16.0+).
+    const pty = ws.labels.shard_conversation && ws.labels.shard_conversation !== c.id ? conversationName(c) : undefined;
+    return terminal(ctx, ws, c.harness, conversationName(c), project, values, undefined, c.worktree_path, { id: c.id, session: c.harness_session_id, title: c.title, ...(pty ? { pty } : {}), choice: recordedChoice(c) });
 }
+/**
+ * `shard ./` (and `agents new --in auto`): new conversations open where `agents targets` says (open_in, 0.17.0+): T3
+ * Code mode, Claude Desktop or claude.ai for Claude (the conversation's Remote Control session), else this terminal.
+ */
+export const launchProjectCommand = async (ctx, values, [path = './', explicit]) => {
+    const named = explicit ?? (values.claude === true ? 'claude' : values.codex === true ? 'codex' : undefined);
+    if (values.resume !== true && values.review !== true) {
+        const project = projectIdentity(path);
+        const app = named === 'claude' || named === 'codex' ? named : new AgentStateStore(ctx.store.dir).app(project.remote ?? project.folder);
+        const where = process.platform === 'linux' && ctx.io.stdin.isTTY ? 'terminal' : openInChoices(ctx, project.slug)[app];
+        if (where === 't3')
+            return launchT3(ctx, values, path, app);
+        if (values.on === undefined && app === 'claude' && (where === 'claude-desktop' || where === 'web'))
+            return startConversation(ctx, values, [path, ...(explicit ? [explicit] : [])], where);
+    }
+    return launchConversationProject(ctx, values, [path, ...(explicit ? [explicit] : [])]);
+};
 /** Select a durable conversation, then use the harness's native terminal for all interaction. */
-export const launchConversationProject = async (ctx, values, [path = './', explicit]) => {
+export const launchConversationProject = (ctx, values, args) => startConversation(ctx, values, args);
+async function startConversation(ctx, values, [path = './', explicit], openIn) {
+    if (values.on !== undefined) {
+        const app = explicit ?? (values.claude === true ? 'claude' : values.codex === true ? 'codex' : undefined);
+        return startThreadOn(ctx, values, path, app);
+    }
+    if (values.review === true)
+        throw new UsageError('--review needs --on <conversation>.');
     const text = await readInitialPrompt(ctx, values);
     // Images are read and validated before allocation, held in memory, and written only into the new VM.
     const images = await readInitialImages(ctx, values, text);
@@ -33,6 +67,8 @@ export const launchConversationProject = async (ctx, values, [path = './', expli
     const app = explicit === 'claude' || explicit === 'codex' ? explicit : store.app(project.remote ?? project.folder);
     if (explicit && explicit !== app)
         throw new UsageError('Choose claude or codex.');
+    // Checked before a VM is allocated; the new conversation's record carries it to its guest (0.17.0+).
+    const choice = modelChoice(values, app);
     if (values.resume === true) {
         // The native pickers are VM-local. C-K6's project picker must select the binding first.
         const records = localConversations(ctx);
@@ -53,7 +89,7 @@ export const launchConversationProject = async (ctx, values, [path = './', expli
         const ws = await conversationWorkspace(ctx, next);
         return conversationTerminal(ctx, ws, next, project.remote ?? project.folder, values);
     }
-    if (app === 'codex')
+    if (app === 'codex' && !linuxTerminalSession(ctx, values))
         return launchCodexCloud(ctx, values, path, images);
     await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
     const signedIn = app === 'claude' ? await cloudClaudeLogin(ctx) : true;
@@ -61,7 +97,7 @@ export const launchConversationProject = async (ctx, values, [path = './', expli
         requireClaudeTerminal(ctx);
     let created;
     try {
-        created = await createConversation(ctx, project.folder, app, 'terminal');
+        created = await createConversation(ctx, project.folder, app, 'terminal', undefined, choice);
     }
     catch (e) {
         if (!conversationsUnavailable(e))
@@ -93,5 +129,17 @@ export const launchConversationProject = async (ctx, values, [path = './', expli
     if (!(await savedMachine(ctx))?.template)
         await syncAgentConfig(ctx, ws);
     await ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
+    if (openIn) {
+        // The agent starts detached in its VM; the conversation then opens in Claude Desktop or claude.ai (Remote Control).
+        const quiet = { ...ctx, io: { ...ctx.io, stdout: { write: () => true } } };
+        await conversationTerminal(quiet, ws, c, project.remote ?? project.folder, { ...values, detach: true });
+        if (openIn === 'claude-desktop')
+            return openClaudeDesktopSession(ctx, ws, c);
+        const url = await remoteControlUrl(ctx, ws, c);
+        if (!ctx.json && !openUrl(url, ctx.io.env))
+            throw new Error(`could not open ${url}`);
+        out(ctx, `${url}\n`, { target: 'web', workspace: ws.data, conversation_id: c.id, url });
+        return 0;
+    }
     return conversationTerminal(ctx, ws, c, project.remote ?? project.folder, values);
-};
+}

package/dist/conversations.d.ts

@@ -1,5 +1,6 @@
 import type { Workspace, WorkspaceView } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
+import type { ModelChoice } from './agent-models.js';
 export type Harness = 'claude' | 'codex';
 export interface Conversation {
     id: string;
@@ -17,6 +18,11 @@ export interface Conversation {
     state: 'working' | 'needs_you' | 'unresolved' | 'done' | 'archived';
     created_at: string;
     ended_at: string | null;
+    landed?: {
+        how: string;
+        at: string;
+        ref: string;
+    } | null;
     last_activity_at?: string;
     durable?: {
         branch_sha: string;
@@ -26,6 +32,14 @@ export interface Conversation {
     } | null;
     ports?: number[];
     restore?: Record<string, unknown> | null;
+    /** The repository and the branch it started from, from APIs that return them. */
+    repo_remote?: string;
+    base_branch?: string | null;
+    role?: string;
+    join_mode?: string | null;
+    /** The model and effort its harness starts with; null is the agent's own default (0.17.0+, APIs that keep them). */
+    model?: string | null;
+    effort?: string | null;
 }
 export interface LocalConversation {
     api_url: string;
@@ -33,21 +47,35 @@ export interface LocalConversation {
     project_id: string;
     conversation: Conversation;
     handed_off?: boolean;
+    /** The branch the conversation started from (0.16.0+), for APIs that do not return base_branch yet. */
+    base_branch?: string;
 }
+/**
+ * Whether the conversation has ended: its VM was reclaimed, or it was archived or discarded. A finished turn is `done`
+ * while its VM still takes the next turn; on Codex Cloud, `done` ends the conversation.
+ */
+export declare const conversationEnded: (c: Pick<Conversation, "state" | "ended_at" | "route" | "landed">) => boolean;
 export declare const conversationName: (c: Conversation) => string;
 export declare function validateConversation(c: Conversation): Conversation;
 export declare function localConversations(ctx: Pick<Ctx, 'store' | 'apiUrl'>): Record<string, LocalConversation>;
-export declare function rememberConversation(ctx: Pick<Ctx, 'store' | 'apiUrl'>, c: Conversation, folder: string, handedOff?: boolean): void;
+export declare function rememberConversation(ctx: Pick<Ctx, 'store' | 'apiUrl'>, c: Conversation, folder: string, handedOff?: boolean, baseBranch?: string): void;
 export declare function conversationsUnavailable(e: unknown): boolean;
 export declare function getConversation(ctx: Ctx, id: string): Promise<Conversation>;
 export declare function listConversations(ctx: Ctx, projectId?: string): Promise<Conversation[]>;
 export declare function resolveConversation(ctx: Ctx, ref: string, folder?: string): Promise<Conversation>;
 /** Re-resolve the binding on every attach: a move changes the VM, never the conversation identity. */
 export declare function conversationWorkspace(ctx: Ctx, c: Conversation): Promise<Workspace>;
+/**
+ * A thread on an existing computer (a join) is prepared by that computer's guest: its worktree, then its harness. Waits
+ * until the guest confirms it (the conversation no longer carries restore instructions), within the wake timeout.
+ */
+export declare function waitThreadReady(ctx: Ctx, c: Conversation, pollMs?: number): Promise<Conversation>;
 export declare function restoreConversationBinding(ctx: Ctx, c: Conversation, ws: Workspace): Promise<void>;
-export declare function createConversationRecord(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string, allocated?: (workspace: WorkspaceView) => void, idempotencyKey?: string): Promise<Conversation>;
-export declare function createConversation(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string): Promise<{
+export declare function createConversationRecord(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string, allocated?: (workspace: WorkspaceView) => void, idempotencyKey?: string, choice?: ModelChoice): Promise<Conversation>;
+export declare function createConversation(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string, choice?: ModelChoice): Promise<{
     conversation: Conversation;
     workspace: Workspace;
 }>;
 export declare function resumeConversation(ctx: Ctx, c: Conversation): Promise<Conversation>;
+/** The model and effort a conversation's harness starts with, as its record keeps them. */
+export declare const recordedChoice: (c: Pick<Conversation, "model" | "effort">) => ModelChoice;