Add Zork engine integration work

2026-05-15 07:55:05 +02:00
parent b8fe8535aa
commit 6faee20268
19 changed files with 4113 additions and 21 deletions
@@ -0,0 +1,90 @@
+/**
+ * Zork LLM Engine
+ *
+ * Runs Zork I (or any Z-machine story file) as a headless subprocess via the
+ * `ifvms` CLI, and wraps every I/O exchange with OpenRouter LLM calls that
+ * translate free natural-language player input into parser commands and
+ * re-voice the Z-machine's raw output as polished narrative prose.
+ *
+ * Configuration (environment variables):
+ *   ZORK_STORY_FILE  – path to the .z5/.z8/.bin story file (default: ./data/z-code/zork1.bin)
+ *   ZORK_MAX_RETRIES – maximum command retry attempts per turn  (default: 3)
+ *   ZORK_HISTORY_SIZE – player-facing outputs stored per room   (default: 5)
+ *   OPENROUTER_API_KEY, OPENROUTER_MODEL – required
+ */
+export interface ZorkSession {
+    characterDescription: string;
+    notes: string[];
+    recentParagraphs: string[];
+    rawTranscript: string[];
+    turnCount: number;
+    timeOfDay: string;
+    weather: string;
+    virtualInventory: string[];
+    /** roomName → last N player-facing output strings */
+    roomHistory: Record<string, string[]>;
+    currentRoom: string;
+    running: boolean;
+}
+/** Subset of the unified TurnResult protocol understood by the client. */
+export interface ZorkTurnResult {
+    paragraphs: Array<{
+        text: string;
+        tags: unknown[];
+    }>;
+    choices: unknown[];
+    inputMode: 'text' | 'end';
+    gameState?: {
+        statusLine?: string;
+    };
+}
+export declare class ZorkLlmEngine {
+    private zork;
+    private session;
+    private prompts;
+    private llm;
+    private model;
+    private resolvedFallbackModel;
+    private llmCallCounter;
+    private maxRetries;
+    private historySize;
+    private storyPath;
+    private static readonly DEPRECATED_MODEL_REPLACEMENTS;
+    constructor();
+    private createCompletion;
+    private resolveFallbackModel;
+    isRunning(): boolean;
+    /**
+     * Start a new game: launch Zork, generate the player character, rewrite the
+     * intro text, and return the first TurnResult for the client.
+     */
+    newGame(): Promise<ZorkTurnResult>;
+    /**
+     * Process player free-text input. Returns the next TurnResult.
+     */
+    processInput(userInput: string): Promise<ZorkTurnResult>;
+    private runCommandPlan;
+    /**
+     * Save the current game state. Returns a JSON string suitable for storing
+     * in the socket's save-game slot map.
+     */
+    saveGame(): Promise<string>;
+    /**
+     * Load a previously saved game. Returns the first TurnResult after restore.
+     */
+    loadGame(savedJson: string): Promise<ZorkTurnResult>;
+    private runSingleCommandLoop;
+    private generateCharacter;
+    private rewriteText;
+    private translateCommand;
+    private evaluateOutput;
+    private executeTool;
+    private appendRecentParagraph;
+    private extractCommands;
+    private appendRawTranscript;
+    private advanceNarratorState;
+    private getDeterministicCommandPlan;
+    private appendRoomHistory;
+    private buildCommonVars;
+    private buildTurnResult;
+}