edge-ai-client-ts 1.0.0

package/dist/session/fail-fast.d.ts

@@ -0,0 +1,70 @@
+/**
+ * AGT-02 Fail-Fast Policy (SPEC §3.3) — tool-output safety invariant.
+ *
+ * Mirrors `edge-client/src/session/fail_fast.rs` 1:1. The edge-client's core
+ * doctrine is "TRUST PI, TRANSPORT 100%": it forwards every pi event verbatim
+ * and does not second-guess pi's reasoning. AGT-02 adds ONE scoped exception:
+ * it inspects pi's **tool execution OUTPUT** (not pi's reasoning/text) for
+ * forbidden OS-policy keywords. When a tool result contains "Access Denied"
+ * / "AppLocker" / "Permission denied", the agent reasoning loop is aborted
+ * immediately and an error is reported to the server, so pi cannot auto-seek
+ * alternative methods that would violate the organization's internal security
+ * policy.
+ *
+ * This does NOT break transport-100%: the triggering event is still forwarded
+ * unchanged — the wrapper only ADDS an abort + a synthetic `error` event.
+ *
+ * Disable for pure-trust mode via `EDGE_FAIL_FAST=0` (or `EDGE_FAIL_FAST=false`).
+ */
+/**
+ * Forbidden keywords per SPEC §3.3 AGT-02. Matched case-insensitively as
+ * substrings of the concatenated tool-output text.
+ * Mirror of Rust `fail_fast::FORBIDDEN_KEYWORDS`.
+ */
+export declare const FORBIDDEN_KEYWORDS: readonly string[];
+/**
+ * Pi event types whose payload may carry tool OUTPUT worth inspecting.
+ * We deliberately do NOT inspect reasoning/text events (`message_update`,
+ * `message_end`, ...) — only concrete tool execution results, so the policy
+ * acts on what a tool actually returned, never on pi's narration.
+ * Mirror of Rust `fail_fast::INSPECTABLE_EVENT_TYPES`.
+ */
+export declare const INSPECTABLE_EVENT_TYPES: readonly string[];
+/**
+ * Synthetic error content emitted on fail-fast. Wording matches SPEC §3.3.
+ * Mirror of Rust `fail_fast::FAIL_FAST_ERROR_CONTENT`.
+ */
+export declare const FAIL_FAST_ERROR_CONTENT = "Permission Denied: OS Blocked";
+/** Env var name (mirror of Rust `fail_fast::fail_fast_enabled`). */
+export declare const ENV_FAIL_FAST = "EDGE_FAIL_FAST";
+/**
+ * Whether AGT-02 fail-fast is enabled. Default ON per SPEC. Disable with
+ * `EDGE_FAIL_FAST=0` (or `false`) for pure trust-pi mode (legacy).
+ *
+ * Mirror of Rust `fail_fast_enabled()`. Reads `process.env` directly — keep
+ * the option to pass a custom env in for testability.
+ */
+export declare function failFastEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * If `event_type` is an inspectable tool-execution event AND its payload text
+ * contains a forbidden keyword, return that keyword (the FIRST match, in the
+ * order defined in `FORBIDDEN_KEYWORDS`). Returns `null` otherwise.
+ *
+ * PURE — no env, no I/O; callers gate on `failFastEnabled()` separately so
+ * the detection logic is unit-testable deterministically.
+ *
+ * Mirror of Rust `fail_fast::detect_forbidden`.
+ */
+export declare function detectForbidden(eventType: string, payload: unknown): string | null;
+/**
+ * Build the synthetic error event the wrapper emits on fail-fast. The shape
+ * matches a pi `error` event (payload can be forwarded over `/edge` exactly
+ * like any other event — transport-100% preserved).
+ *
+ * Mirror of the synthetic-event construction in `fail_fast.rs::on_tool_event`
+ * (the Rust side builds the same `{type:"error", content:FAIL_FAST_ERROR_CONTENT}`).
+ */
+export declare function buildSyntheticErrorEvent(): {
+    type: 'error';
+    content: string;
+};

package/dist/session/fail-fast.js

