@trolleroof/tui 0.2.5 → 0.2.6

package/src/data/bc-export.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, test } from "bun:test";
+import type { TraceEvent, TraceEventChunk } from "../recording/types.js";
+import { extractBehaviorCloningSamples } from "./bc-export.js";
+
+function event(
+  sequence: number,
+  eventType: TraceEvent["event_type"],
+  payload: Record<string, unknown>,
+): TraceEvent {
+  return {
+    schema_version: 2,
+    user_id: "usr_test",
+    game_id: "game_test",
+    chunk_id: sequence <= 4 ? "chk_1" : "chk_2",
+    event_id: `evt_${sequence}`,
+    event_sequence: sequence,
+    event_version: 1,
+    event_type: eventType,
+    visibility: eventType === "engine_checkpoint" ? "privileged" : "policy",
+    client_time_ms: sequence,
+    monotonic_time_us: sequence * 1_000,
+    payload,
+  } as TraceEvent;
+}
+
+function chunk(sequence: number, events: TraceEvent[]): TraceEventChunk {
+  const chunkId = `chk_${sequence}`;
+  return {
+    schema_version: 2,
+    user_id: "usr_test",
+    game_id: "game_test",
+    game_type: "2048",
+    game_version: "1",
+    chunk_id: chunkId,
+    chunk_sequence: sequence,
+    first_event_sequence: events[0]!.event_sequence,
+    last_event_sequence: events.at(-1)!.event_sequence,
+    event_count: events.length,
+    created_at_ms: 10,
+    client: {
+      platform: "tui",
+      application_version: "test",
+      recording_sdk_version: "2",
+    },
+    events: events.map((item) => ({ ...item, chunk_id: chunkId })),
+  };
+}
+
+describe("behavior cloning export", () => {
+  test("joins observations, human controls, and outcomes across chunks", () => {
+    const chunks = [
+      chunk(2, [
+        event(5, "outcome_changed", {
+          score_before: 0,
+          score_after: 4,
+          score_delta: 4,
+          engine_reward: 4,
+          reward_spec_id: "engine_v1",
+          terminal: false,
+          caused_by_event_id: "evt_4",
+          progress: { moved: true, success: false },
+        }),
+        event(6, "control_changed", {
+          based_on_observation_id: "obs_2",
+          control: "left",
+          action: "left",
+          kind: "impulse",
+          actor: "environment",
+        }),
+      ]),
+      chunk(1, [
+        event(1, "episode_started", {
+          game_type: "2048",
+          game_version: "1",
+          ruleset_id: "classic",
+          telemetry_version: 2,
+          platform: "overlay",
+          viewport: { width: 520, height: 740 },
+          control_schema: ["left", "right"],
+          input_semantics: "engine_impulse",
+        }),
+        event(2, "observation", {
+          observation_id: "obs_1",
+          representation: "engine_state_v1",
+          state: { board: [0, 2] },
+        }),
+        event(3, "observation", {
+          observation_id: "obs_2",
+          representation: "engine_state_v1",
+          state: { board: [2, 0] },
+        }),
+        event(4, "control_changed", {
+          based_on_observation_id: "obs_2",
+          control: "right",
+          action: "right",
+          kind: "impulse",
+          actor: "human",
+        }),
+      ]),
+    ];
+
+    expect(extractBehaviorCloningSamples(chunks)).toEqual([
+      expect.objectContaining({
+        schema_version: 1,
+        game_id: "game_test",
+        game_type: "2048",
+        ruleset_id: "classic",
+        observation_id: "obs_2",
+        observation: {
+          representation: "engine_state_v1",
+          state: { board: [2, 0] },
+        },
+        action: "right",
+        reward: 4,
+        score_delta: 4,
+        terminal: false,
+        moved: true,
+      }),
+    ]);
+  });
+
+  test("drops no-op human controls by default and can retain them explicitly", () => {
+    const chunks = [
+      chunk(1, [
+        event(1, "observation", {
+          observation_id: "obs_1",
+          representation: "engine_state_v1",
+          state: { board: [2, 0] },
+        }),
+        event(2, "control_changed", {
+          based_on_observation_id: "obs_1",
+          control: "left",
+          action: "left",
+          kind: "impulse",
+          actor: "human",
+        }),
+        event(3, "outcome_changed", {
+          score_before: 0,
+          score_after: 0,
+          score_delta: 0,
+          engine_reward: 0,
+          reward_spec_id: "engine_v1",
+          terminal: false,
+          caused_by_event_id: "evt_2",
+          progress: { moved: false, success: false },
+        }),
+      ]),
+    ];
+
+    expect(extractBehaviorCloningSamples(chunks)).toEqual([]);
+    expect(extractBehaviorCloningSamples(chunks, { includeNoops: true })).toHaveLength(1);
+  });
+});

