@shardflux/cli 0.16.0 → 0.18.0-next.4

package/dist/t3-asar.js

@@ -0,0 +1,91 @@
+/**
+ * T3 Code's app.asar, read in place (nothing is extracted or run): the app's release version (its package.json) and
+ * whether its server has the ACP Registry provider driver. The same archive ships in the macOS bundle
+ * (Contents/Resources/app.asar) and in the Linux packages (`/opt/T3 Code (Alpha)/resources/app.asar` from the .deb).
+ * Answers are kept for the process per archive, keyed by its size and modification time.
+ */
+import { closeSync, openSync, readFileSync, readSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/** The server CLI inside the archive: what Electron runs as Node to issue T3 sessions. */
+export const T3_SERVER_ENTRY = 'apps/server/dist/bin.mjs';
+const RELEASE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const DRIVER = ['ProviderDriverKind.make("acpRegistry")', "ProviderDriverKind.make('acpRegistry')"].map(s => Buffer.from(s));
+const MAX_FILE = 64 << 20;
+const known = new Map();
+/** One fact about an archive, computed from its header once per size and modification time; `fallback` when unreadable. */
+function fact(archive, key, compute, fallback) {
+    let fd;
+    try {
+        const stat = statSync(archive), stamp = `${stat.size}:${stat.mtimeMs}`;
+        const seen = known.get(archive)?.stamp === stamp ? known.get(archive) : { stamp };
+        if (seen[key] !== undefined)
+            return seen[key];
+        fd = openSync(archive, 'r');
+        const sizes = Buffer.alloc(16);
+        if (readSync(fd, sizes, 0, 16, 0) !== 16)
+            return fallback;
+        const headerSize = sizes.readUInt32LE(12);
+        if (headerSize < 1 || headerSize > 16 << 20)
+            return fallback;
+        const header = Buffer.alloc(headerSize);
+        if (readSync(fd, header, 0, headerSize, 16) !== headerSize)
+            return fallback;
+        const value = compute({ path: archive, fd, size: stat.size, base: 8 + sizes.readUInt32LE(4), header: JSON.parse(header.toString()) });
+        known.set(archive, { ...seen, [key]: value });
+        return value;
+    }
+    catch {
+        return fallback;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function entry(a, path) {
+    let e = a.header;
+    for (const part of path.split('/'))
+        e = e?.files?.[part];
+    return e && !e.files ? e : undefined;
+}
+/** One file's bytes, from the archive or its `.unpacked` folder; undefined when it is missing or out of bounds. */
+function read(a, path) {
+    const e = entry(a, path), size = e?.size;
+    if (!e || !Number.isSafeInteger(size) || !size || size < 1 || size > MAX_FILE)
+        return undefined;
+    if (e.unpacked)
+        return readFileSync(join(`${a.path}.unpacked`, path));
+    const offset = Number(e.offset) + a.base;
+    if (!Number.isSafeInteger(offset) || offset < 16 || offset + size > a.size)
+        return undefined;
+    const bytes = Buffer.alloc(size);
+    return readSync(a.fd, bytes, 0, size, offset) === size ? bytes : undefined;
+}
+/** The app's release version (package.json `version`, e.g. `0.0.46-nightly.20261010.2908`), or null. */
+export function asarVersion(archive) {
+    return fact(archive, 'version', a => {
+        const version = JSON.parse(read(a, 'package.json')?.toString() ?? '{}').version;
+        return typeof version === 'string' && RELEASE.test(version) ? version : null;
+    }, null) ?? null;
+}
+/**
+ * Whether the server registers the ACP Registry driver. A version number alone is insufficient (0.0.45 lacks it while
+ * upstream main had it). Builds put the driver in `bin.mjs` itself, or (nightlies since October 2026) in a chunk the
+ * thin `bin.mjs` entry imports (`binCli-<hash>.mjs`): the entry and the chunks it names are searched.
+ */
+export function t3ArchiveSupportsAcp(archive) {
+    return fact(archive, 'acp', a => {
+        const has = (bytes) => !!bytes && DRIVER.some(marker => bytes.includes(marker));
+        const bin = read(a, T3_SERVER_ENTRY);
+        if (!bin)
+            return false;
+        if (has(bin))
+            return true;
+        // A whole server in bin.mjs (0.0.45: 9 MB) without the driver has none; only a thin entry defers to chunks.
+        if (bin.length > 256 << 10)
+            return false;
+        const dir = T3_SERVER_ENTRY.slice(0, T3_SERVER_ENTRY.lastIndexOf('/') + 1);
+        const chunks = [...bin.toString().matchAll(/(?:\bimport\s*\(\s*|\bfrom\s*)["']\.\/([\w.-]+\.m?js)["']/g)].map(m => m[1]);
+        return [...new Set(chunks)].slice(0, 16).some(chunk => has(read(a, dir + chunk)));
+    }, false) === true;
+}

package/dist/t3-launch.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The CLI side of T3 Code mode (0.17.0+): `shard agents new --in t3 [--prompt…] [--on <ref>]`, `shard ./` and
+ * `--in auto` when T3 is where new conversations open, and `shard agents open t3 <conversation|workspace>`.
+ * --json results (contract shared with the menu bar):
+ *   new:  { target: "t3", mode, project, t3_thread_id, conversation_id, workspace: { workspace_key, id } | null,
+ *           opened: true, focused: false, model, effort, ... }
+ *   open: { opened: true, t3_thread_id, focused: false, ... }
+ * `focused` is false: T3 has no way to show a given thread from outside, so T3 is brought to the front instead.
+ */
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import type { Values } from './args.js';
+import type { AgentApp, T3Install, T3ThreadRequest, T3ThreadResult } from './t3-mode.js';
+/**
+ * A `t3_*` refusal raised once the workspace, conversation or thread exists names them (details.workspace_key,
+ * conversation_id, t3_thread_id), so a client opens what exists instead of starting it again.
+ */
+export declare function withT3Context(error: unknown, ref: {
+    workspace_key?: string | null;
+    conversation_id?: string | null;
+    t3_thread_id?: string | null;
+}): unknown;
+/** The thread to start, when the command carries a first message (`--prompt`, `--prompt-file`, `--image`, `--model`, `--effort`). */
+export declare function t3ThreadRequest(ctx: Ctx, values: Values, app: AgentApp): Promise<T3ThreadRequest | undefined>;
+/**
+ * `agents new --in t3`: with a first message in ACP mode, the thread starts on T3's Shardflux provider (its own VM);
+ * otherwise the project VM is opened as T3's SSH environment (with its phone link), and a first message becomes a
+ * thread on the T3 server in that VM. `--on <ref>` uses that existing workspace instead of the project VM.
+ */
+export declare function launchT3(ctx: Ctx, values: Values, path: string, explicitApp: string | undefined): Promise<number>;
+/** The T3 fields of an SSH-mode result (the thread, when one was started in the VM). */
+export declare function t3Fields(ws: Workspace, project: string, install: T3Install | undefined, started: T3ThreadResult | undefined, conversation?: string | null): Record<string, unknown>;
+/**
+ * `agents open t3 <conversation>` for a conversation that runs on T3's Shardflux provider (ACP mode): T3 is brought to
+ * the front with that thread's id. A conversation of another route opens its VM as T3's SSH environment.
+ */
+export declare function openT3Conversation(ctx: Ctx, conversationId: string, values?: Values): Promise<number>;

package/dist/t3-launch.js

@@ -0,0 +1,133 @@
+import { out, resolveWorkspace, str } from "./commands.js";
+import { CodedError, NotFoundError, UsageError } from "./errors.js";
+import { projectIdentity } from "./project-identity.js";
+import { AgentStateStore } from "./agent-state.js";
+import { readInitialImages, readInitialPrompt } from "./initial-prompt.js";
+import { findAcpThread, openT3, startAcpThread, t3Install, t3NotInstalled, t3OpenFailed } from "./t3-mode.js";
+import { agentReachability } from "./agent-reachability.js";
+import { conversationWorkspace, getConversation } from "./conversations.js";
+import { resolveOn } from "./thread-on-computer.js";
+import { ensureCloudClaude } from "./claude-cloud-login.js";
+import { modelChoice } from "./agent-models.js";
+/**
+ * A `t3_*` refusal raised once the workspace, conversation or thread exists names them (details.workspace_key,
+ * conversation_id, t3_thread_id), so a client opens what exists instead of starting it again.
+ */
+export function withT3Context(error, ref) {
+    if (!(error instanceof CodedError) || !error.code.startsWith('t3_'))
+        return error;
+    const details = { ...error.details, conversation_id: ref.conversation_id ?? error.details?.conversation_id ?? null, workspace_key: ref.workspace_key ?? error.details?.workspace_key ?? null,
+        t3_thread_id: ref.t3_thread_id ?? error.details?.t3_thread_id ?? null };
+    const next = new CodedError(error.code, error.message, error.hint, details);
+    next.stack = error.stack;
+    return next;
+}
+/** The thread to start, when the command carries a first message (`--prompt`, `--prompt-file`, `--image`, `--model`, `--effort`). */
+export async function t3ThreadRequest(ctx, values, app) {
+    const prompt = await readInitialPrompt(ctx, values);
+    const images = await readInitialImages(ctx, values, prompt);
+    if (prompt === undefined) {
+        if (values.model !== undefined || values.effort !== undefined)
+            throw new UsageError('--model and --effort choose how the first message runs: add --prompt or --prompt-file.');
+        return undefined;
+    }
+    // The same choices as every other new thread (agent-models.ts); "default" leaves the agent's own.
+    const choice = modelChoice(values, app);
+    return { app, prompt, ...(choice.model ? { model: choice.model } : {}), ...(choice.effort ? { effort: choice.effort } : {}), ...(images.length ? { images } : {}) };
+}
+/**
+ * `agents new --in t3`: with a first message in ACP mode, the thread starts on T3's Shardflux provider (its own VM);
+ * otherwise the project VM is opened as T3's SSH environment (with its phone link), and a first message becomes a
+ * thread on the T3 server in that VM. `--on <ref>` uses that existing workspace instead of the project VM.
+ */
+export async function launchT3(ctx, values, path, explicitApp) {
+    const install = t3Install(ctx.io.env);
+    if (!install)
+        throw t3NotInstalled();
+    if (explicitApp !== undefined && explicitApp !== 'claude' && explicitApp !== 'codex')
+        throw new UsageError('agent app must be claude or codex');
+    const project = projectIdentity(path);
+    const app = explicitApp ?? new AgentStateStore(ctx.store.dir).app(project.remote ?? project.folder);
+    const request = await t3ThreadRequest(ctx, values, app);
+    const on = str(values.on);
+    if (values.review === true)
+        throw new UsageError('--review starts a Claude reviewer in its terminal; leave out --in t3.');
+    if (on !== undefined) {
+        if (request && install.mode === 'acp') {
+            throw new CodedError('t3_on_not_supported', 'With the Shardflux provider in T3 Code, every thread runs in its own new VM, so it cannot start on an existing workspace.', 'Leave out --on to start the thread in its own VM, or open that workspace in T3 Code with shard agents open t3 <workspace>.', { workspace_key: on, conversation_id: null });
+        }
+        const { ws, conversation } = await onComputer(ctx, on, project.folder);
+        // The thread's agent runs in that VM with the account's logins, as `agents open t3` prepares them.
+        await ensureCloudClaude(ctx, ws);
+        const { openDesktopWorkspace } = await import("./agent-target-commands.js");
+        return openDesktopWorkspace(ctx, ws, 't3', install.version ?? undefined, false, request, install, conversation);
+    }
+    if (request && install.mode === 'acp')
+        return acpThreadOutput(ctx, install, project, request);
+    const { launchProjectWith } = await import("./agent-commands.js");
+    return launchProjectWith(ctx, { ...values, in: 't3' }, [path, app], request, install);
+}
+/**
+ * The computer `--on` names, as for any new thread (thread-on-computer.ts): a workspace key or id, else a conversation
+ * id, key or name (its VM). The T3 server in that VM runs the thread.
+ */
+async function onComputer(ctx, ref, folder) {
+    if (!/^conv_[a-z0-9]{26}$/.test(ref)) {
+        try {
+            const ws = await resolveWorkspace(ctx, ref);
+            return { ws, conversation: ws.labels.shard_conversation || null };
+        }
+        catch (error) {
+            if (!(error instanceof NotFoundError))
+                throw error;
+        }
+    }
+    const target = await resolveOn(ctx, ref, folder);
+    return { ws: await conversationWorkspace(ctx, target), conversation: target.id };
+}
+async function acpThreadOutput(ctx, install, project, request) {
+    const started = await startAcpThread(ctx, install, project.folder, request);
+    new AgentStateStore(ctx.store.dir).saveTarget(project.remote ?? project.folder, 't3');
+    out(ctx, `Started in T3 Code: ${request.prompt.split('\n')[0].slice(0, 80)}${started.conversation_id ? ` (${started.conversation_id})` : ''}\n`, { target: 't3', mode: started.mode, project: project.slug, t3_thread_id: started.t3_thread_id, conversation_id: started.conversation_id, workspace: started.workspace,
+        opened: true, focused: false, model: started.model, effort: started.effort, ...(started.effort_reason ? { effort_reason: started.effort_reason } : {}), app_bundle_id: 'com.t3tools.t3code' });
+    return 0;
+}
+/** The T3 fields of an SSH-mode result (the thread, when one was started in the VM). */
+export function t3Fields(ws, project, install, started, conversation) {
+    return { mode: install?.mode ?? 'ssh', project, t3_thread_id: started?.t3_thread_id ?? null, conversation_id: started?.conversation_id ?? conversation ?? (ws.labels.shard_conversation || null),
+        opened: true, focused: false, model: started?.model ?? null, effort: started?.effort ?? null, ...(started?.effort_reason ? { effort_reason: started.effort_reason } : {}) };
+}
+/**
+ * `agents open t3 <conversation>` for a conversation that runs on T3's Shardflux provider (ACP mode): T3 is brought to
+ * the front with that thread's id. A conversation of another route opens its VM as T3's SSH environment.
+ */
+export async function openT3Conversation(ctx, conversationId, values = {}) {
+    const install = t3Install(ctx.io.env);
+    if (!install)
+        throw t3NotInstalled();
+    const conversation = await getConversation(ctx, conversationId);
+    if (install.mode === 'acp' && conversation.route === 'acp') {
+        let threadId;
+        try {
+            threadId = await findAcpThread(ctx, install, conversationId);
+        }
+        catch (error) {
+            throw withT3Context(error, { conversation_id: conversationId });
+        }
+        try {
+            await openT3(ctx.io.env, install);
+        }
+        catch (error) {
+            throw threadId ? t3OpenFailed(error, { t3_thread_id: threadId, conversation_id: conversationId }) : error;
+        }
+        out(ctx, threadId ? `Opened T3 Code (thread ${threadId}).\n` : 'Opened T3 Code.\n', { target: 't3', mode: 'acp', conversation_id: conversationId, t3_thread_id: threadId, opened: true, focused: false, app_bundle_id: 'com.t3tools.t3code' });
+        return 0;
+    }
+    // Its VM as T3's SSH environment, with the checks every `agents open t3` makes: --reachable and the cloud Claude login.
+    let ws = await conversationWorkspace(ctx, conversation);
+    if (values.reachable !== undefined)
+        ws = await ctx.cloud().workspaces.open({ key: ws.key, ...agentReachability(values), wait: false });
+    await ensureCloudClaude(ctx, ws);
+    const { openDesktopWorkspace } = await import("./agent-target-commands.js");
+    return openDesktopWorkspace(ctx, ws, 't3', install.version ?? undefined, false, undefined, install, conversationId);
+}

package/dist/t3-linux.d.ts

@@ -0,0 +1,68 @@
+type Env = Record<string, string | undefined>;
+export type T3LinuxFormat = 'deb' | 'directory' | 'appimage' | 'flatpak' | 'snap';
+export interface T3LinuxApp {
+    format: T3LinuxFormat;
+    /** The desktop entry's file name (the id `gtk-launch` takes); null for an AppImage found by its file name. */
+    desktop_id: string | null;
+    /** What starts it: the entry's Exec without field codes, or the AppImage. */
+    exec: string[];
+    /** The app's resources/app.asar on this computer (deb, other unpacked installs, flatpak); null for an AppImage or snap. */
+    asar: string | null;
+    /** Flatpak: the app id and the app's files folder on this computer (mounted at /app in its sandbox). */
+    flatpak?: {
+        id: string;
+        files: string;
+    };
+}
+/** A Linux T3 Code: `path` is the program it runs (the executable, or the AppImage). */
+export interface T3LinuxInstall {
+    path: string;
+    version: string | null;
+    linux: T3LinuxApp;
+}
+/** The launcher T3 (nightlies since October 2026) writes to `<T3 home>/bin/t3` for its bundled CLI; for an AppImage it mounts the image itself. */
+export declare const T3_LAUNCHER_MARKER = "Written by T3 Code: runs the desktop app's bundled t3 CLI.";
+/**
+ * The folders scanned on Linux, in XDG precedence: the data home's and each data dir's `applications`, snapd's and
+ * flatpak's exported entries, then the usual AppImage folders. SHARDFLUX_APPLICATIONS_DIRS replaces all of them.
+ */
+export declare function linuxApplicationDirs(env: Env): string[];
+/** The `[Desktop Entry]` group's unlocalized keys (string escapes undone), first value of each key. */
+export declare function desktopEntry(text: string): Record<string, string>;
+/** An entry's Exec as argv (the Desktop Entry quoting rules), field codes and flatpak's @@ markers removed; undefined when malformed. */
+export declare function desktopExec(value: string): string[] | undefined;
+/** The installed T3 Code apps on Linux, from the desktop entries and AppImages in `dirs` (linuxApplicationDirs). */
+export declare function linuxT3Apps(dirs: string[], env: Env): T3LinuxInstall[];
+/**
+ * Whether this install runs the Shardflux provider (ACP mode): the server in its app.asar has the ACP Registry driver
+ * (deb, unpacked installs, flatpak). An AppImage is never mounted to look: its version decides (0.0.46+ have the
+ * driver), and T3's own launcher issues its sessions. A snap starts threads over SSH.
+ */
+export declare function linuxSupportsAcp(app: T3LinuxInstall): boolean;
+/**
+ * The bundled T3 server CLI (Electron as Node, ELECTRON_RUN_AS_NODE=1 set by the caller): the app's executable with
+ * the entry inside its app.asar; a flatpak's through `flatpak run`; an AppImage's through T3's own launcher
+ * (`<T3 home>/bin/t3`, which mounts the image). Undefined when there is none yet.
+ */
+export declare function linuxServerCli(app: T3LinuxInstall, t3Home: string): {
+    command: string;
+    args: string[];
+} | undefined;
+/**
+ * How T3 is opened (or brought to the front, as a second launch of T3 hands over to the running one): `gtk-launch`
+ * with its desktop entry when there is one, else its own program, started detached.
+ */
+export declare function linuxOpenCommands(app: T3LinuxInstall, env: Env): Array<{
+    command: string;
+    args: string[];
+    detached: boolean;
+}>;
+/** Opens T3 Code on Linux. Nothing here ever stops a T3 process: a launcher that hangs is left alone. */
+export declare function openLinuxT3(env: Env, app: T3LinuxInstall): Promise<void>;
+/**
+ * When T3 last started, as the filesystem records it: the program's access time once it is later than its modification
+ * time (dpkg installs both at the build time; relatime updates the access time on the first start, then daily). Null
+ * before the first start and on noatime mounts.
+ */
+export declare function linuxLastUsed(path: string): string | null;
+export {};