@@ -0,0 +1,122 @@
+/**
+ * AGT-02 Fail-Fast Policy (SPEC §3.3) — tool-output safety invariant.
+ *
+ * Mirrors `edge-client/src/session/fail_fast.rs` 1:1. The edge-client's core
+ * doctrine is "TRUST PI, TRANSPORT 100%": it forwards every pi event verbatim
+ * and does not second-guess pi's reasoning. AGT-02 adds ONE scoped exception:
+ * it inspects pi's **tool execution OUTPUT** (not pi's reasoning/text) for
+ * forbidden OS-policy keywords. When a tool result contains "Access Denied"
+ * / "AppLocker" / "Permission denied", the agent reasoning loop is aborted
+ * immediately and an error is reported to the server, so pi cannot auto-seek
+ * alternative methods that would violate the organization's internal security
+ * policy.
+ *
+ * This does NOT break transport-100%: the triggering event is still forwarded
+ * unchanged — the wrapper only ADDS an abort + a synthetic `error` event.
+ *
+ * Disable for pure-trust mode via `EDGE_FAIL_FAST=0` (or `EDGE_FAIL_FAST=false`).
+ */
+// ──────────────────────────── constants ────────────────────────────
+/**
+ * Forbidden keywords per SPEC §3.3 AGT-02. Matched case-insensitively as
+ * substrings of the concatenated tool-output text.
+ * Mirror of Rust `fail_fast::FORBIDDEN_KEYWORDS`.
+ */
+export const FORBIDDEN_KEYWORDS = Object.freeze([
+    'Access Denied',
+    'AppLocker',
+    'Permission denied',
+]);
+/**
+ * Pi event types whose payload may carry tool OUTPUT worth inspecting.
+ * We deliberately do NOT inspect reasoning/text events (`message_update`,
+ * `message_end`, ...) — only concrete tool execution results, so the policy
+ * acts on what a tool actually returned, never on pi's narration.
+ * Mirror of Rust `fail_fast::INSPECTABLE_EVENT_TYPES`.
+ */
+export const INSPECTABLE_EVENT_TYPES = Object.freeze([
+    'tool_execution_update',
+    'tool_execution_end',
+]);
+/**
+ * Synthetic error content emitted on fail-fast. Wording matches SPEC §3.3.
+ * Mirror of Rust `fail_fast::FAIL_FAST_ERROR_CONTENT`.
+ */
+export const FAIL_FAST_ERROR_CONTENT = 'Permission Denied: OS Blocked';
+/** Env var name (mirror of Rust `fail_fast::fail_fast_enabled`). */
+export const ENV_FAIL_FAST = 'EDGE_FAIL_FAST';
+// ──────────────────────────── enablement gate ──────────────────────
+/**
+ * Whether AGT-02 fail-fast is enabled. Default ON per SPEC. Disable with
+ * `EDGE_FAIL_FAST=0` (or `false`) for pure trust-pi mode (legacy).
+ *
+ * Mirror of Rust `fail_fast_enabled()`. Reads `process.env` directly — keep
+ * the option to pass a custom env in for testability.
+ */
+export function failFastEnabled(env = process.env) {
+    const raw = env[ENV_FAIL_FAST];
+    return !(raw === '0' || raw === 'false');
+}
+// ──────────────────────────── detection ────────────────────────────
+/**
+ * Recursively collect every string value in `value` into `out` (newline-
+ * separated). Lets the keyword scan cover nested `result`/`args`/`stdout`
+ * fields regardless of the exact tool event shape pi emits.
+ *
+ * Mirror of Rust `fail_fast::collect_strings`.
+ */
+function collectStrings(value, out) {
+    if (value === null || value === undefined)
+        return;
+    if (typeof value === 'string') {
+        out.push(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const v of value)
+            collectStrings(v, out);
+        return;
+    }
+    if (typeof value === 'object') {
+        for (const v of Object.values(value)) {
+            collectStrings(v, out);
+        }
+    }
+    // numbers, booleans, bigints → skip (only strings match keywords)
+}
+/**
+ * If `event_type` is an inspectable tool-execution event AND its payload text
+ * contains a forbidden keyword, return that keyword (the FIRST match, in the
+ * order defined in `FORBIDDEN_KEYWORDS`). Returns `null` otherwise.
+ *
+ * PURE — no env, no I/O; callers gate on `failFastEnabled()` separately so
+ * the detection logic is unit-testable deterministically.
+ *
+ * Mirror of Rust `fail_fast::detect_forbidden`.
+ */
+export function detectForbidden(eventType, payload) {
+    if (!INSPECTABLE_EVENT_TYPES.includes(eventType))
+        return null;
+    const strings = [];
+    collectStrings(payload, strings);
+    if (strings.length === 0)
+        return null;
+    const blob = strings.join('\n').toLowerCase();
+    for (const kw of FORBIDDEN_KEYWORDS) {
+        if (blob.includes(kw.toLowerCase()))
+            return kw;
+    }
+    return null;
+}
+// ──────────────────────────── synthetic event ──────────────────────
+/**
+ * Build the synthetic error event the wrapper emits on fail-fast. The shape
+ * matches a pi `error` event (payload can be forwarded over `/edge` exactly
+ * like any other event — transport-100% preserved).
+ *
+ * Mirror of the synthetic-event construction in `fail_fast.rs::on_tool_event`
+ * (the Rust side builds the same `{type:"error", content:FAIL_FAST_ERROR_CONTENT}`).
+ */
+export function buildSyntheticErrorEvent() {
+    return { type: 'error', content: FAIL_FAST_ERROR_CONTENT };
+}