package/src/data/bc-export.ts

@@ -0,0 +1,125 @@
+import type {
+  ControlChangedTraceEvent,
+  EpisodeStartedTraceEvent,
+  ObservationTraceEvent,
+  OutcomeChangedTraceEvent,
+  PolicyObservation,
+  TraceActor,
+  TraceEvent,
+  TraceEventChunk,
+} from "../recording/types.js";
+
+export interface BehaviorCloningSample {
+  schema_version: 1;
+  user_id: string;
+  game_id: string;
+  game_type: string;
+  game_version: string;
+  ruleset_id: string | null;
+  event_sequence: number;
+  control_event_id: string;
+  observation_id: string;
+  observation: Omit<PolicyObservation, "observation_id" | "caused_by_event_id">;
+  action: string;
+  actor: TraceActor;
+  reward: number | null;
+  score_delta: number | null;
+  terminal: boolean | null;
+  moved: boolean | null;
+}
+
+export interface BehaviorCloningExportOptions {
+  actors?: readonly TraceActor[];
+  includeNoops?: boolean;
+}
+
+function policyObservation(
+  payload: ObservationTraceEvent["payload"],
+): BehaviorCloningSample["observation"] {
+  const { observation_id: _observationId, caused_by_event_id: _cause, ...observation } = payload;
+  return observation;
+}
+
+function orderedUniqueEvents(chunks: readonly TraceEventChunk[]): TraceEvent[] {
+  const events = new Map<string, TraceEvent>();
+  for (const chunk of chunks) {
+    if (chunk.schema_version !== 2) continue;
+    for (const event of chunk.events) events.set(event.event_id, event);
+  }
+  return [...events.values()].sort((left, right) =>
+    left.game_id.localeCompare(right.game_id) ||
+    left.event_sequence - right.event_sequence
+  );
+}
+
+export function extractBehaviorCloningSamples(
+  chunks: readonly TraceEventChunk[],
+  options: BehaviorCloningExportOptions = {},
+): BehaviorCloningSample[] {
+  const actors = new Set(options.actors ?? ["human"]);
+  const events = orderedUniqueEvents(chunks);
+  const observations = new Map<string, ObservationTraceEvent>();
+  const outcomes = new Map<string, OutcomeChangedTraceEvent>();
+  const rulesets = new Map<string, string>();
+  const chunksByGame = new Map(chunks.map((chunk) => [chunk.game_id, chunk]));
+
+  for (const event of events) {
+    if (event.event_type === "observation") {
+      observations.set(event.payload.observation_id, event);
+    } else if (event.event_type === "outcome_changed") {
+      outcomes.set(event.payload.caused_by_event_id, event);
+    } else if (event.event_type === "episode_started") {
+      rulesets.set(event.game_id, (event as EpisodeStartedTraceEvent).payload.ruleset_id);
+    }
+  }
+
+  const samples: BehaviorCloningSample[] = [];
+  for (const event of events) {
+    if (event.event_type !== "control_changed") continue;
+    const control = event as ControlChangedTraceEvent;
+    if (!actors.has(control.payload.actor) || !control.payload.based_on_observation_id) continue;
+    const observation = observations.get(control.payload.based_on_observation_id);
+    if (!observation || observation.game_id !== control.game_id) continue;
+    const outcome = outcomes.get(control.event_id);
+    const moved = typeof outcome?.payload.progress?.moved === "boolean"
+      ? outcome.payload.progress.moved
+      : null;
+    if (!options.includeNoops && moved === false) continue;
+    const chunk = chunksByGame.get(control.game_id);
+    if (!chunk) continue;
+
+    samples.push({
+      schema_version: 1,
+      user_id: control.user_id,
+      game_id: control.game_id,
+      game_type: chunk.game_type,
+      game_version: chunk.game_version,
+      ruleset_id: rulesets.get(control.game_id) ?? null,
+      event_sequence: control.event_sequence,
+      control_event_id: control.event_id,
+      observation_id: observation.payload.observation_id,
+      observation: policyObservation(observation.payload),
+      action: control.payload.action,
+      actor: control.payload.actor,
+      reward: outcome?.payload.engine_reward ?? null,
+      score_delta: outcome?.payload.score_delta ?? null,
+      terminal: outcome?.payload.terminal ?? null,
+      moved,
+    });
+  }
+  return samples;
+}
+
+export type DatasetSplit = "train" | "validation" | "test";
+
+export function splitForGame(gameId: string): DatasetSplit {
+  let hash = 2_166_136_261;
+  for (const byte of new TextEncoder().encode(gameId)) {
+    hash ^= byte;
+    hash = Math.imul(hash, 16_777_619) >>> 0;
+  }
+  const bucket = hash % 100;
+  if (bucket < 90) return "train";
+  if (bucket < 95) return "validation";
+  return "test";
+}

