pi-app-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# pi-server
+
+Session multiplexer for [pi-coding-agent](https://www.npmjs.com/package/@mariozechner/pi-coding-agent). Exposes N independent `AgentSession` instances through WebSocket and stdio transports.
+
+[![CI](https://github.com/tryingET/pi-server/actions/workflows/ci.yml/badge.svg)](https://github.com/tryingET/pi-server/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/pi-app-server.svg)](https://www.npmjs.com/package/pi-app-server)
+
+> Note: This is a standalone pi server package, not an extension/skills/themes bundle.
+
+## Features
+
+- **Dual transport**: WebSocket (port 3141) + stdio (JSON lines)
+- **Session lifecycle**: Create, delete, list, switch sessions
+- **Command execution**: Deterministic lane serialization per session
+- **Idempotent replay**: Atomic outcome storage with free replay lookups
+- **Optimistic concurrency**: Session versioning for conflict detection
+- **Extension UI**: Full round-trip support for `select`, `confirm`, `input`, `editor`, `interview`
+- **Resource governance**: Rate limiting, session limits, message size limits
+- **Graceful shutdown**: Drain in-flight commands, notify clients
+- **Protocol versioning**: `serverVersion` + `protocolVersion` for compatibility checks
+
+## Installation
+
+```bash
+npm install pi-app-server
+```
+
+## Quick Start
+
+### WebSocket
+
+```bash
+# Start server
+npx pi-server
+
+# Connect with wscat
+wscat -c ws://localhost:3141
+```
+
+```js
+// Create and use a session
+ws> {"type":"create_session","sessionId":"my-session"}
+ws> {"type":"switch_session","sessionId":"my-session"}
+ws> {"id":"cmd-1","type":"prompt","sessionId":"my-session","message":"Hello!"}
+```
+
+### stdio
+
+```bash
+echo '{"type":"create_session","sessionId":"test"}
+{"type":"switch_session","sessionId":"test"}
+{"id":"cmd-1","type":"prompt","sessionId":"test","message":"Hello!"}' | npx pi-server
+```
+
+## Architecture
+
+```
+src/
+├── server.ts               # transports, connection lifecycle, routing glue
+├── session-manager.ts      # orchestration: coordinates stores, engines, sessions
+├── command-router.ts       # session command handlers, routing
+├── command-classification.ts  # pure command classification (timeout, mutation)
+├── command-replay-store.ts    # idempotency, duplicate detection, outcome history
+├── session-version-store.ts   # monotonic version counters per session
+├── command-execution-engine.ts # lane serialization, dependency waits, timeouts
+├── resource-governor.ts    # limits, rate controls, health/metrics
+├── extension-ui.ts         # pending UI request tracking
+├── server-ui-context.ts    # ExtensionUIContext for remote clients
+├── validation.ts           # command validation
+└── types.ts                # wire protocol types + SessionResolver interface
+```
+
+### Core invariants
+
+- For each admitted command, there is exactly one terminal response.
+- For each session ID, there is at most one live `AgentSession`.
+- Subscriber session sets are always a subset of active sessions.
+- Session version is monotonic and mutation-sensitive.
+- Fingerprint excludes retry identity (`id`, `idempotencyKey`) for semantic equivalence.
+
+### Key abstractions
+
+- **`SessionResolver`** — Interface for session access (enables test doubles, future clustering)
+- **`CommandReplayStore`** — Idempotency and duplicate detection
+- **`SessionVersionStore`** — Optimistic concurrency via version counters
+- **`CommandExecutionEngine`** — Deterministic lane serialization and timeout management
+
+## Protocol
+
+See [PROTOCOL.md](./PROTOCOL.md) for the normative wire contract.
+
+### Command → Response
+
+Every command receives exactly one response:
+
+```json
+{"id": "cmd-1", "type": "prompt", "sessionId": "s1", "message": "hello"}
+{"id": "cmd-1", "type": "response", "command": "prompt", "success": true}
+```
+
+### Event Broadcast
+
+Events flow session → subscribers:
+
+```json
+{"type": "event", "sessionId": "s1", "event": {"type": "agent_start", ...}}
+```
+
+### Extension UI Round-Trip
+
+1. Extension calls `ui.select()` → server creates pending request
+2. Server broadcasts `extension_ui_request` event with `requestId`
+3. Client sends `extension_ui_response` command with same `requestId`
+4. Server resolves pending promise → extension continues
+
+### Idempotency & Replay
+
+```json
+// First request with idempotency key
+{"id": "cmd-1", "type": "list_sessions", "idempotencyKey": "key-1"}
+{"id": "cmd-1", "type": "response", "command": "list_sessions", "success": true, ...}
+
+// Retry with same key → replayed (free, no rate limit charge)
+{"id": "cmd-2", "type": "list_sessions", "idempotencyKey": "key-1"}
+{"id": "cmd-2", "type": "response", "command": "list_sessions", "success": true, "replayed": true, ...}
+```
+
+### Timeout semantics (ADR-0001)
+
+- Timeout is a **terminal stored outcome** (`timedOut: true`), not an indeterminate placeholder.
+- Replay of the same command identity returns the **same timeout response**.
+- Late underlying completion does **not** overwrite the stored timeout outcome.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test                    # Unit tests (83)
+npm run test:integration    # Integration tests (26)
+npm run test:fuzz           # Fuzz tests (17)
+
+# Module tests (141)
+node --experimental-vm-modules dist/test-command-classification.js
+node --experimental-vm-modules dist/test-session-version-store.js
+node --experimental-vm-modules dist/test-command-replay-store.js
+node --experimental-vm-modules dist/test-command-execution-engine.js
+
+# Type check + lint
+npm run check
+
+# Full CI
+npm run ci
+```
+
+## Release Process
+
+This project uses [release-please](https://github.com/googleapis/release-please) for automated versioning.
+
+### Automated Flow
+
+1. Push to `main` → release-please creates/updates a release PR
+2. Merge the release PR → Creates GitHub release + git tag
+3. Release published → GitHub Action publishes to npm with provenance
+
+### Manual Release Check
+
+```bash
+npm run release:check
+```
+
+This validates:
+- `package.json` has required fields
+- `dist/` exists with compiled files
+- Entry point has correct shebang
+- `npm pack` produces expected files
+- Full CI passes
+
+## Documentation
+
+| Document | Purpose |
+|----------|---------|
+| [AGENTS.md](./AGENTS.md) | Crystallized learnings, patterns, anti-patterns |
+| [PROTOCOL.md](./PROTOCOL.md) | Normative wire contract |
+| [ADR-0001](./docs/adr/0001-atomic-outcome-storage.md) | Atomic outcome storage decision |
+| [ROADMAP.md](./ROADMAP.md) | Phase tracking and milestones |
+
+## License
+
+MIT

package/dist/command-classification.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Command Classification - unified source of truth for command behavior.
+ *
+ * This module consolidates all command classification logic that was
+ * previously scattered across multiple modules. Single source of truth
+ * prevents drift and makes adding new commands easier.
+ *
+ * Classification dimensions:
+ * - Timeout policy: short (30s), long (5min), or none (uncancellable)
+ * - Mutation: does the command change session state?
+ */
+/**
+ * Get the timeout policy for a command type.
+ * @returns Timeout in ms, or null for uncancellable commands
+ */
+export declare function getCommandTimeoutPolicy(commandType: string, options?: {
+    defaultTimeoutMs?: number;
+    shortTimeoutMs?: number;
+}): number | null;
+/**
+ * Check if a command has a short timeout.
+ */
+export declare function isShortTimeoutCommand(commandType: string): boolean;
+/**
+ * Check if a command cannot be timed out.
+ */
+export declare function isNoTimeoutCommand(commandType: string): boolean;
+/**
+ * Check if a command type mutates session state.
+ * Mutating commands advance the session version.
+ */
+export declare function isMutationCommand(commandType: string): boolean;
+/**
+ * Check if a command is read-only.
+ */
+export declare function isReadOnlyCommand(commandType: string): boolean;
+/**
+ * Full classification of a command type.
+ */
+export interface CommandClassification {
+    /** Timeout in milliseconds, or null for uncancellable */
+    timeoutMs: number | null;
+    /** Whether this is a short timeout command */
+    isShortTimeout: boolean;
+    /** Whether this command can be timed out */
+    isCancellable: boolean;
+    /** Whether this command mutates session state */
+    isMutation: boolean;
+    /** Whether this command is read-only */
+    isReadOnly: boolean;
+}
+/**
+ * Get full classification for a command type.
+ */
+export declare function classifyCommand(commandType: string, options?: {
+    defaultTimeoutMs?: number;
+    shortTimeoutMs?: number;
+}): CommandClassification;
+//# sourceMappingURL=command-classification.d.ts.map

package/dist/command-classification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-classification.d.ts","sourceRoot":"","sources":["../src/command-classification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAiCH;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IACR,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GACA,MAAM,GAAG,IAAI,CASf;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAElE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE/D;AAiCD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAI9D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE9D;AAMD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8CAA8C;IAC9C,cAAc,EAAE,OAAO,CAAC;IACxB,4CAA4C;IAC5C,aAAa,EAAE,OAAO,CAAC;IACvB,iDAAiD;IACjD,UAAU,EAAE,OAAO,CAAC;IACpB,wCAAwC;IACxC,UAAU,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IACR,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GACA,qBAAqB,CASvB"}

package/dist/command-classification.js

@@ -0,0 +1,78 @@
+const SHORT_TIMEOUT_COMMANDS = /* @__PURE__ */ new Set([
+  "get_state",
+  "get_messages",
+  "get_available_models",
+  "get_commands",
+  "get_skills",
+  "get_tools",
+  "list_session_files",
+  "get_session_stats",
+  "get_fork_messages",
+  "get_last_assistant_text",
+  "get_context_usage",
+  "set_session_name"
+]);
+const NO_TIMEOUT_COMMANDS = /* @__PURE__ */ new Set([
+  "create_session"
+  // Session creation is atomic
+]);
+function getCommandTimeoutPolicy(commandType, options) {
+  if (NO_TIMEOUT_COMMANDS.has(commandType)) {
+    return null;
+  }
+  const defaultTimeout = options?.defaultTimeoutMs ?? 5 * 60 * 1e3;
+  const shortTimeout = options?.shortTimeoutMs ?? 30 * 1e3;
+  return SHORT_TIMEOUT_COMMANDS.has(commandType) ? shortTimeout : defaultTimeout;
+}
+function isShortTimeoutCommand(commandType) {
+  return SHORT_TIMEOUT_COMMANDS.has(commandType);
+}
+function isNoTimeoutCommand(commandType) {
+  return NO_TIMEOUT_COMMANDS.has(commandType);
+}
+const READ_ONLY_COMMANDS = /* @__PURE__ */ new Set([
+  "get_state",
+  "get_messages",
+  "get_available_models",
+  "get_commands",
+  "get_skills",
+  "get_tools",
+  "list_session_files",
+  "get_session_stats",
+  "get_fork_messages",
+  "get_last_assistant_text",
+  "get_context_usage",
+  "switch_session"
+  // Switches client focus, doesn't change session
+]);
+const SPECIAL_SESSION_COMMANDS = /* @__PURE__ */ new Set([
+  "extension_ui_response"
+  // Handled by ExtensionUIManager, not session
+]);
+function isMutationCommand(commandType) {
+  if (READ_ONLY_COMMANDS.has(commandType)) return false;
+  if (SPECIAL_SESSION_COMMANDS.has(commandType)) return false;
+  return true;
+}
+function isReadOnlyCommand(commandType) {
+  return READ_ONLY_COMMANDS.has(commandType);
+}
+function classifyCommand(commandType, options) {
+  const timeoutMs = getCommandTimeoutPolicy(commandType, options);
+  return {
+    timeoutMs,
+    isShortTimeout: isShortTimeoutCommand(commandType),
+    isCancellable: timeoutMs !== null,
+    isMutation: isMutationCommand(commandType),
+    isReadOnly: isReadOnlyCommand(commandType)
+  };
+}
+export {
+  classifyCommand,
+  getCommandTimeoutPolicy,
+  isMutationCommand,
+  isNoTimeoutCommand,
+  isReadOnlyCommand,
+  isShortTimeoutCommand
+};
+//# sourceMappingURL=command-classification.js.map

package/dist/command-classification.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/command-classification.ts"],
+  "sourcesContent": ["/**\n * Command Classification - unified source of truth for command behavior.\n *\n * This module consolidates all command classification logic that was\n * previously scattered across multiple modules. Single source of truth\n * prevents drift and makes adding new commands easier.\n *\n * Classification dimensions:\n * - Timeout policy: short (30s), long (5min), or none (uncancellable)\n * - Mutation: does the command change session state?\n */\n\n// =============================================================================\n// TIMEOUT CLASSIFICATION\n// =============================================================================\n\n/**\n * Commands that should have shorter timeout (30 seconds).\n * These are fast operations that don't involve LLM calls.\n */\nconst SHORT_TIMEOUT_COMMANDS = new Set([\n  \"get_state\",\n  \"get_messages\",\n  \"get_available_models\",\n  \"get_commands\",\n  \"get_skills\",\n  \"get_tools\",\n  \"list_session_files\",\n  \"get_session_stats\",\n  \"get_fork_messages\",\n  \"get_last_assistant_text\",\n  \"get_context_usage\",\n  \"set_session_name\",\n]);\n\n/**\n * Commands that should not use command timeout (cannot be safely cancelled).\n * These have side effects that must complete once started.\n */\nconst NO_TIMEOUT_COMMANDS = new Set([\n  \"create_session\", // Session creation is atomic\n]);\n\n/**\n * Get the timeout policy for a command type.\n * @returns Timeout in ms, or null for uncancellable commands\n */\nexport function getCommandTimeoutPolicy(\n  commandType: string,\n  options?: {\n    defaultTimeoutMs?: number;\n    shortTimeoutMs?: number;\n  }\n): number | null {\n  if (NO_TIMEOUT_COMMANDS.has(commandType)) {\n    return null;\n  }\n\n  const defaultTimeout = options?.defaultTimeoutMs ?? 5 * 60 * 1000;\n  const shortTimeout = options?.shortTimeoutMs ?? 30 * 1000;\n\n  return SHORT_TIMEOUT_COMMANDS.has(commandType) ? shortTimeout : defaultTimeout;\n}\n\n/**\n * Check if a command has a short timeout.\n */\nexport function isShortTimeoutCommand(commandType: string): boolean {\n  return SHORT_TIMEOUT_COMMANDS.has(commandType);\n}\n\n/**\n * Check if a command cannot be timed out.\n */\nexport function isNoTimeoutCommand(commandType: string): boolean {\n  return NO_TIMEOUT_COMMANDS.has(commandType);\n}\n\n// =============================================================================\n// MUTATION CLASSIFICATION\n// =============================================================================\n\n/**\n * Commands that don't mutate session state (read-only).\n * These don't advance the session version on success.\n */\nconst READ_ONLY_COMMANDS = new Set([\n  \"get_state\",\n  \"get_messages\",\n  \"get_available_models\",\n  \"get_commands\",\n  \"get_skills\",\n  \"get_tools\",\n  \"list_session_files\",\n  \"get_session_stats\",\n  \"get_fork_messages\",\n  \"get_last_assistant_text\",\n  \"get_context_usage\",\n  \"switch_session\", // Switches client focus, doesn't change session\n]);\n\n/**\n * Commands that appear to target a session but are handled specially.\n * These don't count as session mutations for version purposes.\n */\nconst SPECIAL_SESSION_COMMANDS = new Set([\n  \"extension_ui_response\", // Handled by ExtensionUIManager, not session\n]);\n\n/**\n * Check if a command type mutates session state.\n * Mutating commands advance the session version.\n */\nexport function isMutationCommand(commandType: string): boolean {\n  if (READ_ONLY_COMMANDS.has(commandType)) return false;\n  if (SPECIAL_SESSION_COMMANDS.has(commandType)) return false;\n  return true;\n}\n\n/**\n * Check if a command is read-only.\n */\nexport function isReadOnlyCommand(commandType: string): boolean {\n  return READ_ONLY_COMMANDS.has(commandType);\n}\n\n// =============================================================================\n// COMBINED QUERIES\n// =============================================================================\n\n/**\n * Full classification of a command type.\n */\nexport interface CommandClassification {\n  /** Timeout in milliseconds, or null for uncancellable */\n  timeoutMs: number | null;\n  /** Whether this is a short timeout command */\n  isShortTimeout: boolean;\n  /** Whether this command can be timed out */\n  isCancellable: boolean;\n  /** Whether this command mutates session state */\n  isMutation: boolean;\n  /** Whether this command is read-only */\n  isReadOnly: boolean;\n}\n\n/**\n * Get full classification for a command type.\n */\nexport function classifyCommand(\n  commandType: string,\n  options?: {\n    defaultTimeoutMs?: number;\n    shortTimeoutMs?: number;\n  }\n): CommandClassification {\n  const timeoutMs = getCommandTimeoutPolicy(commandType, options);\n  return {\n    timeoutMs,\n    isShortTimeout: isShortTimeoutCommand(commandType),\n    isCancellable: timeoutMs !== null,\n    isMutation: isMutationCommand(commandType),\n    isReadOnly: isReadOnlyCommand(commandType),\n  };\n}\n"],
+  "mappings": "AAoBA,MAAM,yBAAyB,oBAAI,IAAI;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAMD,MAAM,sBAAsB,oBAAI,IAAI;AAAA,EAClC;AAAA;AACF,CAAC;AAMM,SAAS,wBACd,aACA,SAIe;AACf,MAAI,oBAAoB,IAAI,WAAW,GAAG;AACxC,WAAO;AAAA,EACT;AAEA,QAAM,iBAAiB,SAAS,oBAAoB,IAAI,KAAK;AAC7D,QAAM,eAAe,SAAS,kBAAkB,KAAK;AAErD,SAAO,uBAAuB,IAAI,WAAW,IAAI,eAAe;AAClE;AAKO,SAAS,sBAAsB,aAA8B;AAClE,SAAO,uBAAuB,IAAI,WAAW;AAC/C;AAKO,SAAS,mBAAmB,aAA8B;AAC/D,SAAO,oBAAoB,IAAI,WAAW;AAC5C;AAUA,MAAM,qBAAqB,oBAAI,IAAI;AAAA,EACjC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AACF,CAAC;AAMD,MAAM,2BAA2B,oBAAI,IAAI;AAAA,EACvC;AAAA;AACF,CAAC;AAMM,SAAS,kBAAkB,aAA8B;AAC9D,MAAI,mBAAmB,IAAI,WAAW,EAAG,QAAO;AAChD,MAAI,yBAAyB,IAAI,WAAW,EAAG,QAAO;AACtD,SAAO;AACT;AAKO,SAAS,kBAAkB,aAA8B;AAC9D,SAAO,mBAAmB,IAAI,WAAW;AAC3C;AAyBO,SAAS,gBACd,aACA,SAIuB;AACvB,QAAM,YAAY,wBAAwB,aAAa,OAAO;AAC9D,SAAO;AAAA,IACL;AAAA,IACA,gBAAgB,sBAAsB,WAAW;AAAA,IACjD,eAAe,cAAc;AAAA,IAC7B,YAAY,kBAAkB,WAAW;AAAA,IACzC,YAAY,kBAAkB,WAAW;AAAA,EAC3C;AACF;",
+  "names": []
+}

package/dist/command-execution-engine.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Command Execution Engine - manages lane serialization, dependency waits, and timeouts.
+ *
+ * Responsibilities:
+ * - Deterministic per-lane command serialization
+ * - Dependency resolution with timeout
+ * - Command timeout orchestration with abort hooks
+ * - Lifecycle event emission
+ */
+import type { AgentSession } from "@mariozechner/pi-coding-agent";
+import type { RpcCommand, RpcResponse, SessionResolver } from "./types.js";
+import type { CommandReplayStore } from "./command-replay-store.js";
+import type { SessionVersionStore } from "./session-version-store.js";
+/**
+ * Abort handler for a specific command type.
+ * Called when a command times out to attempt cancellation.
+ */
+export type AbortHandler = (session: AgentSession) => void | Promise<void>;
+/**
+ * Wrap a promise with a timeout.
+ * Returns the promise result or throws on timeout.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, commandType: string, onTimeout?: () => void | Promise<void>): Promise<T>;
+/**
+ * Configuration options for the execution engine.
+ */
+export interface ExecutionEngineOptions {
+    defaultCommandTimeoutMs?: number;
+    shortCommandTimeoutMs?: number;
+    dependencyWaitTimeoutMs?: number;
+    /** Custom abort handlers for command types (extends defaults) */
+    abortHandlers?: Partial<Record<string, AbortHandler>>;
+}
+/**
+ * Command Execution Engine - manages lane serialization and dependency waits.
+ *
+ * Extracted from PiSessionManager to isolate:
+ * - Per-lane command serialization
+ * - Dependency resolution with timeout
+ * - Command timeout with abort hooks
+ */
+export declare class CommandExecutionEngine {
+    /** Deterministic per-lane command serialization tails. */
+    private laneTails;
+    private readonly replayStore;
+    private readonly versionStore;
+    private readonly sessionResolver;
+    private readonly abortHandlers;
+    private readonly defaultCommandTimeoutMs;
+    private readonly shortCommandTimeoutMs;
+    private readonly dependencyWaitTimeoutMs;
+    constructor(replayStore: CommandReplayStore, versionStore: SessionVersionStore, sessionResolver: SessionResolver, options?: ExecutionEngineOptions);
+    /**
+     * Get statistics about the execution engine state.
+     */
+    getStats(): {
+        laneCount: number;
+    };
+    /**
+     * Get the lane key for a command.
+     * Session commands serialize per-session; server commands serialize together.
+     */
+    getLaneKey(command: RpcCommand): string;
+    /**
+     * Run a task in a deterministic serialized lane.
+     * Commands in the same lane execute sequentially.
+     */
+    runOnLane<T>(laneKey: string, task: () => Promise<T>): Promise<T>;
+    /**
+     * Wait for dependency commands to complete.
+     * Returns error if any dependency fails or times out.
+     *
+     * Note: Cross-lane dependency cycles (A→B, B→A) are detected by timeout
+     * rather than explicit cycle detection. This is acceptable because:
+     * 1. Cross-lane dependencies are rare
+     * 2. The dependencyWaitTimeoutMs (default 30s) prevents indefinite deadlock
+     * 3. Same-lane cycles are explicitly detected below
+     */
+    awaitDependencies(dependsOn: string[], laneKey: string): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    /**
+     * Resolve timeout policy for a command.
+     * Returns null for commands that cannot be safely cancelled.
+     */
+    getCommandTimeoutMs(commandType: string): number | null;
+    /**
+     * Best-effort cancellation for timed-out commands.
+     * Uses configured abort handlers (defaults + custom overrides).
+     */
+    abortTimedOutCommand(command: RpcCommand): Promise<void>;
+    /**
+     * Execute a command with timeout.
+     */
+    executeWithTimeout(commandType: string, promise: Promise<RpcResponse>, command: RpcCommand): Promise<RpcResponse>;
+    /**
+     * Check if a session version matches the expected version.
+     * Returns error object if mismatch, undefined if OK.
+     *
+     * @param sessionId - The session to check
+     * @param ifSessionVersion - The expected version
+     * @param commandType - The command type for error context (preserves caller's context)
+     */
+    checkSessionVersion(sessionId: string, ifSessionVersion: number, commandType: string): {
+        type: "response";
+        command: string;
+        success: false;
+        error: string;
+    } | undefined;
+    /**
+     * Clear all lane state (used during disposal).
+     */
+    clear(): void;
+}
+//# sourceMappingURL=command-execution-engine.d.ts.map

package/dist/command-execution-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-execution-engine.d.ts","sourceRoot":"","sources":["../src/command-execution-engine.ts"],"names":[],"mappings":"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"}