@shardflux/cli 0.24.1 → 0.28.0

package/dist/device-helper.js

@@ -42,22 +42,24 @@ export async function runDeviceHelper(ctx, options = {}) {
         }
     })().finally(() => abort.abort());
     void input.catch(() => abort.abort());
-    const ask = async (approval) => {
-        const acp = await askConnectedAcp(ctx.store.dir, approval, signal);
+    // `until` ends one question early: the person chose a mode that lets the request run by itself (device-mode.ts).
+    const ask = async (approval, until) => {
+        const asking = until ? AbortSignal.any([signal, until]) : signal;
+        const acp = await askConnectedAcp(ctx.store.dir, approval, asking);
         if (acp)
             return acp;
         // The desktop app, while it runs, shows it as a Needs-you item (0.25.0+); else the menu bar or the service files.
-        const app = await askDeviceApprover(ctx.store.dir, approval, signal);
+        const app = await askDeviceApprover(ctx.store.dir, approval, asking);
         if (app)
             return app;
         if (options.service)
-            return askLocalDeviceApproval(ctx, approval);
+            return askLocalDeviceApproval({ ...ctx, signal: asking }, approval);
         return new Promise(resolve => {
             const denied = () => { pending.delete(approval.request_id); resolve('deny'); };
-            signal.addEventListener('abort', denied, { once: true });
-            pending.set(approval.request_id, choice => { signal.removeEventListener('abort', denied); resolve(choice); });
+            asking.addEventListener('abort', denied, { once: true });
+            pending.set(approval.request_id, choice => { asking.removeEventListener('abort', denied); resolve(choice); });
             ctx.io.stdout.write(JSON.stringify(approval) + '\n');
-            if (signal.aborted)
+            if (asking.aborted)
                 denied();
         }).finally(() => { if (!signal.aborted)
             ctx.io.stdout.write(JSON.stringify({ type: 'approval_resolved', request_id: approval.request_id }) + '\n'); });
@@ -74,6 +76,10 @@ export async function runDeviceHelper(ctx, options = {}) {
         writePrivateFile(ctx.store.dir, deviceFile, deviceId + '\n');
     }
     const executor = new DeviceExecutor(ctx, ask, deviceId);
+    // A device id another identity registered (an earlier API key `shard setup` replaced, another account) can never
+    // register for this one: a refusal gives this computer a new id (0.27.0+), at most once every 10 minutes, so a second
+    // sign-in change later renews again and a refusal right after a renewal stops (never a loop).
+    let renewedAt = 0;
     const report = (e) => { ctx.io.stderr.write(`Device bridge: ${e instanceof Error ? e.message : String(e)}\n`); };
     let mirroring, twin, returning, preparing, projects;
     try {
@@ -150,7 +156,19 @@ export async function runDeviceHelper(ctx, options = {}) {
             // Registered for every project an agent may ask from (deviceProjects); one poll covers them all where the API
             // lists by device (0.25.0+), else one per project.
             const registered = new Map();
-            let all, deviceWide = true;
+            const registrationFailures = new Map();
+            let all, deviceWide = true, links = true;
+            // This device's local conversations of a project (started here or opened here): their requests come here first.
+            const linked = (projectId) => Object.values(localConversations(ctx)).filter(r => !r.handed_off && (!projectId || r.project_id === projectId))
+                .sort((a, b) => (b.conversation.created_at ?? '').localeCompare(a.conversation.created_at ?? '')).slice(0, 500).map(r => r.conversation.id);
+            const beat = (projectId) => conversationClient(ctx).deviceRequests.heartbeat({ ...(projectId ? { projectId } : {}), deviceId, leaseSeconds: 30, ...(links ? { conversationIds: linked(projectId) } : {}) })
+                .catch((e) => {
+                // An API before device links (0.25.0+ clients) refuses the list: register without it from then on.
+                if (!links || !(e instanceof ShardfluxApiError && [400, 422].includes(e.status)))
+                    throw e;
+                links = false;
+                return conversationClient(ctx).deviceRequests.heartbeat({ ...(projectId ? { projectId } : {}), deviceId, leaseSeconds: 30 });
+            });
             const take = (rows) => {
                 for (const r of rows) {
                     if (r.device_id !== deviceId || working.has(r.id) || working.size >= 8)
@@ -165,13 +183,42 @@ export async function runDeviceHelper(ctx, options = {}) {
                         all = { ids: await deviceProjects(ctx).catch(() => all?.ids ?? []), at: Date.now() };
                     const projects = [...new Set([...Object.values(localConversations(ctx)).map(r => r.project_id), ...all.ids])];
                     for (const projectId of projects) {
+                        const failed = registrationFailures.get(projectId);
+                        if (failed && (failed.next === null || Date.now() < failed.next))
+                            continue;
                         if (Date.now() - (registered.get(projectId) ?? 0) < 10_000)
                             continue;
-                        await conversationClient(ctx).deviceRequests.heartbeat({ ...(projectId ? { projectId } : {}), deviceId, leaseSeconds: 30 }).then(() => registered.set(projectId, Date.now()), (e) => {
-                            // A project this sign-in no longer reaches is skipped until the next listing, never the others.
-                            if (!(e instanceof ShardfluxApiError && [403, 404].includes(e.status)))
-                                throw e;
-                            registered.set(projectId, Date.now() + 290_000);
+                        await beat(projectId).then(() => {
+                            registered.set(projectId, Date.now());
+                            registrationFailures.delete(projectId);
+                        }, (e) => {
+                            if (deviceIdTaken(e) && Date.now() - renewedAt > 600_000) {
+                                renewedAt = Date.now();
+                                const old = deviceId;
+                                deviceId = renewDeviceId(ctx.store.dir, old, projectId);
+                                executor.deviceId = deviceId;
+                                // Every project registers again under the new id, at once.
+                                registered.clear();
+                                registrationFailures.clear();
+                                report(new Error(`this computer's device id ${old} belongs to another sign-in (an earlier API key or account); it registers as ${deviceId} for this one.`));
+                                return;
+                            }
+                            // A refused registration belongs to this project alone. Repeating a
+                            // device identity conflict cannot repair it or hold every later project.
+                            const attempts = (failed?.attempts ?? 0) + 1;
+                            const permanent = e instanceof ShardfluxApiError && !e.retryable;
+                            const stopped = permanent || attempts >= 8;
+                            const wait = Math.min(300_000, 5000 * 2 ** Math.min(attempts - 1, 6));
+                            registrationFailures.set(projectId, { attempts, next: stopped ? null : Date.now() + wait });
+                            const message = e instanceof Error ? e.message : String(e);
+                            if (stopped) {
+                                const action = e instanceof ShardfluxApiError && e.details?.reason === 'device_id_taken'
+                                    ? 'Its device id was renewed moments ago and is refused again; restart the device helper.'
+                                    : 'Check connectivity or sign in again, then restart the device helper to retry.';
+                                report(new Error(`Device helper needs attention for project ${projectId || 'default'} after ${attempts} failed registrations: ${message} ${action}`));
+                            }
+                            else
+                                report(new Error(`Device registration for project ${projectId || 'default'} failed (attempt ${attempts}/8): ${message} Retrying in ${wait / 1000}s.`));
                         });
                     }
                     let polled = false;
@@ -258,3 +305,26 @@ export async function deviceProjects(ctx) {
     }
     return [...ids];
 }
+/** 409 `device_id_taken`: this device id is registered in a project by another identity (POST /v1/device-requests/heartbeat). */
+export function deviceIdTaken(e) {
+    return e instanceof ShardfluxApiError && e.status === 409 && e.details?.reason === 'device_id_taken';
+}
+/**
+ * A new device id for this computer, replacing `old` (0.27.0+). Local state stays: grants are kept by API and folder
+ * or project (device-bridge.ts DeviceGrants), the approval mode by person (device-mode.ts), and the twin's refs by the
+ * id that made them. The old id is kept in `device-id-history.json` (the last 20) for support.
+ */
+export function renewDeviceId(dir, old, projectId) {
+    const id = randomUUID(), historyFile = join(dir, 'device-id-history.json');
+    let history = [];
+    try {
+        const value = JSON.parse(readFileSync(historyFile, 'utf8'));
+        if (Array.isArray(value))
+            history = value;
+    }
+    catch { /* first one */ }
+    history = [...history, { id: old, replaced_at: new Date().toISOString(), replaced_by: id, project_id: projectId || null }].slice(-20);
+    writePrivateFile(dir, historyFile, JSON.stringify(history, null, 2) + '\n');
+    writePrivateFile(dir, join(dir, 'device-id'), id + '\n');
+    return id;
+}

package/dist/device-mode.d.ts

@@ -0,0 +1,44 @@
+export type DeviceApprovalMode = 'auto' | 'read' | 'ask';
+export declare const DEVICE_APPROVAL_MODES: readonly DeviceApprovalMode[];
+/**
+ * The mode before the person chooses one. `undefined`: nothing is decided for them; the first request asks which they
+ * want (the app's prompt, or one line from `shard`), and the app's onboarding asks too. 'auto' or 'ask' here chooses
+ * for everyone who has not.
+ */
+export declare const DEFAULT_DEVICE_APPROVALS: DeviceApprovalMode | undefined;
+/** The kinds that only read this computer: a folder listing, and a file copied to the conversation. */
+export declare const READ_KINDS: ReadonlySet<string>;
+export declare const MODE_LABELS: Record<DeviceApprovalMode, string>;
+/** The one line a person without the app reads when a request needs the choice ("this Mac" on macOS). */
+export declare const chooseLine: (platform?: NodeJS.Platform) => string;
+export interface DeviceSettings {
+    approvals?: DeviceApprovalMode;
+    chosen_at?: string;
+    /** Who chose it, when known: another person signed in on this computer chooses for themselves. */
+    user_id?: string;
+}
+export declare function readDeviceSettings(dir: string): DeviceSettings;
+/** This person's mode on this computer; undefined until they choose one (and DEFAULT_DEVICE_APPROVALS is unset). */
+export declare function deviceApprovalMode(dir: string, userId?: string): DeviceApprovalMode | undefined;
+export declare function setDeviceApprovalMode(dir: string, mode: string, userId?: string): DeviceSettings;
+/** Whether a request of this kind runs without asking under this mode (for the person's own agents). */
+export declare function runsWithoutAsking(mode: DeviceApprovalMode | undefined, kind: string): boolean;
+/** One line of what ran without asking: the start (`running`) and how it ended, folded by `request_id`. */
+export interface DeviceActivity {
+    at: string;
+    request_id: string;
+    conversation_id: string;
+    kind: string;
+    summary: string;
+    mode: DeviceApprovalMode;
+    state: 'running' | 'done' | 'failed' | 'denied';
+    conversation_title?: string;
+    project_name?: string;
+    argv?: string[];
+    local_path?: string;
+    exit_code?: number;
+    finished_at?: string;
+}
+export declare function recordDeviceActivity(dir: string, entry: DeviceActivity): void;
+/** What ran without asking, newest first: one entry per request with its latest state. */
+export declare function deviceActivity(dir: string, limit?: number): DeviceActivity[];

package/dist/device-mode.js

@@ -0,0 +1,119 @@
+/**
+ * How this computer answers its own agents (0.27.0+): the person chooses once, per device, whether their agents run
+ * things here without asking each time. Kept in `<config>/device-settings.json`; changed in the app's Settings or with
+ * `shard device approvals auto|read|ask`. Requests that ran without asking are kept in `<config>/device-activity.jsonl`
+ * (what ran, for which conversation, and how it ended), shown by the app and `shard device approvals`.
+ *
+ * - `ask`: every request asks (Allow once, or Always where a grant applies).
+ * - `read`: listing a folder and copying a file to a conversation run without asking; anything that changes this
+ *   computer (commands, files saved here, ports, linking a folder) asks. Commands are never classified by their text.
+ * - `auto`: every request from this person's own agents runs without asking.
+ *
+ * Only this person's own conversations run without asking (`ownConversation`): a teammate's request always asks.
+ */
+import { appendFileSync, lstatSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { writePrivateFile, ensurePrivateDir } from "./credentials.js";
+import { UsageError } from "./errors.js";
+import { thisComputer } from "./this-computer.js";
+export const DEVICE_APPROVAL_MODES = ['auto', 'read', 'ask'];
+/**
+ * The mode before the person chooses one. `undefined`: nothing is decided for them; the first request asks which they
+ * want (the app's prompt, or one line from `shard`), and the app's onboarding asks too. 'auto' or 'ask' here chooses
+ * for everyone who has not.
+ */
+export const DEFAULT_DEVICE_APPROVALS = undefined;
+/** The kinds that only read this computer: a folder listing, and a file copied to the conversation. */
+export const READ_KINDS = new Set(['dir_list', 'files_pull']);
+export const MODE_LABELS = {
+    auto: 'Allow everything from my agents',
+    read: 'Allow reading, ask before changes',
+    ask: 'Ask every time',
+};
+/** The one line a person without the app reads when a request needs the choice ("this Mac" on macOS). */
+export const chooseLine = (platform = process.platform) => `Let your agents run things on ${thisComputer(platform)} without asking each time? Allow everything: shard device approvals auto · Ask each time: shard device approvals ask`;
+const SETTINGS = 'device-settings.json', ACTIVITY = 'device-activity.jsonl';
+export function readDeviceSettings(dir) {
+    const file = join(dir, SETTINGS);
+    try {
+        if (lstatSync(file).isSymbolicLink() || (statSync(file).mode & 0o077))
+            return {};
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return {};
+        return DEVICE_APPROVAL_MODES.includes(value.approvals) ? value : { ...value, approvals: undefined };
+    }
+    catch {
+        return {};
+    }
+}
+/** This person's mode on this computer; undefined until they choose one (and DEFAULT_DEVICE_APPROVALS is unset). */
+export function deviceApprovalMode(dir, userId) {
+    const s = readDeviceSettings(dir);
+    if (s.approvals && !(s.user_id && userId && s.user_id !== userId))
+        return s.approvals;
+    return DEFAULT_DEVICE_APPROVALS;
+}
+export function setDeviceApprovalMode(dir, mode, userId) {
+    if (!DEVICE_APPROVAL_MODES.includes(mode))
+        throw new UsageError(`Unknown approval mode "${mode}": auto, read or ask.`);
+    const next = { ...readDeviceSettings(dir), approvals: mode, chosen_at: new Date().toISOString() };
+    if (userId)
+        next.user_id = userId;
+    else
+        delete next.user_id;
+    writePrivateFile(dir, join(dir, SETTINGS), JSON.stringify(next, null, 2) + '\n');
+    return next;
+}
+/** Whether a request of this kind runs without asking under this mode (for the person's own agents). */
+export function runsWithoutAsking(mode, kind) {
+    return mode === 'auto' || (mode === 'read' && READ_KINDS.has(kind));
+}
+const ACTIVITY_MAX_BYTES = 512 << 10, ACTIVITY_KEEP = 400;
+export function recordDeviceActivity(dir, entry) {
+    const file = join(dir, ACTIVITY);
+    try {
+        ensurePrivateDir(dir);
+        let size = 0;
+        try {
+            size = statSync(file).size;
+        }
+        catch { /* first entry */ }
+        if (size > ACTIVITY_MAX_BYTES) {
+            const keep = readFileSync(file, 'utf8').split('\n').filter(Boolean).slice(-ACTIVITY_KEEP);
+            writePrivateFile(dir, file, keep.join('\n') + '\n');
+        }
+        appendFileSync(file, JSON.stringify(entry) + '\n', { mode: 0o600 });
+    }
+    catch { /* the request's own result still reaches its conversation */ }
+}
+/** What ran without asking, newest first: one entry per request with its latest state. */
+export function deviceActivity(dir, limit = 20) {
+    let text;
+    try {
+        if (lstatSync(join(dir, ACTIVITY)).isSymbolicLink())
+            return [];
+        text = readFileSync(join(dir, ACTIVITY), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const byId = new Map();
+    for (const line of text.split('\n')) {
+        if (!line)
+            continue;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!e || typeof e.request_id !== 'string')
+            continue;
+        const had = byId.get(e.request_id);
+        byId.delete(e.request_id);
+        byId.set(e.request_id, had ? { ...had, ...e, at: had.at, ...(e.state !== 'running' ? { finished_at: e.at } : {}) } : e);
+    }
+    return [...byId.values()].reverse().slice(0, limit);
+}

package/dist/drive-commands.d.ts

@@ -14,8 +14,8 @@ export interface ProjectScope {
  * `needId` false leaves the key's project unnamed (the API defaults to it), saving a lookup.
  */
 export declare function projectScope(ctx: Ctx, values: Values, needId?: boolean): Promise<ProjectScope>;
-/** `drive ls` rows: size, saved time, type and path (the path last, as `files ls` puts the name). */
-export declare function driveTable(rows: readonly DriveFile[]): string;
+/** `drive ls` and `brain ls` rows: size, saved time, type and path (the path last, as `files ls` puts the name). */
+export declare function driveTable(rows: readonly Pick<DriveFile, 'size' | 'created_at' | 'content_type' | 'path'>[]): string;
 /**
  * The model template as people read it: the primary provider and why, the connected accounts, then one row per role
  * with what it runs and, for a role whose provider is out of usage, until when it waits and what the other provider

package/dist/drive-commands.js

@@ -51,7 +51,7 @@ function drivePath(path, what = 'drive path') {
     }
     return path;
 }
-/** `drive ls` rows: size, saved time, type and path (the path last, as `files ls` puts the name). */
+/** `drive ls` and `brain ls` rows: size, saved time, type and path (the path last, as `files ls` puts the name). */
 export function driveTable(rows) {
     return table(['SIZE', 'SAVED', 'TYPE', 'PATH'], rows.map((f) => [humanBytes(f.size), time(f.created_at), f.content_type, f.path]));
 }

package/dist/errors.js

@@ -266,7 +266,8 @@ export function describeError(err) {
         // details.reason: the operation error's reason (e.g. the scheduler's no_ready_hosts), printed after the message.
         const opDetails = err.operation.error?.details;
         const reason = typeof opDetails === 'object' && opDetails !== null ? opDetails.reason : undefined;
-        const details = { ...(err.errorCode ? { error_code: err.errorCode } : {}), ...(typeof reason === 'string' ? { reason } : {}) };
+        const retryAfter = typeof opDetails === 'object' && opDetails !== null ? opDetails.retry_after_seconds : undefined;
+        const details = { ...(err.errorCode ? { error_code: err.errorCode } : {}), ...(typeof reason === 'string' ? { reason } : {}), ...(typeof retryAfter === 'number' && Number.isFinite(retryAfter) && retryAfter > 0 ? { retry_after_seconds: retryAfter } : {}) };
         // A suspend-when-idle canceled workspace_active (0.7.0+): the workspace was in use and keeps running.
         const message = err.workspaceActive ? `${err.message}: the workspace was in use, so the suspend-when-idle was canceled; it keeps running` : err.message;
         return { code: 'operation_failed', message, operation_id: err.operationId, retryable: err.retryable, ...(Object.keys(details).length ? { details } : {}), operation: err.operation };

package/dist/format.js

@@ -448,7 +448,7 @@ const hoursText = (h) => String(Math.round(h * 100) / 100);
  * while the GPU is stopped (cap_state gpu_blocked), why and what brings it back. Workspaces keep running meanwhile.
  * Nothing without `gpu` (plans without GPU-hours).
  */
-function gpuLines(gpu, resetsAt) {
+function gpuLines(gpu, resetsAt, overageAvailable) {
     if (!isObject(gpu) || typeof gpu.used_hours !== 'number')
         return [];
     const included = typeof gpu.included_hours === 'number' ? gpu.included_hours : null;
@@ -470,6 +470,10 @@ function gpuLines(gpu, resetsAt) {
             rows.push(['GPU', `stopped (spend_cap_reached): workspaces keep running; raise the spend cap (shard billing overage cap <dollars>), or wait for the reset${resets}`]);
             break;
         default:
+            if (!overageAvailable) {
+                rows.push(['GPU', 'stopped (allowance_used): workspaces keep running; choose a paid plan (shard billing plans); overage is unavailable on the current plan']);
+                break;
+            }
             rows.push(['GPU', `stopped (allowance_used): workspaces keep running; turn on overage (shard billing overage on --cap <dollars>), upgrade (shard billing plans), or wait for the reset${resets}`]);
     }
     return rows;
@@ -507,7 +511,7 @@ export function usageText(summary) {
         head.push(['retained state', 'used up: new workspaces and forks are refused (delete workspaces you no longer need, or upgrade)']);
     }
     const resetsAt = isObject(s.period) ? [s.period.resets_at, s.period.end].find((t) => typeof t === 'string') : undefined;
-    head.push(...gpuLines(s.gpu, resetsAt));
+    head.push(...gpuLines(s.gpu, resetsAt, !(isObject(s.spend_cap) && s.spend_cap.available === false)));
     for (const [k, v] of Object.entries(s))
         if (!USAGE_KNOWN.has(k) && (typeof v !== 'object' || v === null))
             head.push([k.replace(/_/g, ' '), scalar(v)]);

package/dist/handlers.js

@@ -5,6 +5,8 @@ import { CONVERSATION_HANDLERS } from "./conversation-commands.js";
 import { BOARD_HANDLERS } from "./board-commands.js";
 import { TRANSCRIPT_HANDLERS } from "./conversation-transcript.js";
 import { ROUTER_HANDLERS } from "./router-commands.js";
+import { ORCHESTRATOR_HANDLERS } from "./orchestrator-commands.js";
+import { TRANSCRIBE_HANDLERS } from "./transcribe-commands.js";
 /**
  * Every command's handler, keyed by its path ("workspaces open", "auth login"): the project-key commands of
  * commands.ts and the account plane of account-commands.ts (0.5.0). args.test.ts checks that it matches COMMANDS.
@@ -24,11 +26,12 @@ import { TWIN_HANDLERS } from "./worktree-twin-engine.js";
 import { CODEX_CLOUD_HANDLERS } from "./codex-cloud.js";
 import { THREAD_HANDLERS } from "./thread-on-computer.js";
 import { CLI_PROXY_HANDLERS } from "./cli-proxy.js";
-import { ACCOUNT_POOL_HANDLERS } from "./account-pool.js";
+import { ACCOUNT_POOL_HANDLERS, AGENT_MODELS_HANDLERS } from "./account-pool.js";
 import { MOVE_HANDLERS } from "./move.js";
 import { AGENT_CONFIG_HANDLERS } from "./agent-config-sync.js";
 import { MACHINE_SETUP_HANDLERS } from "./machine-setup.js";
 import { SETTINGS_HANDLERS } from "./client-settings.js";
 import { PROJECT_PREPARATION_HANDLERS } from "./project-preparation.js";
 import { DRIVE_HANDLERS } from "./drive-commands.js";
-export const HANDLERS = { ...PROJECT_PREPARATION_HANDLERS, ...PROJECT_LINK_HANDLERS, ...MOVE_HANDLERS, ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...BOARD_HANDLERS, ...TRANSCRIPT_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...MACHINE_SETUP_HANDLERS, ...SETTINGS_HANDLERS, ...UPDATE_HANDLERS, ...AGENT_CONFIG_HANDLERS, ...ROUTER_HANDLERS, ...DRIVE_HANDLERS };
+import { BRAIN_HANDLERS } from "./brain-commands.js";
+export const HANDLERS = { ...PROJECT_PREPARATION_HANDLERS, ...PROJECT_LINK_HANDLERS, ...MOVE_HANDLERS, ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...ORCHESTRATOR_HANDLERS, ...BOARD_HANDLERS, ...TRANSCRIPT_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...AGENT_MODELS_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...MACHINE_SETUP_HANDLERS, ...SETTINGS_HANDLERS, ...UPDATE_HANDLERS, ...AGENT_CONFIG_HANDLERS, ...ROUTER_HANDLERS, ...TRANSCRIBE_HANDLERS, ...DRIVE_HANDLERS, ...BRAIN_HANDLERS };

package/dist/land.d.ts

@@ -0,0 +1,121 @@
+import type { Ctx } from './commands.js';
+import { conversationClient } from './conversation-commands.js';
+import type { TwinCell } from './worktree-twin.js';
+/** The hub side of a landing, shipped next to this module (src in the monorepo, dist when published). */
+export declare function hubScript(): string;
+export interface HubLanding {
+    state: 'landed' | 'conflict' | 'unrelated' | 'missing' | 'raced' | 'error';
+    into: string;
+    before?: string | null;
+    after?: string;
+    result?: string;
+    method?: 'ff' | 'merge' | 'already' | 'created';
+    created_result?: boolean;
+    contained?: string[];
+    merge_base?: string | null;
+    stage?: 'integrate' | 'default';
+    conflicts?: string[];
+    source?: string;
+    message?: string;
+    reason?: string;
+}
+/** Merges `result` (made from `sources` when missing) into the hub's default branch, in a VM that reads the hub. */
+export declare function landOnHub(cell: TwinCell, input: {
+    result: string;
+    sources: string[];
+    title: string;
+    into?: string;
+    hub?: string;
+}, signal?: AbortSignal): Promise<HubLanding>;
+export interface FolderLanding {
+    path: string;
+    into: string;
+    state: 'landed' | 'already' | 'conflict' | 'waiting' | 'skipped';
+    sha?: string;
+    method?: string;
+    files?: number;
+    kept?: string[];
+    conflicts?: string[];
+    backup?: string | null;
+    reason?: string;
+}
+export interface FolderInput {
+    folder: string;
+    into: string;
+    name: string;
+    title: string;
+    branch: string;
+    base: string;
+    device: string;
+    stateDir: string;
+    hub?: string;
+    quietMs?: number;
+    signal?: AbortSignal;
+    /** How long a busy folder (a file just saved, a Git operation) is waited for before the answer is "waiting". */
+    patienceMs?: number;
+}
+/** The branch to land in: the one checked out in the folder, else the hub's default branch when the folder has it. */
+export declare function folderBranch(folder: string, fallback: string): Promise<string | null>;
+/**
+ * The result into the folder through the twin's landing (from the hub): the branch moves, the person's uncommitted
+ * edits stay, and the landed commit is checked to be on the branch.
+ */
+export declare function landInFolder(cell: TwinCell, f: FolderInput): Promise<FolderLanding>;
+/** The repository a folder holds, as conversations started from it name it (its origin, else the folder itself). */
+export declare function folderRepository(folder: string): string | null;
+/**
+ * The person's folder for a project on this computer: a linked folder (shard projects link) or where it was started.
+ * With `repository` (a project holds every folder its people linked), only a folder of that repository.
+ */
+export declare function linkedFolder(ctx: Pick<Ctx, 'store' | 'apiUrl'>, projectId: string, conversationId?: string, repository?: string): string | null;
+export declare const displayPath: (path: string) => string;
+export interface LandOutcome {
+    landed: true;
+    task_id?: string;
+    conversation_id?: string;
+    title: string;
+    result: {
+        branch: string;
+        sha: string;
+    };
+    hub: {
+        into: string;
+        sha: string;
+        method: string;
+    };
+    folder: (FolderLanding & {
+        display: string;
+    }) | null;
+    recorded: boolean;
+    record_error?: string;
+    /** One line for people: "Landed in ~/code/best-todo · 3f2a1c9". */
+    message: string;
+}
+/** What a landing needs: the API, a VM that reads the project hub, the person's folder for a project, this device. */
+export interface LandDeps {
+    client: {
+        tasks: Pick<ReturnType<typeof conversationClient>['tasks'], 'get' | 'recordLanding' | 'steer'>;
+        conversations: Pick<ReturnType<typeof conversationClient>['conversations'], 'get' | 'land'>;
+    };
+    hubCell(projectId: string): Promise<{
+        cell: TwinCell;
+        close(): void;
+    }>;
+    folder(projectId: string, conversationId?: string, repository?: string): string | null;
+    device: string;
+    stateDir: string;
+    hub?: string;
+    quietMs?: number;
+    signal?: AbortSignal;
+}
+export declare function landDeps(ctx: Ctx): LandDeps;
+/** What a landing did, for people: the line, then what was not recorded. */
+export declare function landedText(o: LandOutcome): string;
+/** `shard task land <task>`: the task's result into the project's default branch and the linked folder, then recorded. */
+export declare function landTask(d: LandDeps, taskId: string, opts?: {
+    path?: string;
+}): Promise<LandOutcome>;
+/** `shard conversations land <id> merge`: the conversation's branch into the default branch and its folder, then recorded. */
+export declare function landConversation(d: LandDeps, id: string, opts?: {
+    path?: string;
+}): Promise<LandOutcome>;