package/src/data/trajectory.ts

@@ -0,0 +1,103 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+/**
+ * JSONL trajectory logger — one file per episode, one JSON object per line.
+ * Line 1 is an episode header; each subsequent line is a (state, action,
+ * reward) transition; the final line summarizes the episode. This is the
+ * schema the S3 uploader and BC training pipeline will consume.
+ */
+
+export interface EpisodeHeader {
+  kind: "header";
+  episodeId: string;
+  game: string;
+  seed: number;
+  variation: string;
+  goal: string;
+  startedAt: string;
+  schemaVersion: 2;
+}
+
+export interface TransitionLine {
+  kind: "step";
+  t: number;
+  /** Observable state BEFORE the action was taken. */
+  state: unknown;
+  action: string;
+  reward: number;
+  scoreAfter: number;
+  done: boolean;
+}
+
+export interface EpisodeSummary {
+  kind: "summary";
+  steps: number;
+  finalScore: number;
+  success: boolean;
+  endedAt: string;
+  /** "completed" = played to done, "abandoned" = user quit mid-episode. */
+  outcome: "completed" | "abandoned";
+}
+
+export function trajectoryDir(): string {
+  return join(homedir(), ".tui-gamepigeon", "trajectories");
+}
+
+export class TrajectoryLogger {
+  private file: string;
+  private t = 0;
+  private closed = false;
+
+  constructor(game: string, seed: number, variation: string, goal: string) {
+    const dir = trajectoryDir();
+    mkdirSync(dir, { recursive: true });
+    const episodeId = randomUUID();
+    this.file = join(dir, `${game}-${Date.now()}-${episodeId.slice(0, 8)}.jsonl`);
+    const header: EpisodeHeader = {
+      kind: "header",
+      episodeId,
+      game,
+      seed,
+      variation,
+      goal,
+      startedAt: new Date().toISOString(),
+      schemaVersion: 2,
+    };
+    this.write(header);
+  }
+
+  get path(): string {
+    return this.file;
+  }
+
+  logStep(state: unknown, action: string, reward: number, scoreAfter: number, done: boolean): void {
+    if (this.closed) return;
+    const line: TransitionLine = { kind: "step", t: this.t++, state, action, reward, scoreAfter, done };
+    this.write(line);
+  }
+
+  close(finalScore: number, success: boolean, outcome: EpisodeSummary["outcome"]): void {
+    if (this.closed) return;
+    this.closed = true;
+    const summary: EpisodeSummary = {
+      kind: "summary",
+      steps: this.t,
+      finalScore,
+      success,
+      endedAt: new Date().toISOString(),
+      outcome,
+    };
+    this.write(summary);
+  }
+
+  private write(obj: unknown): void {
+    try {
+      appendFileSync(this.file, JSON.stringify(obj) + "\n");
+    } catch {
+      // Logging must never crash gameplay; drop the line on disk errors.
+    }
+  }
+}

package/src/games/connect4/connect4.ts

