@shardflux/cli 0.24.0 → 0.25.0

package/dist/acp-permission-elsewhere.js

@@ -0,0 +1,85 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { objectValue } from "./acp-rpc.js";
+/** How often the watch reads the API while the editor's permission prompt is open (it never touches the VM). */
+export const ELSEWHERE_POLL_MS = 1500;
+/**
+ * The guest reports a request as it journals it, just before the editor's prompt opens: one reported up to this long
+ * before (clock difference with the API included) is this prompt's; an older one counts only while it still waits (an
+ * editor reconnecting to a request that is still open).
+ */
+const REPORTED_BEFORE_MS = 10_000;
+/** The tool and command, path or URL the guest records for an ACP permission request (services/guest-agent ACPPermissionAsk). */
+export function requestIdentity(params) {
+    const call = objectValue(params.toolCall), raw = objectValue(call.rawInput), str = (v) => typeof v === 'string' ? v : '';
+    const location = Array.isArray(call.locations) ? str(objectValue(call.locations[0]).path) : '';
+    const tool = str(call.name) || str(objectValue(objectValue(call._meta).claudeCode).toolName);
+    return { tool: tool || null, detail: str(raw.command) || location || str(raw.file_path) || str(raw.url) };
+}
+/**
+ * While the editor shows the agent's permission prompt, the journal relay is paused, so nothing else of the turn reaches
+ * the editor. The same request is listed through the API, where a person can answer it too (the Shard client, the CLI,
+ * MCP). This resolves with the request once it leaves `pending` that way (answered through the API, or closed because
+ * the agent no longer waits), so the relay can withdraw the editor's prompt and go on with the turn. The request is the
+ * newest one of the conversation with the prompt's tool and command, path or URL that was reported as the prompt opened
+ * or still waits. It resolves null on an API without permission requests (404, 503) or when `signal` ends the prompt;
+ * other errors are retried.
+ */
+export async function answeredElsewhere(client, conversationId, params, openedAt, signal, pollMs = ELSEWHERE_POLL_MS) {
+    const want = requestIdentity(params);
+    let request;
+    for (;;) {
+        try {
+            await delay(pollMs, undefined, { signal });
+        }
+        catch {
+            return null;
+        }
+        try {
+            if (!request) {
+                // Every state, every page: an answer through the API can land before the first read.
+                let mine;
+                for (let cursor, pages = 0; pages < 20; pages++) {
+                    const page = await client.conversations.permissions(conversationId, { limit: 200, ...(cursor ? { cursor } : {}) });
+                    for (const p of page.data) {
+                        if (p.detail === want.detail && (p.tool ?? null) === want.tool && (p.state === 'pending' || Date.parse(p.created_at) >= openedAt - REPORTED_BEFORE_MS))
+                            mine = p;
+                    }
+                    if (!page.nextCursor)
+                        break;
+                    cursor = page.nextCursor;
+                }
+                if (!mine)
+                    continue;
+                if (mine.state !== 'pending')
+                    return mine;
+                request = mine.id;
+                continue;
+            }
+            const p = await client.conversations.permission(conversationId, request);
+            if (p.state !== 'pending')
+                return p;
+        }
+        catch (error) {
+            if (signal.aborted)
+                return null;
+            if (error instanceof ShardfluxApiError && (error.status === 404 || error.status === 503))
+                return null;
+        }
+    }
+}
+/**
+ * The editor-side answer matching a request answered elsewhere: the option of its decision's kind (as the guest picks
+ * it), or a cancelled outcome. The agent already has the first answer; this one only completes the relayed request.
+ */
+export function outcomeFor(p, params) {
+    const options = (Array.isArray(params.options) ? params.options : []).map(objectValue);
+    const wanted = p.decision === 'allow_once' ? ['allow_once', 'allow_always'] : p.decision === 'allow_always' ? ['allow_always', 'allow_once']
+        : p.decision === 'deny' ? ['reject_once', 'reject_always'] : [];
+    for (const kind of wanted) {
+        const option = options.find(o => o.kind === kind);
+        if (typeof option?.optionId === 'string')
+            return { outcome: { outcome: 'selected', optionId: option.optionId } };
+    }
+    return { outcome: { outcome: 'cancelled' } };
+}

package/dist/acp-rpc.d.ts

