@shardflux/cli 0.16.0 → 0.18.0-next.4

package/dist/t3-mode.js

@@ -0,0 +1,676 @@
+/**
+ * T3 Code mode (0.17.0+): new Shardflux threads start in T3 Code itself. T3 has no link that creates or focuses a
+ * thread, so the thread is made through T3's own server API, with a short-lived admin session that T3's own CLI
+ * issues and revokes, and T3 is brought to the front.
+ *
+ * - **ACP mode** (a T3 build with ACP providers, 0.0.46+): T3's server runs on this computer (macOS or Linux) and
+ *   Shardflux is one of its providers (`shard acp`, registered by every `shard` run). The thread is launched on the
+ *   running desktop server (`server-runtime.json`) over its WebSocket RPC (`orchestration.launchThread`) with the
+ *   Shardflux provider, which then gives the thread its own cloud VM. The session is issued by the T3 server the app
+ *   bundles (`ELECTRON_RUN_AS_NODE=1 <app>/Contents/MacOS/<exe> <app.asar>/apps/server/dist/bin.mjs auth session
+ *   issue`; on Linux the app's `t3code` with its `resources/app.asar`, or T3's own `~/.t3/bin/t3` for an AppImage).
+ * - **SSH mode** (stable 0.0.45): T3's server runs in the project VM. `T3_THREAD_SCRIPT` runs there and dispatches
+ *   `thread.create` and `thread.turn.start` over loopback (POST /api/orchestration/dispatch).
+ *
+ * T3's server settings (settings.json) are written only by configureT3Provider, as every `shard` run does to register
+ * the Shardflux provider (t3-provider.ts). Everything else (sessions, projects, threads) changes only through T3's own
+ * API and CLI.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readFileSync, realpathSync } from 'node:fs';
+import { writePrivateFile } from "./credentials.js";
+import { basename, join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { CodedError, UsageError, describeError } from "./errors.js";
+import { AgentStateStore } from "./agent-state.js";
+import { applicationDirs, desktopAppPath, t3Apps } from "./agent-targets.js";
+import { configureT3Provider, t3BundleSupportsAcp, t3HomeDir } from "./t3-provider.js";
+import { linuxLastUsed, linuxServerCli, linuxSupportsAcp, openLinuxT3 } from "./t3-linux.js";
+import { acpSignedIn } from "./acp-login.js";
+import { AcpModelCache } from "./acp-models.js";
+import { nativeModelOptions } from "./acp-catalog.js";
+import { objectValue } from "./acp-rpc.js";
+import { T3_THREAD_SCRIPT } from "./t3-thread-script.js";
+import { t3InstallScript } from "./t3-runtime.js";
+import { uploadInitialImages } from "./initial-prompt.js";
+export const T3_BUNDLE_ID = 'com.t3tools.t3code';
+/** Where each app's new conversations can open: Claude in a terminal, Claude Desktop, claude.ai or T3; Codex in the Codex app or T3. */
+export const OPEN_IN_TARGETS = { claude: ['terminal', 'claude-desktop', 'web', 't3'], codex: ['codex-app', 't3'] };
+export const openInTargets = (app, platform = process.platform) => platform === 'linux' && app === 'codex' ? ['terminal', 't3'] : OPEN_IN_TARGETS[app];
+/** T3 0.0.45's built-in defaults (DEFAULT_MODEL_BY_PROVIDER), used only when T3 in the VM has not described its models yet. */
+const T3_DEFAULT_MODEL = { claude: 'claude-fable-5-1', codex: 'gpt-6-astra' };
+const T3_START_WAIT_MS = 30_000;
+const CONVERSATION_WAIT_MS = 30_000;
+const SIGN_IN_FIX = 'Sign in with shard auth login (or the Shardflux provider’s Sign in in T3 Code), then run this again.';
+const SPOTLIGHT_DATE = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2} [+-]\d{4}$/;
+const isoDate = (raw) => {
+    const parsed = SPOTLIGHT_DATE.test(raw) ? new Date(raw.replace(' ', 'T').replace(' ', '')) : null;
+    return parsed && !Number.isNaN(parsed.getTime()) ? parsed.toISOString() : null;
+};
+/**
+ * Native lookups that tests replace: Spotlight's last-used dates of app bundles, one `mdls` for all of them (macOS), or
+ * when each program last started, from its access time (Linux, t3-linux.ts).
+ */
+export const t3Native = {
+    lastUsedMany(paths, env, platform = process.platform) {
+        if (!paths.length)
+            return {};
+        if (platform !== 'darwin')
+            return Object.fromEntries(paths.map(path => [path, linuxLastUsed(path)]));
+        const r = spawnSync('mdls', ['-name', 'kMDItemLastUsedDate', '-raw', ...paths], { env, encoding: 'utf8', input: '', timeout: 3000 });
+        // -raw separates the values with NUL; a bundle Spotlight has no date for prints "(null)".
+        const values = r.status === 0 ? r.stdout.split('\0').map(v => v.trim()) : [];
+        return Object.fromEntries(paths.map((path, i) => [path, values.length === paths.length ? isoDate(values[i]) : null]));
+    },
+};
+/** Spotlight takes about 40 ms per call, so the dates are kept for a few minutes (app-usage.json in the config dir). */
+export const LAST_USED_TTL_MS = 5 * 60_000;
+export function lastUsedDates(ctx, paths, now = Date.now()) {
+    const file = join(ctx.store.dir, 'app-usage.json');
+    let cache = {};
+    try {
+        cache = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch { /* first lookup */ }
+    const fresh = typeof cache.checked_at === 'number' && now - cache.checked_at >= 0 && now - cache.checked_at < LAST_USED_TTL_MS;
+    if (fresh && cache.dates && paths.every(p => p in cache.dates))
+        return Object.fromEntries(paths.map(p => [p, cache.dates[p] ?? null]));
+    const dates = t3Native.lastUsedMany(paths, ctx.io.env);
+    try {
+        writePrivateFile(ctx.store.dir, file, JSON.stringify({ checked_at: now, dates }) + '\n');
+    }
+    catch { /* a cache only */ }
+    return dates;
+}
+/** Whether an installed T3 runs the Shardflux provider: its server has the ACP Registry driver (t3-asar.ts, t3-linux.ts). */
+const supportsAcp = (app) => app.linux ? linuxSupportsAcp({ ...app, linux: app.linux }) : t3BundleSupportsAcp(app.path);
+/** The installed T3 Code, preferring a build with ACP providers when several channels are installed. */
+export function t3Install(env, platform = process.platform, dirs = applicationDirs(env, platform)) {
+    const apps = t3Apps(dirs, platform, env);
+    const acp = apps.find(supportsAcp);
+    const app = acp ?? apps[0];
+    return app ? { path: app.path, version: app.version, mode: acp ? 'acp' : 'ssh', ...(app.linux ? { linux: app.linux } : {}) } : undefined;
+}
+export { t3HomeDir };
+/** The Shardflux provider instance in T3's server settings (read only; every `shard` run writes it, see t3-provider.ts). */
+export function t3ProviderRegistered(env) {
+    try {
+        const doc = JSON.parse(readFileSync(join(t3HomeDir(env), 'userdata', 'settings.json'), 'utf8'));
+        const instance = doc.providerInstances?.shardflux;
+        return !!instance && instance.driver === 'acpRegistry' && instance.enabled !== false && JSON.stringify(instance.config?.commandArgs) === '["acp"]';
+    }
+    catch {
+        return false;
+    }
+}
+/** The project a workspace key belongs to, matched against a project slug (two repositories with one name: `<slug>-<6 hex>`). */
+function sameProject(key, slug) {
+    const project = key.split('/')[0] ?? '';
+    return project === slug || (project.startsWith(`${slug.slice(0, 89)}-`) && /^[0-9a-f]{6}$/.test(project.slice(Math.min(slug.length, 89) + 1)));
+}
+/**
+ * T3 is connected when a new thread can start in it now: in ACP mode the Shardflux provider is in T3's settings and
+ * this computer is signed in; in SSH mode this project has a T3 SSH environment set up from this computer (signed in).
+ * `last_used_at` is looked up only when asked for (`agents targets`).
+ */
+export function t3Status(ctx, opts = {}) {
+    const install = opts.install === undefined ? t3Install(ctx.io.env) : opts.install ?? undefined;
+    if (!install)
+        return { installed: false, mode: null, connected: false, version: null, last_used_at: null };
+    const connected = acpSignedIn(ctx) && (install.mode === 'acp'
+        ? t3ProviderRegistered(ctx.io.env)
+        : !!opts.project && new AgentStateStore(ctx.store.dir).t3Environments(ctx.apiUrl).some(e => sameProject(e.workspace, opts.project)));
+    return { installed: true, mode: install.mode, connected, version: install.version, last_used_at: opts.lastUsed ? lastUsedDates(ctx, usagePaths(ctx, install).paths)[install.path] ?? null : null };
+}
+/** T3 and the other installed desktop apps whose last use decides the default: one Spotlight lookup covers them all. */
+function usagePaths(ctx, install) {
+    const dirs = applicationDirs(ctx.io.env);
+    const others = [desktopAppPath(dirs, 'Claude.app', 'com.anthropic.claudefordesktop'), desktopAppPath(dirs, 'Codex.app', 'com.openai.codex') ?? desktopAppPath(dirs, 'ChatGPT.app', 'com.openai.codex')]
+        .filter((p) => !!p);
+    return { paths: [install.path, ...others], others };
+}
+/**
+ * Where each app's new conversations open for `project`: the choice saved with `agents targets --open-in` while it is
+ * available, else T3 when it is connected and the most recently used of the installed desktop apps, else a terminal
+ * (Claude) or the Codex app. Lookups run only when an answer needs them: none for a saved terminal, web or Codex app
+ * choice, and Spotlight only when T3 is installed and connected (cached, see lastUsedDates).
+ */
+export function openInFor(ctx, project, known = {}) {
+    const saved = objectValue(new AgentStateStore(ctx.store.dir).read().open_in);
+    const dirs = applicationDirs(ctx.io.env);
+    let install, status, first;
+    const t3 = () => install === undefined ? (install = t3Install(ctx.io.env) ?? null) : install;
+    const claudeDesktop = () => known.clients ? known.clients.includes('claude-desktop') : desktopAppPath(dirs, 'Claude.app', 'com.anthropic.claudefordesktop') !== undefined;
+    const valid = (app) => {
+        const value = saved[app];
+        if (typeof value !== 'string' || !openInTargets(app).includes(value))
+            return undefined;
+        return value === 't3' ? (t3() ? value : undefined) : value === 'claude-desktop' ? (claudeDesktop() ? value : undefined) : value;
+    };
+    const t3First = () => first ??= (() => {
+        const app = t3();
+        if (!app)
+            return false;
+        status ??= t3Status(ctx, { project, install: app });
+        if (!status.connected)
+            return false;
+        const { paths, others } = usagePaths(ctx, app);
+        const dates = lastUsedDates(ctx, paths);
+        const mine = dates[app.path];
+        return !!mine && others.every(p => !dates[p] || dates[p] <= mine);
+    })();
+    const choose = (app) => {
+        const value = valid(app);
+        return value ? { target: value, saved: true } : { target: t3First() ? 't3' : app === 'claude' || process.platform === 'linux' ? 'terminal' : 'codex-app', saved: false };
+    };
+    return { claude: choose('claude'), codex: choose('codex') };
+}
+export function openInChoices(ctx, project, known = {}) {
+    const choices = openInFor(ctx, project, known);
+    return { claude: choices.claude.target, codex: choices.codex.target };
+}
+const available = (target, status, clients) => target === 't3' ? status.installed : target === 'claude-desktop' ? clients.includes('claude-desktop') : true;
+/** `--open-in claude=t3,codex=t3`: validated against what is installed, then saved in agents.json. */
+export function saveOpenIn(ctx, spec, status, clients) {
+    const choices = {};
+    for (const part of spec.split(',').map(s => s.trim()).filter(Boolean)) {
+        const [app, target, extra] = part.split('=').map(s => s.trim());
+        if (app !== 'claude' && app !== 'codex' || !target || extra !== undefined)
+            throw new UsageError('--open-in takes app=target pairs, e.g. claude=t3,codex=t3.');
+        if (!openInTargets(app).includes(target))
+            throw new UsageError(`--open-in: ${app} opens in ${openInTargets(app).join(', ')}.`);
+        if (target === 't3' && !status.installed)
+            throw t3NotInstalled();
+        if (!available(target, status, clients))
+            throw new UsageError(`--open-in: ${target} is not installed on this computer.`);
+        choices[app] = target;
+    }
+    if (!Object.keys(choices).length)
+        throw new UsageError('--open-in takes app=target pairs, e.g. claude=t3,codex=t3.');
+    new AgentStateStore(ctx.store.dir).update(doc => { doc.open_in = { ...objectValue(doc.open_in), ...choices }; });
+}
+/** A T3 thread was started, then a later step failed: the error names the thread so a client opens it, never starts another. */
+export function t3OpenFailed(error, ref) {
+    return new CodedError('t3_open_failed', `Started the thread in T3 Code, but T3 Code did not open: ${describeError(error).message}`, 'Open T3 Code; the thread is in its list.', { t3_thread_id: ref.t3_thread_id, conversation_id: ref.conversation_id ?? null, workspace_key: ref.workspace_key ?? null });
+}
+function t3Started(error, ref) {
+    const info = describeError(error);
+    return new CodedError(error instanceof CodedError && error.code.startsWith('t3_') ? error.code : 't3_server_unreachable', `Started the thread in T3 Code, then: ${info.message}`, 'Open T3 Code; the thread is in its list.', { t3_thread_id: ref.t3_thread_id, conversation_id: ref.conversation_id ?? null, workspace_key: null });
+}
+export const t3NotInstalled = () => new CodedError('t3_not_installed', 'T3 Code is not installed on this computer.', 'Install T3 Code from https://t3.codes, open it once, then run this again.');
+const t3NotConnected = (message, fix) => new CodedError('t3_not_connected', message, fix);
+const t3Unreachable = (message, fix = 'Open T3 Code, then run this again.') => new CodedError('t3_server_unreachable', message, fix);
+const t3Unsupported = (message) => new CodedError('t3_version_unsupported', message, 'Update T3 Code (Settings → About), then run this again.');
+/** A T3 server newer than this shard speaks: shard is what needs the update. */
+const t3TooNew = (message) => new CodedError('t3_version_unsupported', message, 'Update shard with shard update, then run this again.');
+/** The first line of the prompt, as T3 titles a thread before it names it. */
+export function t3ThreadTitle(prompt) {
+    const line = prompt.split('\n').map(l => l.trim()).find(Boolean) ?? 'New thread';
+    return line.length > 80 ? `${line.slice(0, 79).trimEnd()}…` : line;
+}
+/**
+ * Opens T3 Code (or brings it to the front): the install `shard` chose. On macOS `open -a <path>` (every T3 channel
+ * shares one bundle id, so `open -b` could start another installed channel); on Linux its desktop entry with
+ * `gtk-launch`, else its program (t3-linux.ts).
+ */
+export async function openT3(env, install) {
+    if (!install)
+        throw t3NotInstalled();
+    if (install.linux)
+        return openLinuxT3(env, { path: install.path, version: install.version, linux: install.linux });
+    const child = spawn('open', ['-a', install.path], { env, stdio: 'ignore' });
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('T3 Code did not open in time')); }, 10_000);
+        child.once('error', e => { clearTimeout(timer); reject(e); });
+        child.once('exit', code => { clearTimeout(timer); if (code === 0)
+            resolve();
+        else
+            reject(new Error(`could not open T3 Code (open exited ${code})`)); });
+    });
+}
+// ── SSH mode: the T3 server in the project VM ──────────────────────────────────────────────────────────────────────
+/** Starts the thread in the VM's T3 server (T3_THREAD_SCRIPT); the prompt travels on stdin, never in argv. */
+export async function startSshThread(ctx, ws, version, projectPath, request) {
+    if (!version)
+        throw t3Unsupported('The installed T3 Code reports no release version, so the matching T3 server cannot run in the workspace.');
+    const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+    // Images go into the VM as files first (exec stdin is bounded); the script attaches them inline and removes them.
+    const images = request.images ?? [];
+    const unreachable = (error) => error instanceof CodedError ? error
+        : t3Unreachable(`T3 in ${ws.key} could not be reached: ${describeError(error).message}`, 'Run shard agents new --in t3 again.');
+    try {
+        await uploadInitialImages(cell, images, ctx.signal);
+    }
+    catch (error) {
+        throw unreachable(error);
+    }
+    const input = {
+        version, install_script: t3InstallScript(version), project_path: projectPath, app: request.app, model: request.model ?? null, effort: request.effort ?? null,
+        title: t3ThreadTitle(request.prompt), prompt: request.prompt, default_model: T3_DEFAULT_MODEL[request.app], standin_path: '/home/user/.local/bin/sf-t3-tunnel',
+        images: images.map((image, i) => ({ path: image.path, name: `image-${i + 1}.${image.type === 'jpeg' ? 'jpg' : image.type}`, mime: `image/${image.type}` })),
+    };
+    let run;
+    try {
+        run = await cell.exec.run(['python3', '-c', T3_THREAD_SCRIPT], { user: 'user', stdin: JSON.stringify(input), timeoutMs: 360_000, maxOutputBytes: 1 << 16, signal: ctx.signal });
+    }
+    catch (error) {
+        throw unreachable(error);
+    }
+    let result;
+    try {
+        result = JSON.parse(run.stdout.trim().split('\n').at(-1) ?? '');
+    }
+    catch {
+        throw t3Unreachable(`T3 in ${ws.key} gave no answer${run.stderr.trim() ? `: ${run.stderr.trim().slice(0, 300)}` : ''}.`, `Run shard agents new --in t3 again.`);
+    }
+    if (result.ok !== true || typeof result.thread_id !== 'string')
+        throw sshThreadError(ws.key, result);
+    const effort = typeof result.effort === 'string' ? result.effort : null;
+    return { mode: 'ssh', t3_thread_id: result.thread_id, conversation_id: null, workspace: { workspace_key: ws.key, id: ws.id },
+        model: typeof result.model === 'string' ? result.model : null, effort, ...(request.effort && !effort ? { effort_reason: 'not_offered' } : {}) };
+}
+function sshThreadError(key, result) {
+    const message = typeof result.message === 'string' ? result.message : `T3 in ${key} did not start the thread.`;
+    // thread.create succeeded before a later step failed: the thread is in T3 and is named, so it is opened, not duplicated.
+    const thread = typeof result.thread_id === 'string' ? { t3_thread_id: result.thread_id } : {};
+    switch (result.error) {
+        case 'version_unsupported': return t3TooNew(`T3 ${typeof result.server_version === 'string' ? result.server_version : ''} in ${key} is newer than this shard supports (orchestration protocol ${String(result.protocol)}).`.replace('T3  in', 'T3 in'));
+        case 'model_unavailable': return new CodedError('t3_model_unavailable', message, 'Choose one of the listed models with --model.', { models: Array.isArray(result.models) ? result.models : [] });
+        case 'dispatch_failed': return new CodedError('t3_thread_failed', message, 'Run the command again; the project checkout in the workspace must exist.', { status: result.status ?? null, tag: result.tag ?? null, reason: result.reason ?? null, ...thread });
+        default: return new CodedError('t3_server_unreachable', message, `Run shard agents new --in t3 again; T3 in ${key} starts its server on the next try.`, thread);
+    }
+}
+async function describe(origin, signal) {
+    try {
+        const r = await fetch(`${origin}/.well-known/t3/environment`, { signal: AbortSignal.any([signal, AbortSignal.timeout(3000)]) });
+        return r.ok ? await r.json() : undefined;
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw error;
+        return undefined;
+    }
+}
+async function runningServer(base, signal) {
+    let runtime;
+    try {
+        runtime = JSON.parse(readFileSync(join(base, 'userdata', 'server-runtime.json'), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    const origin = typeof runtime.origin === 'string' ? runtime.origin : '';
+    if (!/^http:\/\/(127\.0\.0\.1|localhost):\d{1,5}$/.test(origin) || !Number.isSafeInteger(runtime.pid))
+        return undefined;
+    try {
+        process.kill(runtime.pid, 0);
+    }
+    catch (error) {
+        if (error.code !== 'EPERM')
+            return undefined;
+    }
+    const descriptor = await describe(origin, signal);
+    return descriptor ? { origin, descriptor, base } : undefined;
+}
+/** The running desktop server; T3 is opened (which starts it) when none answers. */
+export async function localT3Server(ctx, install, waitMs = T3_START_WAIT_MS) {
+    const base = t3HomeDir(ctx.io.env);
+    const found = await runningServer(base, ctx.signal);
+    if (found)
+        return found;
+    await openT3(ctx.io.env, install);
+    const deadline = Date.now() + waitMs;
+    while (Date.now() < deadline) {
+        await delay(500, undefined, { signal: ctx.signal });
+        const started = await runningServer(base, ctx.signal);
+        if (started)
+            return started;
+    }
+    throw t3Unreachable(`T3 Code’s server did not answer within ${Math.round(waitMs / 1000)} s.`);
+}
+/**
+ * The server CLI the app bundles: on macOS the bundle's executable with `<app.asar>/apps/server/dist/bin.mjs`; on Linux
+ * the app's own executable the same way, or for an AppImage T3's own launcher (linuxServerCli).
+ */
+function serverCli(install, env) {
+    if (install.linux) {
+        const cli = linuxServerCli({ path: install.path, version: install.version, linux: install.linux }, t3HomeDir(env));
+        if (!cli)
+            throw t3Unreachable(`T3 Code has not written its command line launcher (${join(t3HomeDir(env), 'bin', 't3')}) yet.`, 'Open T3 Code once, then run this again.');
+        return cli;
+    }
+    const r = spawnSync('/usr/libexec/PlistBuddy', ['-c', 'Print :CFBundleExecutable', join(install.path, 'Contents', 'Info.plist')], { encoding: 'utf8', input: '', timeout: 2000 });
+    const exe = r.status === 0 ? r.stdout.trim() : '';
+    if (!exe || exe.includes('/'))
+        throw t3Unsupported('The installed T3 Code bundle names no executable.');
+    return { command: join(install.path, 'Contents', 'MacOS', exe), args: [join(install.path, 'Contents', 'Resources', 'app.asar', 'apps', 'server', 'dist', 'bin.mjs')] };
+}
+/** Runs the T3 server CLI the app bundles (Electron as Node), the same code the desktop runs as its backend. */
+function t3Cli(ctx, install, args) {
+    const cli = serverCli(install, ctx.io.env);
+    return new Promise((resolve, reject) => {
+        const child = spawn(cli.command, [...cli.args, ...args], { env: { ...ctx.io.env, ELECTRON_RUN_AS_NODE: '1' }, stdio: ['ignore', 'pipe', 'pipe'], signal: ctx.signal });
+        let stdout = '', stderr = '';
+        child.stdout.on('data', (c) => { stdout += c.toString(); });
+        child.stderr.on('data', (c) => { stderr += c.toString(); });
+        const timer = setTimeout(() => child.kill('SIGKILL'), 60_000);
+        child.once('error', e => { clearTimeout(timer); reject(e); });
+        child.once('close', code => { clearTimeout(timer); resolve({ code, stdout, stderr }); });
+    });
+}
+async function issueSession(ctx, install, base) {
+    const r = await t3Cli(ctx, install, ['auth', 'session', 'issue', '--base-dir', base, '--ttl', '5m', '--label', 'Shardflux thread start', '--json']);
+    let session = {};
+    try {
+        session = JSON.parse(r.stdout);
+    }
+    catch { /* reported below */ }
+    if (r.code !== 0 || typeof session.token !== 'string' || typeof session.sessionId !== 'string')
+        throw t3Unreachable(`T3 Code did not issue a session${r.stderr.trim() ? `: ${r.stderr.trim().split('\n').at(-1)}` : ''}.`);
+    ctx.addSecret(session.token);
+    return { token: session.token, sessionId: session.sessionId };
+}
+async function revokeSession(ctx, install, base, session) {
+    await t3Cli({ ...ctx, signal: new AbortController().signal }, install, ['auth', 'session', 'revoke', session.sessionId, '--base-dir', base]).catch(() => undefined);
+}
+class T3HttpError extends Error {
+    status;
+    tag;
+    reason;
+    constructor(status, tag, reason, path) {
+        super(`T3 Code answered ${path} with ${status}${tag ? ` ${tag}` : ''}${reason ? ` (${reason})` : ''}.`);
+        this.status = status;
+        this.tag = tag;
+        this.reason = reason;
+    }
+}
+async function t3Http(server, session, method, path, signal, body) {
+    const r = await fetch(server.origin + path, {
+        method, signal: AbortSignal.any([signal, AbortSignal.timeout(30_000)]),
+        headers: { authorization: `Bearer ${session.token}`, accept: 'application/json', 'x-t3-orchestration-protocol': '2', ...(body !== undefined ? { 'content-type': 'application/json' } : {}) },
+        ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+    });
+    const text = await r.text();
+    let parsed;
+    try {
+        parsed = text ? JSON.parse(text) : {};
+    }
+    catch {
+        parsed = {};
+    }
+    const doc = objectValue(parsed);
+    if (!r.ok)
+        throw new T3HttpError(r.status, typeof doc._tag === 'string' ? doc._tag : undefined, typeof doc.reason === 'string' ? doc.reason : undefined, path);
+    return doc;
+}
+/** One Effect RPC request over T3's WebSocket (JSON frames: Request → Exit), authorized by a ticket from the session. */
+export async function t3Rpc(server, session, tag, payload, signal, timeoutMs = 30_000) {
+    const ticket = await t3Http(server, session, 'POST', '/api/auth/websocket-ticket', signal);
+    if (typeof ticket.ticket !== 'string')
+        throw t3Unreachable('T3 Code issued no WebSocket ticket.');
+    const url = new URL('/ws', server.origin.replace(/^http/, 'ws'));
+    url.searchParams.set('wsTicket', ticket.ticket);
+    url.searchParams.set('orchestrationProtocol', '2');
+    const ws = new WebSocket(url);
+    try {
+        return await new Promise((resolve, reject) => {
+            const fail = (error) => { clearTimeout(timer); signal.removeEventListener('abort', aborted); reject(error); };
+            const aborted = () => fail(signal.reason instanceof Error ? signal.reason : new Error('aborted'));
+            const timer = setTimeout(() => fail(t3Unreachable(`T3 Code did not answer ${tag} within ${Math.round(timeoutMs / 1000)} s.`)), timeoutMs);
+            signal.addEventListener('abort', aborted, { once: true });
+            ws.onopen = () => ws.send(JSON.stringify({ _tag: 'Request', id: '1', tag, payload, headers: [] }));
+            ws.onerror = () => fail(t3Unreachable(`T3 Code refused the WebSocket connection for ${tag}.`));
+            ws.onclose = event => fail(t3Unreachable(`T3 Code closed the connection before answering ${tag} (${event.code}).`));
+            ws.onmessage = event => {
+                let data;
+                try {
+                    data = JSON.parse(String(event.data));
+                }
+                catch {
+                    return;
+                }
+                for (const raw of Array.isArray(data) ? data : [data]) {
+                    const message = objectValue(raw);
+                    if (message._tag === 'Ping')
+                        ws.send(JSON.stringify({ _tag: 'Pong' }));
+                    else if (message._tag === 'Exit' && String(message.requestId) === '1') {
+                        clearTimeout(timer);
+                        signal.removeEventListener('abort', aborted);
+                        const exit = objectValue(message.exit);
+                        if (exit._tag === 'Success')
+                            resolve(exit.value);
+                        else
+                            reject(new T3RpcFailure(tag, exit.cause));
+                    }
+                    else if (message._tag === 'Defect' || message._tag === 'ClientProtocolError')
+                        fail(new T3RpcFailure(tag, [message]));
+                }
+            };
+        });
+    }
+    finally {
+        ws.onclose = null;
+        ws.close();
+    }
+}
+class T3RpcFailure extends Error {
+    causes;
+    constructor(tag, cause) {
+        const causes = (Array.isArray(cause) ? cause : [cause]).map(objectValue);
+        const error = objectValue(causes[0]?.error ?? causes[0]?.defect);
+        super(`T3 Code refused ${tag}: ${typeof error.message === 'string' ? error.message : (typeof error._tag === 'string' ? error._tag : 'failed')}.`);
+        this.causes = causes;
+    }
+}
+async function ensureLocalProject(server, session, folder, signal) {
+    const root = realpathSync(folder);
+    const snapshot = await t3Http(server, session, 'GET', '/api/projects', signal);
+    const projects = Array.isArray(snapshot.projects) ? snapshot.projects.map(objectValue) : [];
+    const existing = projects.find(p => p.deletedAt === null && p.workspaceRoot === root && typeof p.id === 'string');
+    if (existing)
+        return existing.id;
+    const created = await t3Http(server, session, 'POST', '/api/projects/mutate', signal, { type: 'project.create', commandId: randomUUID(), projectId: randomUUID(), title: basename(root) || 'project', workspaceRoot: root });
+    if (typeof created.id !== 'string')
+        throw t3Unreachable('T3 Code did not return the project it created.');
+    return created.id;
+}
+/**
+ * The Shardflux provider's model: `shardflux:<app>:<id>`, `default` unless asked. With the conversation catalog this
+ * computer cached for the project (acp-models.ts), an unknown model is refused before anything starts, and an effort is
+ * sent only as a config option the session offers (T3 applies modelSelection.options by ACP config option id).
+ */
+function acpSelection(ctx, folder, request) {
+    const raw = request.model ?? 'default';
+    const prefixed = /^shardflux:(claude|codex):(.+)$/.exec(raw);
+    if (prefixed && prefixed[1] !== request.app)
+        throw new UsageError(`--model ${raw} is a ${prefixed[1]} model; use --app ${prefixed[1]}.`);
+    const id = prefixed ? prefixed[2] : raw;
+    const native = new AcpModelCache(ctx.store.dir).lookup(ctx, folder)?.catalog[request.app];
+    if (native && id !== 'default') {
+        let ids = [];
+        try {
+            ids = nativeModelOptions(native).map(o => String(o.value));
+        }
+        catch { /* an unreadable catalog checks nothing */ }
+        if (ids.length && !ids.includes(id))
+            throw new CodedError('t3_model_unavailable', `Shardflux has no ${request.app} model ${id} for this project.`, `Choose one of: ${ids.join(', ')}.`, { models: ids });
+    }
+    const model = `shardflux:${request.app}:${id}`;
+    let effort = null, option;
+    if (request.effort && native) {
+        const configs = Array.isArray(native.configOptions) ? native.configOptions.map(objectValue) : [];
+        option = configs.find(c => c.type === 'select' && (c.category === 'thought_level' || ['effort', 'reasoning_effort', 'reasoningEffort', 'thought_level'].includes(String(c.id))));
+        const values = Array.isArray(option?.options) ? option.options.flatMap(o => { const v = objectValue(o); return Array.isArray(v.options) ? v.options.map(x => objectValue(x).value) : [v.value]; }) : [];
+        if (option && values.includes(request.effort))
+            effort = request.effort;
+    }
+    // The levels a session offers are known from this project's first Shardflux conversation on this computer.
+    const effortReason = request.effort && !effort ? (native ? 'not_offered' : 'models_not_known') : undefined;
+    return { selection: { instanceId: 'shardflux', model, ...(effort && option ? { options: [{ id: String(option.id), value: effort }] } : {}) }, model, effort, ...(effortReason ? { effortReason } : {}) };
+}
+/**
+ * Images for the first message (T3 0.0.46+): `attachments.createUploadUrl` over the RPC, then the bytes to the signed
+ * upload URL (POST, exact Content-Length); the launch then claims them by id.
+ */
+async function uploadLocalImages(server, session, images, signal) {
+    const attachments = [];
+    for (const [i, image] of images.entries()) {
+        const meta = { type: 'image', name: `image-${i + 1}.${image.type === 'jpeg' ? 'jpg' : image.type}`, mimeType: `image/${image.type}`, sizeBytes: image.data.byteLength };
+        const issued = objectValue(await t3Rpc(server, session, 'attachments.createUploadUrl', meta, signal));
+        if (typeof issued.attachmentId !== 'string' || typeof issued.relativeUrl !== 'string' || !issued.relativeUrl.startsWith('/'))
+            throw new CodedError('t3_thread_failed', 'T3 Code issued no upload URL for the image.', 'Run the command again.');
+        const r = await fetch(server.origin + issued.relativeUrl, { method: 'POST', body: image.data, headers: { 'content-type': meta.mimeType, 'content-length': String(image.data.byteLength) }, signal: AbortSignal.any([signal, AbortSignal.timeout(60_000)]) });
+        if (!r.ok) {
+            const detail = (await r.text().catch(() => '')).trim().slice(0, 200);
+            throw new CodedError('t3_thread_failed', `T3 Code refused the image upload (${r.status}${detail ? `: ${detail}` : ''}).`, 'Attach a PNG, JPEG, GIF or WebP image of at most 10 MiB.');
+        }
+        attachments.push({ type: 'image', id: issued.attachmentId, name: meta.name, mimeType: meta.mimeType, sizeBytes: meta.sizeBytes });
+    }
+    return attachments;
+}
+/** The VM of a conversation the Shardflux provider recorded on this computer (its ACP session record in agents.json). */
+async function conversationWorkspaceRef(ctx, conversationId) {
+    const state = new AgentStateStore(ctx.store.dir).read();
+    const record = objectValue(objectValue(objectValue(state.conversations)[conversationId]).conversation);
+    const session = Object.values(objectValue(state.acp_sessions)).map(objectValue).find(r => r.conversationId === conversationId);
+    const id = typeof record.workspace_id === 'string' ? record.workspace_id : typeof session?.workspaceId === 'string' ? session.workspaceId : null;
+    if (!id)
+        return null;
+    try {
+        return { workspace_key: (await ctx.cloud().workspaces.get(id)).key, id };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The conversation of the Shardflux ACP session a T3 thread opened. T3 names that session in the thread's attempts
+ * (`nativeThreadId`) once the first turn starts; until then the one session the provider opened for this folder since
+ * the launch is it (agents.json, shared with the `shard acp` T3 runs). Null when neither settles within the wait.
+ */
+async function threadConversation(ctx, server, session, threadId, folder, known, waitMs) {
+    const deadline = Date.now() + waitMs;
+    const store = new AgentStateStore(ctx.store.dir);
+    let native;
+    while (!ctx.signal.aborted) {
+        if (!native) {
+            try {
+                const detail = await t3Http(server, session, 'GET', `/api/orchestration/threads/${encodeURIComponent(threadId)}`, ctx.signal);
+                const attempts = Array.isArray(objectValue(detail.projection).attempts) ? objectValue(detail.projection).attempts : [];
+                native = attempts.map(a => objectValue(a).nativeThreadId).find((id) => typeof id === 'string' && id.startsWith('sf-') && !known.has(id));
+            }
+            catch { /* the thread is still being set up */ }
+        }
+        const sessions = objectValue(store.read().acp_sessions);
+        if (native) {
+            const record = objectValue(sessions[native]);
+            if (typeof record.conversationId === 'string')
+                return record.conversationId;
+        }
+        else {
+            const fresh = Object.entries(sessions).filter(([id, r]) => !known.has(id) && objectValue(r).folder === folder).map(([, r]) => objectValue(r));
+            if (fresh.length === 1 && typeof fresh[0].conversationId === 'string')
+                return fresh[0].conversationId;
+        }
+        if (Date.now() >= deadline)
+            return null;
+        await delay(500, undefined, { signal: ctx.signal });
+    }
+    return null;
+}
+/** Starts a T3 thread on the Shardflux provider (ACP mode) and brings T3 to the front. */
+export async function startAcpThread(ctx, install, folder, request, waitMs = CONVERSATION_WAIT_MS) {
+    if (!acpSignedIn(ctx))
+        throw t3NotConnected('This computer is not signed in to Shardflux, so T3 Code’s Shardflux provider cannot start a VM.', SIGN_IN_FIX);
+    if (!t3ProviderRegistered(ctx.io.env)) {
+        try {
+            await configureT3Provider(ctx.io.env, ctx.store.dir, false, ctx.signal);
+        }
+        catch { /* reported below */ }
+        if (!t3ProviderRegistered(ctx.io.env))
+            throw t3NotConnected('T3 Code has no Shardflux provider.', 'In T3 Code, Settings → Providers → Add → Shardflux (or remove the other provider named shardflux), then run this again.');
+    }
+    const server = await localT3Server(ctx, install);
+    const protocol = server.descriptor.orchestrationProtocolVersion ?? 1;
+    const named = `T3 Code ${server.descriptor.serverVersion ?? install.version ?? ''}`.trimEnd();
+    if (protocol < 2)
+        throw t3Unsupported(`${named} speaks orchestration protocol ${protocol}; Shardflux threads need protocol 2.`);
+    if (protocol > 2)
+        throw t3TooNew(`${named} is newer than this shard supports (orchestration protocol ${protocol}).`);
+    const { selection, model, effort, effortReason } = acpSelection(ctx, folder, request);
+    const session = await issueSession(ctx, install, server.base);
+    try {
+        const projectId = await ensureLocalProject(server, session, folder, ctx.signal);
+        const known = new Set(Object.keys(objectValue(new AgentStateStore(ctx.store.dir).read().acp_sessions)));
+        const attachments = await uploadLocalImages(server, session, request.images ?? [], ctx.signal);
+        const threadId = randomUUID();
+        let launched;
+        try {
+            launched = await t3Rpc(server, session, 'orchestration.launchThread', {
+                commandId: randomUUID(), threadId, projectId, title: t3ThreadTitle(request.prompt), modelSelection: selection, runtimeMode: 'full-access', interactionMode: 'default',
+                workspaceStrategy: { type: 'root' }, initialMessage: { messageId: randomUUID(), text: request.prompt, attachments },
+            }, ctx.signal);
+        }
+        catch (error) {
+            if (error instanceof T3RpcFailure && /No orchestration provider adapter is registered for shardflux/.test(JSON.stringify(error.causes))) {
+                throw t3NotConnected('T3 Code has not loaded its Shardflux provider yet.', 'Open T3 Code’s Settings → Providers, check Shardflux is on, then run this again.');
+            }
+            if (error instanceof T3RpcFailure)
+                throw new CodedError('t3_thread_failed', error.message, 'Run the command again.');
+            throw error;
+        }
+        const id = objectValue(launched).threadId;
+        const t3ThreadId = typeof id === 'string' ? id : threadId;
+        // The thread exists from here on: T3 comes to the front first, and a failure after this names the thread.
+        const opened = await openT3(ctx.io.env, install).then(() => undefined, (error) => error);
+        let conversation = null;
+        try {
+            conversation = await threadConversation(ctx, server, session, t3ThreadId, realpathSync(folder), known, waitMs);
+            if (conversation)
+                new AgentStateStore(ctx.store.dir).update(doc => { doc.t3_threads = { ...objectValue(doc.t3_threads), [conversation]: t3ThreadId }; });
+        }
+        catch (error) {
+            throw t3Started(error, { t3_thread_id: t3ThreadId, conversation_id: conversation });
+        }
+        const workspace = conversation ? await conversationWorkspaceRef(ctx, conversation) : null;
+        if (opened)
+            throw t3OpenFailed(opened, { t3_thread_id: t3ThreadId, conversation_id: conversation, workspace_key: workspace?.workspace_key ?? null });
+        return { mode: 'acp', t3_thread_id: t3ThreadId, conversation_id: conversation, workspace, model, effort, ...(effortReason ? { effort_reason: effortReason } : {}) };
+    }
+    finally {
+        await revokeSession(ctx, install, server.base, session);
+    }
+}
+const stamp = (thread) => typeof thread.updatedAt === 'string' ? thread.updatedAt : typeof thread.createdAt === 'string' ? thread.createdAt : '';
+/** The T3 thread of a Shardflux conversation started in T3 (ACP mode): the one remembered, else a search of recent Shardflux threads. */
+export async function findAcpThread(ctx, install, conversationId) {
+    const state = new AgentStateStore(ctx.store.dir).read();
+    const remembered = objectValue(state.t3_threads)[conversationId];
+    if (typeof remembered === 'string')
+        return remembered;
+    const sessions = new Set(Object.entries(objectValue(state.acp_sessions)).filter(([, r]) => objectValue(r).conversationId === conversationId).map(([id]) => id));
+    if (!sessions.size)
+        return null;
+    const server = await localT3Server(ctx, install);
+    if ((server.descriptor.orchestrationProtocolVersion ?? 1) !== 2)
+        return null;
+    const session = await issueSession(ctx, install, server.base);
+    try {
+        const shell = await t3Http(server, session, 'GET', '/api/orchestration/shell', ctx.signal);
+        const threads = (Array.isArray(shell.threads) ? shell.threads.map(objectValue) : []).filter(t => t.providerInstanceId === 'shardflux' && typeof t.id === 'string')
+            .sort((a, b) => stamp(b).localeCompare(stamp(a))).slice(0, 25);
+        for (const thread of threads) {
+            const detail = await t3Http(server, session, 'GET', `/api/orchestration/threads/${encodeURIComponent(thread.id)}`, ctx.signal).catch(() => ({}));
+            const attempts = objectValue(objectValue(detail).projection).attempts;
+            if (Array.isArray(attempts) && attempts.some(a => sessions.has(String(objectValue(a).nativeThreadId)))) {
+                new AgentStateStore(ctx.store.dir).update(doc => { doc.t3_threads = { ...objectValue(doc.t3_threads), [conversationId]: thread.id }; });
+                return thread.id;
+            }
+        }
+        return null;
+    }
+    finally {
+        await revokeSession(ctx, install, server.base, session);
+    }
+}