@@ -0,0 +1,81 @@
+import type { Game, StepResult } from "../../core/game.js";
+import { Rng } from "../../core/rng.js";
+import { COLS, botMove, drop, emptyBoard, isFull, winner, type Board } from "./engine.js";
+
+export type Connect4Action = "left" | "right" | "drop" | "bot_move";
+
+export interface Connect4State {
+  board: Board;
+  cursor: number;
+  /** 0 in progress, 1 player won, 2 bot won, 3 draw. */
+  result: number;
+}
+
+
+export class Connect4Game implements Game<Connect4State, Connect4Action> {
+  readonly name = "connect4";
+  readonly actions = ["left", "right", "drop", "bot_move"] as const;
+  readonly keymap = { space: "drop", enter: "drop", down: "drop" } as const;
+
+  private rng = new Rng(0);
+  private board: Board = emptyBoard();
+  private cursor = 3;
+  private result = 0;
+
+  reset(seed: number): void {
+    this.rng = new Rng(seed);
+    this.board = emptyBoard();
+    this.cursor = 3;
+    this.result = 0;
+  }
+
+  step(action: Connect4Action): StepResult {
+    if (this.result !== 0) return { reward: 0, moved: false, done: true, success: this.result === 1 };
+    if (action === "left" || action === "right") {
+      const nc = this.cursor + (action === "left" ? -1 : 1);
+      if (nc < 0 || nc >= COLS) return { reward: 0, moved: false, done: false, success: false };
+      this.cursor = nc;
+      return { reward: 0, moved: true, done: false, success: false };
+    }
+    if (action === "bot_move") {
+      const botColumn = botMove(this.board, this.rng);
+      drop(this.board, botColumn, 2);
+      const randomEffects = { kind: "bot_move", column: botColumn };
+      if (winner(this.board) === 2) {
+        this.result = 2;
+        return { reward: 0, moved: true, done: true, success: false, randomEffects };
+      }
+      if (isFull(this.board)) {
+        this.result = 3;
+        return { reward: 50, moved: true, done: true, success: false, randomEffects };
+      }
+      return { reward: 0, moved: true, done: false, success: false, randomEffects };
+    }
+    if (drop(this.board, this.cursor, 1) < 0) return { reward: 0, moved: false, done: false, success: false };
+    if (winner(this.board) === 1) {
+      this.result = 1;
+      return { reward: 100, moved: true, done: true, success: true };
+    }
+    if (isFull(this.board)) {
+      this.result = 3;
+      return { reward: 50, moved: true, done: true, success: false };
+    }
+    return { reward: 1, moved: true, done: false, success: false };
+  }
+
+  state(): Connect4State {
+    return { board: this.board.map((r) => [...r]), cursor: this.cursor, result: this.result };
+  }
+
+  score(): number {
+    return this.result === 1 ? 100 : this.result === 3 ? 50 : 0;
+  }
+
+  isOver(): boolean {
+    return this.result !== 0;
+  }
+
+  hasWon(): boolean {
+    return this.result === 1;
+  }
+}

package/src/games/connect4/engine.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from "bun:test";
+import { Rng } from "../../core/rng.js";
+import { COLS, ROWS, botMove, drop, emptyBoard, legalColumns, winner, type Board } from "./engine.js";
+import { Connect4Game } from "./connect4.js";
+
+describe("connect4 engine", () => {
+  it("pieces stack from the bottom", () => {
+    const b = emptyBoard();
+    expect(drop(b, 3, 1)).toBe(ROWS - 1);
+    expect(drop(b, 3, 2)).toBe(ROWS - 2);
+  });
+
+  it("full columns reject drops and leave legalColumns", () => {
+    const b = emptyBoard();
+    for (let i = 0; i < ROWS; i++) drop(b, 0, 1);
+    expect(drop(b, 0, 1)).toBe(-1);
+    expect(legalColumns(b)).not.toContain(0);
+    expect(legalColumns(b)).toHaveLength(COLS - 1);
+  });
+
+  it("detects horizontal, vertical, and diagonal wins", () => {
+    const h = emptyBoard();
+    for (let c = 0; c < 4; c++) drop(h, c, 1);
+    expect(winner(h)).toBe(1);
+
+    const v = emptyBoard();
+    for (let i = 0; i < 4; i++) drop(v, 2, 2);
+    expect(winner(v)).toBe(2);
+
+    const d = emptyBoard();
+    // Build a / diagonal for player 1.
+    const cols = [1, 2, 2, 3, 3, 3];
+    for (const c of cols) drop(d, c, 2);
+    d[ROWS - 1]![0] = 1;
+    d[ROWS - 2]![1] = 1;
+    d[ROWS - 3]![2] = 1;
+    d[ROWS - 4]![3] = 1;
+    expect(winner(d)).toBe(1);
+  });
+
+  it("bot takes an immediate win", () => {
+    const b = emptyBoard();
+    for (let i = 0; i < 3; i++) drop(b, 5, 2);
+    for (let i = 0; i < 2; i++) drop(b, 0, 1);
+    expect(botMove(b, new Rng(1))).toBe(5);
+  });
+
+  it("bot blocks the player's immediate win", () => {
+    const b = emptyBoard();
+    for (let i = 0; i < 3; i++) drop(b, 1, 1);
+    expect(botMove(b, new Rng(1))).toBe(1);
+  });
+});
+
+describe("Connect4Game", () => {
+  it("reports the bot column selected after a bot_move action", () => {
+    const g = new Connect4Game();
+    g.reset(7);
+    g.step("drop");
+    expect(g.step("bot_move").randomEffects).toEqual({
+      kind: "bot_move",
+      column: expect.any(Number),
+    });
+  });
+
+  it("plays a full deterministic game per seed", () => {
+    const g = new Connect4Game();
+    g.reset(1234);
+    let guard = 0;
+    while (!g.isOver() && guard++ < 100) {
+      const res = g.step("drop");
+      if (!res.moved) g.step("left"); // column filled up; aim elsewhere
+    }
+    expect(g.isOver()).toBe(true);
+    expect([0, 50, 100]).toContain(g.score());
+  });
+});