package/dist/session/manager.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Session manager — mirrors `edge-client/src/session/manager.rs`.
+ *
+ * Owns PTY shell sessions + SFTP sessions + Pi RPC sessions.
+ * Keys are session_id UUIDs. Implements the request lifecycle:
+ * - Create a session: assign a UUID session_id, call underlying manager.
+ * - Incoming frames from binary WS routed by session_id.
+ * - Heartbeat metadata (activeSessionCount, shellSessionCount, piSessionCount).
+ * - Cleanup on edge-client shutdown (kill all child processes, flush SFTP).
+ */
+import { ShellManager } from './shell.js';
+import type { FrameTypeValue } from './shell-frame.js';
+import { SftpForwarder } from './sftp.js';
+import { PiProcess } from './pi-rpc.js';
+import type { ResourcesConfig, StreamMessage } from './pi-rpc.js';
+import { SessionIdStore } from './persistence.js';
+/** Session type discrimination. */
+export type SessionType = 'shell' | 'sftp' | 'pi';
+/** Heartbeat metadata. Mirrors Rust SessionManager heartbeat fields. */
+export interface HeartbeatMetadata {
+    readonly activeSessionCount: number;
+    readonly shellSessionCount: number;
+    readonly piSessionCount: number;
+}
+/** Callback for heartbeat metadata updates. */
+export type HeartbeatHandler = (metadata: HeartbeatMetadata) => void;
+/** Options for the session manager. */
+export interface SessionManagerOptions {
+    readonly machineId: string;
+    readonly shellEnabled: boolean;
+    readonly piPath?: string;
+    readonly resources?: ResourcesConfig;
+}
+export declare class SessionManager {
+    private readonly machineId;
+    private readonly piPath;
+    private readonly resources;
+    /** Active sessions keyed by session_id. */
+    private readonly sessions;
+    /** Shell manager (PTY sessions). */
+    private readonly shell;
+    /** SFTP forwarder (file browser RPC). */
+    private readonly sftp;
+    /** Pi processes keyed by agent_id (not session_id). */
+    private readonly piProcesses;
+    /** Persistence store for pi session IDs. */
+    private readonly sessionIdStore;
+    /** Event emitter for outgoing messages. */
+    private readonly emitter;
+    constructor(opts: SessionManagerOptions);
+    /**
+     * Open a new shell session. Mirrors Rust `ShellManager::open` lifecycle.
+     * Returns the assigned session_id.
+     */
+    openShellSession(cols: number, rows: number, shell?: string): Promise<string>;
+    /**
+     * Handle a shell-related frame from the binary WS.
+     * Routes to the appropriate underlying manager.
+     */
+    handleShellFrame(frameType: FrameTypeValue, sessionId: string, payload: Buffer): void;
+    /**
+     * Handle an SFTP frame from the binary WS.
+     * Delegates to the SFTP forwarder.
+     */
+    handleSftpFrame(sessionId: string, frameType: number, payload: Buffer): void;
+    /**
+     * Get or create a Pi process for an agent_id.
+     * Mirrors Rust `SessionManager::get_or_create_session`.
+     */
+    getOrCreatePiSession(agentId: string): Promise<PiProcess>;
+    /**
+     * Forward a prompt to a Pi process for agent_id.
+     * Mirrors Rust `SessionManager::execute_command`.
+     */
+    executeCommand(agentId: string, msgId: string, prompt: string): Promise<void>;
+    /**
+     * Forward extension_ui_response to a Pi process.
+     * Mirrors Rust `SessionManager::forward_extension_ui_response`.
+     */
+    forwardExtensionUIResponse(agentId: string, requestId: string, response: Record<string, unknown>): Promise<void>;
+    /**
+     * Switch model for a Pi process.
+     * Mirrors Rust `SessionManager::set_model`.
+     */
+    setModel(agentId: string, provider: string, modelId: string): Promise<void>;
+    /**
+     * Set thinking level for a Pi process.
+     * Mirrors Rust `SessionManager::set_thinking_level`.
+     */
+    setThinkingLevel(agentId: string, level: string): Promise<void>;
+    /**
+     * Trigger compaction for a Pi process.
+     * Mirrors Rust `SessionManager::compact`.
+     */
+    compact(agentId: string): Promise<void>;
+    /**
+     * Forward get_available_models to a Pi process.
+     * Mirrors Rust `SessionManager::get_available_models`.
+     */
+    getAvailableModels(agentId: string, id: string): Promise<void>;
+    /**
+     * Terminate a Pi session for agent_id.
+     * Mirrors Rust `SessionManager::terminate_session`.
+     */
+    terminateSession(agentId: string): Promise<void>;
+    /**
+     * Terminate all Pi sessions. Mirrors Rust `SessionManager::terminate_all`.
+     */
+    terminateAll(): Promise<void>;
+    /** Get current heartbeat metadata. */
+    heartbeatMetadata(): HeartbeatMetadata;
+    /** Register a heartbeat handler. */
+    onHeartbeat(handler: HeartbeatHandler): void;
+    private emitHeartbeat;
+    /**
+     * Close all sessions (edge shutdown). Mirrors Rust `ShellManager::close_all`
+     * + `SessionManager::terminate_all`.
+     */
+    closeAll(): Promise<void>;
+    /** Subscribe to raw wire frames from shell sessions. */
+    onWireFrame(handler: (frame: Buffer) => void): void;
+    /** Subscribe to SFTP response frames. */
+    onSftpFrame(handler: (sessionId: string, frameType: number, payload: Buffer) => void): void;
+    /** Subscribe to pi events (StreamMessage). */
+    onPiEvent(handler: (msg: StreamMessage) => void): void;
+    /** Subscribe to pi exit events. */
+    onPiExit(handler: (agentId: string) => void): void;
+    /** Subscribe to shell exit events. */
+    onShellExited(handler: (sessionId: string, code: number) => void): void;
+    /** Get the shell manager (for binary WS wiring). */
+    getShellManager(): ShellManager;
+    /** Get the SFTP forwarder (for binary WS wiring). */
+    getSftpForwarder(): SftpForwarder;
+    /** Get the session ID store (for persistence). */
+    getSessionIdStore(): SessionIdStore;
+}

