@shardflux/cli 0.16.0 → 0.18.0-next.4

package/dist/t3-linux.js

@@ -0,0 +1,343 @@
+/**
+ * T3 Code on Linux (0.17.0+): finding the installed desktop app, its version and route, and opening it.
+ *
+ * T3 ships a .deb and an AppImage (electron-builder, 0.0.45 and the nightlies, verified from the release assets):
+ * - .deb (package `t3code`): the app in `/opt/T3 Code (Alpha)/` (`/opt/T3 Code (Nightly)/` for nightlies) with the
+ *   executable `t3code`, `resources/app.asar` and `resources/package-type` ("deb"); the entry
+ *   `/usr/share/applications/t3code.desktop` (`Name=T3 Code (Alpha)`, `Exec="/opt/T3 Code (Alpha)/t3code" %U`,
+ *   `StartupWMClass=t3code`, `MimeType=x-scheme-handler/t3code;…`); `/usr/bin/t3code` is an update-alternatives link
+ *   made by its postinst. dpkg records nightlies as `0.0.46~nightly.<date>.<run>`.
+ * - AppImage: `T3-Code-<version>-<x86_64|arm64>.AppImage`, a squashfs image that is never mounted here; AppImageLauncher
+ *   and Gear Lever integrate it with a copy of the same entry (`X-AppImage-Version`, `Exec=<the AppImage> %U`).
+ *
+ * Entries are found in the XDG application folders (also snapd's and flatpak's exports) and keyed on what the entry
+ * says (its Name, and StartupWMClass, the t3code URL scheme or a T3 flatpak id), never on its file name; only files
+ * whose name could be one are read, so a computer without T3 costs a few directory listings and no subprocess.
+ */
+import { spawn, spawnSync } from 'node:child_process';
+import { accessSync, constants, openSync, readFileSync, readSync, closeSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, delimiter, dirname, isAbsolute, join, relative } from 'node:path';
+import { T3_SERVER_ENTRY, asarVersion, t3ArchiveSupportsAcp } from "./t3-asar.js";
+const RELEASE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const MAYBE_ENTRY = /t3|^appimagekit_|^gearlever_/i;
+const APPIMAGE = /^t3[-_ ]?code.*\.appimage$/i;
+/** `T3-Code-<version>-<arch>.AppImage`, also as AppImageLauncher renames it (`…-x86_64_<hash>.AppImage`). */
+const APPIMAGE_VERSION = /^T3[-_ ]?Code-(\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?)-(?:x86_64|x64|amd64|arm64|aarch64|armv7l)(?![0-9A-Za-z])/i;
+const FLATPAK_ID = 'com.t3tools.t3code';
+/** 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 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 function linuxApplicationDirs(env) {
+    const home = env.HOME || homedir();
+    const dataHome = env.XDG_DATA_HOME && isAbsolute(env.XDG_DATA_HOME) ? env.XDG_DATA_HOME : join(home, '.local', 'share');
+    const dataDirs = (env.XDG_DATA_DIRS || '/usr/local/share:/usr/share').split(':').filter(d => isAbsolute(d));
+    return [...new Set([dataHome, ...dataDirs, '/usr/local/share', '/usr/share'].map(d => join(d, 'applications')).concat('/var/lib/snapd/desktop/applications', '/var/lib/flatpak/exports/share/applications', join(dataHome, 'flatpak', 'exports', 'share', 'applications'), join(home, 'Applications'), join(home, 'AppImages'), join(home, '.local', 'bin'), join(home, 'Downloads')))];
+}
+/** The `[Desktop Entry]` group's unlocalized keys (string escapes undone), first value of each key. */
+export function desktopEntry(text) {
+    const keys = {};
+    let main = false;
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        if (line.startsWith('[')) {
+            main = line === '[Desktop Entry]';
+            continue;
+        }
+        const eq = line.indexOf('=');
+        if (!main || eq < 1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (!key.includes('[') && !(key in keys))
+            keys[key] = line.slice(eq + 1).trim().replace(/\\([sntr\\])/g, (_, c) => ({ s: ' ', n: '\n', t: '\t', r: '\r', '\\': '\\' })[c]);
+    }
+    return keys;
+}
+/** An entry's Exec as argv (the Desktop Entry quoting rules), field codes and flatpak's @@ markers removed; undefined when malformed. */
+export function desktopExec(value) {
+    const args = [];
+    let current = '', started = false, quoted = false;
+    for (let i = 0; i < value.length; i++) {
+        const c = value[i];
+        if (quoted) {
+            if (c === '\\' && i + 1 < value.length && '"`$\\'.includes(value[i + 1]))
+                current += value[++i];
+            else if (c === '"')
+                quoted = false;
+            else
+                current += c;
+        }
+        else if (c === '"') {
+            quoted = true;
+            started = true;
+        }
+        else if (c === ' ' || c === '\t') {
+            if (started)
+                args.push(current);
+            current = '';
+            started = false;
+        }
+        else {
+            current += c;
+            started = true;
+        }
+    }
+    if (quoted)
+        return undefined;
+    if (started)
+        args.push(current);
+    return args.filter(a => !/^%[fFuUdDnNickvm]$/.test(a) && !/^@@[uf]?$/.test(a)).map(a => a.replace(/%(%|[a-zA-Z])/g, (_, c) => c === '%' ? '%' : ''));
+}
+/** Whether an entry is T3 Code's: its Name, and its window class, URL scheme or flatpak id. */
+function isT3Entry(e) {
+    if ((e.Type ?? 'Application') !== 'Application' || !/^T3 Code(?: \(.+\))?$/.test(e.Name ?? ''))
+        return false;
+    return e.StartupWMClass === 't3code' || (e.MimeType ?? '').split(';').includes('x-scheme-handler/t3code') || e['X-Flatpak'] === FLATPAK_ID;
+}
+const executable = (path) => { try {
+    accessSync(path, constants.X_OK);
+    return statSync(path).isFile();
+}
+catch {
+    return false;
+} };
+const real = (path) => { try {
+    return realpathSync(path);
+}
+catch {
+    return path;
+} };
+const onPath = (name, env) => isAbsolute(name) ? (executable(name) ? name : undefined) : (env.PATH ?? '').split(delimiter).filter(Boolean).map(dir => join(dir, name)).find(executable);
+const release = (value) => value && RELEASE.test(value) ? value : null;
+/** A type 2 AppImage: an ELF file with `AI\x02` at byte 8. */
+function isAppImage(path) {
+    if (/\.appimage$/i.test(path))
+        return true;
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+        const b = Buffer.alloc(11);
+        return readSync(fd, b, 0, 11, 0) === 11 && b.subarray(0, 4).equals(Buffer.from('\x7fELF', 'latin1')) && b.subarray(8, 11).equals(Buffer.from('AI\x02', 'latin1'));
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+/** dpkg's version of the `t3code` package, in T3's own form (dpkg writes `0.0.46~nightly…` for `0.0.46-nightly…`). */
+function dpkgVersion(env) {
+    const r = spawnSync('dpkg-query', ['-W', '-f=${Version}', 't3code'], { env, encoding: 'utf8', input: '', timeout: 2000 });
+    return r.status === 0 ? release(r.stdout.trim().replace(/^\d+:/, '').replaceAll('~', '-')) : null;
+}
+/** The resources/app.asar of an unpacked Electron app, one or two folders below `root` (a flatpak's files). */
+function findAsar(root) {
+    const at = (dir) => { const asar = join(dir, 'resources', 'app.asar'); try {
+        return statSync(asar).isFile() ? asar : undefined;
+    }
+    catch {
+        return undefined;
+    } };
+    const children = (dir) => { try {
+        return readdirSync(dir, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => join(dir, d.name));
+    }
+    catch {
+        return [];
+    } };
+    return at(root) ?? children(root).map(at).find(Boolean) ?? children(root).flatMap(children).slice(0, 64).map(at).find(Boolean);
+}
+/** The install a T3 entry describes, from its program: an AppImage, a flatpak, a snap, or an unpacked app folder. */
+function fromEntry(e, id, dir, env) {
+    const exec = desktopExec(e.Exec ?? '');
+    if (!exec?.length)
+        return undefined;
+    let i = 0;
+    if (basename(exec[0]) === 'env') {
+        i = 1;
+        while (i < exec.length && /^[A-Za-z_]\w*=/.test(exec[i]))
+            i++;
+    }
+    const program = exec[i];
+    if (!program)
+        return undefined;
+    const entryVersion = release(e['X-AppImage-Version']);
+    if (e['X-Flatpak']) {
+        const appId = e['X-Flatpak'];
+        const root = dir.endsWith(join('exports', 'share', 'applications')) ? dirname(dirname(dirname(dir))) : '/var/lib/flatpak';
+        const files = join(root, 'app', appId, 'current', 'active', 'files');
+        const asar = findAsar(files) ?? null;
+        const command = exec.find(a => a.startsWith('--command='))?.slice('--command='.length);
+        const exe = asar ? join(dirname(dirname(asar)), basename(command || 't3code')) : files;
+        return { path: exe, version: (asar ? asarVersion(asar) : null) ?? entryVersion, linux: { format: 'flatpak', desktop_id: id, exec, asar: executable(exe) ? asar : null, flatpak: { id: appId, files } } };
+    }
+    const resolved = onPath(program, env);
+    if (!resolved)
+        return undefined;
+    if (e['X-SnapInstanceName'] || resolved.startsWith('/snap/bin/') || dir === '/var/lib/snapd/desktop/applications') {
+        const name = e['X-SnapInstanceName'] || basename(resolved);
+        let version = null;
+        try {
+            version = release(/^version:\s*['"]?([^'"\s]+)/m.exec(readFileSync(join('/snap', name, 'current', 'meta', 'snap.yaml'), 'utf8'))?.[1]);
+        }
+        catch { /* no snap metadata */ }
+        return { path: resolved, version, linux: { format: 'snap', desktop_id: id, exec, asar: null } };
+    }
+    const target = real(resolved);
+    if (isAppImage(target)) {
+        return { path: target, version: entryVersion ?? release(APPIMAGE_VERSION.exec(basename(target))?.[1]), linux: { format: 'appimage', desktop_id: id, exec, asar: null } };
+    }
+    const asar = join(dirname(target), 'resources', 'app.asar');
+    let found = false;
+    try {
+        found = statSync(asar).isFile();
+    }
+    catch { /* not an unpacked Electron app */ }
+    let deb = false;
+    try {
+        deb = readFileSync(join(dirname(target), 'resources', 'package-type'), 'utf8').trim() === 'deb';
+    }
+    catch { /* not from the .deb */ }
+    const version = (found ? asarVersion(asar) : null) ?? (deb ? dpkgVersion(env) : null) ?? entryVersion;
+    return { path: target, version, linux: { format: deb ? 'deb' : 'directory', desktop_id: id, exec, asar: found ? asar : null } };
+}
+/** The installed T3 Code apps on Linux, from the desktop entries and AppImages in `dirs` (linuxApplicationDirs). */
+export function linuxT3Apps(dirs, env) {
+    const found = [], ids = new Set(), loose = [];
+    for (const dir of dirs) {
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            if (APPIMAGE.test(name)) {
+                loose.push(join(dir, name));
+                continue;
+            }
+            if (!name.endsWith('.desktop') || !MAYBE_ENTRY.test(name) || ids.has(name))
+                continue;
+            let text;
+            try {
+                text = readFileSync(join(dir, name), 'utf8');
+            }
+            catch {
+                continue;
+            }
+            // The first entry with an id wins (XDG precedence); a Hidden one removes that id.
+            ids.add(name);
+            const e = desktopEntry(text);
+            if (e.Hidden === 'true' || !isT3Entry(e) || (e.TryExec && !onPath(e.TryExec, env)))
+                continue;
+            const app = fromEntry(e, name, dir, env);
+            if (app && !found.some(f => f.path === app.path))
+                found.push(app);
+        }
+    }
+    for (const file of loose) {
+        const path = real(file);
+        if (!executable(path) || found.some(f => f.path === path))
+            continue;
+        found.push({ path, version: release(APPIMAGE_VERSION.exec(basename(path))?.[1]), linux: { format: 'appimage', desktop_id: null, exec: [path], asar: null } });
+    }
+    return found;
+}
+/** `0.0.46` and later (nightlies of 0.0.46 included). */
+const atLeast046 = (version) => {
+    const [major = 0, minor = 0, patch = 0] = /^(\d+)\.(\d+)\.(\d+)/.exec(version ?? '')?.slice(1).map(Number) ?? [];
+    return major > 0 || minor > 0 || patch >= 46;
+};
+/**
+ * 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 function linuxSupportsAcp(app) {
+    if (app.linux.format === 'appimage')
+        return !!app.version && atLeast046(app.version);
+    return app.linux.format !== 'snap' && !!app.linux.asar && t3ArchiveSupportsAcp(app.linux.asar);
+}
+/**
+ * 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 function linuxServerCli(app, t3Home) {
+    const { format, asar, flatpak } = app.linux;
+    if ((format === 'deb' || format === 'directory') && asar)
+        return { command: app.path, args: [join(asar, T3_SERVER_ENTRY)] };
+    if (format === 'flatpak' && flatpak && asar) {
+        const inside = (path) => `/app/${relative(flatpak.files, path)}`;
+        return { command: 'flatpak', args: ['run', `--command=${inside(app.path)}`, '--env=ELECTRON_RUN_AS_NODE=1', flatpak.id, inside(join(asar, T3_SERVER_ENTRY))] };
+    }
+    if (format === 'appimage') {
+        const launcher = join(t3Home, 'bin', 't3');
+        try {
+            if (executable(launcher) && readFileSync(launcher, 'utf8').includes(T3_LAUNCHER_MARKER))
+                return { command: launcher, args: [] };
+        }
+        catch { /* not written yet */ }
+    }
+    return 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 function linuxOpenCommands(app, env) {
+    const { desktop_id: id, exec, format, flatpak } = app.linux;
+    const gtk = id ? onPath('gtk-launch', env) : undefined;
+    return [
+        ...(gtk && id ? [{ command: gtk, args: [id], detached: false }] : []),
+        format === 'flatpak' && flatpak ? { command: 'flatpak', args: ['run', flatpak.id], detached: true } : { command: exec[0], args: exec.slice(1), detached: true },
+    ];
+}
+/** Opens T3 Code on Linux. Nothing here ever stops a T3 process: a launcher that hangs is left alone. */
+export async function openLinuxT3(env, app) {
+    let last;
+    for (const { command, args, detached } of linuxOpenCommands(app, env)) {
+        try {
+            await new Promise((resolve, reject) => {
+                const child = spawn(command, args, { env, stdio: 'ignore', detached });
+                if (detached) {
+                    child.once('spawn', () => { child.unref(); resolve(); });
+                    child.once('error', reject);
+                    return;
+                }
+                const timer = setTimeout(() => { child.unref(); reject(new Error(`${basename(command)} did not answer 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(`${basename(command)} exited ${code}`)); });
+            });
+            return;
+        }
+        catch (error) {
+            last = error;
+        }
+    }
+    throw new Error(`could not open T3 Code (${last instanceof Error ? last.message : String(last)})`);
+}
+/**
+ * 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 function linuxLastUsed(path) {
+    try {
+        const s = statSync(path);
+        return s.atimeMs > s.mtimeMs + 1000 ? new Date(s.atimeMs).toISOString() : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/t3-mode.d.ts

@@ -0,0 +1,129 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import { CodedError } from './errors.js';
+import { t3HomeDir } from './t3-provider.js';
+import type { T3LinuxApp } from './t3-linux.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 declare const openInTargets: (app: AgentApp, platform?: NodeJS.Platform) => readonly OpenIn[];
+/** The T3 Code `shard` uses: its .app bundle (macOS) or program (Linux, with how it was installed in `linux`). */
+export interface T3Install {
+    path: string;
+    version: string | null;
+    mode: T3Mode;
+    linux?: T3LinuxApp;
+}
+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 (macOS), or
+ * when each program last started, from its access time (Linux, t3-linux.ts).
+ */
+export declare const t3Native: {
+    lastUsedMany(paths: readonly string[], env: Record<string, string | undefined>, platform?: NodeJS.Platform): 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, dirs?: string[]): T3Install | undefined;
+export { t3HomeDir };
+/** 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. 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 declare function openT3(env: Record<string, string | undefined>, install: Pick<T3Install, 'path' | 'version' | 'linux'> | undefined): 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>;