@shardflux/cli 0.15.2 → 0.17.0

package/dist/t3-phone.d.ts

@@ -0,0 +1,17 @@
+import type { T3Link } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+export interface T3PhoneLink {
+    link: T3Link;
+    /** The person's T3 Connect sign-in to approve, once: open `verification_uri`, confirm `user_code`. */
+    signIn?: {
+        verification_uri: string;
+        user_code: string;
+    };
+    /** No signed-in session here to start the sign-in with (`shard auth login` first). */
+    needsLogin?: boolean;
+}
+/**
+ * Links a workspace for the T3 app on the phone (0.17.0+). An API key links with its creator's sign-in; starting that
+ * sign-in takes the person's own session, so the sign-in comes from `shard`'s session when the key has none yet.
+ */
+export declare function t3PhoneLink(ctx: Ctx, workspaceId: string): Promise<T3PhoneLink>;

package/dist/t3-phone.js

@@ -0,0 +1,15 @@
+/**
+ * Links a workspace for the T3 app on the phone (0.17.0+). An API key links with its creator's sign-in; starting that
+ * sign-in takes the person's own session, so the sign-in comes from `shard`'s session when the key has none yet.
+ */
+export async function t3PhoneLink(ctx, workspaceId) {
+    const link = await ctx.cloud().t3.link(workspaceId);
+    if (link.status !== 'needs_sign_in')
+        return { link };
+    if (link.sign_in)
+        return { link, signIn: link.sign_in };
+    if (ctx.store.profile(ctx.apiUrl).session?.state !== 'active')
+        return { link, needsLogin: true };
+    const flow = await ctx.account().t3.signIn();
+    return { link, signIn: flow };
+}

package/dist/t3-thread-script.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What `shard agents new --in t3 --prompt…` runs inside the project VM in SSH mode (T3 Code 0.0.45, whose server runs in
+ * the VM). It takes its input on stdin (the prompt and the session it issues never appear in argv) and prints one JSON
+ * line. Everything goes through T3's own interfaces, the way T3's CLI does it (apps/server/src/cli/project.ts):
+ *  1. the T3 runtime T3 installs (`~/.t3/runtime/versions/<version>/t3`), installing it when the prewarm has not;
+ *  2. the running server (`~/.t3/userdata/server-runtime.json`, its pid alive and `/` answering), else
+ *     `t3 serve --host 127.0.0.1 --port <first free from 3773> --base-dir ~/.t3`, the command T3's SSH launch uses, so
+ *     the desktop reuses that server when it connects (packages/ssh/src/tunnel.ts);
+ *  3. a 5-minute admin session (`t3 auth session issue --json`), used for the calls below and revoked after;
+ *  4. the project (`GET /api/orchestration/snapshot`, else `project.create` for the checkout);
+ *  5. `thread.create` then `thread.turn.start` (`POST /api/orchestration/dispatch`) over loopback.
+ * Every exit prints one JSON line (a failed revoke is logged on stderr, never in place of the result), and the images
+ * the CLI wrote for the first message are removed on every path. A server it starts logs to ~/.shardflux/t3-serve.log.
+ * The model is the one asked for, else the provider's default in T3's own provider cache (`~/.t3/caches/<id>.json`),
+ * else T3's built-in default. An effort is sent as the provider option T3 reads (`effort` for Claude,
+ * `reasoningEffort` for Codex) when the model offers it, or when T3 has not described the model yet.
+ */
+export declare const T3_THREAD_SCRIPT: string;

package/dist/t3-thread-script.js