package/src/games/connect4/engine.ts

@@ -0,0 +1,89 @@
+import type { Rng } from "../../core/rng.js";
+
+/**
+ * Pure Connect Four rules on the standard 7×6 board, plus a small
+ * deterministic bot: win if possible, block if necessary, otherwise prefer
+ * central columns with a seeded tie-break.
+ */
+
+export const COLS = 7;
+export const ROWS = 6;
+
+/** 0 empty, 1 player, 2 bot. */
+export type Cell = 0 | 1 | 2;
+export type Board = Cell[][];
+
+export function emptyBoard(): Board {
+  return Array.from({ length: ROWS }, () => Array<Cell>(COLS).fill(0));
+}
+
+export function legalColumns(board: Board): number[] {
+  const cols: number[] = [];
+  for (let c = 0; c < COLS; c++) if (board[0]![c] === 0) cols.push(c);
+  return cols;
+}
+
+/** Drop into `col`; returns the landing row or -1 if the column is full. */
+export function drop(board: Board, col: number, piece: Cell): number {
+  for (let r = ROWS - 1; r >= 0; r--) {
+    if (board[r]![col] === 0) {
+      board[r]![col] = piece;
+      return r;
+    }
+  }
+  return -1;
+}
+
+const DIRS: Array<[number, number]> = [
+  [1, 0],
+  [0, 1],
+  [1, 1],
+  [1, -1],
+];
+
+/** 0 if nobody has four in a row yet. */
+export function winner(board: Board): Cell {
+  for (let r = 0; r < ROWS; r++) {
+    for (let c = 0; c < COLS; c++) {
+      const p = board[r]![c]!;
+      if (p === 0) continue;
+      for (const [dc, dr] of DIRS) {
+        let n = 1;
+        while (n < 4 && board[r + dr * n]?.[c + dc * n] === p) n++;
+        if (n === 4) return p;
+      }
+    }
+  }
+  return 0;
+}
+
+export function isFull(board: Board): boolean {
+  return legalColumns(board).length === 0;
+}
+
+function winsAt(board: Board, col: number, piece: Cell): boolean {
+  const row = drop(board, col, piece);
+  if (row < 0) return false;
+  const won = winner(board) === piece;
+  board[row]![col] = 0;
+  return won;
+}
+
+/** Bot policy: take a win, block the player's win, else center-biased random. */
+export function botMove(board: Board, rng: Rng): number {
+  const legal = legalColumns(board);
+  for (const c of legal) if (winsAt(board, c, 2)) return c;
+  for (const c of legal) if (winsAt(board, c, 1)) return c;
+  // Avoid handing the player an immediate win on top of our piece.
+  const safe = legal.filter((c) => {
+    const row = drop(board, c, 2);
+    const losing = legalColumns(board).some((pc) => winsAt(board, pc, 1));
+    board[row]![c] = 0;
+    return !losing;
+  });
+  const pool = safe.length > 0 ? safe : legal;
+  const weight = (c: number): number => 4 - Math.abs(3 - c);
+  const best = Math.max(...pool.map(weight));
+  const top = pool.filter((c) => weight(c) === best);
+  return top[rng.int(top.length)]!;
+}