85 lines
2.8 KiB
TypeScript
85 lines
2.8 KiB
TypeScript
/**
|
|
* 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;
|
|
}
|