@shardflux/cli 0.13.5 → 0.14.0

package/dist/acp-journal.js

@@ -0,0 +1,232 @@
+import { randomUUID } from 'node:crypto';
+import { StringDecoder } from 'node:string_decoder';
+import { AcpRpc } from "./acp-rpc.js";
+// InputACP's private, same-uid socket receipt protocol. Stdin avoids Linux's 128 KiB per-argument limit.
+export const ACP_INPUT_SCRIPT = `import json, os, socket, sys
+payload = sys.stdin.buffer.readline((2 << 20) + 1024)
+if not payload.endswith(b'\\n') or len(json.dumps(json.loads(payload)['message'], separators=(',', ':'), ensure_ascii=False).encode()) > 2 << 20:
+    raise ValueError('ACP input exceeds 2 MiB')
+folder = os.open(sys.argv[1], os.O_RDONLY)
+try:
+    with socket.socket(socket.AF_UNIX) as peer:
+        peer.settimeout(10)
+        address = os.path.join(sys.argv[1], 'control.sock')
+        if len(address.encode()) >= 108: address = '/proc/self/fd/%d/control.sock' % folder
+        peer.connect(address)
+        peer.sendall(payload)
+        response = peer.makefile('rb').readline(65536)
+        result = json.loads(response)
+        if result.get('accepted') is not True: raise ValueError(result.get('error', 'ACP input was not acknowledged'))
+        sys.stdout.buffer.write(response)
+finally:
+    os.close(folder)
+`;
+/** Replay is finite; a live follower exists only while a turn/RPC needs output. Native supervision is CVB's. */
+export class AcpJournal {
+    rpc;
+    #cell;
+    #conversation;
+    #cwd;
+    #cursor;
+    #save;
+    #controller = new AbortController();
+    #signal;
+    #initial;
+    #ready = false;
+    #reading;
+    #reader;
+    #follower;
+    #writing = Promise.resolve();
+    #paused = 0;
+    constructor(cell, conversation, _harness, cwd, cursor, save, signal) {
+        if (!/^[a-zA-Z0-9_-]{1,96}$/.test(conversation))
+            throw new Error('Invalid ACP conversation identity');
+        this.#cell = cell;
+        this.#conversation = conversation;
+        this.#cwd = cwd;
+        this.#cursor = cursor;
+        this.#save = save;
+        this.#signal = AbortSignal.any([signal, this.#controller.signal]);
+        this.rpc = new AcpRpc(message => {
+            const encoded = JSON.stringify(message);
+            if (Buffer.byteLength(encoded) > 2 << 20)
+                return Promise.reject(new Error('ACP input exceeds 2 MiB'));
+            const inputId = randomUUID();
+            if (message.method === 'session/prompt' && message.id != null) {
+                this.#cursor.prompt_id = message.id;
+                this.#save();
+            }
+            const run = this.#writing.then(async () => {
+                await this.#deliver(inputId, encoded);
+                this.#follow();
+            });
+            this.#writing = run.catch(error => { this.rpc.close(error instanceof Error ? error : new Error(String(error))); });
+            return run;
+        });
+        this.rpc.onIdle = () => { if (!this.#wanted())
+            this.#reader?.abort(); };
+    }
+    #wanted() { return !this.#signal.aborted && !this.rpc.closed && this.#paused === 0 && (this.rpc.busy || this.#cursor.prompt_id !== undefined); }
+    async #deliver(inputId, message) {
+        const dir = `/home/user/.local/share/shardflux/acp/${this.#conversation}`;
+        const payload = Buffer.from(`{"mode":"input","input_id":${JSON.stringify(inputId)},"message":${message}}\n`);
+        const session = await this.#cell.exec.start({ argv: ['python3', '-c', ACP_INPUT_SCRIPT, dir], cwd: this.#cwd, stdin_open: true, timeout_ms: 15_000 }, this.#signal);
+        let offset = 0, stdout = '';
+        try {
+            while (offset < payload.length) {
+                const bytes = payload.subarray(offset, offset + 65536);
+                const ack = await this.#cell.exec.input(session.session_id, bytes, { offset, close: offset + bytes.length === payload.length, signal: this.#signal });
+                const accepted = ack.offset - offset;
+                if (!Number.isSafeInteger(accepted) || accepted <= 0 || accepted > bytes.length || (ack.closed && ack.offset !== payload.length))
+                    throw new Error('Invalid ACP input acknowledgement');
+                offset = ack.offset;
+            }
+            let exit;
+            for await (const event of await this.#cell.exec.output(session.session_id, { follow: true, signal: this.#signal })) {
+                if (event.type === 'error')
+                    throw new Error(event.error?.error.message ?? 'ACP input failed');
+                if (event.type === 'exit')
+                    exit = event.session?.exit_code;
+                if (event.type === 'output' && event.stream === 'stdout' && event.data)
+                    stdout += Buffer.from(event.data, 'base64').toString();
+                if (stdout.length > 65536)
+                    throw new Error('Invalid ACP input receipt');
+            }
+            if (exit !== 0 || JSON.parse(stdout).accepted !== true)
+                throw new Error('ACP delivery is unverified; load this session before continuing.');
+        }
+        finally {
+            await this.#cell.exec.cancel(session.session_id, 0).catch(() => undefined);
+        }
+        // Never resend an uncertain mutation. Its stable input identity is fenced by CVB before provider stdin.
+    }
+    start() {
+        this.#initial ??= this.#replay().then(() => { this.#ready = true; this.#follow(); }).catch(error => { this.rpc.close(error instanceof Error ? error : new Error(String(error))); throw error; });
+        return this.#initial;
+    }
+    pause() { this.#paused++; this.#reader?.abort(); void this.#detach(); }
+    resume() { this.#paused = Math.max(0, this.#paused - 1); this.#follow(); }
+    async #entry(line) {
+        if (!line.trim())
+            return;
+        const entry = JSON.parse(line);
+        if (entry.error)
+            throw new Error(entry.error);
+        if (!Number.isSafeInteger(entry.seq) || entry.seq < 1)
+            throw new Error('Invalid ACP journal entry');
+        if (entry.seq <= this.#cursor.from_seq)
+            return;
+        if (entry.seq !== this.#cursor.from_seq + 1)
+            throw new Error('ACP journal has a sequence gap');
+        if (entry.message) {
+            if (entry.message.method === undefined && entry.message.id === this.#cursor.prompt_id) {
+                delete this.#cursor.prompt_id;
+            }
+            this.rpc.feed(Buffer.from(JSON.stringify(entry.message) + '\n'));
+            await this.rpc.drain();
+        }
+        this.#cursor.from_seq = entry.seq;
+        this.#save();
+        if (entry.ended)
+            this.rpc.close(new Error('Native ACP session ended'));
+    }
+    async #replay() {
+        const path = `/home/user/.local/share/shardflux/acp/${this.#conversation}/journal.ndjson`;
+        this.#signal.throwIfAborted();
+        const snapshot = await this.#cell.files.stat(path);
+        const decoder = new StringDecoder('utf8');
+        let tail = '';
+        for (let offset = 0; offset < snapshot.size;) {
+            this.#signal.throwIfAborted();
+            const bytes = await this.#cell.files.read(path, { offset, length: Math.min(1 << 20, snapshot.size - offset) });
+            if (!bytes.length)
+                throw new Error('ACP journal changed during replay');
+            offset += bytes.length;
+            tail += decoder.write(bytes);
+            let newline;
+            while ((newline = tail.indexOf('\n')) >= 0) {
+                const line = tail.slice(0, newline);
+                tail = tail.slice(newline + 1);
+                await this.#entry(line);
+            }
+            if (Buffer.byteLength(tail) > 4 << 20)
+                throw new Error('ACP journal frame exceeds 4 MiB');
+        }
+        // An append can straddle the snapshot cut. The follower replays that whole frame from the saved sequence.
+        decoder.end();
+    }
+    #follow() {
+        if (!this.#ready || this.#reading || !this.#wanted())
+            return;
+        const reader = new AbortController();
+        this.#reader = reader;
+        this.#reading = this.#read(reader).finally(() => { this.#reading = undefined; if (this.#reader === reader)
+            this.#reader = undefined; this.#follow(); });
+    }
+    async #read(reader) {
+        const signal = AbortSignal.any([this.#signal, reader.signal]);
+        try {
+            let failures = 0;
+            while (this.#wanted() && !signal.aborted) {
+                const decoder = new StringDecoder('utf8');
+                let tail = '', offset = 0;
+                try {
+                    const session = await this.#cell.exec.start({ argv: ['sf-agent', 'acp', 'attach', '--conversation', this.#conversation, '--from-seq', String(this.#cursor.from_seq), '--follow'], cwd: this.#cwd, timeout_ms: 0 }, signal);
+                    this.#follower = session.session_id;
+                    for await (const event of await this.#cell.exec.output(session.session_id, { follow: true, signal })) {
+                        if (event.type === 'error')
+                            throw new Error(event.error?.error.message ?? 'ACP journal failed');
+                        if (event.type === 'exit')
+                            throw new Error('ACP journal detached');
+                        if (event.type !== 'output' || event.stream !== 'stdout' || !event.data)
+                            continue;
+                        const bytes = Buffer.from(event.data, 'base64'), at = event.offset ?? offset;
+                        if (at > offset)
+                            throw new Error('ACP follower output has a byte gap');
+                        const fresh = bytes.subarray(Math.max(0, offset - at));
+                        offset = Math.max(offset, at + bytes.length);
+                        tail += decoder.write(fresh);
+                        for (let newline; (newline = tail.indexOf('\n')) >= 0;) {
+                            const line = tail.slice(0, newline);
+                            tail = tail.slice(newline + 1);
+                            await this.#entry(line);
+                            failures = 0;
+                        }
+                        if (Buffer.byteLength(tail) > 4 << 20)
+                            throw new Error('ACP journal frame exceeds 4 MiB');
+                        if (!this.#wanted())
+                            return;
+                    }
+                    if (!signal.aborted)
+                        throw new Error('ACP journal connection ended');
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        break;
+                    if (++failures > 3)
+                        throw error;
+                }
+                finally {
+                    await this.#detach();
+                }
+            }
+        }
+        catch (error) {
+            this.rpc.close(error instanceof Error ? error : new Error(String(error)));
+        }
+    }
+    async #detach() {
+        const follower = this.#follower;
+        this.#follower = undefined;
+        if (follower)
+            await this.#cell.exec.cancel(follower, 0).catch(() => undefined);
+    }
+    async close() {
+        this.#controller.abort();
+        this.rpc.close();
+        await this.#writing;
+        await this.#initial?.catch(() => undefined);
+        await this.#reading;
+        await this.#detach();
+    }
+}

package/dist/acp-rpc.d.ts

@@ -0,0 +1,41 @@
+export type RpcId = string | number;
+export type ObjectValue = Record<string, unknown>;
+export interface RpcMessage extends ObjectValue {
+    jsonrpc: '2.0';
+    id?: RpcId | null;
+    method?: string;
+    params?: ObjectValue;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export declare class RpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+export declare const objectValue: (value: unknown) => ObjectValue;
+/** Each peer owns its request namespace; adapter IDs never escape to another conversation. */
+export declare class AcpRpc {
+    #private;
+    readonly pending: Map<RpcId, {
+        resolve(value: unknown): void;
+        reject(error: unknown): void;
+        timer?: ReturnType<typeof setTimeout>;
+        cleanup?(): void;
+    }>;
+    handler: (method: string, params: ObjectValue, request: boolean) => Promise<unknown>;
+    onIdle: () => void;
+    onResponse: (message: RpcMessage) => void;
+    constructor(write: (message: RpcMessage) => Promise<void>);
+    get busy(): boolean;
+    get closed(): boolean;
+    feed(bytes: Uint8Array): void;
+    request(method: string, params: ObjectValue, timeoutMs?: number, signal?: AbortSignal): Promise<unknown>;
+    notify(method: string, params: ObjectValue): Promise<void>;
+    close(error?: Error): void;
+    drain(): Promise<void>;
+}

package/dist/acp-rpc.js

@@ -0,0 +1,115 @@
+import { StringDecoder } from 'node:string_decoder';
+import { randomUUID } from 'node:crypto';
+export class RpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) { super(message); this.code = code; this.data = data; }
+}
+export const objectValue = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+/** Each peer owns its request namespace; adapter IDs never escape to another conversation. */
+export class AcpRpc {
+    pending = new Map();
+    handler = () => Promise.reject(new RpcError(-32601, 'Method not found'));
+    onIdle = () => { };
+    onResponse = () => { };
+    #write;
+    #decoder = new StringDecoder('utf8');
+    #buffer = '';
+    #next = 0;
+    #namespace = randomUUID();
+    #closed;
+    #inbound = 0;
+    #receiving = new Set();
+    constructor(write) { this.#write = write; }
+    get busy() { return this.pending.size > 0 || this.#inbound > 0; }
+    get closed() { return this.#closed !== undefined; }
+    feed(bytes) {
+        this.#buffer += this.#decoder.write(Buffer.from(bytes));
+        let newline;
+        while ((newline = this.#buffer.indexOf('\n')) >= 0) {
+            const line = this.#buffer.slice(0, newline);
+            this.#buffer = this.#buffer.slice(newline + 1);
+            if (Buffer.byteLength(line) > 16 << 20)
+                throw new RpcError(-32700, 'Message exceeds 16 MiB');
+            if (!line.trim())
+                continue;
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch {
+                throw new RpcError(-32700, 'Invalid JSON');
+            }
+            const message = objectValue(value);
+            if (message.jsonrpc !== '2.0')
+                throw new RpcError(-32600, 'Invalid JSON-RPC message');
+            const receiving = this.#receive(message).catch(error => this.close(error instanceof Error ? error : new Error(String(error))));
+            this.#receiving.add(receiving);
+            void receiving.finally(() => this.#receiving.delete(receiving));
+        }
+        if (Buffer.byteLength(this.#buffer) > 16 << 20)
+            throw new RpcError(-32700, 'Message exceeds 16 MiB');
+    }
+    async #receive(message) {
+        if (message.method !== undefined) {
+            const request = message.id !== undefined;
+            this.#inbound++;
+            try {
+                const result = await this.handler(message.method, message.params ?? {}, request);
+                if (request)
+                    await this.#write({ jsonrpc: '2.0', id: message.id, result: result ?? {} });
+            }
+            catch (error) {
+                if (request) {
+                    const e = error instanceof RpcError ? error : new RpcError(-32603, error instanceof Error ? error.message : String(error));
+                    await this.#write({ jsonrpc: '2.0', id: message.id, error: { code: e.code, message: e.message, ...(e.data === undefined ? {} : { data: e.data }) } });
+                }
+            }
+            finally {
+                this.#inbound--;
+                this.onIdle();
+            }
+            return;
+        }
+        if (message.id === undefined || message.id === null)
+            return;
+        this.onResponse(message);
+        const pending = this.pending.get(message.id);
+        if (!pending)
+            return;
+        this.pending.delete(message.id);
+        clearTimeout(pending.timer);
+        pending.cleanup?.();
+        if (message.error)
+            pending.reject(new RpcError(message.error.code, message.error.message, message.error.data));
+        else
+            pending.resolve(message.result);
+        this.onIdle();
+    }
+    request(method, params, timeoutMs = 120_000, signal) {
+        if (this.#closed)
+            return Promise.reject(this.#closed);
+        if (signal?.aborted)
+            return Promise.reject(signal.reason instanceof Error ? signal.reason : new Error('Request interrupted'));
+        const id = `shard-${this.#namespace}-${++this.#next}`;
+        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(); };
+            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(); });
+        });
+    }
+    notify(method, params) { return this.#write({ jsonrpc: '2.0', method, params }); }
+    close(error = new Error('Connection closed')) {
+        this.#closed = error;
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.cleanup?.();
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+    async drain() { await Promise.all([...this.#receiving]); }
+}

package/dist/acp.d.ts

@@ -0,0 +1,27 @@
+import type { Ctx } from './commands.js';
+import { AcpRpc, RpcError } from './acp-rpc.js';
+import type { ObjectValue } from './acp-rpc.js';
+type App = 'claude' | 'codex';
+type ErrorMapper = (error: unknown) => RpcError;
+export declare function acpModel(app: App, id: string): string;
+export declare function parseAcpModel(value: unknown): {
+    app: App;
+    id: string;
+};
+export declare function acpModelOptions(catalog: Record<App, ObjectValue>): ObjectValue[];
+export declare function acpError(error: unknown): RpcError;
+/** Rewrite structural session/file references, never the agent's prose or command output. */
+export declare function acpReferences(value: unknown, record: {
+    id: string;
+    nativeId?: string;
+    folder: string;
+}, root: string, inbound?: boolean): unknown;
+/** One provider, two harness catalogs. The model selection determines the VM's native harness. */
+export declare class ShardfluxAcp {
+    #private;
+    constructor(ctx: Ctx, client: AcpRpc, errors?: ErrorMapper);
+    handle(method: string, params: ObjectValue, request: boolean): Promise<unknown>;
+    close(): Promise<void>;
+}
+export declare function runAcp(ctx: Ctx, errors?: ErrorMapper): Promise<number>;
+export {};