@@ -0,0 +1,245 @@
+/**
+ * What `shard agents new --in t3 --prompt…` runs inside the project VM in SSH mode (T3 Code 0.0.45, whose server runs in
+ * the VM). It takes its input on stdin (the prompt and the session it issues never appear in argv) and prints one JSON
+ * line. Everything goes through T3's own interfaces, the way T3's CLI does it (apps/server/src/cli/project.ts):
+ *  1. the T3 runtime T3 installs (`~/.t3/runtime/versions/<version>/t3`), installing it when the prewarm has not;
+ *  2. the running server (`~/.t3/userdata/server-runtime.json`, its pid alive and `/` answering), else
+ *     `t3 serve --host 127.0.0.1 --port <first free from 3773> --base-dir ~/.t3`, the command T3's SSH launch uses, so
+ *     the desktop reuses that server when it connects (packages/ssh/src/tunnel.ts);
+ *  3. a 5-minute admin session (`t3 auth session issue --json`), used for the calls below and revoked after;
+ *  4. the project (`GET /api/orchestration/snapshot`, else `project.create` for the checkout);
+ *  5. `thread.create` then `thread.turn.start` (`POST /api/orchestration/dispatch`) over loopback.
+ * Every exit prints one JSON line (a failed revoke is logged on stderr, never in place of the result), and the images
+ * the CLI wrote for the first message are removed on every path. A server it starts logs to ~/.shardflux/t3-serve.log.
+ * The model is the one asked for, else the provider's default in T3's own provider cache (`~/.t3/caches/<id>.json`),
+ * else T3's built-in default. An effort is sent as the provider option T3 reads (`effort` for Claude,
+ * `reasoningEffort` for Codex) when the model offers it, or when T3 has not described the model yet.
+ */
+export const T3_THREAD_SCRIPT = String.raw `import base64, json, os, socket, subprocess, sys, time, urllib.error, urllib.request, uuid
+cfg = json.load(sys.stdin)
+home = os.path.expanduser('~')
+base = os.path.expanduser(cfg.get('base') or '~/.t3')
+version = cfg['version']
+t3 = cfg.get('t3') or os.path.join(base, 'runtime', 'versions', version, 't3')
+out = {'ok': True, 'server_started': False}
+
+def remove_images():
+    for image in cfg.get('images') or []:
+        try: os.remove(image['path'])
+        except OSError: pass
+
+def done(ok, error=None, message=None, **extra):
+    remove_images()
+    out['ok'] = ok
+    if error: out['error'] = error
+    if message: out['message'] = message[:500]
+    out.update(extra)
+    sys.stdout.write(json.dumps(out) + '\n')
+    sys.exit(0 if ok else 1)
+
+def runtime_ready():
+    if cfg.get('t3'): return os.access(t3, os.X_OK)
+    try:
+        with open(os.path.join(os.path.dirname(t3), '.install-complete')) as f: marker = f.read().strip()
+    except OSError:
+        return False
+    return os.access(t3, os.X_OK) and marker == version
+
+if not runtime_ready():
+    # A prewarm that is still downloading holds the install lock; this installer then exits at once and the wait follows it.
+    if cfg.get('install_script'):
+        try:
+            subprocess.run(['sh', '-c', cfg['install_script']], stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=float(cfg.get('install_timeout', 600)))
+        except Exception as e:
+            done(False, 'runtime_not_installed', 'The T3 runtime did not install in the workspace: %s' % e)
+    deadline = time.time() + float(cfg.get('install_wait', 300))
+    while not runtime_ready() and time.time() < deadline: time.sleep(1)
+    if not runtime_ready(): done(False, 'runtime_not_installed', 'The T3 runtime did not install in the workspace.')
+
+opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+def get(url, timeout=3):
+    with opener.open(url, timeout=timeout) as r: return r.status, r.read()
+def ready(origin):
+    try:
+        status, _ = get(origin + '/')
+        return 200 <= status < 300
+    except Exception:
+        return False
+def alive(pid):
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+state_dir = os.path.join(base, 'userdata')
+def running_origin():
+    try:
+        with open(os.path.join(state_dir, 'server-runtime.json')) as f: runtime = json.load(f)
+        pid, origin = int(runtime['pid']), str(runtime['origin'])
+    except Exception:
+        return None
+    if not (origin.startswith('http://127.0.0.1:') or origin.startswith('http://localhost:')) or not alive(pid): return None
+    return origin if ready(origin) else None
+
+origin = running_origin()
+if origin is None:
+    port = None
+    for candidate in range(int(cfg.get('default_port', 3773)), int(cfg.get('default_port', 3773)) + 200):
+        probe = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        try:
+            probe.bind(('127.0.0.1', candidate))
+            port = candidate
+            break
+        except OSError:
+            continue
+        finally:
+            probe.close()
+    if port is None: done(False, 'server_not_ready', 'No free port for the T3 server.')
+    # Shardflux's own log stays out of T3's data directory.
+    log_dir = os.path.join(home, '.shardflux')
+    os.makedirs(log_dir, exist_ok=True)
+    log = open(os.path.join(log_dir, 't3-serve.log'), 'ab')
+    env = dict(os.environ, T3CODE_NO_BROWSER='1')
+    standin = cfg.get('standin_path')
+    if standin and os.access(standin, os.X_OK): env['T3CODE_CLOUDFLARED_PATH'] = standin
+    server = subprocess.Popen(['nohup', t3, 'serve', '--host', '127.0.0.1', '--port', str(port), '--base-dir', base],
+                              stdin=subprocess.DEVNULL, stdout=log, stderr=subprocess.STDOUT, env=env, cwd=home, start_new_session=True, close_fds=True)
+    out['server_started'] = True
+    origin = 'http://127.0.0.1:%d' % port
+    deadline = time.time() + float(cfg.get('start_wait', 120))
+    while not ready(origin):
+        if server.poll() is not None or time.time() > deadline: done(False, 'server_not_ready', 'The T3 server in the workspace did not start.')
+        time.sleep(0.25)
+out['origin'] = origin
+
+try:
+    _, raw = get(origin + '/.well-known/t3/environment', timeout=10)
+    descriptor = json.loads(raw)
+except Exception as e:
+    done(False, 'server_not_ready', 'The T3 server did not describe itself: %s' % e)
+out['server_version'] = descriptor.get('serverVersion')
+protocol = descriptor.get('orchestrationProtocolVersion', 1)
+out['protocol'] = protocol
+if protocol != 1:
+    done(False, 'version_unsupported', 'T3 %s in the workspace uses orchestration protocol %s.' % (descriptor.get('serverVersion'), protocol))
+
+try:
+    issued = subprocess.run([t3, 'auth', 'session', 'issue', '--base-dir', base, '--ttl', '5m', '--label', 'Shardflux thread start', '--json'],
+                            stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=float(cfg.get('issue_timeout', 60)))
+except Exception as e:
+    done(False, 'session_not_issued', 'T3 issued no session: %s' % e)
+try:
+    session = json.loads(issued.stdout)
+    token, session_id = session['token'], session.get('sessionId')
+except Exception:
+    done(False, 'session_not_issued', (issued.stderr or 'T3 issued no session').strip())
+
+def call(method, path, body=None):
+    data = json.dumps(body).encode() if body is not None else None
+    request = urllib.request.Request(origin + path, data=data, method=method,
+                                     headers={'authorization': 'Bearer ' + token, 'content-type': 'application/json', 'accept': 'application/json'})
+    try:
+        with opener.open(request, timeout=60) as r: status, raw = r.status, r.read()
+    except urllib.error.HTTPError as e:
+        status, raw = e.code, e.read()
+    try:
+        parsed = json.loads(raw) if raw else None
+    except Exception:
+        parsed = None
+    if not 200 <= status < 300:
+        tag = parsed.get('_tag') if isinstance(parsed, dict) else None
+        reason = parsed.get('reason') if isinstance(parsed, dict) else None
+        detail = ' '.join(str(v) for v in (tag, reason) if v)
+        done(False, 'dispatch_failed', 'T3 answered %s %s with %s%s.' % (method, path, status, ' ' + detail if detail else ''), status=status, tag=tag, reason=reason)
+    return parsed
+
+def now():
+    return time.strftime('%Y-%m-%dT%H:%M:%S', time.gmtime()) + '.%03dZ' % (int(time.time() * 1000) % 1000)
+
+def provider_models(instance):
+    try:
+        with open(os.path.join(base, 'caches', instance + '.json')) as f: provider = json.load(f)
+        models = provider.get('models')
+        return models if isinstance(models, list) and models else None
+    except Exception:
+        return None
+
+try:
+    snapshot = call('GET', '/api/orchestration/snapshot')
+    root = os.path.realpath(cfg['project_path']).rstrip('/') or '/'
+    project = next((p for p in snapshot.get('projects', []) if p.get('deletedAt') is None and p.get('workspaceRoot') == root), None)
+    if project is None:
+        project_id = str(uuid.uuid4())
+        call('POST', '/api/orchestration/dispatch', {'type': 'project.create', 'commandId': str(uuid.uuid4()), 'projectId': project_id,
+             'title': os.path.basename(root) or 'project', 'workspaceRoot': root, 'createdAt': now()})
+        out['project_created'] = True
+    else:
+        project_id = project['id']
+        out['project_created'] = False
+    out['project_id'] = project_id
+
+    instance = 'codex' if cfg['app'] == 'codex' else 'claudeAgent'
+    option_id = 'reasoningEffort' if cfg['app'] == 'codex' else 'effort'
+    models = provider_models(instance)
+    # A server started just now describes its providers within seconds of starting.
+    wait_until = time.time() + float(cfg.get('models_wait', 10))
+    while models is None and out['server_started'] and time.time() < wait_until:
+        time.sleep(0.5)
+        models = provider_models(instance)
+    model = cfg.get('model')
+    described = None
+    if models:
+        if model:
+            family = [m for m in models if cfg['app'] == 'claude' and model in ('fable', 'opus', 'sonnet', 'haiku') and str(m.get('slug', '')).startswith('claude-%s-' % model)]
+            described = next((m for m in family if not m.get('isLegacy')), None) or (family[0] if family else None)
+            described = described or next((m for m in models if m.get('slug') == model or model in (m.get('aliases') or [])), None)
+            if described is None:
+                done(False, 'model_unavailable', 'T3 in the workspace has no %s model %s.' % (cfg['app'], model), models=[m.get('slug') for m in models if not m.get('isLegacy')])
+            model = described['slug']
+        else:
+            described = next((m for m in models if m.get('isDefault')), None) or next((m for m in models if not m.get('isLegacy')), None)
+            model = described['slug'] if described else None
+    if not model: model = cfg['default_model']
+    effort = cfg.get('effort')
+    if effort and described is not None:
+        descriptors = ((described.get('capabilities') or {}).get('optionDescriptors') or [])
+        option = next((d for d in descriptors if d.get('id') == option_id), None)
+        if option is None or effort not in [o.get('id') for o in option.get('options') or []]: effort = None
+    selection = {'instanceId': instance, 'model': model}
+    if effort: selection['options'] = [{'id': option_id, 'value': effort}]
+    out['model'] = model
+    out['effort'] = effort or None
+    out['instance_id'] = instance
+
+    # Images the CLI wrote into the VM go inline (T3 0.0.45 UploadChatImageAttachment: dataUrl); T3 stores its own copy.
+    attachments = []
+    for image in cfg.get('images') or []:
+        with open(image['path'], 'rb') as f: data = f.read()
+        attachments.append({'type': 'image', 'name': image['name'], 'mimeType': image['mime'], 'sizeBytes': len(data),
+                            'dataUrl': 'data:%s;base64,%s' % (image['mime'], base64.b64encode(data).decode())})
+    out['attachments'] = len(attachments)
+
+    thread_id = str(uuid.uuid4())
+    created_at = now()
+    call('POST', '/api/orchestration/dispatch', {'type': 'thread.create', 'commandId': str(uuid.uuid4()), 'threadId': thread_id, 'projectId': project_id,
+         'title': cfg['title'], 'modelSelection': selection, 'runtimeMode': cfg.get('runtime_mode', 'full-access'), 'interactionMode': 'default',
+         'branch': None, 'worktreePath': None, 'createdAt': created_at})
+    out['thread_id'] = thread_id
+    started = call('POST', '/api/orchestration/dispatch', {'type': 'thread.turn.start', 'commandId': str(uuid.uuid4()), 'threadId': thread_id,
+         'message': {'messageId': str(uuid.uuid4()), 'role': 'user', 'text': cfg['prompt'], 'attachments': attachments},
+         'modelSelection': selection, 'titleSeed': cfg['title'], 'runtimeMode': cfg.get('runtime_mode', 'full-access'), 'interactionMode': 'default', 'createdAt': now()})
+    out['sequence'] = (started or {}).get('sequence')
+except Exception as e:
+    # A connection that drops mid-call still reports what exists (thread_id when thread.create got through).
+    done(False, 'dispatch_failed', 'T3 did not answer: %s' % e)
+finally:
+    remove_images()
+    if session_id:
+        try:
+            subprocess.run([t3, 'auth', 'session', 'revoke', session_id, '--base-dir', base], stdin=subprocess.DEVNULL, capture_output=True, timeout=float(cfg.get('revoke_timeout', 60)))
+        except Exception as e:
+            # The session expires by itself in 5 minutes; the thread (if made) is still reported.
+            sys.stderr.write('t3 session revoke failed: %s\n' % e)
+            out['revoke_failed'] = True
+done(True)
+`;

