@shardflux/cli 0.13.6 → 0.14.0

package/dist/conversation-terminal.js

@@ -0,0 +1,74 @@
+import { randomUUID } from 'node:crypto';
+import { AgentStateStore } from "./agent-state.js";
+import { projectIdentity, projectLabels } from "./project-identity.js";
+import { createConversation, conversationWorkspace, conversationsUnavailable, listConversations, localConversations, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
+import { terminal } from "./agent-commands.js";
+import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
+import { syncAgentCredentials } from "./agent-credentials.js";
+import { prepareProjectTemplate } from "./project-template-setup.js";
+import { projectWorkspacePath, seedAgentRepository } from "./agent-repository.js";
+import { syncAgentConfig } from "./agent-config-sync.js";
+import { savedMachine } from "./filesystem-state.js";
+import { ensureMenubar, MenubarManager } from "./menubar.js";
+import { UsageError } from "./errors.js";
+import { localResumeTerminal } from "./conversation-local-resume.js";
+import { agentReachability } from "./agent-reachability.js";
+/** Select a durable conversation, then use the harness's native terminal for all interaction. */
+export const launchConversationProject = async (ctx, values, [path = './', explicit]) => {
+    const project = projectIdentity(path), store = new AgentStateStore(ctx.store.dir);
+    const app = explicit === 'claude' || explicit === 'codex' ? explicit : store.app(project.remote ?? project.folder);
+    if (explicit && explicit !== app)
+        throw new UsageError('Choose claude or codex.');
+    if (values.resume === true) {
+        // The native pickers are VM-local. C-K6's project picker must select the binding first.
+        const records = localConversations(ctx);
+        const conversations = (await listConversations(ctx)).filter(c => records[c.id]?.folder === project.folder && c.harness === app);
+        if (!conversations.length)
+            throw new UsageError('This project has no saved conversations. Start one with shard ./.');
+        ctx.io.stderr.write(conversations.map((c, i) => `${i + 1}. ${c.title || c.key} (${c.state})\n`).join(''));
+        const selected = await ctx.input.secret('Continue conversation number: ', 'conversation number', 'pipe its number');
+        const c = conversations[Number(selected) - 1];
+        if (!/^\d+$/.test(selected) || !c)
+            throw new UsageError('Choose a conversation number from the list.');
+        if (records[c.id]?.handed_off && (c.state === 'done' || c.state === 'archived'))
+            return localResumeTerminal(ctx, c, project.folder);
+        const next = await resumeConversation(ctx, c);
+        rememberConversation(ctx, next, project.folder);
+        const ws = await conversationWorkspace(ctx, next);
+        await restoreConversationBinding(ctx, next, ws);
+        return terminal(ctx, ws, app, next.key.split('/').at(-1), project.remote ?? project.folder, values, undefined, next.worktree_path, { id: next.id, session: next.harness_session_id });
+    }
+    await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
+    const signedIn = app === 'claude' ? await cloudClaudeLogin(ctx) : true;
+    if (!signedIn)
+        requireClaudeTerminal(ctx);
+    let created;
+    try {
+        created = await createConversation(ctx, project.folder, app, 'terminal');
+    }
+    catch (e) {
+        if (!conversationsUnavailable(e))
+            throw e;
+        // Optional migration: preserve the native terminal on the old control plane, without reviving main sync.
+        const name = `c-${randomUUID().slice(0, 12)}`;
+        const prepared = await prepareProjectTemplate(ctx, project, undefined);
+        const ws = await ctx.cloud().workspaces.open({ ...agentReachability(values), key: `${project.slug}/${name}`, template: prepared.template,
+            labels: { ...projectLabels(project, name, app), ...prepared.labels, repo_path: projectWorkspacePath(project) },
+            wait: { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal } });
+        await seedAgentRepository(ctx, ws, project.folder, { populate: true });
+        if (!signedIn)
+            await loginClaudeInWorkspace(ctx, ws);
+        if (!(await savedMachine(ctx))?.template)
+            await syncAgentConfig(ctx, ws);
+        return terminal(ctx, ws, app, name, project.remote ?? project.folder, values, prepared.setupHash);
+    }
+    const { conversation: c, workspace: ws } = created;
+    if (values.reachable !== undefined)
+        await ctx.cloud().workspaces.open({ key: ws.key, ...agentReachability(values), wait: false });
+    if (!signedIn)
+        await loginClaudeInWorkspace(ctx, ws);
+    if (!(await savedMachine(ctx))?.template)
+        await syncAgentConfig(ctx, ws);
+    await ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
+    return terminal(ctx, ws, app, c.key.split('/').at(-1), project.remote ?? project.folder, values, undefined, c.worktree_path, { id: c.id, session: c.harness_session_id });
+};

package/dist/conversation-worktree.d.ts

@@ -0,0 +1,4 @@
+import type { Ctx } from './commands.js';
+import type { Conversation } from './conversations.js';
+export declare function checkConversationWorktree(ctx: Pick<Ctx, 'store' | 'apiUrl'>, c: Conversation, folder: string, root: string): void;
+export declare function rememberConversationWorktree(ctx: Pick<Ctx, 'store' | 'apiUrl'>, c: Conversation, folder: string, root: string): void;

package/dist/conversation-worktree.js

@@ -0,0 +1,22 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { writePrivateFile } from "./credentials.js";
+import { UsageError } from "./errors.js";
+function identity(ctx, c, folder, root) {
+    const owner = { api_url: ctx.apiUrl, project_id: c.project_id, conversation_id: c.id, folder: realpathSync(folder), root };
+    const key = createHash('sha256').update(owner.folder).update(root).digest('hex');
+    return { owner, file: join(ctx.store.dir, 'conversation-worktrees', `${key}.json`) };
+}
+export function checkConversationWorktree(ctx, c, folder, root) {
+    const { owner, file } = identity(ctx, c, folder, root);
+    if (lstatSync(root).isSymbolicLink() || !existsSync(file) || lstatSync(file).isSymbolicLink() || (lstatSync(file).mode & 0o077))
+        throw new UsageError('The local conversation worktree has no matching private ownership record.');
+    const saved = JSON.parse(readFileSync(file, 'utf8'));
+    if (Object.entries(owner).some(([key, value]) => saved[key] !== value))
+        throw new UsageError('The local conversation worktree belongs to another conversation or API profile.');
+}
+export function rememberConversationWorktree(ctx, c, folder, root) {
+    const { owner, file } = identity(ctx, c, folder, root);
+    writePrivateFile(dirname(file), file, JSON.stringify(owner) + '\n');
+}

package/dist/conversations.d.ts

@@ -0,0 +1,53 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+export type Harness = 'claude' | 'codex';
+export interface Conversation {
+    id: string;
+    project_id: string;
+    key: string;
+    title: string;
+    summary: string;
+    harness: Harness;
+    harness_session_id: string | null;
+    route: 'terminal' | 'acp' | 'codex-app' | 'claude-desktop' | 't3-ssh';
+    workspace_id: string;
+    worktree_path: string;
+    branch: string;
+    base_commit: string;
+    state: 'working' | 'needs_you' | 'unresolved' | 'done' | 'archived';
+    created_at: string;
+    ended_at: string | null;
+    last_activity_at?: string;
+    durable?: {
+        branch_sha: string;
+        transcript_bytes: number;
+        branch_in_hub: boolean;
+        transcript_in_project_space: boolean;
+    } | null;
+    ports?: number[];
+    restore?: Record<string, unknown> | null;
+}
+export interface LocalConversation {
+    api_url: string;
+    folder: string;
+    project_id: string;
+    conversation: Conversation;
+    handed_off?: boolean;
+}
+export declare const conversationName: (c: Conversation) => string;
+export declare function validateConversation(c: Conversation): Conversation;
+export declare function localConversations(ctx: Pick<Ctx, 'store' | 'apiUrl'>): Record<string, LocalConversation>;
+export declare function rememberConversation(ctx: Pick<Ctx, 'store' | 'apiUrl'>, c: Conversation, folder: string, handedOff?: boolean): void;
+export declare function conversationsUnavailable(e: unknown): boolean;
+export declare function getConversation(ctx: Ctx, id: string): Promise<Conversation>;
+export declare function listConversations(ctx: Ctx, projectId?: string): Promise<Conversation[]>;
+export declare function resolveConversation(ctx: Ctx, ref: string, folder?: string): Promise<Conversation>;
+/** Re-resolve the binding on every attach: a move changes the VM, never the conversation identity. */
+export declare function conversationWorkspace(ctx: Ctx, c: Conversation): Promise<Workspace>;
+export declare function restoreConversationBinding(ctx: Ctx, c: Conversation, ws: Workspace): Promise<void>;
+export declare function createConversationRecord(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string): Promise<Conversation>;
+export declare function createConversation(ctx: Ctx, folder: string, harness: Harness, route: Conversation['route'], name?: string): Promise<{
+    conversation: Conversation;
+    workspace: Workspace;
+}>;
+export declare function resumeConversation(ctx: Ctx, c: Conversation): Promise<Conversation>;

package/dist/conversations.js

@@ -0,0 +1,118 @@
+import { randomUUID } from 'node:crypto';
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { AgentStateStore } from "./agent-state.js";
+import { gitRunner } from "./agent-git.js";
+import { projectIdentity } from "./project-identity.js";
+import { seedAgentRepository } from "./agent-repository.js";
+import { UsageError } from "./errors.js";
+import { conversationClient } from "./conversation-commands.js";
+export const conversationName = (c) => {
+    const name = c.key.split('/').at(-1);
+    if (!/^[a-z0-9][a-z0-9-]{0,47}$/.test(name) || c.branch !== `shard/${name}`)
+        throw new Error('Conversation returned an invalid branch or name');
+    return name;
+};
+export function validateConversation(c) {
+    if (!c || !/^conv_[a-z0-9]{26}$/.test(c.id) || !c.project_id || !c.workspace_id || !c.worktree_path?.startsWith('/home/user/') || /[\0\r\n]/.test(c.worktree_path) || !['claude', 'codex'].includes(c.harness))
+        throw new Error('Conversation response omitted its identity or binding');
+    conversationName(c);
+    return c;
+}
+export function localConversations(ctx) {
+    const records = new AgentStateStore(ctx.store.dir).read().conversations ?? {};
+    return Object.fromEntries(Object.entries(records).filter(([, r]) => r.api_url === ctx.apiUrl));
+}
+export function rememberConversation(ctx, c, folder, handedOff = false) {
+    validateConversation(c);
+    new AgentStateStore(ctx.store.dir).update(doc => {
+        const records = doc.conversations ?? {};
+        records[c.id] = { api_url: ctx.apiUrl, folder, project_id: c.project_id, conversation: c, ...(handedOff ? { handed_off: true } : {}) };
+        doc.conversations = records;
+    });
+}
+export function conversationsUnavailable(e) {
+    return e instanceof ShardfluxApiError && ((e.status === 503 && e.details?.reason === 'conversations_unavailable') || (e.status === 404 && !e.details?.reason));
+}
+export async function getConversation(ctx, id) {
+    const data = await conversationClient(ctx).conversations.get(id);
+    const c = { ...data, ports: data.card.ports };
+    return validateConversation(c);
+}
+export async function listConversations(ctx, projectId) {
+    const all = [];
+    let cursor;
+    do {
+        const page = await conversationClient(ctx).conversations.list({ ...(projectId ? { projectId } : {}), limit: 200, ...(cursor ? { cursor } : {}) });
+        all.push(...page.data.map(validateConversation));
+        cursor = page.nextCursor ?? undefined;
+    } while (cursor);
+    return all;
+}
+export async function resolveConversation(ctx, ref, folder) {
+    if (ref.startsWith('conv_'))
+        return getConversation(ctx, ref);
+    const matches = (await listConversations(ctx)).filter(c => c.key === ref || conversationName(c) === ref);
+    const records = localConversations(ctx);
+    const scoped = folder ? matches.filter(c => records[c.id]?.folder === projectIdentity(folder).folder) : matches;
+    if (scoped.length !== 1)
+        throw new UsageError(scoped.length ? 'Use the full conversation key or id.' : 'Conversation not found.');
+    return scoped[0];
+}
+/** Re-resolve the binding on every attach: a move changes the VM, never the conversation identity. */
+export async function conversationWorkspace(ctx, c) {
+    const ws = await conversationClient(ctx).workspaces.get(c.workspace_id);
+    if (ws.data.deleted_at)
+        throw new UsageError('This conversation is saved. Resume it to continue.');
+    if (!ws.ready)
+        await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+    return ws;
+}
+export async function restoreConversationBinding(ctx, c, ws) {
+    if (!c.restore || c.restore.kind === 'new')
+        return;
+    const cell = ws.cell();
+    if (c.restore.kind === 'join' && c.restore.read_only === true) {
+        const review = await cell.exec.run(['sf-agent', 'conversation', 'restore', '--args', '{"start":false}'], { cwd: c.worktree_path, env: { SF_CONVERSATION_ID: c.id }, timeoutMs: 120_000, signal: ctx.signal });
+        if (review.exitCode !== 0)
+            throw new Error(`Reviewer restore failed: ${review.stderr.trim()}`);
+        return;
+    }
+    await cell.files.mkdir(c.worktree_path, { parents: true });
+    const init = await cell.exec.run(['git', '-C', c.worktree_path, 'init'], { timeoutMs: 30_000, signal: ctx.signal });
+    if (init.exitCode !== 0)
+        throw new Error(`Conversation restore could not initialize its repository: ${init.stderr.trim()}`);
+    const result = await cell.exec.run(['sf-agent', 'conversation', 'restore', '--args', '{"start":false}'], { cwd: c.worktree_path, env: { SF_CONVERSATION_ID: c.id }, timeoutMs: 120_000, signal: ctx.signal });
+    if (result.exitCode !== 0)
+        throw new Error(`Conversation restore failed: ${result.stderr.trim()}`);
+}
+export async function createConversationRecord(ctx, folder, harness, route, name) {
+    const project = projectIdentity(folder);
+    // Detect the optional control-plane feature before applying the new Git contract to old APIs.
+    await conversationClient(ctx).conversations.list({ limit: 1 });
+    const git = gitRunner(project.folder, { ...process.env, ...ctx.io.env }, ctx.signal);
+    const commit = await git(['rev-parse', 'HEAD']);
+    const branch = await git(['symbolic-ref', '--quiet', '--short', 'HEAD']).catch(() => undefined);
+    const response = await conversationClient(ctx).conversations.create({ repoRemote: project.remote ?? `file://${project.folder}`, harness, route, mode: 'new',
+        base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), projectId: ctx.store.profile(ctx.apiUrl).project_id }, { idempotencyKey: randomUUID(), signal: ctx.signal });
+    const c = validateConversation({ ...response.conversation, restore: response.restore });
+    rememberConversation(ctx, c, project.folder);
+    return c;
+}
+export async function createConversation(ctx, folder, harness, route, name) {
+    const project = projectIdentity(folder);
+    const c = await createConversationRecord(ctx, project.folder, harness, route, name);
+    const ws = await conversationWorkspace(ctx, c);
+    // This is a one-time seed. A conversation never watches or writes the owner's checkout.
+    await seedAgentRepository(ctx, ws, project.folder, { root: c.worktree_path, populate: true });
+    const cell = ws.cell();
+    const result = await cell.exec.run(['git', '-C', c.worktree_path, 'checkout', '-B', c.branch, c.base_commit], { timeoutMs: 30_000, signal: ctx.signal });
+    if (result.exitCode !== 0)
+        throw new Error(`Conversation branch could not be prepared: ${result.stderr.trim()}`);
+    return { conversation: c, workspace: ws };
+}
+export async function resumeConversation(ctx, c) {
+    if (c.state !== 'done' && c.state !== 'archived')
+        return getConversation(ctx, c.id);
+    const response = await conversationClient(ctx).conversations.resume(c.id, { idempotencyKey: randomUUID(), signal: ctx.signal });
+    return validateConversation({ ...response.conversation, restore: response.restore });
+}

