@shardflux/cli 0.24.0 → 0.25.0

package/dist/device-helper.js

@@ -1,5 +1,7 @@
 import { setTimeout as delay } from 'node:timers/promises';
-import { DeviceExecutor, askConnectedAcp } from "./device-bridge.js";
+import { DeviceExecutor, askConnectedAcp, askDeviceApprover } from "./device-bridge.js";
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { allOrgs, allProjects } from "./account-scope.js";
 import { ConversationMirrorState, mirrorProjectConversations } from "./conversation-stash.js";
 import { FilesMirrorState, mirrorFilesOnce } from "./files-mirror.js";
 import { withTargetLock } from "./target-lock.js";
@@ -44,6 +46,10 @@ export async function runDeviceHelper(ctx, options = {}) {
         const acp = await askConnectedAcp(ctx.store.dir, approval, signal);
         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);
+        if (app)
+            return app;
         if (options.service)
             return askLocalDeviceApproval(ctx, approval);
         return new Promise(resolve => {
@@ -141,22 +147,71 @@ export async function runDeviceHelper(ctx, options = {}) {
                     await delay(wait, undefined, { signal }).catch(() => undefined);
                 }
             })();
+            // 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, 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)
+                        continue;
+                    const work = executor.execute(r).catch(report).finally(() => working.delete(r.id));
+                    working.set(r.id, work);
+                }
+            };
             while (!signal.aborted) {
                 try {
-                    for (const projectId of new Set(Object.values(localConversations(ctx)).map(r => r.project_id))) {
-                        await conversationClient(ctx).deviceRequests.heartbeat({ projectId, deviceId, leaseSeconds: 30 });
-                        let cursor;
-                        do {
-                            const page = await conversationClient(ctx).deviceRequests.list({ projectId, state: 'pending', limit: 200, ...(cursor ? { cursor } : {}) });
-                            for (const r of page.data) {
-                                if (r.device_id !== deviceId || working.has(r.id) || working.size >= 8)
-                                    continue;
-                                const work = executor.execute(r).catch(report).finally(() => working.delete(r.id));
-                                working.set(r.id, work);
-                            }
-                            cursor = page.nextCursor ?? undefined;
-                        } while (cursor && !signal.aborted);
+                    if (!all || Date.now() - all.at > 300_000)
+                        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) {
+                        if (Date.now() - (registered.get(projectId) ?? 0) < 10_000)
+                            continue;
+                        await beat(projectId).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);
+                        });
+                    }
+                    let polled = false;
+                    if (deviceWide && registered.size) {
+                        try {
+                            let cursor;
+                            do {
+                                const page = await conversationClient(ctx).deviceRequests.list({ deviceId, state: 'pending', limit: 200, ...(cursor ? { cursor } : {}) });
+                                take(page.data);
+                                cursor = page.nextCursor ?? undefined;
+                            } while (cursor && !signal.aborted);
+                            polled = true;
+                        }
+                        catch (e) {
+                            if (e instanceof ShardfluxApiError && [400, 422].includes(e.status))
+                                deviceWide = false;
+                            else
+                                throw e;
+                        }
                     }
+                    if (!polled)
+                        for (const projectId of projects) {
+                            let cursor;
+                            do {
+                                const page = await conversationClient(ctx).deviceRequests.list({ ...(projectId ? { projectId } : {}), state: 'pending', limit: 200, ...(cursor ? { cursor } : {}) });
+                                take(page.data);
+                                cursor = page.nextCursor ?? undefined;
+                            } while (cursor && !signal.aborted);
+                        }
                     await executor.reap();
                 }
                 catch (e) {
@@ -185,3 +240,32 @@ export async function runDeviceHelper(ctx, options = {}) {
         await input.catch(() => undefined);
     }
 }
+/**
+ * The projects this device answers for besides its local conversations' (0.25.0+): the signed-in project (the API
+ * key's, or the default one), and with a person's own sign-in and no key, every project they can reach (at most 100).
+ * A home conversation, an Orchestrator master or a chat the desktop app started asks from these.
+ */
+export async function deviceProjects(ctx) {
+    const profile = ctx.store.profile(ctx.apiUrl), ids = new Set();
+    if (profile.project_id)
+        ids.add(profile.project_id);
+    if (profile.api_key?.project_id)
+        ids.add(profile.api_key.project_id);
+    const key = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || profile.api_key !== undefined;
+    const session = Boolean(ctx.io.env.SHARDFLUX_SESSION_TOKEN?.trim()) || profile.session !== undefined;
+    if (key && !ids.size)
+        ids.add(''); // the key's own project: the API takes it from the key
+    if (!key && session) {
+        const account = ctx.account();
+        for (const org of await allOrgs(account)) {
+            for (const p of await allProjects(account, org.id)) {
+                ids.add(p.id);
+                if (ids.size >= 100)
+                    break;
+            }
+            if (ids.size >= 100)
+                break;
+        }
+    }
+    return [...ids];
+}