@@ -34,7 +34,8 @@ export declare class AcpRpc {
     get busy(): boolean;
     get closed(): boolean;
     feed(bytes: Uint8Array): void;
-    request(method: string, params: ObjectValue, timeoutMs?: number, signal?: AbortSignal): Promise<unknown>;
+    /** `cancelOnAbort`: an abort also tells the peer the request is withdrawn (`$/cancel_request`), so an editor drops its prompt. */
+    request(method: string, params: ObjectValue, timeoutMs?: number, signal?: AbortSignal, cancelOnAbort?: boolean): Promise<unknown>;
     notify(method: string, params: ObjectValue): Promise<void>;
     close(error?: Error): void;
     drain(): Promise<void>;

package/dist/acp-rpc.js

@@ -86,7 +86,8 @@ export class AcpRpc {
             pending.resolve(message.result);
         this.onIdle();
     }
-    request(method, params, timeoutMs = 120_000, signal) {
+    /** `cancelOnAbort`: an abort also tells the peer the request is withdrawn (`$/cancel_request`), so an editor drops its prompt. */
+    request(method, params, timeoutMs = 120_000, signal, cancelOnAbort = false) {
         if (this.#closed)
             return Promise.reject(this.#closed);
         if (signal?.aborted)
@@ -95,7 +96,15 @@ export class AcpRpc {
         return new Promise((resolve, reject) => {
             const cleanup = () => signal?.removeEventListener('abort', abort);
             const timer = timeoutMs > 0 ? setTimeout(() => { this.pending.delete(id); cleanup(); reject(new RpcError(-32000, 'Request timed out', { code: 'timeout', fix: 'Try the message again.' })); this.onIdle(); }, timeoutMs) : undefined;
-            const abort = () => { this.pending.delete(id); clearTimeout(timer); cleanup(); reject(signal?.reason instanceof Error ? signal.reason : new Error('Request interrupted')); this.onIdle(); };
+            const abort = () => {
+                this.pending.delete(id);
+                clearTimeout(timer);
+                cleanup();
+                if (cancelOnAbort && !this.#closed)
+                    void this.#write({ jsonrpc: '2.0', method: '$/cancel_request', params: { requestId: id } }).catch(() => undefined);
+                reject(signal?.reason instanceof Error ? signal.reason : new Error('Request interrupted'));
+                this.onIdle();
+            };
             this.pending.set(id, { resolve, reject, timer, cleanup });
             signal?.addEventListener('abort', abort, { once: true });
             void this.#write({ jsonrpc: '2.0', id, method, params }).catch((error) => { this.pending.delete(id); clearTimeout(timer); cleanup(); reject(error instanceof Error ? error : new Error(String(error))); this.onIdle(); });

package/dist/acp.js

@@ -6,6 +6,8 @@ import { AcpRpc, RpcError, objectValue } from "./acp-rpc.js";
 import { ACP_PROBE_CATALOG, nativeCurrentModel, nativeModelOptions, withoutNativeModel } from "./acp-catalog.js";
 import { ACP_LIFECYCLE, AcpModelCache, acpScope } from "./acp-models.js";
 import { AcpJournal } from "./acp-journal.js";
+import { answeredElsewhere, outcomeFor } from "./acp-permission-elsewhere.js";
+import { conversationClient } from "./conversation-commands.js";
 import { getConversation, conversationWorkspace, preparedInFlight, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
 import { seedEvent } from "./seed-phases.js";
 import { projectIdentity } from "./project-identity.js";
@@ -45,6 +47,35 @@ export function acpModelOptions(catalog) {
     });
 }
 const SIGN_IN = 'Sign in to Shardflux from your editor (or run shard acp --login).';
+const CONVERSATION_ID = /^conv_[a-z2-7]{26}$/;
+/** A remote session has no local folder to keep in step: its files stay in the conversation's computer. */
+const NO_FILES = { root: '', conflicts: () => [], reconcile: () => Promise.resolve(), settled: () => true };
+/** The last sequence number in a conversation's ACP journal: a session loaded by id follows from there (its history comes
+ *  from the agent's own session/load replay, not from the journal). */
+async function journalEnd(cell, conversationId) {
+    const path = `/home/user/.local/share/shardflux/acp/${conversationId}/journal.ndjson`;
+    let size;
+    try {
+        size = (await cell.files.stat(path)).size;
+    }
+    catch (error) {
+        if (error.status === 404)
+            return 0;
+        throw error;
+    }
+    for (let want = 64 << 10;; want *= 4) {
+        const start = Math.max(0, size - want), text = Buffer.from(await cell.files.read(path, { offset: start, length: size - start })).toString('utf8');
+        const lines = text.split('\n').filter(Boolean), last = start > 0 && lines.length < 2 ? undefined : lines.at(-1);
+        if (last !== undefined) {
+            const seq = JSON.parse(last).seq;
+            if (Number.isSafeInteger(seq))
+                return seq;
+            throw new Error('Invalid ACP journal entry');
+        }
+        if (start === 0)
+            return 0;
+    }
+}
 function supervisorOwner(workspaceId, conversationId, app, text) {
     const status = JSON.parse(text);
     if (status.conversation_id !== conversationId || status.harness !== app || !Number.isSafeInteger(status.pid) || status.pid <= 0 || !status.start)
@@ -125,7 +156,7 @@ export class ShardfluxAcp {
         if (!this.#initialized)
             throw new RpcError(-32600, 'Initialize first');
         if (method === 'session/list') {
-            const sessions = Object.values(this.#records()).filter(r => r.apiUrl === this.#ctx.apiUrl && (!params.cwd || r.folder === params.cwd));
+            const sessions = Object.values(this.#records()).filter(r => r.apiUrl === this.#ctx.apiUrl && !r.remote && (!params.cwd || r.folder === params.cwd));
             return { sessions: sessions.map(r => ({ sessionId: r.id, cwd: r.folder, updatedAt: r.updatedAt })) };
         }
         if (method === 'session/new') {
@@ -163,12 +194,14 @@ export class ShardfluxAcp {
             throw new RpcError(-32601, 'The provider probe has no conversation.');
         if (typeof params.sessionId !== 'string')
             throw new RpcError(-32602, 'A conversation is required');
-        const session = this.#session(params.sessionId, params.cwd);
+        const session = this.#session(params.sessionId, params.cwd, method);
         const { record } = session;
         if (method === 'session/close') {
             await this.#close(session);
             return {};
         }
+        if (record.remote && !record.model)
+            await this.#remoteHarness(record);
         if (method === 'session/set_model' || (method === 'session/set_config_option' && params.configId === 'model')) {
             const model = String(method === 'session/set_model' ? params.modelId : params.value), selected = parseAcpModel(model);
             if (!record.catalog && record.conversationId)
@@ -272,11 +305,17 @@ export class ShardfluxAcp {
                     record.scope = acpScope(ctx.apiUrl, view);
                     this.#cache.remember(ctx, record.folder, record.scope);
                     if (previous && JSON.stringify(previous) !== JSON.stringify(record.scope)) {
-                        record.catalog = this.#cache.read(record.scope);
-                        const app = record.catalog.claude ? 'claude' : 'codex';
-                        record.model = record.catalog[app] ? acpModel(app, nativeCurrentModel(record.catalog[app])) : '';
-                        if (session.announced)
-                            void this.#modelUpdate(session).catch(() => { });
+                        const cached = this.#cache.read(record.scope);
+                        // A newer template of the same account has no cached models yet: the models this session offered stay
+                        // until its live discovery replaces them, so an editor's first choice is not refused (0.25.0+). Before, the
+                        // list went empty for those seconds and set_model failed with "no longer available".
+                        if (Object.keys(cached).length || previous.organizationId !== record.scope.organizationId) {
+                            record.catalog = cached;
+                            const app = record.catalog.claude ? 'claude' : 'codex';
+                            record.model = record.catalog[app] ? acpModel(app, nativeCurrentModel(record.catalog[app])) : '';
+                            if (session.announced)
+                                void this.#modelUpdate(session).catch(() => { });
+                        }
                     }
                     this.#save(record);
                 },
@@ -354,9 +393,15 @@ export class ShardfluxAcp {
         this.#save(record);
         await this.#modelUpdate(session);
     }
-    #session(id, cwd) {
-        const record = this.#records()[id];
-        if (!record || record.apiUrl !== this.#ctx.apiUrl || (cwd !== undefined && (typeof cwd !== 'string' || projectIdentity(cwd).folder !== record.folder)))
+    #session(id, cwd, method) {
+        let record = this.#records()[id];
+        // Any client can open a conversation it knows by id (session/load or session/resume with a conv_ id): it relays to
+        // the conversation's own ACP session in its computer, with no folder of this computer to sync.
+        if (!record && CONVERSATION_ID.test(id) && (method === 'session/load' || method === 'session/resume')) {
+            record = { id, apiUrl: this.#ctx.apiUrl, folder: typeof cwd === 'string' ? cwd : '', conversationId: id, model: '', from_seq: 0, prompted: true, remote: true, updatedAt: new Date().toISOString() };
+            this.#save(record);
+        }
+        if (!record || record.apiUrl !== this.#ctx.apiUrl || (cwd !== undefined && (typeof cwd !== 'string' || (record.remote ? cwd !== record.folder : projectIdentity(cwd).folder !== record.folder))))
             throw new RpcError(-32000, 'Conversation not found.');
         let session = this.#sessions.get(id);
         if (!session) {
@@ -365,6 +410,17 @@ export class ShardfluxAcp {
         }
         return session;
     }
+    /** A conversation loaded by id: its harness from the API. Only an ACP conversation has a session to relay to. */
+    async #remoteHarness(record) {
+        const c = await getConversation(this.#ctx, record.conversationId);
+        if (c.route !== 'acp')
+            throw new RpcError(-32602, `This conversation runs in ${c.route === 'terminal' ? 'a terminal' : c.route}; open it there.`);
+        if (!c.harness_session_id)
+            throw new RpcError(-32602, 'This conversation has not started its session yet. Try again in a moment.');
+        record.app = c.harness;
+        record.model = acpModel(c.harness, DEFAULT_MODEL);
+        this.#save(record);
+    }
     /** True when this call started the connection (and so reconciled the project files just now). */
     async #connect(session) {
         await session.prepared;
@@ -428,20 +484,21 @@ export class ShardfluxAcp {
             const current = await getConversation(ctx, record.conversationId);
             session.conversation = await resumeConversation(ctx, current);
             session.ws = await conversationWorkspace(ctx, session.conversation);
-            rememberConversation(ctx, session.conversation, record.folder);
+            if (!record.remote)
+                rememberConversation(ctx, session.conversation, record.folder);
             mark('conversation');
         }
         await signIn;
         mark('signed_in');
         let c = session.conversation;
         const cell = session.ws.cell();
-        const menubar = ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
+        const menubar = record.remote ? Promise.resolve() : ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
         await restoreConversationBinding(ctx, c, session.ws);
         mark('binding');
         // The project files are reconciled, device approvals served and the supervisor launched side by side; the native
         // session starts once the supervisor is up, and the connection is done (the prompt goes) once the files are
         // reconciled too (0.21.1+).
-        const files = (async () => {
+        const files = record.remote ? Promise.resolve(NO_FILES) : (async () => {
             const boundary = await projectSyncBoundary({ ...ctx, signal: AbortSignal.any([ctx.signal, session.stop.signal]) }, session.ws, projectIdentity(record.folder), {
                 root: c.worktree_path, agent: record.id.replace(/^sf-/, 'acp-'), seed: false,
                 stateKey: `acp:${ctx.apiUrl}:${record.id}:${record.folder}`, ...(session.hashes ? { cache: session.hashes } : {}),
@@ -464,7 +521,7 @@ export class ShardfluxAcp {
         session.approvals ??= await serveAcpDeviceApprovals(ctx.store.dir, c.id, async (approval) => {
             const result = objectValue(await this.#client.request('session/request_permission', { sessionId: record.id,
                 toolCall: { toolCallId: approval.request_id, title: approval.summary, kind: 'execute', status: 'pending' },
-                options: [{ optionId: 'once', name: 'Allow once', kind: 'allow_once' }, ...(!approval.outside ? [{ optionId: 'always', name: 'Always for this project', kind: 'allow_always' }] : []), { optionId: 'deny', name: 'Deny', kind: 'reject_once' }] }, 0, AbortSignal.any([ctx.signal, session.stop.signal])));
+                options: [{ optionId: 'once', name: 'Allow once', kind: 'allow_once' }, ...(approval.scope === 'folder' ? [{ optionId: 'always', name: 'Always for this folder', kind: 'allow_always' }] : !approval.outside ? [{ optionId: 'always', name: 'Always for this project', kind: 'allow_always' }] : []), { optionId: 'deny', name: 'Deny', kind: 'reject_once' }] }, 0, AbortSignal.any([ctx.signal, session.stop.signal])));
             const outcome = objectValue(result.outcome);
             return outcome.outcome === 'selected' && (outcome.optionId === 'once' || outcome.optionId === 'always') ? outcome.optionId : 'deny';
         });
@@ -480,7 +537,8 @@ export class ShardfluxAcp {
         if (c.harness !== app)
             throw new Error('The guest did not claim this conversation harness.');
         session.conversation = c;
-        rememberConversation(ctx, c, record.folder);
+        if (!record.remote)
+            rememberConversation(ctx, c, record.folder);
         const owner = supervisorOwner(session.ws.id, c.id, app, statusText);
         if (owner === null)
             throw new Error('ACP supervisor identity does not match this conversation.');
@@ -488,7 +546,8 @@ export class ShardfluxAcp {
         // A cold restore can replace the journal owner without changing the VM id.
         // Its sequence starts at zero; an old cursor would drop initialize/load replies.
         if (record.workspaceId !== session.ws.id || record.owner !== owner) {
-            record.from_seq = 0;
+            // A conversation loaded by id follows its journal from now: the agent's session/load replays its history.
+            record.from_seq = record.remote ? await journalEnd(cell, c.id) : 0;
             delete record.prompt_id;
         }
         record.workspaceId = session.ws.id;
@@ -508,17 +567,28 @@ export class ShardfluxAcp {
                     mapped.update = { ...update, ...this.#configuration(record.model, native, record.catalog) };
                 }
             }
-            if (request) {
-                if (method === 'session/request_permission')
-                    transport.pause();
+            if (request && method === 'session/request_permission') {
+                // The journal relay pauses while the editor shows the prompt (a parked VM stays parked). The person can answer
+                // the same request through the API meanwhile (0.25.0+): then the editor's prompt is withdrawn and the turn goes on.
+                transport.pause();
+                const stop = new AbortController(), signal = AbortSignal.any([ctx.signal, session.stop.signal]);
                 try {
-                    return acpReferences(await this.#client.request(method, mapped, 0, AbortSignal.any([ctx.signal, session.stop.signal])), record, c.worktree_path, true);
+                    const asked = this.#client.request(method, mapped, 0, AbortSignal.any([signal, stop.signal]), true).then(result => ({ result }));
+                    const elsewhere = answeredElsewhere(conversationClient(ctx), c.id, params, Date.now(), AbortSignal.any([signal, stop.signal]))
+                        .then(p => p ? { p } : new Promise(() => undefined));
+                    const first = await Promise.race([asked, elsewhere]);
+                    if ('result' in first)
+                        return acpReferences(first.result, record, c.worktree_path, true);
+                    asked.catch(() => undefined);
+                    return outcomeFor(first.p, mapped);
                 }
                 finally {
-                    if (method === 'session/request_permission')
-                        transport.resume();
+                    stop.abort();
+                    transport.resume();
                 }
             }
+            if (request)
+                return acpReferences(await this.#client.request(method, mapped, 0, AbortSignal.any([ctx.signal, session.stop.signal])), record, c.worktree_path, true);
             await this.#client.notify(method, mapped);
         };
         session.transport = transport;
@@ -530,6 +600,9 @@ export class ShardfluxAcp {
                 throw new Error('Agent protocol version changed');
             mark('initialized');
             const nativeId = c.harness_session_id ?? record.nativeId;
+            // The history a load replays (session/update notifications) reaches the editor under its own session id.
+            if (nativeId)
+                record.nativeId = nativeId;
             const result = objectValue(await transport.rpc.request(nativeId ? 'session/load' : 'session/new', { cwd: c.worktree_path, mcpServers: [{ name: 'shardflux', command: '/usr/local/bin/sf-agent', args: ['conversation', 'mcp'], env: [{ name: 'SF_CONVERSATION_ID', value: c.id }] }], ...(nativeId ? { sessionId: nativeId } : {}) }));
             const id = result.sessionId ?? nativeId;
             mark('session');

package/dist/agent-credentials.d.ts

@@ -9,6 +9,9 @@ export declare function readAgentCredentials(opts?: CredentialSources): Promise<
     app: AgentCredentialApp;
     files: AgentCredentialFile[];
 }>>;
+/** The API's fingerprint of a login as this CLI copies it (the API hashes the same canonical file list), so a login on
+ * this computer can be told apart from the copy in the cloud without uploading it. */
+export declare function credentialFingerprint(files: readonly AgentCredentialFile[]): string;
 /** Reusable by the path launcher (L4). Returns metadata only. */
 export declare function syncAgentCredentials(cloud: Shardflux, opts?: CredentialSources): Promise<import("@shardflux/sdk").AgentCredentialMetadata[]>;
 export declare const AGENT_CREDENTIAL_HANDLERS: Record<string, Handler>;

package/dist/agent-credentials.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -55,6 +56,12 @@ export async function readAgentCredentials(opts = {}) {
         out.push({ app: 'codex', files: [file('~/.codex/auth.json', object(codex, opts.redact), opts.redact)] });
     return out;
 }
+/** The API's fingerprint of a login as this CLI copies it (the API hashes the same canonical file list), so a login on
+ * this computer can be told apart from the copy in the cloud without uploading it. */
+export function credentialFingerprint(files) {
+    const canonical = [...files].sort((a, b) => a.path.localeCompare(b.path)).map(({ path, content_b64, mode }) => ({ path, content_b64, mode }));
+    return createHash('sha256').update(JSON.stringify(canonical)).digest('hex');
+}
 /** Reusable by the path launcher (L4). Returns metadata only. */
 export async function syncAgentCredentials(cloud, opts = {}) {
     const sessions = await readAgentCredentials(opts);

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.24.0";
+export declare const CLI_VERSION = "0.25.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;