Consolidate engine docs and naming

2026-05-19 11:09:37 +02:00
parent 121b174f2c
commit dbcb8f4284
47 changed files with 826 additions and 1992 deletions
@@ -0,0 +1,84 @@
+/**
+ * Z-code LLM Engine
+ *
+ * Runs a 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):
+ *   ZCODE_STORY_FILE - path to the .z5/.z8/.bin story file (default: ./data/z-code/zork1.bin)
+ *   ZCODE_MAX_RETRIES - maximum command retry attempts per turn  (default: 3)
+ *   ZCODE_HISTORY_SIZE - player-facing outputs stored per room   (default: 5)
+ *   OPENROUTER_API_KEY, OPENROUTER_MODEL - required
+ */
+import { TurnResult } from '../interfaces/turn-result';
+export interface ZcodeSession {
+    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;
+}
+export type ZcodeTurnResult = TurnResult;
+export declare class ZcodeLlmEngine {
+    private zmachine;
+    private session;
+    private prompts;
+    private llm;
+    private model;
+    private resolvedFallbackModel;
+    private llmCallCounter;
+    private maxRetries;
+    private historySize;
+    private nextTurnId;
+    private storyPath;
+    private static readonly DEPRECATED_MODEL_REPLACEMENTS;
+    constructor(options?: {
+        storyPath?: string;
+        promptDir?: string;
+    });
+    private createCompletion;
+    private resolveFallbackModel;
+    isRunning(): boolean;
+    /**
+     * Start a new game: launch the Z-machine story, generate the player character, rewrite the
+     * intro text, and return the first TurnResult for the client.
+     */
+    newGame(): Promise<ZcodeTurnResult>;
+    /**
+     * Process player free-text input. Returns the next TurnResult.
+     */
+    processInput(userInput: string): Promise<ZcodeTurnResult>;
+    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<ZcodeTurnResult>;
+    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;
+}