edge-ai-client-ts 1.0.0

package/dist/session/persistence.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Session persistence — mirrors `edge-client/src/session/persistence.rs`.
+ *
+ * B5 — PROCESS-restart persistence for the `(agent_id → pi session_id)` map.
+ *
+ * `SessionManager` previously kept this map in-memory only; when the edge-client
+ * daemon restarted (systemd/crash/deploy) the map was lost and pi was respawned
+ * fresh (history gone), even though pi's session files on disk are intact.
+ * We persist the map to `~/.config/edge-ai-agent/sessions.json` so a restarted
+ * edge-client can resume the same pi session via `--session-id`.
+ *
+ * ## Design
+ * - The inner map is guarded by a mutex.
+ * - `getOrInit` for an EXISTING agent_id is a fast map lookup (no factory, no I/O).
+ * - `save` runs only when a NEW id is assigned. The snapshot is cloned under
+ *   the lock and the atomic write happens outside the lock so concurrent lookups
+ *   are not stalled on I/O.
+ *
+ * ## Atomic write
+ * Write to `<path>.tmp` then rename over `<path>` (same-dir rename is atomic
+ * on POSIX and on Windows since Node 14+).
+ *
+ * ## Encrypted at rest (optional)
+ * Uses AES-256-GCM via `src/crypto/aes-gcm.ts` with the buffer_key from
+ * `loadBufferKey(settings)` when provided.
+ */
+/** Session persistence options. */
+export interface PersistenceOptions {
+    /** Path to the sessions.json file. Defaults to `<configDir>/sessions.json`. */
+    readonly filePath?: string;
+    /** If true, persist to disk. If false, in-memory only (for tests). */
+    readonly persist?: boolean;
+    /** AES-256-GCM key for encryption at rest (optional). */
+    readonly encryptionKey?: Uint8Array;
+}
+export declare class SessionIdStore {
+    private readonly map;
+    private readonly filePath;
+    private readonly persist;
+    private readonly encryptionKey;
+    constructor(opts?: PersistenceOptions);
+    /**
+     * Get the session ID for `agent_id`, or initialize via `factory` + persist.
+     *
+     * Returns the existing ID if present (fast path: one map lookup, no factory).
+     * Otherwise calls `factory()` (which generates a UUID), inserts it, and
+     * persists to disk (best-effort).
+     *
+     * Mirrors Rust `SessionIdStore::get_or_init`.
+     */
+    getOrInit(agentId: string, factory: () => string): Promise<string>;
+    /**
+     * Atomic write to disk. Best-effort; logs a warning on error and never throws.
+     * No-op for the in-memory variant.
+     *
+     * Mirrors Rust `SessionIdStore::save`.
+     */
+    save(): Promise<void>;
+    /**
+     * Load the map from disk. Missing/corrupt file → empty map.
+     * Mirrors Rust `SessionIdStore::load`.
+     */
+    private loadFromDisk;
+    /**
+     * Check if an agent_id has a stored session ID.
+     */
+    has(agentId: string): boolean;
+    /**
+     * Get the stored session ID for an agent_id, or undefined.
+     */
+    get(agentId: string): string | undefined;
+    /**
+     * Get the number of stored sessions.
+     */
+    size(): number;
+    /**
+     * Create an in-memory only store (for tests). No file I/O.
+     */
+    static inMemory(): SessionIdStore;
+}
+/** Session state to persist. Mirrors Rust session persistence fields. */
+export interface SessionState {
+    /** Working directory for the session. */
+    readonly cwd: string;
+    /** Environment variables for the session. */
+    readonly env: Record<string, string>;
+    /** Agent ID associated with this session. */
+    readonly agentId: string;
+    /** Timestamp when the session was opened (Unix epoch ms). */
+    readonly openedAt: number;
+}
+/**
+ * Persist full session state to disk (encrypted at rest).
+ * Mirrors Rust persistence.rs session state persistence.
+ *
+ * Uses AES-256-GCM encryption when a key is provided.
+ */
+export declare function persistSessionState(state: SessionState, filePath: string, encryptionKey?: Uint8Array): void;
+/**
+ * Load session state from disk (decrypted if key provided).
+ * Returns undefined if the file doesn't exist or is corrupt.
+ */
+export declare function loadSessionState(filePath: string, encryptionKey?: Uint8Array): SessionState | undefined;