package/dist/terminal-onboarding.d.ts

@@ -0,0 +1,11 @@
+import type { Ctx, Handler } from './commands.js';
+import type { Values } from './args.js';
+import { onboardingReport } from './onboarding.js';
+export interface OnboardingDeps {
+    handlers?: Record<string, Handler>;
+    report?: typeof onboardingReport;
+    startHelper?: () => void;
+    loginCodex?: (ctx: Ctx) => Promise<void>;
+}
+/** Linux's first run orchestrates the same auth, setup and live inspection used by the Mac onboarding. */
+export declare function terminalOnboarding(ctx: Ctx, values: Values, deps?: OnboardingDeps): Promise<number>;

package/dist/terminal-onboarding.js

@@ -0,0 +1,75 @@
+import { spawn } from 'node:child_process';
+import { ACCOUNT_HANDLERS } from "./account-commands.js";
+import { AGENT_CREDENTIAL_HANDLERS } from "./agent-credentials.js";
+import { CODEX_CLOUD_HANDLERS } from "./codex-cloud.js";
+import { foundApps, onboardingReport, parseApps } from "./onboarding.js";
+import { requireTermsAcceptance, showLegalNotice } from "./legal.js";
+import { json } from "./format.js";
+import { UsageError } from "./errors.js";
+const handlers = { ...ACCOUNT_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...CODEX_CLOUD_HANDLERS };
+async function loginCodex(ctx) {
+    const child = spawn('codex', ['login', ...(!ctx.io.env.DISPLAY && !ctx.io.env.WAYLAND_DISPLAY ? ['--device-auth'] : [])], { env: ctx.io.env, stdio: 'inherit', signal: ctx.signal });
+    await new Promise((resolve, reject) => {
+        child.once('error', () => reject(new UsageError('Install the Codex CLI, then run codex login and shard.')));
+        child.once('exit', code => code === 0 ? resolve() : reject(new UsageError('Finish codex login, then run shard again.')));
+    });
+}
+/** Linux's first run orchestrates the same auth, setup and live inspection used by the Mac onboarding. */
+export async function terminalOnboarding(ctx, values, deps = {}) {
+    const commands = deps.handlers ?? handlers, report = deps.report ?? onboardingReport;
+    if (ctx.sessionSource() === null) {
+        ctx.io.stdout.write('Sign in to Shardflux\n');
+        if (!ctx.input.interactive) {
+            showLegalNotice(ctx);
+            ctx.io.stdout.write('Run shard in a terminal, or shard auth login --browser followed by shard setup.\n');
+            return 0;
+        }
+        await requireTermsAcceptance(ctx, values);
+        await commands['auth login'](ctx, { browser: true, open: !!(ctx.io.env.DISPLAY || ctx.io.env.WAYLAND_DISPLAY) }, []);
+    }
+    // Setup creates/reuses the project key. --inspect below is the live source of connection status.
+    try {
+        ctx.apiKey();
+    }
+    catch {
+        await commands.setup(ctx, { codex: false }, []);
+    }
+    deps.startHelper?.();
+    let apps = parseApps(values.apps) ?? await foundApps(ctx.io.env);
+    if (ctx.input.interactive && values.apps === undefined) {
+        const selected = (await ctx.input.answer(`Connect Claude, Codex or both? [${apps.join(',') || 'both'}] `))?.trim().toLowerCase();
+        apps = parseApps(selected === 'both' ? 'claude,codex' : selected || (apps.length ? apps : 'claude,codex'));
+    }
+    const inspect = { ...values, apps: apps.join(','), connect: true };
+    let state = await report(ctx, inspect);
+    for (const connection of state.connections.filter(c => c.picked && c.state === 'action')) {
+        const argv = connection.action?.command;
+        if (!argv || !ctx.input.interactive)
+            continue;
+        ctx.io.stdout.write(`${connection.action.title}\n`);
+        if (argv[0] === 'codex')
+            await (deps.loginCodex ?? loginCodex)(ctx);
+        else {
+            // These are the existing onboarding action commands, not a second implementation of sign-in.
+            const command = argv.slice(1, 4).join(' ');
+            if (command === 'agents credentials login')
+                await commands[command](ctx, {}, ['claude']);
+            else if (command === 'agents codex enable')
+                await commands[command](ctx, {}, []);
+            else if (argv[1] === 'setup')
+                await commands.setup(ctx, { ...inspect, inspect: true, 'retry-codex': true }, []);
+        }
+    }
+    state = await report(ctx, inspect);
+    if (ctx.json)
+        ctx.io.stdout.write(json({ onboarding: state, next: 'shard ./' }));
+    else {
+        for (const c of state.connections.filter(c => c.id === 'account' || c.picked))
+            ctx.io.stdout.write(`${c.id}: ${c.fact}${c.action?.command && c.state !== 'verified' ? ` Run ${c.action.command.join(' ')}.` : ''}\n`);
+        if (state.ready)
+            ctx.io.stdout.write('Ready. Run shard ./ in your project.\n');
+        else
+            ctx.io.stdout.write('Finish the connection above, then run shard again.\n');
+    }
+    return state.ready ? 0 : 1;
+}

