@agent-foundry/replay

TypeScript type definitions and utilities for Agent Foundry replay manifest schema.

Overview

This package provides TypeScript type definitions for the replay manifest schema used in Agent Foundry applications. It includes all necessary types for creating, validating, and working with replay data structures.

Installation

npm install @agent-foundry/replay

yarn add @agent-foundry/replay

pnpm add @agent-foundry/replay

Usage

Basic Import

import type { ReplayManifestV1 } from '@agent-foundry/replay';

Type Definitions

The package exports the following main types:

ReplayManifestV1

The main replay manifest interface containing all game session data:

import type { ReplayManifestV1 } from '@agent-foundry/replay';

const manifest: ReplayManifestV1 = {
  schema: 'lifeRestart.replay.v1',
  gameId: 'lr-abc123-def456',
  gameVersion: '1.0.0',
  createdAt: '2024-01-01T00:00:00.000Z',
  language: 'en-us',
  seed: 12345,
  dataHash: 'abc123...',
  inputs: {
    selectedTalents: [1, 2, 3],
    propertyAllocation: {
      CHR: 5,
      INT: 5,
      STR: 5,
      MNY: 5,
      SPR: 5,
    },
  },
  timeline: [/* ... */],
  highlights: [/* ... */],
  summary: {/* ... */},
};

Supporting Types

• PropertySnapshot - Property values at a point in time
• PropertyEffectsRecord - Property changes applied
• TimelineEntry - Single event in the timeline
• Highlight - Important moment marker
• GameSummary - Final game statistics
• PlayerInputsRecord - Player choices
• HighlightType - Types of highlights

Utility Functions

The package includes utility functions for working with manifests:

import { ReplayManifestUtils } from '@agent-foundry/replay';

// Generate a unique game ID
const gameId = ReplayManifestUtils.generateGameId();
// Returns: "lr-abc123-def456"

// Validate a manifest
const isValid = ReplayManifestUtils.validate(unknownData);
// Returns: boolean

// Parse from JSON string
const manifest = ReplayManifestUtils.parse(jsonString);
// Returns: ReplayManifestV1

// Stringify to JSON
const json = ReplayManifestUtils.stringify(manifest, true);
// Returns: formatted JSON string

Example: Validating a Manifest

import { ReplayManifestUtils } from '@agent-foundry/replay';

function loadReplay(jsonString: string): ReplayManifestV1 {
  try {
    const manifest = ReplayManifestUtils.parse(jsonString);
    return manifest;
  } catch (error) {
    console.error('Invalid replay manifest:', error);
    throw error;
  }
}

Example: Creating a Manifest

import type { ReplayManifestV1 } from '@agent-foundry/replay';
import { ReplayManifestUtils } from '@agent-foundry/replay';

function createManifest(): ReplayManifestV1 {
  return {
    schema: 'lifeRestart.replay.v1',
    gameId: ReplayManifestUtils.generateGameId(),
    gameVersion: '1.0.0',
    createdAt: new Date().toISOString(),
    language: 'en-us',
    seed: Math.floor(Math.random() * 1000000),
    dataHash: '',
    inputs: {
      selectedTalents: [],
      propertyAllocation: {
        CHR: 0,
        INT: 0,
        STR: 0,
        MNY: 0,
        SPR: 0,
      },
    },
    timeline: [],
    highlights: [],
    summary: {
      finalAge: 0,
      rating: '',
      score: 0,
      peakProperties: {
        CHR: 0,
        INT: 0,
        STR: 0,
        MNY: 0,
        SPR: 0,
      },
      totalEvents: 0,
      highlightsCount: 0,
      duration: 0,
    },
  };
}

Type Definitions

ReplayManifestV1

The complete replay manifest structure:

interface ReplayManifestV1 {
  schema: 'lifeRestart.replay.v1';
  gameId: string;
  gameVersion: string;
  createdAt: string;
  language: string;
  seed: number;
  dataHash: string;
  inputs: PlayerInputsRecord;
  timeline: TimelineEntry[];
  highlights: Highlight[];
  summary: GameSummary;
}

TimelineEntry

A single event in the game timeline:

interface TimelineEntry {
  age: number;
  eventId: number;
  description: string;
  grade?: number;
  effects?: PropertyEffectsRecord;
  propertyDeltas: Partial<PropertySnapshot>;
  propertiesAfter: PropertySnapshot;
  branchEventId?: number;
}

Highlight

A marker for important moments:

interface Highlight {
  age: number;
  type: HighlightType;
  label: string;
  importance: number;
  eventId?: number;
  metadata?: Record<string, unknown>;
}

Requirements

• TypeScript 5.3.3 or higher
• Node.js 18+ (for runtime usage)

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• GitHub Issues
• Documentation

Publishing

Prerequisites

1. Ensure you have an npm account and are logged in:

   npm login

2. Verify you have access to the @agent-foundry organization on npm.

Release Steps

1. Update version in package.json:

   # For patch version (1.0.0 -> 1.0.1)
   npm version patch
      
   # For minor version (1.0.0 -> 1.1.0)
   npm version minor
      
   # For major version (1.0.0 -> 2.0.0)
   npm version major

2. Build the package (automatically runs via prepublishOnly script):

   npm run build

3. Verify the build output:

   ls -la dist/

4. Publish to npm:

   npm publish

   The prepublishOnly script will automatically:

   • Clean the dist directory
   • Build the TypeScript files
   • Ensure only the correct files are published (as specified in package.json files field)

5. Verify the publication:

   npm view @agent-foundry/replay

Notes

• The package is configured with "access": "public" in publishConfig, so scoped packages are published publicly
• Only files specified in the files field (dist, src, README.md) will be included in the published package
• The prepublishOnly hook ensures the package is always built before publishing

Version History

1.0.0

• Initial release
• TypeScript type definitions for replay manifest schema
• Utility functions for manifest validation and parsing