package/dist/session/manager.js

@@ -0,0 +1,291 @@
+/**
+ * Session manager — mirrors `edge-client/src/session/manager.rs`.
+ *
+ * Owns PTY shell sessions + SFTP sessions + Pi RPC sessions.
+ * Keys are session_id UUIDs. Implements the request lifecycle:
+ * - Create a session: assign a UUID session_id, call underlying manager.
+ * - Incoming frames from binary WS routed by session_id.
+ * - Heartbeat metadata (activeSessionCount, shellSessionCount, piSessionCount).
+ * - Cleanup on edge-client shutdown (kill all child processes, flush SFTP).
+ */
+import { randomUUID } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import { ShellManager } from './shell.js';
+import { SftpForwarder } from './sftp.js';
+import { PiProcess } from './pi-rpc.js';
+import { SessionIdStore } from './persistence.js';
+// ---------------------------------------------------------------------------
+// SessionManager
+// ---------------------------------------------------------------------------
+export class SessionManager {
+    machineId;
+    piPath;
+    resources;
+    /** Active sessions keyed by session_id. */
+    sessions = new Map();
+    /** Shell manager (PTY sessions). */
+    shell;
+    /** SFTP forwarder (file browser RPC). */
+    sftp;
+    /** Pi processes keyed by agent_id (not session_id). */
+    piProcesses = new Map();
+    /** Persistence store for pi session IDs. */
+    sessionIdStore;
+    /** Event emitter for outgoing messages. */
+    emitter = new EventEmitter();
+    constructor(opts) {
+        this.machineId = opts.machineId;
+        this.piPath = opts.piPath ?? 'pi';
+        this.resources = opts.resources ?? { memory_max_mb: 2048, cpu_quota_percent: 50, tasks_max: 256 };
+        this.shell = new ShellManager({ enabled: opts.shellEnabled });
+        this.sftp = new SftpForwarder();
+        this.sessionIdStore = new SessionIdStore();
+        // Wire shell events → outbound
+        this.shell.onFrame((frame) => {
+            this.emitter.emit('wire_frame', frame);
+        });
+        this.shell.onExit((sessionId, code) => {
+            this.emitter.emit('shell_exited', sessionId, code);
+            // Clean up session entry
+            this.sessions.delete(sessionId);
+            this.emitHeartbeat();
+        });
+        // Wire sftp events → outbound
+        this.sftp.onFrame((sessionId, frameType, payload) => {
+            this.emitter.emit('sftp_frame', sessionId, frameType, payload);
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Shell sessions
+    // -------------------------------------------------------------------------
+    /**
+     * Open a new shell session. Mirrors Rust `ShellManager::open` lifecycle.
+     * Returns the assigned session_id.
+     */
+    async openShellSession(cols, rows, shell) {
+        const sessionId = randomUUID();
+        await this.shell.open(sessionId, cols, rows, shell);
+        this.sessions.set(sessionId, {
+            sessionId,
+            type: 'shell',
+            createdAt: Date.now(),
+        });
+        this.emitHeartbeat();
+        return sessionId;
+    }
+    /**
+     * Handle a shell-related frame from the binary WS.
+     * Routes to the appropriate underlying manager.
+     */
+    handleShellFrame(frameType, sessionId, payload) {
+        // Delegate to shell manager for Data, Resize, Close, OpenControl, CloseControl
+        this.shell.handleFrame(frameType, sessionId, payload);
+    }
+    /**
+     * Handle an SFTP frame from the binary WS.
+     * Delegates to the SFTP forwarder.
+     */
+    handleSftpFrame(sessionId, frameType, payload) {
+        this.sftp.handleFrame(sessionId, frameType, payload);
+    }
+    // -------------------------------------------------------------------------
+    // Pi sessions
+    // -------------------------------------------------------------------------
+    /**
+     * Get or create a Pi process for an agent_id.
+     * Mirrors Rust `SessionManager::get_or_create_session`.
+     */
+    async getOrCreatePiSession(agentId) {
+        const existing = this.piProcesses.get(agentId);
+        if (existing !== undefined && existing.isAlive()) {
+            return existing;
+        }
+        // If dead, remove and respawn
+        if (existing !== undefined) {
+            existing.terminate();
+            this.piProcesses.delete(agentId);
+        }
+        const sessionId = await this.sessionIdStore.getOrInit(agentId, () => randomUUID());
+        const proc = new PiProcess({
+            agentId,
+            piPath: this.piPath,
+            machineId: this.machineId,
+            resources: this.resources,
+            resumeSessionId: sessionId,
+        });
+        await proc.spawn({
+            agentId,
+            piPath: this.piPath,
+            machineId: this.machineId,
+            resources: this.resources,
+            resumeSessionId: sessionId,
+        });
+        // Wire events
+        proc.onEvent((msg) => {
+            this.emitter.emit('pi_event', msg);
+        });
+        proc.onExit((id) => {
+            this.emitter.emit('pi_exit', id);
+        });
+        this.piProcesses.set(agentId, proc);
+        this.emitHeartbeat();
+        return proc;
+    }
+    /**
+     * Forward a prompt to a Pi process for agent_id.
+     * Mirrors Rust `SessionManager::execute_command`.
+     */
+    async executeCommand(agentId, msgId, prompt) {
+        const pi = await this.getOrCreatePiSession(agentId);
+        const behavior = pi.isStreaming() ? 'followUp' : undefined;
+        pi.sendPrompt(msgId, prompt, behavior);
+    }
+    /**
+     * Forward extension_ui_response to a Pi process.
+     * Mirrors Rust `SessionManager::forward_extension_ui_response`.
+     */
+    async forwardExtensionUIResponse(agentId, requestId, response) {
+        const pi = this.piProcesses.get(agentId);
+        if (pi === undefined) {
+            // No active session — pi will expire the request
+            return;
+        }
+        pi.sendExtensionUIResponse(requestId, response);
+    }
+    /**
+     * Switch model for a Pi process.
+     * Mirrors Rust `SessionManager::set_model`.
+     */
+    async setModel(agentId, provider, modelId) {
+        const pi = this.piProcesses.get(agentId);
+        if (pi === undefined)
+            return;
+        pi.setModel(provider, modelId);
+    }
+    /**
+     * Set thinking level for a Pi process.
+     * Mirrors Rust `SessionManager::set_thinking_level`.
+     */
+    async setThinkingLevel(agentId, level) {
+        const pi = this.piProcesses.get(agentId);
+        if (pi === undefined)
+            return;
+        pi.setThinkingLevel(level);
+    }
+    /**
+     * Trigger compaction for a Pi process.
+     * Mirrors Rust `SessionManager::compact`.
+     */
+    async compact(agentId) {
+        const pi = this.piProcesses.get(agentId);
+        if (pi === undefined)
+            return;
+        pi.compact();
+    }
+    /**
+     * Forward get_available_models to a Pi process.
+     * Mirrors Rust `SessionManager::get_available_models`.
+     */
+    async getAvailableModels(agentId, id) {
+        const pi = await this.getOrCreatePiSession(agentId);
+        pi.getAvailableModels(id);
+    }
+    /**
+     * Terminate a Pi session for agent_id.
+     * Mirrors Rust `SessionManager::terminate_session`.
+     */
+    async terminateSession(agentId) {
+        const pi = this.piProcesses.get(agentId);
+        if (pi !== undefined) {
+            pi.terminate();
+            this.piProcesses.delete(agentId);
+            this.emitHeartbeat();
+        }
+    }
+    /**
+     * Terminate all Pi sessions. Mirrors Rust `SessionManager::terminate_all`.
+     */
+    async terminateAll() {
+        for (const [agentId, pi] of this.piProcesses) {
+            pi.terminate();
+            this.piProcesses.delete(agentId);
+        }
+        this.emitHeartbeat();
+    }
+    // -------------------------------------------------------------------------
+    // Heartbeat
+    // -------------------------------------------------------------------------
+    /** Get current heartbeat metadata. */
+    heartbeatMetadata() {
+        let shellCount = 0;
+        let piCount = 0;
+        for (const entry of this.sessions.values()) {
+            if (entry.type === 'shell')
+                shellCount++;
+        }
+        piCount = this.piProcesses.size;
+        return {
+            activeSessionCount: shellCount + piCount,
+            shellSessionCount: shellCount,
+            piSessionCount: piCount,
+        };
+    }
+    /** Register a heartbeat handler. */
+    onHeartbeat(handler) {
+        this.emitter.on('heartbeat', handler);
+    }
+    emitHeartbeat() {
+        this.emitter.emit('heartbeat', this.heartbeatMetadata());
+    }
+    // -------------------------------------------------------------------------
+    // Shutdown
+    // -------------------------------------------------------------------------
+    /**
+     * Close all sessions (edge shutdown). Mirrors Rust `ShellManager::close_all`
+     * + `SessionManager::terminate_all`.
+     */
+    async closeAll() {
+        this.shell.closeAll();
+        await this.terminateAll();
+        this.sessions.clear();
+        this.emitHeartbeat();
+    }
+    // -------------------------------------------------------------------------
+    // Wire event subscriptions
+    // -------------------------------------------------------------------------
+    /** Subscribe to raw wire frames from shell sessions. */
+    onWireFrame(handler) {
+        this.emitter.on('wire_frame', handler);
+    }
+    /** Subscribe to SFTP response frames. */
+    onSftpFrame(handler) {
+        this.emitter.on('sftp_frame', handler);
+    }
+    /** Subscribe to pi events (StreamMessage). */
+    onPiEvent(handler) {
+        this.emitter.on('pi_event', handler);
+    }
+    /** Subscribe to pi exit events. */
+    onPiExit(handler) {
+        this.emitter.on('pi_exit', handler);
+    }
+    /** Subscribe to shell exit events. */
+    onShellExited(handler) {
+        this.emitter.on('shell_exited', handler);
+    }
+    // -------------------------------------------------------------------------
+    // Accessors
+    // -------------------------------------------------------------------------
+    /** Get the shell manager (for binary WS wiring). */
+    getShellManager() {
+        return this.shell;
+    }
+    /** Get the SFTP forwarder (for binary WS wiring). */
+    getSftpForwarder() {
+        return this.sftp;
+    }
+    /** Get the session ID store (for persistence). */
+    getSessionIdStore() {
+        return this.sessionIdStore;
+    }
+}