@shardflux/cli 0.16.0 → 0.17.0

package/dist/codex-cloud.d.ts

@@ -1,13 +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): Promise<void>;
+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";
@@ -33,16 +34,24 @@ export async function submitCloudInitialPrompt(ctx, c, prompt, workspaceKey) {
     }
 }
 /** 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) { return output(ctx, c, task, submitted); }
-async function output(ctx, c, task, submitted = false) {
+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. */
@@ -114,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)
@@ -132,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,8 +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");
@@ -35,6 +36,20 @@ 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)

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";
@@ -16,6 +18,11 @@ 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')
@@ -23,10 +30,28 @@ export async function conversationTerminal(ctx, ws, c, project, values) {
     await restoreConversationBinding(ctx, c, ws);
     // 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 } : {}) });
+    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);
@@ -42,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);
@@ -62,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;
@@ -70,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))
@@ -102,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;
@@ -31,6 +37,9 @@ export interface Conversation {
     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;
@@ -41,6 +50,11 @@ export interface LocalConversation {
     /** 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>;
@@ -57,9 +71,11 @@ export declare function conversationWorkspace(ctx: Ctx, c: Conversation): Promis
  */
 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;

package/dist/conversations.js

@@ -9,6 +9,11 @@ import { UsageError } from "./errors.js";
 import { conversationClient } from "./conversation-commands.js";
 import { recordSeedSnapshot } from "./files-mirror.js";
 import { rememberTwinSeed, sendTwinSeed, twinCheckoutArgv, twinSeed } from "./worktree-twin.js";
+/**
+ * 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 const conversationEnded = (c) => !!c.ended_at || c.state === 'archived' || c.landed?.how === 'discarded' || (c.route === 'codex-cloud' && c.state === 'done');
 export const conversationName = (c) => {
     const name = c.key.split('/').at(-1);
     if (!/^[a-z0-9][a-z0-9-]{0,47}$/.test(name) || c.branch !== `shard/${name}`)
@@ -116,7 +121,7 @@ export async function restoreConversationBinding(ctx, c, ws) {
     if (result.exitCode !== 0)
         throw new Error(`Conversation restore failed: ${result.stderr.trim()}`);
 }
-export async function createConversationRecord(ctx, folder, harness, route, name, allocated, idempotencyKey = randomUUID()) {
+export async function createConversationRecord(ctx, folder, harness, route, name, allocated, idempotencyKey = randomUUID(), choice = {}) {
     const project = projectIdentity(folder);
     await ensureProjectGit(ctx, project.folder);
     // Both the conversation API and its legacy workspace fallback need a usable local HEAD.
@@ -128,16 +133,16 @@ export async function createConversationRecord(ctx, folder, harness, route, name
     const seed = await twinSeed(ctx.store.dir, project.folder, head, ctx.store.profile(ctx.apiUrl).project_id).catch(() => ({ commit: head, snapshot: false }));
     const commit = seed.commit;
     const response = await conversationClient(ctx).conversations.create({ repoRemote: project.remote ?? `file://${project.folder}`, harness, route, mode: 'new',
-        base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), projectId: ctx.store.profile(ctx.apiUrl).project_id }, { idempotencyKey, signal: ctx.signal });
+        base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), ...choice, projectId: ctx.store.profile(ctx.apiUrl).project_id }, { idempotencyKey, signal: ctx.signal });
     const c = validateConversation({ ...response.conversation, restore: response.restore });
     allocated?.(response.workspace);
     rememberTwinSeed(ctx.store.dir, c.id, project.folder, seed, branch);
     rememberConversation(ctx, c, project.folder, false, branch);
     return c;
 }
-export async function createConversation(ctx, folder, harness, route, name) {
+export async function createConversation(ctx, folder, harness, route, name, choice = {}) {
     const project = projectIdentity(folder);
-    const c = await createConversationRecord(ctx, project.folder, harness, route, name);
+    const c = await createConversationRecord(ctx, project.folder, harness, route, name, undefined, undefined, choice);
     try {
         const ws = await conversationWorkspace(ctx, c);
         // This is a one-time seed. A conversation never watches or writes the owner's checkout.
@@ -163,8 +168,10 @@ export async function createConversation(ctx, folder, harness, route, name) {
     }
 }
 export async function resumeConversation(ctx, c) {
-    if (c.state !== 'done' && c.state !== 'archived')
+    if (!conversationEnded(c))
         return getConversation(ctx, c.id);
     const response = await conversationClient(ctx).conversations.resume(c.id, { idempotencyKey: randomUUID(), signal: ctx.signal });
     return validateConversation({ ...response.conversation, restore: response.restore });
 }
+/** The model and effort a conversation's harness starts with, as its record keeps them. */
+export const recordedChoice = (c) => ({ ...(c.model ? { model: c.model } : {}), ...(c.effort ? { effort: c.effort } : {}) });

package/dist/device-approvals.d.ts

@@ -0,0 +1,12 @@
+import type { DeviceApproval, DeviceChoice } from './device-bridge.js';
+import type { Ctx, Handler } from './commands.js';
+type Pending = DeviceApproval & {
+    nonce: string;
+    pid: number;
+};
+export declare function pendingDeviceApprovals(dir: string): Pending[];
+export declare function answerDeviceApproval(dir: string, id: string, choice: DeviceChoice): void;
+/** Local user-owned files carry approvals; cloud data can never answer its own request. */
+export declare function askLocalDeviceApproval(ctx: Ctx, approval: DeviceApproval): Promise<DeviceChoice>;
+export declare const DEVICE_HANDLERS: Record<string, Handler>;
+export {};

package/dist/device-approvals.js

@@ -0,0 +1,73 @@
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readdirSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { writePrivateFile } from "./credentials.js";
+import { UsageError } from "./errors.js";
+import { json } from "./format.js";
+const paths = (dir, id) => {
+    if (!/^[a-zA-Z0-9_-]{1,96}$/.test(id))
+        throw new UsageError('Invalid device request id.');
+    return { pending: join(dir, 'device-approvals', `${id}.json`), answer: join(dir, 'device-answers', `${id}.json`) };
+};
+export function pendingDeviceApprovals(dir) {
+    let names;
+    try {
+        names = readdirSync(join(dir, 'device-approvals'));
+    }
+    catch {
+        return [];
+    }
+    return names.filter(n => n.endsWith('.json')).flatMap(n => {
+        try {
+            const p = JSON.parse(readFileSync(paths(dir, n.slice(0, -5)).pending, 'utf8'));
+            process.kill(p.pid, 0);
+            return [p];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+export function answerDeviceApproval(dir, id, choice) {
+    const pending = pendingDeviceApprovals(dir).find(p => p.request_id === id);
+    if (!pending)
+        throw new UsageError('That request is no longer waiting for approval. Run shard device requests.');
+    writePrivateFile(join(dir, 'device-answers'), paths(dir, id).answer, JSON.stringify({ nonce: pending.nonce, choice }));
+}
+/** Local user-owned files carry approvals; cloud data can never answer its own request. */
+export async function askLocalDeviceApproval(ctx, approval) {
+    const file = paths(ctx.store.dir, approval.request_id), nonce = randomUUID();
+    rmSync(file.answer, { force: true });
+    writePrivateFile(join(ctx.store.dir, 'device-approvals'), file.pending, JSON.stringify({ ...approval, nonce, pid: process.pid }));
+    spawnSync('notify-send', ['--', 'Shardflux approval', `${approval.summary}\nReview: shard device requests`], { env: ctx.io.env, stdio: 'ignore', timeout: 2000 });
+    try {
+        while (!ctx.signal.aborted) {
+            try {
+                const answer = JSON.parse(readFileSync(file.answer, 'utf8'));
+                if (answer.nonce === nonce && ['once', 'always', 'deny'].includes(answer.choice))
+                    return answer.choice;
+            }
+            catch { /* wait for the local CLI */ }
+            await delay(200, undefined, { signal: ctx.signal }).catch(() => undefined);
+        }
+        return 'deny';
+    }
+    finally {
+        rmSync(file.pending, { force: true });
+        rmSync(file.answer, { force: true });
+    }
+}
+export const DEVICE_HANDLERS = {
+    'device requests'(ctx) {
+        const requests = pendingDeviceApprovals(ctx.store.dir);
+        ctx.io.stdout.write(ctx.json ? json({ requests }) : requests.length ? requests.map(r => `${r.request_id}: ${r.summary}\n  Project: ${r.project_name ?? r.project_id}; conversation: ${r.conversation_title ?? r.conversation_id}\n  Local: ${r.local_path ?? '(none)'}; remote: ${r.remote_path ?? '(none)'}${r.argv ? `\n  Command: ${JSON.stringify(r.argv)}` : ''}${r.local_port ? `\n  Ports: ${r.local_port} → ${r.remote_port}` : ''}\n  shard device approve ${r.request_id} | shard device deny ${r.request_id}\n`).join('') : 'No device requests waiting for approval.\n');
+        return Promise.resolve(0);
+    },
+    ...Object.fromEntries(['approve', 'deny'].map(action => [`device ${action}`, (ctx, _values, [id]) => {
+            answerDeviceApproval(ctx.store.dir, id, action === 'approve' ? 'once' : 'deny');
+            ctx.io.stdout.write(ctx.json ? json({ request_id: id, choice: action }) : `Device request ${id}: ${action === 'approve' ? 'approved once' : 'denied'}.\n`);
+            return Promise.resolve(0);
+        }])),
+};

package/dist/device-helper.d.ts

@@ -1,3 +1,5 @@
 import type { Ctx } from './commands.js';
 /** The menu bar owns this helper and its stdin; VM data can request actions but cannot answer approvals. */
-export declare function runDeviceHelper(ctx: Ctx): Promise<number>;
+export declare function runDeviceHelper(ctx: Ctx, options?: {
+    service?: boolean;
+}): Promise<number>;

package/dist/device-helper.js

@@ -12,13 +12,14 @@ import { writePrivateFile } from "./credentials.js";
 import { conversationClient } from "./conversation-commands.js";
 import { Readable } from 'node:stream';
 import { runWorktreeTwin } from "./worktree-twin-engine.js";
+import { askLocalDeviceApproval } from "./device-approvals.js";
 /** The menu bar owns this helper and its stdin; VM data can request actions but cannot answer approvals. */
-export async function runDeviceHelper(ctx) {
+export async function runDeviceHelper(ctx, options = {}) {
     const abort = new AbortController(), signal = AbortSignal.any([ctx.signal, abort.signal]);
     ctx = { ...ctx, signal };
     const pending = new Map();
     const inputSource = Readable.from(ctx.io.stdin, { objectMode: false, signal });
-    const input = (async () => {
+    const input = options.service ? Promise.resolve() : (async () => {
         let tail = '';
         for await (const bytes of inputSource) {
             tail += Buffer.from(bytes).toString();
@@ -41,6 +42,8 @@ export async function runDeviceHelper(ctx) {
         const acp = await askConnectedAcp(ctx.store.dir, approval, signal);
         if (acp)
             return acp;
+        if (options.service)
+            return askLocalDeviceApproval(ctx, approval);
         return new Promise(resolve => {
             const denied = () => { pending.delete(approval.request_id); resolve('deny'); };
             signal.addEventListener('abort', denied, { once: true });

package/dist/errors.d.ts

@@ -114,6 +114,8 @@ export declare class ExecSessionRunningError extends HintedError {
 export interface ErrorInfo {
     code: string;
     message: string;
+    /** A refusal `shard` detects itself (CodedError, 0.17.0+): the next step, as plain text (the `hint:` line). */
+    fix?: string;
     status?: number;
     request_id?: string;
     retryable?: boolean;

package/dist/errors.js

@@ -241,7 +241,7 @@ export function describeError(err) {
     if (err instanceof GitError)
         return { code: 'git_error', message: err.message, retryable: false };
     if (err instanceof CodedError)
-        return { code: err.code, message: err.message, retryable: false, ...(err.details ? { details: err.details } : {}) };
+        return { code: err.code, message: err.message, retryable: false, ...(err.hint ? { fix: err.hint } : {}), ...(err.details ? { details: err.details } : {}) };
     if (err instanceof CheckoutTimeoutError) {
         return { code: 'timeout', message: `${err.message}; the checkout stays open (pay at its URL, then check with: shard billing status)`, last_state: err.checkout.status, details: { checkout_id: err.checkout.id, status: err.checkout.status, url: err.checkout.url } };
     }

package/dist/handlers.js

@@ -1,3 +1,4 @@
+import { DEVICE_HANDLERS } from "./device-approvals.js";
 import { CREDENTIAL_HANDLERS } from "./credential-prompts.js";
 import { CONVERSATION_HANDLERS } from "./conversation-commands.js";
 /**
@@ -18,4 +19,5 @@ import { CONVERSATION_HANDLERS as LOCAL_CONVERSATION_HANDLERS } from "./conversa
 import { TWIN_HANDLERS } from "./worktree-twin-engine.js";
 import { CODEX_CLOUD_HANDLERS } from "./codex-cloud.js";
 import { THREAD_HANDLERS } from "./thread-on-computer.js";
-export const HANDLERS = { ...CODEX_CLOUD_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };
+import { CLI_PROXY_HANDLERS } from "./cli-proxy.js";
+export const HANDLERS = { ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };

package/dist/index.d.ts

@@ -24,4 +24,8 @@ export type { ErrorInfo } from './errors.js';
 export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, suspendRequestText, suspendWhenIdleText, table, time, usageText, workspaceDetail, workspaceTable } from './format.js';
 export { TimingRecorder, coldBootNotice, hostLostNotice, lostSuspendNotice, notices, timingJson, timingText } from './timing.js';
 export { readAgentCredentials, syncAgentCredentials } from './agent-credentials.js';
+export { detectLocalCliProxy, importCliProxy } from './cli-proxy.js';
+export type { ImportOptions, ImportResult, LocalCliProxy, LocalLogin } from './cli-proxy.js';
+export { ensureCliProxyHub, readHubInfo } from './cli-proxy-hub.js';
+export type { EnsureOptions, EnsureResult, HubInfo } from './cli-proxy-hub.js';
 export type { CredentialSources } from './agent-credentials.js';

package/dist/index.js

@@ -16,3 +16,6 @@ export { EXIT, AuthConfigError, CheckoutEndedError, ExecutionFailedError, Execut
 export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, suspendRequestText, suspendWhenIdleText, table, time, usageText, workspaceDetail, workspaceTable } from "./format.js";
 export { TimingRecorder, coldBootNotice, hostLostNotice, lostSuspendNotice, notices, timingJson, timingText } from "./timing.js";
 export { readAgentCredentials, syncAgentCredentials } from "./agent-credentials.js";
+// Hosted CLIProxyAPI (onboarding offers the import when detectLocalCliProxy() finds logins).
+export { detectLocalCliProxy, importCliProxy } from "./cli-proxy.js";
+export { ensureCliProxyHub, readHubInfo } from "./cli-proxy-hub.js";

package/dist/linux-helper.d.ts

@@ -0,0 +1,12 @@
+import type { Ctx } from './commands.js';
+export declare const HELPER_UNIT = "shardflux-helper.service";
+export declare const helperUnitPath: (home: string) => string;
+/** No credentials in the unit: the helper reads the same private store as shard. */
+export declare function helperUnit(ctx: Pick<Ctx, 'runtime' | 'store' | 'apiUrl' | 'io'>): string;
+export type Systemctl = (args: string[]) => boolean;
+export declare function installLinuxHelper(ctx: Ctx, deps?: {
+    platform?: NodeJS.Platform;
+    run?: Systemctl;
+}): boolean;
+/** The caller owns fallback lifetime; never leave an unmanaged background process behind. */
+export declare function startLinuxHelper(ctx: Ctx): () => Promise<void>;