package/dist/thread-on-computer.d.ts

@@ -0,0 +1,35 @@
+import type { Ctx, Handler } from './commands.js';
+import type { Values } from './args.js';
+import type { Conversation, Harness } from './conversations.js';
+/** A conversation still bound to its computer: not ended, archived or discarded (a settled `done` turn still is). */
+export declare const activeConversation: (c: Pick<Conversation, "state" | "ended_at" | "route" | "landed">) => boolean;
+export interface ComputerThread {
+    id: string;
+    key: string;
+    title: string;
+    harness: Harness;
+    state: Conversation['state'];
+    route: Conversation['route'];
+    role: string;
+    join_mode: string | null;
+    branch: string;
+}
+export interface Computer {
+    workspace_id: string;
+    workspace_key: string;
+    state: 'running' | 'suspended';
+    last_activity_at: string | null;
+    conversations: ComputerThread[];
+}
+/** The project's conversations: its repository's, or (for a folder without a remote) the ones started from it. */
+export declare function projectConversations(ctx: Pick<Ctx, 'store' | 'apiUrl'>, all: Conversation[], folder: string): Conversation[];
+/** Computers a new thread can start on: each live VM (running or parked, never deleted) of the project's active conversations. */
+export declare function listComputers(ctx: Ctx, folder: string): Promise<Computer[]>;
+/**
+ * The conversation whose computer `--on` names: a conversation id, key or name, or the VM's workspace key or id (then
+ * the VM's own conversation, else its oldest live thread).
+ */
+export declare function resolveOn(ctx: Ctx, ref: string, folder: string): Promise<Conversation>;
+/** Starts the thread on `--on`'s computer and opens it like a new conversation of that app. */
+export declare function startThreadOn(ctx: Ctx, values: Values, path: string, explicitApp?: string): Promise<number>;
+export declare const THREAD_HANDLERS: Record<string, Handler>;

