@shardflux/cli 0.15.2 → 0.17.0

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.path);
+        }
+        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-mode.d.ts

@@ -0,0 +1,121 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import { CodedError } from './errors.js';
+import type { InitialImage } from './initial-prompt.js';
+export declare const T3_BUNDLE_ID = "com.t3tools.t3code";
+export type T3Mode = 'acp' | 'ssh';
+export type AgentApp = 'claude' | 'codex';
+export type OpenIn = 'terminal' | 'claude-desktop' | 'web' | 'codex-app' | 't3';
+/** 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 declare const OPEN_IN_TARGETS: Record<AgentApp, readonly OpenIn[]>;
+export interface T3Install {
+    path: string;
+    version: string | null;
+    mode: T3Mode;
+}
+export interface T3Status {
+    installed: boolean;
+    mode: T3Mode | null;
+    connected: boolean;
+    version: string | null;
+    last_used_at: string | null;
+}
+export interface T3ThreadRequest {
+    app: AgentApp;
+    prompt: string;
+    model?: string;
+    effort?: string;
+    images?: readonly InitialImage[];
+}
+/** Why a requested `--effort` reached T3 as none: the model offers no such level, or its levels are not known yet. */
+export type EffortReason = 'not_offered' | 'models_not_known';
+export interface T3ThreadResult {
+    mode: T3Mode;
+    t3_thread_id: string;
+    conversation_id: string | null;
+    workspace: {
+        workspace_key: string;
+        id: string;
+    } | null;
+    model: string | null;
+    effort: string | null;
+    effort_reason?: EffortReason;
+}
+/** Native lookups that tests replace: Spotlight's last-used dates of app bundles, one `mdls` for all of them. */
+export declare const t3Native: {
+    lastUsedMany(paths: readonly string[], env: Record<string, string | undefined>): Record<string, string | 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 declare const LAST_USED_TTL_MS: number;
+export declare function lastUsedDates(ctx: Ctx, paths: readonly string[], now?: number): Record<string, string | null>;
+/** The installed T3 Code, preferring a build with ACP providers when several channels are installed. */
+export declare function t3Install(env: Record<string, string | undefined>, platform?: NodeJS.Platform): T3Install | undefined;
+export declare function t3HomeDir(env: Record<string, string | undefined>): string;
+/** The Shardflux provider instance in T3's server settings (read only; every `shard` run writes it, see t3-provider.ts). */
+export declare function t3ProviderRegistered(env: Record<string, string | undefined>): boolean;
+/**
+ * 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 declare function t3Status(ctx: Ctx, opts?: {
+    project?: string | null;
+    install?: T3Install | null;
+    lastUsed?: boolean;
+}): T3Status;
+export interface OpenInChoice {
+    target: OpenIn;
+    saved: boolean;
+}
+/**
+ * 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 declare function openInFor(ctx: Ctx, project: string | null, known?: {
+    clients?: readonly string[];
+}): Record<AgentApp, OpenInChoice>;
+export declare function openInChoices(ctx: Ctx, project: string | null, known?: {
+    clients?: readonly string[];
+}): Record<AgentApp, OpenIn>;
+/** `--open-in claude=t3,codex=t3`: validated against what is installed, then saved in agents.json. */
+export declare function saveOpenIn(ctx: Ctx, spec: string, status: T3Status, clients: readonly string[]): void;
+/** A T3 thread was started, then a later step failed: the error names the thread so a client opens it, never starts another. */
+export declare function t3OpenFailed(error: unknown, ref: {
+    t3_thread_id: string;
+    conversation_id?: string | null;
+    workspace_key?: string | null;
+}): CodedError;
+export declare const t3NotInstalled: () => CodedError;
+/** The first line of the prompt, as T3 titles a thread before it names it. */
+export declare function t3ThreadTitle(prompt: string): string;
+/**
+ * Opens T3 Code (or brings it to the front): the install `shard` chose (`open -a <path>`). Every T3 channel shares one
+ * bundle id, so `open -b` could start another installed channel.
+ */
+export declare function openT3(env: Record<string, string | undefined>, appPath: string): Promise<void>;
+/** Starts the thread in the VM's T3 server (T3_THREAD_SCRIPT); the prompt travels on stdin, never in argv. */
+export declare function startSshThread(ctx: Ctx, ws: Workspace, version: string | undefined, projectPath: string, request: T3ThreadRequest): Promise<T3ThreadResult>;
+interface Descriptor {
+    serverVersion?: string;
+    orchestrationProtocolVersion?: number;
+}
+export interface LocalT3Server {
+    origin: string;
+    descriptor: Descriptor;
+    base: string;
+}
+interface T3Session {
+    token: string;
+    sessionId: string;
+}
+/** The running desktop server; T3 is opened (which starts it) when none answers. */
+export declare function localT3Server(ctx: Ctx, install: T3Install, waitMs?: number): Promise<LocalT3Server>;
+/** One Effect RPC request over T3's WebSocket (JSON frames: Request → Exit), authorized by a ticket from the session. */
+export declare function t3Rpc(server: LocalT3Server, session: T3Session, tag: string, payload: unknown, signal: AbortSignal, timeoutMs?: number): Promise<unknown>;
+/** Starts a T3 thread on the Shardflux provider (ACP mode) and brings T3 to the front. */
+export declare function startAcpThread(ctx: Ctx, install: T3Install, folder: string, request: T3ThreadRequest, waitMs?: number): Promise<T3ThreadResult>;
+/** The T3 thread of a Shardflux conversation started in T3 (ACP mode): the one remembered, else a search of recent Shardflux threads. */
+export declare function findAcpThread(ctx: Ctx, install: T3Install, conversationId: string): Promise<string | null>;
+export {};