edge-ai-client-ts 1.0.0

package/dist/session/pi-rpc.js

@@ -0,0 +1,412 @@
+/**
+ * Pi RPC integration — spawns the `pi` coding-agent CLI.
+ * Mirrors `edge-client/src/session/pi_rpc.rs`.
+ *
+ * Edge-client is a transport layer: forward prompt to pi stdin, forward
+ * ALL events from pi stdout to the buffer queue, handle buffering/ACK/reconnect.
+ *
+ * ## systemd-run wrapping (Phase 4 #3)
+ * When `systemd-run --user --scope` is available AND resource limits are set,
+ * pi is spawned under a per-agent transient scope that enforces MemoryMax /
+ * CPUQuota / TasksMax via Linux cgroups.
+ *
+ * ## Session continuity (GAP-017/P5)
+ * Each agent_id gets a stable pi session ID. On respawn, the same ID is reused
+ * so pi reopens its session file (conversation context survives).
+ */
+import * as child_process from 'node:child_process';
+import * as os from 'node:os';
+import { EventEmitter } from 'node:events';
+/** True if any resource limit is set (non-zero). Mirrors Rust has_limits(). */
+export function hasLimits(config) {
+    return config.memory_max_mb > 0 || config.cpu_quota_percent > 0 || config.tasks_max > 0;
+}
+// ---------------------------------------------------------------------------
+// systemd-run probing (mirrors Rust systemd_run_available)
+// ---------------------------------------------------------------------------
+let cachedSystemdRunAvailable;
+/**
+ * Probe whether `systemd-run` is available. Caches the result (probe once
+ * per process). Returns false on non-Linux or if `systemd-run` isn't on PATH.
+ * Mirrors Rust `systemd_run_available()`.
+ */
+export function systemdRunAvailable() {
+    if (cachedSystemdRunAvailable !== undefined) {
+        return cachedSystemdRunAvailable;
+    }
+    if (process.platform !== 'linux') {
+        cachedSystemdRunAvailable = false;
+        return false;
+    }
+    try {
+        const result = child_process.spawnSync('systemd-run', ['--version'], {
+            stdio: 'ignore',
+            timeout: 5000,
+        });
+        cachedSystemdRunAvailable = result.status === 0;
+    }
+    catch {
+        cachedSystemdRunAvailable = false;
+    }
+    return cachedSystemdRunAvailable;
+}
+/**
+ * Reset the systemd-run probe cache (for testing).
+ * @internal
+ */
+export function resetSystemdRunCache() {
+    cachedSystemdRunAvailable = undefined;
+}
+// ---------------------------------------------------------------------------
+// cgroup wrapping (mirrors Rust wrap_with_cgroup)
+// ---------------------------------------------------------------------------
+/**
+ * Build the wrapped program + arg vector for a pi spawn, optionally under
+ * a per-agent `systemd-run --user --scope` transient unit.
+ *
+ * When `wrap` is false, returns `(piPath, originalArgs)` unchanged.
+ * When `wrap` is true, returns `("systemd-run", ["--user", "--scope", ...])`.
+ *
+ * Pure function — no I/O, fully unit-testable.
+ */
+export function wrapWithCgroup(piPath, originalArgs, agentId, resources, wrap) {
+    if (!wrap) {
+        return { program: piPath, args: [...originalArgs] };
+    }
+    const args = [
+        '--user',
+        '--scope',
+        `--unit=edge-pi-${agentId}`,
+    ];
+    if (resources.memory_max_mb > 0) {
+        args.push(`--property=MemoryMax=${resources.memory_max_mb}M`);
+    }
+    if (resources.cpu_quota_percent > 0) {
+        args.push(`--property=CPUQuota=${resources.cpu_quota_percent}%`);
+    }
+    if (resources.tasks_max > 0) {
+        args.push(`--property=TasksMax=${resources.tasks_max}`);
+    }
+    args.push(piPath);
+    args.push(...originalArgs);
+    return { program: 'systemd-run', args };
+}
+export class PiProcess {
+    agentId;
+    machineId;
+    emitter = new EventEmitter();
+    child = null;
+    alive = false;
+    streaming = false;
+    sessionId;
+    parseErrors = 0;
+    currentMsgId;
+    constructor(opts) {
+        this.agentId = opts.agentId;
+        this.machineId = opts.machineId;
+        this.sessionId = opts.resumeSessionId;
+    }
+    /**
+     * Spawn pi process. Mirrors Rust `PiProcess::spawn`.
+     * Returns a promise that resolves when the process is spawned.
+     */
+    async spawn(opts) {
+        const envCtx = this.buildEnvContext(opts.machineId);
+        const baseArgs = ['--mode', 'rpc', '--name', opts.agentId];
+        const resumeArgs = [];
+        if (opts.resumeSessionId !== undefined) {
+            resumeArgs.push('--session-id', opts.resumeSessionId);
+        }
+        else {
+            resumeArgs.push('--no-session');
+        }
+        resumeArgs.push('--append-system-prompt', envCtx);
+        // Decide whether to wrap under systemd-run
+        const wrap = process.platform === 'linux' && hasLimits(opts.resources) && systemdRunAvailable();
+        const { program, args: wrappedArgs } = wrapWithCgroup(opts.piPath, baseArgs, opts.agentId, opts.resources, wrap);
+        const allArgs = [...wrappedArgs, ...resumeArgs];
+        const spawnFn = opts.spawnFn ?? child_process.spawn;
+        this.child = spawnFn(program, allArgs, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        this.alive = true;
+        // Wire stdout reader
+        if (this.child.stdout !== null) {
+            this.child.stdout.setEncoding('utf8');
+            let buffer = '';
+            this.child.stdout.on('data', (chunk) => {
+                buffer += chunk;
+                const lines = buffer.split('\n');
+                buffer = lines.pop() ?? '';
+                for (const line of lines) {
+                    const raw = line.trimEnd();
+                    if (raw.length === 0)
+                        continue;
+                    this.handleStdoutLine(raw);
+                }
+            });
+        }
+        // Wire stderr reader (log only, do not forward)
+        if (this.child.stderr !== null) {
+            this.child.stderr.setEncoding('utf8');
+            this.child.stderr.on('data', (chunk) => {
+                const lines = chunk.split('\n');
+                for (const line of lines) {
+                    const trimmed = line.trimEnd();
+                    if (trimmed.length > 0) {
+                        this.emitter.emit('stderr', `[pi:${this.agentId}:stderr] ${trimmed}`);
+                    }
+                }
+            });
+        }
+        // Handle process exit
+        this.child.on('exit', () => {
+            this.alive = false;
+            this.emitter.emit('exit', this.agentId);
+        });
+        this.child.on('error', () => {
+            this.alive = false;
+        });
+    }
+    handleStdoutLine(raw) {
+        let event;
+        try {
+            event = JSON.parse(raw);
+        }
+        catch {
+            this.parseErrors++;
+            this.emitter.emit('stderr', `[pi:${this.agentId}:stdout] parse failed: ${raw.slice(0, 500)}`);
+            return;
+        }
+        // Track turn boundary
+        if (event.type === 'agent_start') {
+            this.streaming = true;
+        }
+        else if (event.type === 'agent_end') {
+            this.streaming = false;
+        }
+        // Forward event as StreamMessage
+        const msgId = this.extractEventMsgId(event) ?? this.currentMsgId ?? 'unknown';
+        const entry = {
+            msg_id: msgId,
+            machine_id: this.machineId,
+            agent_id: this.agentId,
+            type: event.type,
+            payload: event,
+            timestamp: Date.now(),
+        };
+        this.emitter.emit('event', entry);
+    }
+    extractEventMsgId(event) {
+        // Check event.payload.id first (pi RpcResponse echoes it)
+        const id = event['id'];
+        if (typeof id === 'string' && id.trim().length > 0) {
+            return id.trim();
+        }
+        // Check alternate keys
+        for (const key of ['messageId', 'requestId']) {
+            const val = event[key];
+            if (typeof val === 'string' && val.trim().length > 0) {
+                return val.trim();
+            }
+        }
+        return undefined;
+    }
+    /** Send a command to pi stdin. */
+    writeCommand(cmd) {
+        if (this.child?.stdin === null || this.child?.stdin === undefined) {
+            throw new Error('pi stdin closed');
+        }
+        const json = JSON.stringify(cmd);
+        this.child.stdin.write(json + '\n');
+        this.currentMsgId = typeof cmd.id === 'string' ? cmd.id : this.currentMsgId;
+    }
+    /** Send a prompt command. Mirrors Rust PiProcess::send_prompt. */
+    sendPrompt(msgId, message, streamingBehavior) {
+        const cmd = {
+            id: msgId,
+            type: 'prompt',
+            message,
+            ...(streamingBehavior !== undefined ? { streamingBehavior } : {}),
+        };
+        this.writeCommand(cmd);
+    }
+    /** Send an abort command. Mirrors Rust PiProcess::send_abort. */
+    sendAbort() {
+        this.writeCommand({ type: 'abort' });
+    }
+    /** Forward extension_ui_response to pi. */
+    sendExtensionUIResponse(requestId, response) {
+        const cmd = {
+            type: 'extension_ui_response',
+            id: requestId,
+            ...response,
+        };
+        if (this.child?.stdin === null || this.child?.stdin === undefined) {
+            throw new Error('pi stdin closed');
+        }
+        this.child.stdin.write(JSON.stringify(cmd) + '\n');
+    }
+    /** Switch LLM model. Mirrors Rust PiProcess::set_model. */
+    setModel(provider, modelId) {
+        this.writeCommand({
+            type: 'set_model',
+            provider,
+            modelId,
+        });
+    }
+    /** Set thinking level. Mirrors Rust PiProcess::set_thinking_level. */
+    setThinkingLevel(level) {
+        this.writeCommand({ type: 'set_thinking_level', level });
+    }
+    /** Manual context compaction. Mirrors Rust PiProcess::compact. */
+    compact() {
+        this.writeCommand({ type: 'compact' });
+    }
+    /** Get available models. Mirrors Rust PiProcess::get_available_models. */
+    getAvailableModels(id) {
+        this.writeCommand({ type: 'get_available_models', id });
+    }
+    /** Is the agent currently streaming (between agent_start and agent_end)? */
+    isStreaming() {
+        return this.streaming;
+    }
+    /** Is the pi process still alive (stdout not EOF)? GAP-003 health check. */
+    isAlive() {
+        return this.alive;
+    }
+    /** Number of unparseable stdout lines (Q4 GAP-020 health counter). */
+    getParseErrorCount() {
+        return this.parseErrors;
+    }
+    /** Captured pi session ID (GAP-017/P5). */
+    getPersistedSessionId() {
+        return this.sessionId;
+    }
+    /** Register a handler for StreamMessage events. */
+    onEvent(handler) {
+        this.emitter.on('event', handler);
+    }
+    /** Register a handler for exit events. */
+    onExit(handler) {
+        this.emitter.on('exit', handler);
+    }
+    /** Register a handler for stderr log lines. */
+    onStderr(handler) {
+        this.emitter.on('stderr', handler);
+    }
+    /**
+     * Graceful shutdown: send abort, close stdin, kill child.
+     * Mirrors Rust PiProcess::terminate.
+     */
+    terminate() {
+        try {
+            this.sendAbort();
+        }
+        catch {
+            // stdin may already be closed
+        }
+        if (this.child?.stdin !== null && this.child?.stdin !== undefined) {
+            this.child.stdin.end();
+        }
+        if (this.child !== null) {
+            try {
+                this.child.kill();
+            }
+            catch {
+                // process may already be dead
+            }
+        }
+        this.alive = false;
+    }
+    buildEnvContext(machineId) {
+        const platform = os.platform();
+        const user = process.env.USER ?? process.env.USERNAME ?? 'unknown';
+        const cwd = process.cwd();
+        return (`[Edge Client Context]\n` +
+            `Machine ID: ${machineId}\n` +
+            `Operating System: ${platform}\n` +
+            `User: ${user}\n` +
+            `Working Directory: ${cwd}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// RpcCommand factories (mirrors Rust RpcCommand methods)
+// ---------------------------------------------------------------------------
+export function promptCommand(id, message) {
+    return { id, type: 'prompt', message };
+}
+export function promptWithStreamingCommand(id, message, behavior) {
+    return { id, type: 'prompt', message, streamingBehavior: behavior };
+}
+export function abortCommand() {
+    return { type: 'abort' };
+}
+export function setModelCommand(provider, modelId) {
+    return { type: 'set_model', provider, modelId };
+}
+export function setThinkingLevelCommand(level) {
+    return { type: 'set_thinking_level', level };
+}
+export function compactCommand() {
+    return { type: 'compact' };
+}
+export function getAvailableModelsCommand(id) {
+    return { type: 'get_available_models', id };
+}
+// ---------------------------------------------------------------------------
+// Pure helpers for testing (mirrors Rust pure functions)
+// ---------------------------------------------------------------------------
+/**
+ * Generate a pi-compatible session ID (RFC 4122 v4 UUID).
+ * Mirrors Rust `new_session_id()`.
+ */
+export function newPiSessionId() {
+    // Use crypto.randomUUID() for UUIDv4
+    return crypto.randomUUID();
+}
+/**
+ * Extract pi sessionId from event payload.
+ * Mirrors Rust `extract_session_id`.
+ */
+export function extractSessionId(eventType, payload) {
+    // get_state response → data.sessionId (authoritative source)
+    if (eventType === 'response') {
+        const command = payload['command'];
+        if (command === 'get_state') {
+            const data = payload['data'];
+            if (typeof data === 'object' && data !== null) {
+                const sessionId = data['sessionId'];
+                if (typeof sessionId === 'string' && sessionId.length > 0) {
+                    return sessionId;
+                }
+            }
+        }
+    }
+    // Defensive: check common keys
+    for (const key of ['sessionId', 'session_id']) {
+        const val = payload[key];
+        if (typeof val === 'string' && val.length > 0) {
+            return val;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve msg_id for a forwarded event. Mirrors Rust `event_msg_id`.
+ * Prefers pi's own id in payload, falls back to currentMsgId.
+ */
+export function eventMsgId(payload, fallback) {
+    const id = payload['id'];
+    if (typeof id === 'string' && id.trim().length > 0) {
+        return id.trim();
+    }
+    for (const key of ['messageId', 'message_id', 'requestId', 'request_id']) {
+        const val = payload[key];
+        if (typeof val === 'string' && val.trim().length > 0) {
+            return val.trim();
+        }
+    }
+    const trimmed = fallback.trim();
+    return trimmed.length > 0 ? trimmed : 'unknown';
+}

package/dist/session/sftp.d.ts

@@ -0,0 +1,64 @@
+/**
+ * SFTP-over-frame — structured file RPC over the shell binary channel.
+ * Mirrors `edge-client/src/session/sftp.rs`.
+ *
+ * A frame type `FrameType::Sftp = 6` carries a JSON request/response payload
+ * on the existing 17-byte shell frame. The relay is a dumb byte-pump:
+ * it forwards Sftp frames verbatim; ALL filesystem logic lives here.
+ * Under the hood this is JSON RPC over `node:fs` — we do NOT shell out
+ * to `sftp` (the edge-client already runs as the Standard User with full
+ * filesystem access).
+ *
+ * ## Protocol
+ * Request (browser → edge, Sftp frame payload = UTF-8 JSON):
+ * ```json
+ * {"op":"list|read|write|delete|stat","path":"/abs/path"[,"content":"..."],"reqId":1}
+ * ```
+ * Response (edge → browser):
+ * ```json
+ * {"reqId":1,"ok":true,"data":{...}}
+ * {"reqId":1,"ok":false,"error":"..."}
+ * ```
+ *
+ * ## P1-a / R-MED-2 — per-session SFTP chroot
+ * When the relay sends an `SftpRoot` control frame (frame type 7) on shell
+ * session open, the edge stores the supplied root path in a per-session map.
+ * Every subsequent Sftp op for that session is resolved under the root.
+ * A `null` root (or absent) means "no chroot" (default).
+ *
+ * ## E-H2 — max file size for read/write ops
+ * Files larger than 32 MiB are refused to prevent browser OOM.
+ */
+interface SftpRequest {
+    op: string;
+    path: string;
+    content?: string;
+    reqId?: number;
+}
+interface SftpResponse {
+    reqId: number;
+    ok: boolean;
+    data?: Record<string, unknown>;
+    error?: string;
+}
+declare function setSessionRoot(sessionId: string, payload: Buffer): void;
+declare function resolveSftpPath(sessionId: string, userPath: string): string;
+declare function dispatch(sessionId: string, req: SftpRequest): SftpResponse;
+export type FrameHandler = (sessionId: string, frameType: number, payload: Buffer) => void;
+export declare class SftpForwarder {
+    private readonly emitter;
+    /**
+     * Handle an inbound Sftp frame. Mirrors Rust `handle_sftp_request`.
+     * Parses the JSON request, dispatches the file op, and emits the response
+     * frame (to be sent back to the relay/browser).
+     */
+    handleFrame(sessionId: string, frameType: number, payload: Buffer): void;
+    /**
+     * Register a handler for outbound Sftp response frames.
+     * The handler receives (sessionId, frameType, payloadBytes).
+     */
+    onFrame(handler: FrameHandler): void;
+}
+/** Clear all session roots (for tests only). */
+export declare function clearSessionRoots(): void;
+export { setSessionRoot, resolveSftpPath, dispatch };