package/dist/thread-on-computer.js

@@ -0,0 +1,206 @@
+import { linuxTerminalSession } from "./linux-terminal.js";
+// A new Claude or Codex thread on an existing conversation's computer (0.16.0+): `shard agents new --on <ref>`,
+// `shard ./ --on <ref>` and `shard agents computers`. The thread joins that VM as a worker (its own branch and
+// worktree, sharing the VM's packages, caches, services, ports and files) or, with --review, as a read-only Claude
+// reviewer. Codex threads are genuine Codex Cloud threads. docs/progress/thread-on-existing-vm.md.
+import { randomUUID } from 'node:crypto';
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { out, str } from "./commands.js";
+import { UsageError } from "./errors.js";
+import { table } from "./format.js";
+import { AgentStateStore } from "./agent-state.js";
+import { normalizeRemote, projectIdentity } from "./project-identity.js";
+import { progress } from "./progress.js";
+import { conversationClient } from "./conversation-commands.js";
+import { conversationEnded, conversationName, conversationWorkspace, getConversation, listConversations, localConversations, rememberConversation, validateConversation, waitThreadReady } from "./conversations.js";
+import { syncAgentCredentials } from "./agent-credentials.js";
+import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
+import { promptWithImages, readInitialImages, readInitialPrompt, uploadInitialImages } from "./initial-prompt.js";
+import { recordSeedSnapshot } from "./files-mirror.js";
+import { ensureCodexCloud, printCloudThread, submitCloudInitialPrompt } from "./codex-cloud.js";
+import { modelChoice } from "./agent-models.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const SHA = /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/;
+/** A conversation still bound to its computer: not ended, archived or discarded (a settled `done` turn still is). */
+export const activeConversation = (c) => !conversationEnded(c);
+/** The project's conversations: its repository's, or (for a folder without a remote) the ones started from it. */
+export function projectConversations(ctx, all, folder) {
+    const project = projectIdentity(folder), remote = project.remote ?? `file://${project.folder}`, records = localConversations(ctx);
+    const same = (r) => { try {
+        return normalizeRemote(r, project.folder) === remote;
+    }
+    catch {
+        return false;
+    } };
+    return all.filter(c => c.repo_remote ? same(c.repo_remote) : records[c.id]?.folder === project.folder);
+}
+/** The VM's own conversation first (its label), then the oldest thread on it. */
+function host(bound, label) {
+    return bound.find(c => c.id === label) ?? [...bound].sort((a, b) => a.created_at.localeCompare(b.created_at))[0];
+}
+const thread = (c) => ({ id: c.id, key: c.key, title: c.title, harness: c.harness, state: c.state, route: c.route,
+    role: c.role ?? 'main', join_mode: c.join_mode ?? null, branch: c.branch });
+/** Computers a new thread can start on: each live VM (running or parked, never deleted) of the project's active conversations. */
+export async function listComputers(ctx, folder) {
+    const client = conversationClient(ctx);
+    const groups = new Map();
+    for (const c of projectConversations(ctx, await listConversations(ctx), folder).filter(activeConversation))
+        groups.set(c.workspace_id, [...groups.get(c.workspace_id) ?? [], c]);
+    const computers = await Promise.all([...groups].map(async ([id, bound]) => {
+        let ws;
+        try {
+            ws = await client.workspaces.get(id);
+        }
+        catch (error) {
+            if (error instanceof ShardfluxApiError && error.status === 404)
+                return null;
+            throw error;
+        }
+        const observed = String(ws.data.observed_state ?? '');
+        if (ws.data.deleted_at || ['failed', 'deleted', 'deleting'].includes(observed))
+            return null;
+        const own = host(bound, ws.labels.shard_conversation);
+        const ordered = [own, ...bound.filter(c => c !== own).sort((a, b) => a.created_at.localeCompare(b.created_at))];
+        const last = bound.map(c => c.last_activity_at ?? c.created_at).sort().at(-1) ?? null;
+        return { workspace_id: ws.id, workspace_key: ws.key, state: observed === 'suspended' ? 'suspended' : 'running', last_activity_at: last, conversations: ordered.map(thread) };
+    }));
+    return computers.filter((c) => c !== null).sort((a, b) => (b.last_activity_at ?? '').localeCompare(a.last_activity_at ?? ''));
+}
+/**
+ * The conversation whose computer `--on` names: a conversation id, key or name, or the VM's workspace key or id (then
+ * the VM's own conversation, else its oldest live thread).
+ */
+export async function resolveOn(ctx, ref, folder) {
+    if (!ref.trim())
+        throw new UsageError('--on needs a conversation or computer; list them with shard agents computers.');
+    let target;
+    if (/^conv_[a-z0-9]{26}$/.test(ref))
+        target = await getConversation(ctx, ref);
+    else {
+        const all = await listConversations(ctx);
+        const keyed = all.filter(c => c.key === ref);
+        if (keyed.length === 1)
+            target = keyed[0];
+        else if (UUID.test(ref) || ref.includes('/')) {
+            const client = conversationClient(ctx);
+            let ws = null;
+            try {
+                ws = UUID.test(ref) ? await client.workspaces.get(ref) : await client.workspaces.findByKey(ref, { includeDeleted: false, signal: ctx.signal });
+            }
+            catch (error) {
+                if (!(error instanceof ShardfluxApiError && error.status === 404))
+                    throw error;
+            }
+            if (ws)
+                target = host(all.filter(c => c.workspace_id === ws.id && activeConversation(c)), ws.labels.shard_conversation);
+        }
+        else {
+            const named = projectConversations(ctx, all, folder).filter(c => conversationName(c) === ref);
+            const live = named.filter(activeConversation);
+            if ((live.length || named.length) > 1)
+                throw new UsageError(`Several conversations are named ${ref}; use its key or id (shard agents computers lists them).`);
+            target = live[0] ?? named[0];
+        }
+    }
+    if (!target)
+        throw new UsageError(`No conversation or computer "${ref}" in this project. List them with shard agents computers.`);
+    if (!activeConversation(target))
+        throw new UsageError(`${target.title || target.key} has ended, so its computer is not available. Start the thread on a new computer, or continue that conversation with shard agents open ${target.id}.`);
+    return target;
+}
+/** `git rev-parse HEAD` of the target's worktree in its VM: the new thread starts from its committed work. */
+async function targetHead(ws, target, signal) {
+    const head = await ws.cell().exec.run(['git', '-C', target.worktree_path, 'rev-parse', 'HEAD'], { timeoutMs: 30_000, maxOutputBytes: 4096, signal });
+    const sha = head.stdout.trim();
+    return head.exitCode === 0 && SHA.test(sha) ? sha : target.base_commit;
+}
+/** Records a thread that could never be admitted as discarded, so it never holds the shared computer. */
+async function abandon(ctx, c) {
+    try {
+        await conversationClient(ctx).conversations.land(c.id, 'discard', { idempotencyKey: `abandon-${c.id}`, signal: ctx.signal });
+    }
+    catch { /* the API refuses it again on the next try */ }
+}
+/** Starts the thread on `--on`'s computer and opens it like a new conversation of that app. */
+export async function startThreadOn(ctx, values, path, explicitApp) {
+    const ref = str(values.on) ?? '';
+    for (const flag of ['like', 'in', 'resume', 'new'])
+        if (values[flag] !== undefined && !(flag === 'in' && ['terminal', 'codex-app'].includes(String(values.in))))
+            throw new UsageError(`--${flag} cannot be combined with --on.`);
+    if (values.computer === true)
+        throw new UsageError('--computer is a setting of a new computer; a thread with --on uses its computer as it is.');
+    const text = await readInitialPrompt(ctx, values);
+    const images = await readInitialImages(ctx, values, text);
+    const initialPrompt = text === undefined ? undefined : promptWithImages(text, images);
+    const project = projectIdentity(path), projectKey = project.remote ?? project.folder, store = new AgentStateStore(ctx.store.dir);
+    const chosen = explicitApp ?? str(values.app);
+    if (chosen !== undefined && chosen !== 'claude' && chosen !== 'codex')
+        throw new UsageError('--app must be claude or codex');
+    const app = chosen ?? store.app(projectKey);
+    const nativeCodex = app === 'codex' && linuxTerminalSession(ctx, values);
+    const review = values.review === true;
+    if (review && app === 'codex')
+        throw new UsageError('--review starts a read-only Claude reviewer. A Codex thread on a computer works on its own branch; omit --review.');
+    const choice = modelChoice(values, app);
+    const name = str(values.name);
+    if (name !== undefined && !/^[a-z0-9][a-z0-9-]{0,47}$/.test(name))
+        throw new UsageError('--name must match ^[a-z0-9][a-z0-9-]{0,47}$');
+    const target = await resolveOn(ctx, ref, path);
+    let signedIn = true;
+    if (app === 'claude') {
+        await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
+        signedIn = Boolean(await cloudClaudeLogin(ctx));
+        if (!signedIn)
+            requireClaudeTerminal(ctx);
+        if (!ctx.json && values.detach !== true && (!ctx.io.stdin.isTTY || !ctx.io.stdin.setRawMode))
+            throw new UsageError('agent terminal requires a TTY; add --json to start it detached');
+    }
+    else if (nativeCodex)
+        await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
+    else
+        await ensureCodexCloud(ctx);
+    progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} on the computer with ${target.title || target.key}…`);
+    const ws = await conversationWorkspace(ctx, target);
+    const commit = await targetHead(ws, target, ctx.signal);
+    const baseBranch = target.base_branch ?? undefined;
+    await uploadInitialImages(ws.cell(), images, ctx.signal);
+    const response = await conversationClient(ctx).conversations.create({ projectId: target.project_id, repoRemote: target.repo_remote ?? ws.labels.repo_remote ?? '',
+        harness: app, route: app === 'codex' && !nativeCodex ? 'codex-cloud' : 'terminal', mode: 'join', parentId: target.id, ...(review ? { joinMode: 'reviewer' } : {}),
+        base: { commit, ...(baseBranch ? { branch: baseBranch } : {}) }, ...(name ? { name } : {}), ...choice }, { idempotencyKey: randomUUID(), signal: ctx.signal });
+    let c = validateConversation({ ...response.conversation, restore: response.restore });
+    rememberConversation(ctx, c, project.folder, false, baseBranch);
+    store.save(projectKey, app);
+    if (app === 'codex' && !nativeCodex) {
+        try {
+            await ctx.cloud().codex.admit(c.id, { idempotencyKey: `codex-${c.id}`, signal: ctx.signal });
+        }
+        catch (error) {
+            await abandon(ctx, c);
+            throw error;
+        }
+        const task = await ctx.cloud().codex.waitTask(c.id, { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+        // The worktree exists once admission prepared it: record where the thread started for the files shelf.
+        await recordSeedSnapshot(ws, c, ctx.signal);
+        if (initialPrompt !== undefined)
+            await submitCloudInitialPrompt(ctx, c, initialPrompt, ws.key);
+        await printCloudThread(ctx, c, task, initialPrompt !== undefined, choice);
+        return 0;
+    }
+    // The computer's guest prepares the worktree and starts the harness; the terminal attaches to that session.
+    c = await waitThreadReady(ctx, c);
+    if (!review)
+        await recordSeedSnapshot(ws, c, ctx.signal);
+    if (!signedIn)
+        await loginClaudeInWorkspace(ctx, ws);
+    const { conversationTerminal } = await import("./conversation-terminal.js");
+    return conversationTerminal(ctx, ws, c, projectKey, { ...values, ...(initialPrompt === undefined ? {} : { initialPrompt }) });
+}
+export const THREAD_HANDLERS = {
+    async 'agents computers'(ctx, values) {
+        const computers = await listComputers(ctx, str(values.path) ?? './');
+        const label = (t) => `${t.title || t.key} (${t.harness}, ${t.state.replace('_', ' ')})`;
+        out(ctx, computers.length ? table(['COMPUTER', 'STATE', 'THREADS'], computers.map(c => [c.workspace_key, c.state, c.conversations.map(label).join('; ')]))
+            : 'No computers to start a thread on. Start a conversation with shard ./ first.\n', { computers });
+        return 0;
+    },
+};

package/dist/update.d.ts

@@ -59,5 +59,5 @@ export declare function update(ctx: Ctx, values: Record<string, unknown>, deps?:
 export declare function recordInstall(dir: string, runtime: Runtime, distribution: {
     package: string;
     version: string;
-}): void;
+}, env?: NodeJS.ProcessEnv): void;
 export declare const UPDATE_HANDLERS: Record<string, Handler>;