package/dist/session/persistence.js

@@ -0,0 +1,194 @@
+/**
+ * Session persistence — mirrors `edge-client/src/session/persistence.rs`.
+ *
+ * B5 — PROCESS-restart persistence for the `(agent_id → pi session_id)` map.
+ *
+ * `SessionManager` previously kept this map in-memory only; when the edge-client
+ * daemon restarted (systemd/crash/deploy) the map was lost and pi was respawned
+ * fresh (history gone), even though pi's session files on disk are intact.
+ * We persist the map to `~/.config/edge-ai-agent/sessions.json` so a restarted
+ * edge-client can resume the same pi session via `--session-id`.
+ *
+ * ## Design
+ * - The inner map is guarded by a mutex.
+ * - `getOrInit` for an EXISTING agent_id is a fast map lookup (no factory, no I/O).
+ * - `save` runs only when a NEW id is assigned. The snapshot is cloned under
+ *   the lock and the atomic write happens outside the lock so concurrent lookups
+ *   are not stalled on I/O.
+ *
+ * ## Atomic write
+ * Write to `<path>.tmp` then rename over `<path>` (same-dir rename is atomic
+ * on POSIX and on Windows since Node 14+).
+ *
+ * ## Encrypted at rest (optional)
+ * Uses AES-256-GCM via `src/crypto/aes-gcm.ts` with the buffer_key from
+ * `loadBufferKey(settings)` when provided.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { configDir, atomicWriteFile } from '../config/settings.js';
+// ---------------------------------------------------------------------------
+// SessionIdStore
+// ---------------------------------------------------------------------------
+export class SessionIdStore {
+    map = new Map();
+    filePath;
+    persist;
+    encryptionKey;
+    constructor(opts) {
+        this.persist = opts?.persist ?? true;
+        this.encryptionKey = opts?.encryptionKey;
+        if (this.persist) {
+            this.filePath = opts?.filePath ?? path.join(configDir(), 'sessions.json');
+            this.loadFromDisk();
+        }
+        else {
+            this.filePath = '';
+        }
+    }
+    /**
+     * Get the session ID for `agent_id`, or initialize via `factory` + persist.
+     *
+     * Returns the existing ID if present (fast path: one map lookup, no factory).
+     * Otherwise calls `factory()` (which generates a UUID), inserts it, and
+     * persists to disk (best-effort).
+     *
+     * Mirrors Rust `SessionIdStore::get_or_init`.
+     */
+    async getOrInit(agentId, factory) {
+        // Fast path: existing agent_id
+        const existing = this.map.get(agentId);
+        if (existing !== undefined) {
+            return existing;
+        }
+        // Slow path: new agent_id
+        const newId = factory();
+        let isNew = false;
+        // Double-check under a conceptual lock (JS is single-threaded for sync code)
+        const current = this.map.get(agentId);
+        if (current !== undefined) {
+            // A concurrent caller inserted first; reuse theirs
+            return current;
+        }
+        this.map.set(agentId, newId);
+        isNew = true;
+        // Only persist when we actually added a new id
+        if (isNew) {
+            await this.save();
+        }
+        return newId;
+    }
+    /**
+     * Atomic write to disk. Best-effort; logs a warning on error and never throws.
+     * No-op for the in-memory variant.
+     *
+     * Mirrors Rust `SessionIdStore::save`.
+     */
+    async save() {
+        if (!this.persist)
+            return;
+        // Snapshot under the lock (in JS, just clone the map)
+        const snapshot = {};
+        for (const [k, v] of this.map) {
+            snapshot[k] = v;
+        }
+        try {
+            const content = JSON.stringify(snapshot, null, 2);
+            atomicWriteFile(this.filePath, content);
+        }
+        catch (e) {
+            // Best-effort — log warning, never panic
+            console.warn(`[persistence] failed to persist sessions.json: ${String(e)}`);
+        }
+    }
+    /**
+     * Load the map from disk. Missing/corrupt file → empty map.
+     * Mirrors Rust `SessionIdStore::load`.
+     */
+    loadFromDisk() {
+        try {
+            const content = fs.readFileSync(this.filePath, 'utf8');
+            const parsed = JSON.parse(content);
+            for (const [k, v] of Object.entries(parsed)) {
+                if (typeof v === 'string') {
+                    this.map.set(k, v);
+                }
+            }
+        }
+        catch (e) {
+            const err = e;
+            if (err.code === 'ENOENT') {
+                // First run / no persistence yet — normal, not a warning
+                return;
+            }
+            // Corrupt or unreadable file — start with empty map
+            console.warn(`[persistence] sessions.json load failed: ${String(e)}; starting empty`);
+        }
+    }
+    /**
+     * Check if an agent_id has a stored session ID.
+     */
+    has(agentId) {
+        return this.map.has(agentId);
+    }
+    /**
+     * Get the stored session ID for an agent_id, or undefined.
+     */
+    get(agentId) {
+        return this.map.get(agentId);
+    }
+    /**
+     * Get the number of stored sessions.
+     */
+    size() {
+        return this.map.size;
+    }
+    /**
+     * Create an in-memory only store (for tests). No file I/O.
+     */
+    static inMemory() {
+        return new SessionIdStore({ persist: false });
+    }
+}
+/**
+ * Persist full session state to disk (encrypted at rest).
+ * Mirrors Rust persistence.rs session state persistence.
+ *
+ * Uses AES-256-GCM encryption when a key is provided.
+ */
+export function persistSessionState(state, filePath, encryptionKey) {
+    const plaintext = JSON.stringify(state);
+    if (encryptionKey !== undefined) {
+        // Encrypt at rest using AES-256-GCM
+        // Dynamic import to avoid circular dependency
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { encrypt } = require('../crypto/aes-gcm.js');
+        const encrypted = encrypt(encryptionKey, plaintext);
+        atomicWriteFile(filePath, encrypted);
+    }
+    else {
+        atomicWriteFile(filePath, plaintext);
+    }
+}
+/**
+ * Load session state from disk (decrypted if key provided).
+ * Returns undefined if the file doesn't exist or is corrupt.
+ */
+export function loadSessionState(filePath, encryptionKey) {
+    try {
+        const data = fs.readFileSync(filePath);
+        if (encryptionKey !== undefined) {
+            // Decrypt
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { decrypt } = require('../crypto/aes-gcm.js');
+            const result = decrypt(Buffer.from(data), encryptionKey);
+            return JSON.parse(result.plaintext);
+        }
+        // Plaintext JSON
+        const content = data.toString('utf8');
+        return JSON.parse(content);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/session/pi-rpc.d.ts

@@ -0,0 +1,164 @@
+/**
+ * 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';
+/** RPC command sent to pi stdin. Mirrors Rust RpcCommand. */
+export interface RpcCommand {
+    /** Correlation id (= msg_id of cloud command). */
+    readonly id?: string;
+    /** Command type: "prompt" | "abort" | "set_model" | etc. */
+    readonly type: string;
+    /** Prompt message. */
+    readonly message?: string;
+    /** Streaming behavior: "steer" | "followUp". */
+    readonly streamingBehavior?: string;
+    /** Additional fields (provider, modelId, level, etc.). */
+    readonly [key: string]: unknown;
+}
+/** Event received from pi stdout. Mirrors Rust PiEvent. */
+export interface PiEvent {
+    /** Event type: "agent_start" | "agent_end" | "tool_execution_start" | etc. */
+    readonly type: string;
+    /** All other fields from pi (flatten passthrough). */
+    readonly [key: string]: unknown;
+}
+/** StreamMessage structure for forwarding pi events. Mirrors Rust StreamMessage. */
+export interface StreamMessage {
+    readonly msg_id: string;
+    readonly machine_id: string;
+    readonly agent_id: string;
+    readonly type: string;
+    readonly payload: unknown;
+    readonly timestamp: number;
+}
+export interface ResourcesConfig {
+    readonly memory_max_mb: number;
+    readonly cpu_quota_percent: number;
+    readonly tasks_max: number;
+}
+/** True if any resource limit is set (non-zero). Mirrors Rust has_limits(). */
+export declare function hasLimits(config: ResourcesConfig): boolean;
+/**
+ * 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 declare function systemdRunAvailable(): boolean;
+/**
+ * Reset the systemd-run probe cache (for testing).
+ * @internal
+ */
+export declare function resetSystemdRunCache(): void;
+/**
+ * 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 declare function wrapWithCgroup(piPath: string, originalArgs: readonly string[], agentId: string, resources: ResourcesConfig, wrap: boolean): {
+    program: string;
+    args: string[];
+};
+export interface PiProcessOptions {
+    readonly agentId: string;
+    readonly piPath: string;
+    readonly machineId: string;
+    readonly resources: ResourcesConfig;
+    /** Stable pi session ID for GAP-017/P5 session continuity. */
+    readonly resumeSessionId?: string;
+    /** Path override for spawning (default: child_process.spawn). */
+    readonly spawnFn?: typeof child_process.spawn;
+}
+export declare class PiProcess {
+    private readonly agentId;
+    private readonly machineId;
+    private readonly emitter;
+    private child;
+    private alive;
+    private streaming;
+    private readonly sessionId;
+    private parseErrors;
+    private currentMsgId;
+    constructor(opts: PiProcessOptions);
+    /**
+     * Spawn pi process. Mirrors Rust `PiProcess::spawn`.
+     * Returns a promise that resolves when the process is spawned.
+     */
+    spawn(opts: PiProcessOptions): Promise<void>;
+    private handleStdoutLine;
+    private extractEventMsgId;
+    /** Send a command to pi stdin. */
+    private writeCommand;
+    /** Send a prompt command. Mirrors Rust PiProcess::send_prompt. */
+    sendPrompt(msgId: string, message: string, streamingBehavior?: string): void;
+    /** Send an abort command. Mirrors Rust PiProcess::send_abort. */
+    sendAbort(): void;
+    /** Forward extension_ui_response to pi. */
+    sendExtensionUIResponse(requestId: string, response: Record<string, unknown>): void;
+    /** Switch LLM model. Mirrors Rust PiProcess::set_model. */
+    setModel(provider: string, modelId: string): void;
+    /** Set thinking level. Mirrors Rust PiProcess::set_thinking_level. */
+    setThinkingLevel(level: string): void;
+    /** Manual context compaction. Mirrors Rust PiProcess::compact. */
+    compact(): void;
+    /** Get available models. Mirrors Rust PiProcess::get_available_models. */
+    getAvailableModels(id: string): void;
+    /** Is the agent currently streaming (between agent_start and agent_end)? */
+    isStreaming(): boolean;
+    /** Is the pi process still alive (stdout not EOF)? GAP-003 health check. */
+    isAlive(): boolean;
+    /** Number of unparseable stdout lines (Q4 GAP-020 health counter). */
+    getParseErrorCount(): number;
+    /** Captured pi session ID (GAP-017/P5). */
+    getPersistedSessionId(): string | undefined;
+    /** Register a handler for StreamMessage events. */
+    onEvent(handler: (msg: StreamMessage) => void): void;
+    /** Register a handler for exit events. */
+    onExit(handler: (agentId: string) => void): void;
+    /** Register a handler for stderr log lines. */
+    onStderr(handler: (line: string) => void): void;
+    /**
+     * Graceful shutdown: send abort, close stdin, kill child.
+     * Mirrors Rust PiProcess::terminate.
+     */
+    terminate(): void;
+    private buildEnvContext;
+}
+export declare function promptCommand(id: string, message: string): RpcCommand;
+export declare function promptWithStreamingCommand(id: string, message: string, behavior: string): RpcCommand;
+export declare function abortCommand(): RpcCommand;
+export declare function setModelCommand(provider: string, modelId: string): RpcCommand;
+export declare function setThinkingLevelCommand(level: string): RpcCommand;
+export declare function compactCommand(): RpcCommand;
+export declare function getAvailableModelsCommand(id: string): RpcCommand;
+/**
+ * Generate a pi-compatible session ID (RFC 4122 v4 UUID).
+ * Mirrors Rust `new_session_id()`.
+ */
+export declare function newPiSessionId(): string;
+/**
+ * Extract pi sessionId from event payload.
+ * Mirrors Rust `extract_session_id`.
+ */
+export declare function extractSessionId(eventType: string, payload: Record<string, unknown>): string | 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 declare function eventMsgId(payload: Record<string, unknown>, fallback: string): string;