package/dist/drive-commands.d.ts

@@ -0,0 +1,25 @@
+import type { DriveFile, ModelTemplate, Shardflux, ShardfluxAccount } from '@shardflux/sdk';
+import type { Values } from './args.js';
+import type { Ctx, Handler } from './commands.js';
+/** A project API key is in use: SHARDFLUX_API_KEY, else the key `shard setup` saved for this API URL. */
+export declare const hasApiKey: (ctx: Ctx) => boolean;
+export interface ProjectScope {
+    client: Shardflux | ShardfluxAccount;
+    /** Undefined only when `needId` was false and the API key's own project is meant. */
+    projectId: string | undefined;
+}
+/**
+ * Who acts and in which project. `--project` acts as the signed-in person when there is a sign-in (their projects,
+ * by id or slug), else with the API key. Without it: the API key's own project, else the person's default project.
+ * `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;
+/**
+ * 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
+ * would run instead.
+ */
+export declare function modelTemplateText(t: ModelTemplate): string;
+export declare const DRIVE_HANDLERS: Record<string, Handler>;

package/dist/drive-commands.js

@@ -0,0 +1,201 @@
+/**
+ * The project drive and the model template (0.25.0+): `shard drive ls|get|put|rm` and `shard models`,
+ * `shard models primary`. Both act in one project: the API key's own, or `--project`; a person signed in without a
+ * key acts in their default project (`shard projects use`), or the only one there is.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { encodeDrivePath } from '@shardflux/sdk';
+import { UUID } from "./args.js";
+import { resolveOrg, resolveProject } from "./account-scope.js";
+import { out, principal, readInput, str } from "./commands.js";
+import { AuthConfigError, UsageError } from "./errors.js";
+import { humanBytes } from "./files-mirror.js";
+import { json, table, time } from "./format.js";
+/** A drive file of up to 5 GiB is read into memory to send it with its SHA-256. */
+const MAX_PUT_BYTES = 5 * 1024 ** 3;
+const SHA256 = /^[0-9a-f]{64}$/i;
+/** A project API key is in use: SHARDFLUX_API_KEY, else the key `shard setup` saved for this API URL. */
+export const hasApiKey = (ctx) => Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
+/**
+ * Who acts and in which project. `--project` acts as the signed-in person when there is a sign-in (their projects,
+ * by id or slug), else with the API key. Without it: the API key's own project, else the person's default project.
+ * `needId` false leaves the key's project unnamed (the API defaults to it), saving a lookup.
+ */
+export async function projectScope(ctx, values, needId = true) {
+    const given = str(values.project);
+    const signedIn = ctx.sessionSource() !== null;
+    if (signedIn && (given !== undefined || !hasApiKey(ctx))) {
+        const account = ctx.account();
+        return { client: account, projectId: (await resolveProject(ctx, account, values)).id };
+    }
+    const cloud = ctx.cloud();
+    if (given !== undefined) {
+        if (!UUID.test(given))
+            throw new UsageError(`--project with an API key takes the project id (got "${given}").`, 'or sign in to name projects by slug: shard auth login');
+        return { client: cloud, projectId: given };
+    }
+    if (!needId)
+        return { client: cloud, projectId: undefined };
+    return { client: cloud, projectId: ctx.apiKey().saved?.project_id ?? (await principal(ctx)).project_id };
+}
+/** A drive path checked as the SDK sends it: relative, no empty, `.` or `..` segments (exit 2 before any request). */
+function drivePath(path, what = 'drive path') {
+    try {
+        encodeDrivePath(path);
+    }
+    catch (err) {
+        if (err instanceof TypeError)
+            throw new UsageError(`${what}: ${err.message}`);
+        throw err;
+    }
+    return path;
+}
+/** `drive 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]));
+}
+const SOURCES = {
+    marked: 'the organization’s choice',
+    project: 'this project’s choice',
+    first_connected: 'connected first',
+};
+const ROLE_ORDER = ['master', 'builder', 'hard', 'light', 'reviewer'];
+const providerName = (p) => (p === 'claude' ? 'Claude' : 'Codex');
+/**
+ * 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
+ * would run instead.
+ */
+export function modelTemplateText(t) {
+    const lines = [];
+    if (t.primary === null)
+        lines.push('Connect Claude or Codex to run tasks: shard agents accounts add claude (or codex).');
+    else
+        lines.push(`Primary: ${t.primary} (${t.primary_source ? SOURCES[t.primary_source] : 'connected first'})${t.secondary ? `, secondary: ${t.secondary}` : ''}`);
+    if (t.connected.length)
+        lines.push(`Connected: ${t.connected.map((c) => `${c.provider}${c.plan_type ? ` (${c.plan_type})` : ''}`).join(', ')}`);
+    if (t.task_harness !== null || t.attempt > 0)
+        lines.push(`Task: ${[t.task_harness ? `on ${t.task_harness}` : '', t.attempt > 0 ? `retry ${t.attempt}` : ''].filter(Boolean).join(', ')}`);
+    const rows = ROLE_ORDER.map((role) => {
+        const r = t.roles[role];
+        const effort = `${r.effort ?? 'default'}${r.planning_effort ? ` (plans ${r.planning_effort})` : ''}`;
+        const wait = r.wait ? `${time(r.wait.until)}${r.wait.alternative ? `, or now: ${r.wait.alternative.label}` : ''}` : '-';
+        return [role, r.harness, r.model, effort, wait];
+    });
+    return `${lines.join('\n')}\n\n${table(['ROLE', 'HARNESS', 'MODEL', 'EFFORT', 'WAITS UNTIL'], rows)}`;
+}
+function harnessOf(values) {
+    const h = str(values.harness);
+    if (h !== undefined && h !== 'claude' && h !== 'codex')
+        throw new UsageError(`--harness must be claude or codex (got "${h}").`);
+    return h;
+}
+function attemptOf(values) {
+    const a = str(values.attempt);
+    if (a === undefined)
+        return undefined;
+    if (!/^\d+$/.test(a) || Number(a) > 10)
+        throw new UsageError(`--attempt must be 0 for a first run, or 1 to 10 for a retry (got "${a}").`);
+    return Number(a);
+}
+export const DRIVE_HANDLERS = {
+    async 'drive ls'(ctx, values, [prefix]) {
+        const { client, projectId } = await projectScope(ctx, values);
+        const limitText = str(values.limit);
+        const limit = limitText === undefined ? undefined : Number(limitText);
+        if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 1000))
+            throw new UsageError('--limit must be 1 to 1000.');
+        const rows = [];
+        const seen = new Set();
+        let cursor = str(values.cursor), next;
+        do {
+            const page = await client.drive.list(projectId, { ...(prefix ? { prefix } : {}), ...(limit ? { limit } : values.all === true ? { limit: 1000 } : {}), ...(cursor ? { cursor } : {}), signal: ctx.signal });
+            rows.push(...page.data);
+            next = page.nextCursor;
+            cursor = next ?? undefined;
+            if (values.all === true && cursor) {
+                if (seen.has(cursor))
+                    throw new UsageError('The drive listing repeated its cursor. Try again.');
+                seen.add(cursor);
+            }
+        } while (values.all === true && cursor);
+        out(ctx, rows.length ? driveTable(rows) : 'No files.\n', { data: rows, next_cursor: next });
+        if (!ctx.json && next)
+            ctx.io.stderr.write(`more: shard drive ls${prefix ? ` ${prefix}` : ''} --cursor ${next}\n`);
+        return 0;
+    },
+    async 'drive get'(ctx, values, [path]) {
+        drivePath(path);
+        const sha256 = str(values.sha256)?.toLowerCase();
+        if (sha256 !== undefined && !SHA256.test(sha256))
+            throw new UsageError('--sha256 takes the 64 hex characters of a version’s SHA-256 (shard drive ls --json shows them).');
+        const { client, projectId } = await projectScope(ctx, values);
+        const file = await client.drive.read(projectId, path, { ...(sha256 ? { sha256 } : {}), signal: ctx.signal });
+        const dest = str(values.out);
+        const meta = { path, sha256: file.sha256, size: file.size, content_type: file.contentType };
+        if (dest !== undefined) {
+            await writeFile(dest, file.bytes);
+            out(ctx, `Wrote ${path} to ${dest} (${humanBytes(file.size)}, sha256 ${file.sha256})\n`, { ...meta, out: dest });
+        }
+        else if (ctx.json) {
+            ctx.io.stdout.write(json({ ...meta, content_base64: Buffer.from(file.bytes).toString('base64') }));
+        }
+        else {
+            ctx.io.stdout.write(file.bytes);
+        }
+        return 0;
+    },
+    async 'drive put'(ctx, values, [local, target]) {
+        if (local === '-' && target === undefined)
+            throw new UsageError('Name the drive path when the file comes from standard input: shard drive put - <drive-path>');
+        const path = drivePath(target ?? basename(local), target === undefined ? `the file name "${basename(local)}"` : 'drive path');
+        const bytes = local === '-' ? await readInput(ctx, '-', MAX_PUT_BYTES, 'standard input') : await readFile(local).catch((e) => {
+            throw new UsageError(`cannot read "${local}" (${e.code === 'EISDIR' ? 'a folder; put its files one by one' : e.code ?? e.message})`);
+        });
+        const contentType = str(values['content-type']);
+        const { client, projectId } = await projectScope(ctx, values);
+        const file = await client.drive.save(projectId, path, bytes, { ...(contentType ? { contentType } : {}), signal: ctx.signal });
+        out(ctx, `Saved ${file.path} (${humanBytes(file.size)}, ${file.content_type})\nsha256 ${file.sha256}\n`, { file });
+        return 0;
+    },
+    async 'drive rm'(ctx, values, [path]) {
+        drivePath(path);
+        const { client, projectId } = await projectScope(ctx, values);
+        await client.drive.remove(projectId, path, { signal: ctx.signal });
+        out(ctx, `Removed ${path}\n`, { path, removed: true });
+        return 0;
+    },
+    async models(ctx, values) {
+        const harness = harnessOf(values), attempt = attemptOf(values);
+        const { client, projectId } = await projectScope(ctx, values, false);
+        const t = await client.modelTemplate.get({ ...(projectId ? { projectId } : {}), ...(harness ? { harness } : {}), ...(attempt !== undefined ? { attempt } : {}), signal: ctx.signal });
+        out(ctx, modelTemplateText(t), t);
+        return 0;
+    },
+    async 'models primary'(ctx, values, [choice]) {
+        const word = choice.toLowerCase();
+        if (!['claude', 'codex', 'clear'].includes(word))
+            throw new UsageError(`Choose claude, codex or clear (got "${choice}").`);
+        const provider = word === 'clear' ? null : word;
+        if (str(values.org) !== undefined && str(values.project) !== undefined)
+            throw new UsageError('Choose --org (the organization’s default) or --project (one project).');
+        let t, whose;
+        if (str(values.org) !== undefined) {
+            if (ctx.sessionSource() === null)
+                throw new AuthConfigError('The organization’s default is set by its owners and admins, signed in.', 'sign in: shard auth login (an API key sets its own project’s: shard models primary <claude|codex> without --org)');
+            const account = ctx.account();
+            const org = await resolveOrg(ctx, account, values);
+            t = await account.modelTemplate.setPrimary({ provider, organizationId: org.id, signal: ctx.signal });
+            whose = `${org.name}’s`;
+        }
+        else {
+            const { client, projectId } = await projectScope(ctx, values);
+            t = await client.modelTemplate.setPrimary({ provider, projectId: projectId, signal: ctx.signal });
+            whose = 'this project’s';
+        }
+        // The template that follows shows the primary now in effect and where it comes from.
+        out(ctx, `${provider ? `${providerName(provider)} is ${whose} primary.` : `Cleared ${whose} primary.`}\n${modelTemplateText(t)}`, t);
+        return 0;
+    },
+};

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

@@ -1,6 +1,11 @@
 import { DEVICE_HANDLERS } from "./device-approvals.js";
+import { PROJECT_LINK_HANDLERS } from "./device-folders.js";
 import { CREDENTIAL_HANDLERS } from "./credential-prompts.js";
 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 { 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.
@@ -26,4 +31,5 @@ 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";
-export const HANDLERS = { ...PROJECT_PREPARATION_HANDLERS, ...MOVE_HANDLERS, ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_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 };
+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, ...TRANSCRIBE_HANDLERS, ...DRIVE_HANDLERS };

package/dist/land.d.ts

@@ -0,0 +1,116 @@
+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' | '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 person's folder for a project on this computer: a linked folder (shard projects link) or where it was started. */
+export declare function linkedFolder(ctx: Pick<Ctx, 'store' | 'apiUrl'>, projectId: string, conversationId?: 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): 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>;