package/dist/device-bridge.d.ts

@@ -0,0 +1,80 @@
+import type { CellClient, Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import type { Conversation } from './conversations.js';
+export type DeviceChoice = 'once' | 'always' | 'deny';
+export interface DeviceRequest {
+    id: string;
+    project_id: string;
+    conversation_id: string;
+    state: string;
+    device_id: string | null;
+    kind: 'exec' | 'files_pull' | 'files_push' | 'port_forward' | 'port_reverse' | 'try_locally';
+    exec?: {
+        argv: string[];
+        cwd_relative?: string;
+        timeout_seconds?: number;
+    };
+    files?: {
+        local_path_relative: string;
+        remote_path: string;
+        max_bytes?: number;
+    };
+    port?: {
+        remote_port: number;
+        local_port: number;
+    };
+}
+export interface DeviceApproval {
+    type: 'approval';
+    request_id: string;
+    project_id: string;
+    conversation_id: string;
+    summary: string;
+    outside: boolean;
+}
+type Result = {
+    state: 'approved' | 'denied' | 'running' | 'done' | 'failed';
+    exit_code?: number;
+    stdout_b64?: string;
+    stderr_b64?: string;
+    files_artifact?: string;
+};
+/** Resolve every existing ancestor, including symlinks. Missing leaf files do not hide an outside parent. */
+export declare function devicePath(root: string, requested?: string): {
+    path: string;
+    outside: boolean;
+};
+export declare class DeviceGrants {
+    readonly file: string;
+    constructor(dir: string);
+    key(api: string, project: string): string;
+    read(): Record<string, {
+        root: string;
+        kinds: string[];
+    }>;
+    allows(api: string, project: string, root: string, kind: string, outside: boolean): boolean;
+    save(api: string, project: string, root: string, kind: string): Promise<void>;
+}
+export declare function deviceSummary(r: DeviceRequest): string;
+export declare function tryLocallyAction(r: DeviceRequest): 'start' | 'stop' | null;
+export declare function ensureConversationWorktree(ctx: Ctx, c: Conversation, folder: string, ws?: Workspace): Promise<string>;
+export declare function deviceExec(argv: string[], cwd: string, timeoutSeconds?: number, signal?: AbortSignal): Promise<Result>;
+export declare class DeviceExecutor {
+    #private;
+    constructor(ctx: Ctx, ask: (approval: DeviceApproval) => Promise<DeviceChoice>, deviceId: string);
+    result(r: DeviceRequest, result: Result): Promise<void>;
+    execute(r: DeviceRequest): Promise<void>;
+    reap(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function devicePort(ws: Workspace, cell: CellClient, kind: 'port_forward' | 'port_reverse', ports: {
+    local_port: number;
+    remote_port: number;
+}, signal: AbortSignal): Promise<{
+    stop(): Promise<void>;
+}>;
+export declare function serveAcpDeviceApprovals(dir: string, id: string, ask: (a: DeviceApproval) => Promise<DeviceChoice>): Promise<{
+    stop(): Promise<void>;
+}>;
+export declare function askConnectedAcp(dir: string, approval: DeviceApproval, signal: AbortSignal): Promise<DeviceChoice | null>;
+export {};