@agent-play/sdk 3.2.2 → 3.3.3

package/dist/browser-Dpx-0L8A.d.ts

@@ -0,0 +1,1078 @@
+import { z } from 'zod';
+
+/**
+ * Domain types for sessions, journeys, agents, and the shared world map exposed by the SDK and server.
+ */
+/** Role for a single line in the interaction log / chat stream. */
+type WorldInteractionRole = "user" | "assistant" | "tool";
+/**
+ * Payload for {@link RemotePlayWorld.recordInteraction}.
+ *
+ * @property playerId - Player id returned from `addAgent` / `addPlayer`.
+ * @property role - Who "spoke" the line.
+ * @property text - Plain text; may be truncated for display server-side.
+ */
+type RecordInteractionInput = {
+    playerId: string;
+    role: WorldInteractionRole;
+    text: string;
+};
+/** How the watch UI should render and coerce a single assist tool argument. */
+type AssistToolFieldType = "string" | "number" | "boolean";
+/**
+ * Per-parameter metadata for assist tools. Legacy snapshots may omit `fieldType`; the UI treats that as `"string"`.
+ */
+type AssistToolParameterSpec = {
+    fieldType: AssistToolFieldType;
+    field?: string;
+};
+/**
+ * Metadata for a tool whose name starts with `assist_`, shown as assist actions on the watch UI.
+ *
+ * @property parameters - Derived from Zod object `schema` when present: each key maps to
+ *   {@link AssistToolParameterSpec} with `fieldType` from schema introspection. May include `_note` when no schema shape exists.
+ */
+type AssistToolSpec = {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+};
+/**
+ * Serializable shape returned by {@link langchainRegistration} for agent registration.
+ *
+ * @property type - Always `"langchain"` for this adapter.
+ * @property toolNames - All tool names from the agent (must include `chat_tool`).
+ * @property assistTools - Subset of tools with `assist_` prefix, for UI buttons.
+ */
+type LangChainAgentRegistration = {
+    type: "langchain";
+    toolNames: string[];
+    assistTools?: AssistToolSpec[];
+};
+/** Minimal player identity in the SDK (without preview URL). */
+type PlayAgentInformation = {
+    id: string;
+    name: string;
+    sid: string;
+    createdAt: Date;
+    updatedAt: Date;
+};
+/** Input fields for {@link AddAgentInput} / {@link AddPlayerInput} before `agent` is attached. */
+type PlatformAgentInformation = {
+    name: string;
+    type: string;
+    version?: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+};
+/**
+ * Register an automation agent in the world, tied to **agent node identity**.
+ *
+ * Use **`langchainRegistration(agent)`** for `agent` (requires a **`chat_tool`** tool; `assist_*`
+ * tools are indexed for the watch UI).
+ *
+ * **`nodeId`** is the **agent node id** (from **`agent-play create`** when the server uses a repository).
+ * It is sent on the wire as `agentId` for server compatibility; treating it as a node id makes the
+ * contract explicit for billing, validation, and event attribution.
+ */
+type P2aEnableFlag = "on" | "off";
+type RealtimeWebrtcClientSecret = {
+    clientSecret: string;
+    expiresAt?: string;
+    model: string;
+    voice?: string;
+};
+/** OpenAI Realtime minting options used by {@link RemotePlayWorld.initAudio}. */
+type RemotePlayWorldOpenAiAudioOptions = {
+    /** Server-side OpenAI key used to mint ephemeral browser client secrets. */
+    apiKey?: string;
+    /** Realtime model id, defaults to `gpt-realtime`. */
+    model?: string;
+    /** Realtime voice id, defaults to `marin`. */
+    voice?: string;
+    /** Explicit system instructions for the realtime session. */
+    instructions?: string;
+    /** Template fallback for instructions; `{{agentName}}` placeholder is supported. */
+    instructionsTemplate?: string;
+};
+/** Configuration payload for enabling SDK-managed realtime audio initialization. */
+type RemotePlayWorldInitAudioOptions = {
+    openai: RemotePlayWorldOpenAiAudioOptions;
+};
+type AddAgentInput = PlatformAgentInformation & {
+    /** Registration from {@link langchainRegistration}. */
+    agent: LangChainAgentRegistration;
+    /** Main node id that owns the agent (required on repository-backed servers). */
+    mainNodeId?: string;
+    /** Agent node id — same value the server stores as registered `agentId`. */
+    nodeId: string;
+    /**
+     * When **`"on"`**, registration enables OpenAI Realtime provisioning for this agent.
+     * Omitted or **`"off"`** disables realtime voice for this registration.
+     */
+    enableP2a?: P2aEnableFlag;
+    /**
+     * Per-agent instructions for OpenAI Realtime when **`enableP2a`** is **`"on"`** (e.g. from
+     * **`personality.txt`**). Ignored when **`initAudio`** was given explicit **`openai.instructions`**,
+     * which still wins as a global override.
+     */
+    realtimeInstructions?: string;
+};
+/**
+ * Register a player (agent) in the world.
+ *
+ * @deprecated Prefer {@link AddAgentInput} and `RemotePlayWorld.prototype.addAgent` for SDK and automation; use `nodeId` there instead of `agentId`.
+ *
+ * Use **`langchainRegistration(agent)`** for `agent` (requires a **`chat_tool`** tool; `assist_*`
+ * tools are indexed for the watch UI).
+ *
+ * **`agentId`** is required: use an id from **`agent-play create`** when the server uses a repository
+ * (with account **`passwHash`** from **`RemotePlayWorld`**), or any stable string for local dev without Redis.
+ */
+type AddPlayerInput = PlatformAgentInformation & {
+    /** Registration from {@link langchainRegistration}. */
+    agent: LangChainAgentRegistration;
+    /** Main node id that owns the agent (required on repository-backed servers). */
+    mainNodeId?: string;
+    /** Registered agent id (or session-local id without Redis). */
+    agentId: string;
+    /**
+     * When **`"on"`**, registration enables OpenAI Realtime provisioning for this agent.
+     * Omitted or **`"off"`** disables realtime voice for this registration.
+     *
+     * Same semantics as {@link AddAgentInput} **`enableP2a`**.
+     */
+    enableP2a?: P2aEnableFlag;
+    /**
+     * Same semantics as {@link AddAgentInput} **`realtimeInstructions`**.
+     */
+    realtimeInstructions?: string;
+};
+/** Zone counter event surfaced on snapshots and signals. */
+type ZoneEventInfo = {
+    zoneCount: number;
+    flagged?: boolean;
+    at: string;
+};
+/** Yield counter event surfaced on snapshots and signals. */
+type YieldEventInfo = {
+    yieldCount: number;
+    at: string;
+};
+/** Repository-backed summary returned with `addAgent` when the agent is (or maps to) a stored registration. */
+type RegisteredAgentSummary = {
+    agentId: string;
+    name: string;
+    toolNames: string[];
+    zoneCount: number;
+    yieldCount: number;
+    flagged: boolean;
+};
+/** Result of `addAgent` / `addPlayer` including watch URL and registered-agent metadata from the server. */
+type RegisteredPlayer = PlayAgentInformation & {
+    previewUrl: string;
+    registeredAgent: RegisteredAgentSummary;
+    /** Echo of registration-time P2A flag (defaults to **`"off"`**). */
+    enableP2a: P2aEnableFlag;
+    /** Optional OpenAI Realtime WebRTC client-secret payload for browser-side direct voice. */
+    realtimeWebrtc?: RealtimeWebrtcClientSecret;
+    connectionId?: string;
+    leaseTtlSeconds?: number;
+};
+/** First step of a journey: user message origin. */
+type OriginJourneyStep = {
+    type: "origin";
+    content: string;
+    messageId: string;
+};
+/** Middle step: tool invocation on the map. */
+type StructureJourneyStep = {
+    type: "structure";
+    toolName: string;
+    toolCallId: string;
+    args: Record<string, unknown>;
+    result?: string;
+};
+/** Final step: assistant reply. */
+type DestinationJourneyStep = {
+    type: "destination";
+    content: string;
+    messageId: string;
+};
+/** Union of journey step shapes. */
+type JourneyStep = OriginJourneyStep | StructureJourneyStep | DestinationJourneyStep;
+/**
+ * Ordered journey with timestamps; sent to the server via `recordJourney`.
+ *
+ * @property steps - Ordered path from origin through tool steps to destination.
+ * @property startedAt, completedAt - Wall times for the run (client or server).
+ */
+type Journey = {
+    steps: JourneyStep[];
+    startedAt: Date;
+    completedAt: Date;
+};
+/** Journey step after server assigns coordinates (and optional structure id). */
+type PositionedStep = JourneyStep & {
+    x?: number;
+    y?: number;
+    structureId?: string;
+};
+type AgentPlayWorldMapBounds = {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+};
+/**
+ * One agent on the world map. Coordinates are grid positions; the server enforces unique `(x,y)` per occupant.
+ */
+type AgentPlayWorldMapAgentOccupant = {
+    kind: "agent";
+    nodeId?: string;
+    agentId: string;
+    name: string;
+    x: number;
+    y: number;
+    /**
+     * Integration label from addPlayer `type` (e.g. `langchain`). Populated from the snapshot field `platform`. The legacy wire field `agentType` is deprecated and accepted only for backward compatibility when parsing JSON.
+     */
+    platform?: string;
+    toolNames?: string[];
+    assistToolNames?: string[];
+    assistTools?: AssistToolSpec[];
+    hasChatTool?: boolean;
+    enableP2a?: P2aEnableFlag;
+    realtimeInstructions?: string;
+    realtimeWebrtc?: RealtimeWebrtcClientSecret;
+    stationary?: boolean;
+    lastUpdate?: unknown;
+    recentInteractions?: Array<{
+        role: WorldInteractionRole;
+        text: string;
+        at: string;
+        seq: number;
+    }>;
+    zoneCount?: number;
+    yieldCount?: number;
+    flagged?: boolean;
+    onZone?: ZoneEventInfo;
+    onYield?: YieldEventInfo;
+};
+/** MCP server shown as a separate map occupant (distinct from LangChain agents). */
+type AgentPlayWorldMapHumanOccupant = {
+    kind: "human";
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    interactive?: boolean;
+};
+/** MCP server shown as a separate map occupant (distinct from LangChain agents). */
+type AgentPlayWorldMapMcpOccupant = {
+    kind: "mcp";
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    url?: string;
+};
+type AgentPlaySpaceAmenityKind = "supermarket" | "shop" | "car_wash";
+type AgentPlaySpaceOwner = {
+    displayName: string;
+    playerId?: string;
+    nodeId?: string;
+};
+type AgentPlaySpaceCatalogEntry = {
+    id: string;
+    name: string;
+    description: string;
+    designKey: string;
+    owner: AgentPlaySpaceOwner;
+    amenities: AgentPlaySpaceAmenityKind[];
+    activityObjectIds?: string[];
+};
+/** Map anchor linking one or more authored spaces (see {@link AgentPlaySpaceCatalogEntry}). */
+type AgentPlayWorldMapStructureOccupant = {
+    kind: "structure";
+    id: string;
+    name: string;
+    x: number;
+    y: number;
+    worldId: string;
+    spaceIds: string[];
+    /** When true, the anchor is fixed map furniture (e.g. authored spaces). */
+    stationary?: boolean;
+    primaryAmenity?: AgentPlaySpaceAmenityKind;
+    amenities?: AgentPlaySpaceAmenityKind[];
+};
+/** Spatial index: axis-aligned bounds plus every agent and MCP registration placed on the grid. */
+type AgentPlayWorldMap = {
+    bounds: AgentPlayWorldMapBounds;
+    occupants: (AgentPlayWorldMapHumanOccupant | AgentPlayWorldMapAgentOccupant | AgentPlayWorldMapMcpOccupant | AgentPlayWorldMapStructureOccupant)[];
+};
+/** Wire shape for seeded world zones (matches server snapshot `worldLayout`). */
+type AgentPlayWorldLayoutZone = {
+    id: string;
+    streetId: string;
+    streetLabel: string;
+    rect: AgentPlayWorldMapBounds;
+    primaryGroup: "agent" | "space" | "mcp";
+    allowedGroups: readonly ("agent" | "space" | "mcp")[];
+};
+type AgentPlayWorldLayout = {
+    rev: number;
+    bounds: AgentPlayWorldMapBounds;
+    zones: AgentPlayWorldLayoutZone[];
+    streets: readonly {
+        id: string;
+        label: string;
+    }[];
+};
+/**
+ * Session snapshot from {@link RemotePlayWorld.getWorldSnapshot}.
+ * Agents and MCP servers appear only under **`worldMap.occupants`** (no separate `players` list).
+ */
+type AgentPlaySnapshot = {
+    sid: string;
+    worldMap: AgentPlayWorldMap;
+    worldLayout?: AgentPlayWorldLayout;
+    spaces?: AgentPlaySpaceCatalogEntry[];
+    mcpServers?: Array<{
+        id: string;
+        name: string;
+        url?: string;
+    }>;
+};
+type PlayerChainNotifyNodeRef = {
+    stableKey: string;
+    leafIndex: number;
+    removed?: boolean;
+    updatedAt?: string;
+};
+type PlayerChainFanoutNotify = {
+    updatedAt: string;
+    nodes: PlayerChainNotifyNodeRef[];
+};
+type PlayerChainGenesisStableKey = "__genesis__";
+type PlayerChainHeaderStableKey = "__header__";
+type PlayerChainGenesisNode = {
+    kind: "genesis";
+    stableKey: PlayerChainGenesisStableKey;
+    text: string;
+};
+type PlayerChainHeaderNode = {
+    kind: "header";
+    stableKey: PlayerChainHeaderStableKey;
+    sid: string;
+    bounds: AgentPlayWorldMapBounds;
+};
+type PlayerChainOccupantRemovedNode = {
+    kind: "occupant";
+    stableKey: string;
+    removed: true;
+};
+type PlayerChainOccupantPresentNode = {
+    kind: "occupant";
+    stableKey: string;
+    removed: false;
+    occupant: AgentPlayWorldMapHumanOccupant | AgentPlayWorldMapAgentOccupant | AgentPlayWorldMapMcpOccupant | AgentPlayWorldMapStructureOccupant;
+};
+type PlayerChainSpaceRemovedNode = {
+    kind: "space";
+    stableKey: string;
+    removed: true;
+};
+type PlayerChainSpacePresentNode = {
+    kind: "space";
+    stableKey: string;
+    removed: false;
+    space: AgentPlaySpaceCatalogEntry;
+};
+type PlayerChainNodeResponse = PlayerChainGenesisNode | PlayerChainHeaderNode | PlayerChainOccupantRemovedNode | PlayerChainOccupantPresentNode | PlayerChainSpaceRemovedNode | PlayerChainSpacePresentNode;
+/** Full journey + path update (SSE `world:journey`); coordinates are embedded in `path` steps. */
+type WorldJourneyUpdate = {
+    playerId: string;
+    journey: Journey;
+    path: PositionedStep[];
+};
+
+/**
+ * Axis-aligned rectangle in world coordinates (grid units). Used by the server to clamp paths
+ * and by the watch UI to clamp joystick-driven movement.
+ *
+ * @remarks **Consumers:** {@link clampWorldPosition}, {@link boundsContain}; server `PlayWorld` and
+ * play-ui canvas both import these helpers from `@agent-play/sdk`.
+ */
+type WorldBounds = {
+    /** Inclusive minimum X. */
+    minX: number;
+    /** Inclusive minimum Y. */
+    minY: number;
+    /** Inclusive maximum X. */
+    maxX: number;
+    /** Inclusive maximum Y. */
+    maxY: number;
+};
+/** Minimum playable span aligned with the watch canvas scrolling world (~20×20 cells). */
+declare const MINIMUM_PLAY_WORLD_BOUNDS: WorldBounds;
+declare function expandBoundsToMinimumPlayArea(bounds: WorldBounds): WorldBounds;
+/**
+ * Clamps a point to lie inside `bounds` along both axes.
+ *
+ * @param p - Position with `x` and `y` in world units.
+ * @param bounds - Valid rectangle (`min` ≤ `max` per axis).
+ * @returns Same point if inside, otherwise clamped to the nearest edge.
+ *
+ * @remarks **Callers:** server `PlayWorld` path enrichment; play-ui joystick and preview. **Callees:** `Math.min/Math.max`.
+ */
+declare function clampWorldPosition(p: {
+    x: number;
+    y: number;
+}, bounds: WorldBounds): {
+    x: number;
+    y: number;
+};
+/**
+ * @returns Whether `p` lies inside or on the border of `bounds`.
+ *
+ * @remarks **Callers:** optional UI checks. **Callees:** none.
+ */
+declare function boundsContain(bounds: WorldBounds, p: {
+    x: number;
+    y: number;
+}): boolean;
+
+type OccupancyGridPoint = {
+    x: number;
+    y: number;
+};
+declare const OCCUPANCY_POINT_MULTIPLIER = 5;
+declare const CONTINUOUS_RENDER_OFFSET = 0.2;
+declare const DEFAULT_AGENT_SPAWN_MIN_DISTANCE = 0.9;
+/** @deprecated Prefer {@link WorldLayout} zones from snapshot; quartile geometry is legacy. */
+declare const SPATIAL_ZONE_INDEX_AGENTS = 0;
+/** @deprecated Prefer {@link WorldLayout} zones from snapshot; quartile geometry is legacy. */
+declare const SPATIAL_ZONE_INDEX_SPACES = 2;
+/** @deprecated Prefer layout zone rects; quartile geometry is legacy. */
+declare function spatialZoneBounds(quartileIndex: number): WorldBounds;
+/** @deprecated Prefer {@link centerOfZone} with a layout zone. */
+declare function spatialZoneCenter(quartileIndex: number): OccupancyGridPoint;
+declare function pointCellInRect(wx: number, wy: number, bounds: WorldBounds): boolean;
+declare function listOccupancyPointsInRect(bounds: WorldBounds): readonly OccupancyGridPoint[];
+declare function buildRankedOccupancyPointsInRect(bounds: WorldBounds): OccupancyGridPoint[];
+/** @deprecated Prefer {@link pointCellInZone} with a layout zone. */
+declare function pointCellInSpatialZone(wx: number, wy: number, zoneIndex: number): boolean;
+/** @deprecated Prefer {@link listOccupancyPointsForZone}. */
+declare function listOccupancyPointsForSpatialZone(zoneIndex: number): readonly OccupancyGridPoint[];
+/** @deprecated Prefer {@link occupancyPointsGroupedByZones}. */
+declare function occupancyPointsGroupedBySpatialZone(): readonly (readonly OccupancyGridPoint[])[];
+/** @deprecated Prefer points from the agent primary zone in {@link WorldLayout}. */
+declare function listAllowedOccupancyPoints(): readonly OccupancyGridPoint[];
+declare function occupancyKeyForPosition(x: number, y: number): string;
+/** @deprecated Prefer {@link buildRankedOccupancyPointsForZone}. */
+declare function buildRankedOccupancyPointsForSpatialZone(zoneIndex: number): OccupancyGridPoint[];
+/** Back-compat: agent-zone ranking only. */
+declare function buildRankedOccupancyPoints(): OccupancyGridPoint[];
+declare function boundingWorldRectForOccupancyPoints(points: readonly OccupancyGridPoint[]): {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+} | null;
+declare function isAgentSpawnOccupancyPointAvailableInRect(input: {
+    rect: WorldBounds;
+    point: OccupancyGridPoint;
+    occupiedKeys: ReadonlySet<string>;
+    existingOccupants: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    minDistance?: number;
+}): boolean;
+declare function isSpaceAnchorOccupancyPointAvailableInRect(input: {
+    rect: WorldBounds;
+    point: OccupancyGridPoint;
+    occupiedKeys: ReadonlySet<string>;
+    existingOccupants: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    structureAnchors: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    minDistance: number;
+    structureMinDistance: number;
+}): boolean;
+declare function isAgentSpawnOccupancyPointAvailable(input: {
+    point: OccupancyGridPoint;
+    occupiedKeys: ReadonlySet<string>;
+    existingOccupants: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    minDistance?: number;
+}): boolean;
+declare function isSpaceAnchorOccupancyPointAvailable(input: {
+    point: OccupancyGridPoint;
+    occupiedKeys: ReadonlySet<string>;
+    existingOccupants: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    structureAnchors: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    minDistance: number;
+    structureMinDistance: number;
+}): boolean;
+
+type StreetPoolEntry = {
+    id: string;
+    label: string;
+};
+declare const STREET_NAME_POOL: readonly StreetPoolEntry[];
+declare function getStreetPoolEntryById(id: string): StreetPoolEntry | undefined;
+
+type OccupantGroup = "agent" | "space" | "mcp";
+type Street = {
+    id: string;
+    label: string;
+};
+type Zone = {
+    id: string;
+    streetId: string;
+    streetLabel: string;
+    rect: WorldBounds;
+    primaryGroup: OccupantGroup;
+    allowedGroups: readonly OccupantGroup[];
+};
+type WorldLayout = {
+    rev: number;
+    bounds: WorldBounds;
+    zones: readonly Zone[];
+    streets: readonly Street[];
+};
+declare function streetFromPoolEntry(entry: StreetPoolEntry): Street;
+declare function zonesForGroup(layout: WorldLayout, group: OccupantGroup): readonly Zone[];
+declare function primaryZoneForGroup(layout: WorldLayout, group: OccupantGroup): Zone | undefined;
+declare function enumerateIntegerCellsInRect(rect: WorldBounds): OccupancyGridPoint[];
+declare function cellsForZone(zone: Zone): readonly OccupancyGridPoint[];
+declare function centerOfZone(zone: Zone): OccupancyGridPoint;
+declare function pointCellInZone(wx: number, wy: number, zone: Zone): boolean;
+declare function listOccupancyPointsForZone(zone: Zone): readonly OccupancyGridPoint[];
+declare function buildRankedOccupancyPointsForZone(zone: Zone): OccupancyGridPoint[];
+declare function occupancyPointsGroupedByZones(layout: WorldLayout): readonly (readonly OccupancyGridPoint[])[];
+declare function nextStreetFromPool(usedStreetIds: ReadonlySet<string>): StreetPoolEntry | undefined;
+declare function pickZoneForGroup(layout: WorldLayout, group: OccupantGroup): Zone;
+declare function availableCellsForZone(zone: Zone, occupiedCellKeys: ReadonlySet<string>): OccupancyGridPoint[];
+declare function isAgentSpawnOccupancyPointAvailableInZone(input: {
+    zone: Zone;
+    point: OccupancyGridPoint;
+    occupiedKeys: ReadonlySet<string>;
+    existingOccupants: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    minDistance?: number;
+}): boolean;
+declare function isSpaceAnchorOccupancyPointAvailableInZone(input: {
+    zone: Zone;
+    point: OccupancyGridPoint;
+    occupiedKeys: ReadonlySet<string>;
+    existingOccupants: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    structureAnchors: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>;
+    minDistance: number;
+    structureMinDistance: number;
+}): boolean;
+type WorldLayoutBoundsField = "minX" | "minY" | "maxX" | "maxY";
+declare function migrateWorldLayoutBounds(input: {
+    layout: WorldLayout;
+    bounds: WorldBounds;
+}): WorldLayout;
+declare function applyBoundsFieldUpdateToLayout(input: {
+    layout: WorldLayout;
+    field: WorldLayoutBoundsField;
+    value: number;
+}): WorldLayout;
+declare function createVerticalStripSeedLayout(input: {
+    bounds: WorldBounds;
+    streets: readonly [StreetPoolEntry, StreetPoolEntry, StreetPoolEntry];
+}): WorldLayout;
+
+/**
+ * @packageDocumentation
+ * @module @agent-play/sdk/space-content-model
+ *
+ * Zod schemas and helpers for the **server-authoritative content** a space owns
+ * inside each amenity kind, plus the **per-player wallet** that funds purchases.
+ *
+ * **Scope**
+ * - {@link SaleStateSchema}: shared sub-record describing whether an item is
+ *   still available for purchase or has already been sold (and to whom).
+ * - {@link ShopItemSchema}, {@link SupermarketItemSchema}, {@link CarWashCarSchema}:
+ *   the three amenity-content kinds. Each carries a `sale` block.
+ * - {@link PlayerWalletSchema} + {@link createInitialPlayerWallet}: every player
+ *   starts with **`$70`** ({@link DEFAULT_PLAYER_WALLET_BALANCE_USD}); the wallet
+ *   is seeded lazily on first read by the server.
+ * - {@link PurchaseRecordSchema}: append-only audit row stored per player.
+ * - {@link isItemAvailableForPurchase}: pure helper consumed by the `purchase`
+ *   RPC (server) and the item-tooltip / sprite renderers (client).
+ *
+ * @see ../../packages/web-ui/src/server/agent-play/session-store.ts for the
+ *      session-store interface that persists these records.
+ * @see ../../packages/web-ui/src/app/api/agent-play/sdk/rpc/route.ts for the
+ *      RPC handlers that write them.
+ */
+
+/**
+ * Sale state attached to every amenity content record.
+ *
+ * @remarks
+ * Records start as `{ status: "available" }`. The `purchase` RPC flips them
+ * to `{ status: "sold", soldToPlayerId, soldAt }` inside a `WATCH`/`MULTI`
+ * transaction so concurrent buyers cannot both succeed.
+ *
+ * @example
+ * ```ts
+ * SaleStateSchema.parse({ status: "available" });
+ * SaleStateSchema.parse({
+ *   status: "sold",
+ *   soldToPlayerId: "player-42",
+ *   soldAt: new Date().toISOString(),
+ * });
+ * ```
+ *
+ * @public
+ */
+declare const SaleStateSchema: z.ZodObject<{
+    status: z.ZodEnum<["available", "sold"]>;
+    soldToPlayerId: z.ZodOptional<z.ZodString>;
+    soldAt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "available" | "sold";
+    soldToPlayerId?: string | undefined;
+    soldAt?: string | undefined;
+}, {
+    status: "available" | "sold";
+    soldToPlayerId?: string | undefined;
+    soldAt?: string | undefined;
+}>;
+/** Runtime type derived from {@link SaleStateSchema}. @public */
+type SaleState = z.infer<typeof SaleStateSchema>;
+/**
+ * Shop amenity item — books, music, coffee.
+ *
+ * @remarks
+ * Inserted by `addShopItem` AQL / RPC. Always starts with
+ * `sale.status === "available"`. Client renders this via
+ * `sprite-shop-item.ts` and the bookstore amenity stage.
+ *
+ * @example
+ * ```ts
+ * ShopItemSchema.parse({
+ *   id: "shop-1",
+ *   spaceId: "space-42",
+ *   type: "book",
+ *   name: "Hitchhiker's Guide",
+ *   description: "Don't panic.",
+ *   priceUsd: 12.5,
+ *   createdAt: new Date().toISOString(),
+ *   sale: { status: "available" },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare const ShopItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    spaceId: z.ZodString;
+    type: z.ZodEnum<["book", "music", "coffee"]>;
+    name: z.ZodString;
+    description: z.ZodString;
+    priceUsd: z.ZodNumber;
+    createdAt: z.ZodString;
+    sale: z.ZodObject<{
+        status: z.ZodEnum<["available", "sold"]>;
+        soldToPlayerId: z.ZodOptional<z.ZodString>;
+        soldAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    }, {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    type: "book" | "music" | "coffee";
+    id: string;
+    spaceId: string;
+    name: string;
+    description: string;
+    priceUsd: number;
+    createdAt: string;
+    sale: {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    };
+}, {
+    type: "book" | "music" | "coffee";
+    id: string;
+    spaceId: string;
+    name: string;
+    description: string;
+    priceUsd: number;
+    createdAt: string;
+    sale: {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    };
+}>;
+/** Runtime type for {@link ShopItemSchema}. @public */
+type ShopItem = z.infer<typeof ShopItemSchema>;
+/**
+ * Supermarket amenity item — laid out on a 4×5 grid of slots.
+ *
+ * @remarks
+ * `row` selects the section (1=Fruits, 2=Mens, 3=Womens, 4=Kids in the
+ * client-side stage); `column` is 1..5. If the AQL caller omits `column` the
+ * server picks the next free slot in that row.
+ *
+ * @example
+ * ```ts
+ * SupermarketItemSchema.parse({
+ *   id: "sm-1",
+ *   spaceId: "space-42",
+ *   row: 1,
+ *   column: 3,
+ *   name: "Apple",
+ *   description: "fresh",
+ *   priceUsd: 1.25,
+ *   createdAt: new Date().toISOString(),
+ *   sale: { status: "available" },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare const SupermarketItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    spaceId: z.ZodString;
+    row: z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>;
+    column: z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>]>;
+    name: z.ZodString;
+    description: z.ZodString;
+    priceUsd: z.ZodNumber;
+    createdAt: z.ZodString;
+    sale: z.ZodObject<{
+        status: z.ZodEnum<["available", "sold"]>;
+        soldToPlayerId: z.ZodOptional<z.ZodString>;
+        soldAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    }, {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    spaceId: string;
+    name: string;
+    description: string;
+    priceUsd: number;
+    createdAt: string;
+    sale: {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    };
+    row: 1 | 2 | 3 | 4;
+    column: 1 | 5 | 2 | 3 | 4;
+}, {
+    id: string;
+    spaceId: string;
+    name: string;
+    description: string;
+    priceUsd: number;
+    createdAt: string;
+    sale: {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    };
+    row: 1 | 2 | 3 | 4;
+    column: 1 | 5 | 2 | 3 | 4;
+}>;
+/** Runtime type for {@link SupermarketItemSchema}. @public */
+type SupermarketItem = z.infer<typeof SupermarketItemSchema>;
+/**
+ * Car-wash amenity car parked in one of nine slots.
+ *
+ * @remarks
+ * Client renders the car via `sprite-car.ts`, parameterised by `colorHex`.
+ * Sold cars flip to a desaturated palette plus a `SOLD` banner overlay.
+ *
+ * @example
+ * ```ts
+ * CarWashCarSchema.parse({
+ *   id: "car-1",
+ *   spaceId: "space-42",
+ *   slot: 5,
+ *   name: "Mustang",
+ *   model: "GT",
+ *   year: 2023,
+ *   priceUsd: 45000,
+ *   colorHex: "#ff3344",
+ *   createdAt: new Date().toISOString(),
+ *   sale: { status: "available" },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare const CarWashCarSchema: z.ZodObject<{
+    id: z.ZodString;
+    spaceId: z.ZodString;
+    slot: z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>, z.ZodLiteral<5>, z.ZodLiteral<6>, z.ZodLiteral<7>, z.ZodLiteral<8>, z.ZodLiteral<9>]>;
+    name: z.ZodString;
+    model: z.ZodString;
+    year: z.ZodNumber;
+    priceUsd: z.ZodNumber;
+    colorHex: z.ZodString;
+    createdAt: z.ZodString;
+    sale: z.ZodObject<{
+        status: z.ZodEnum<["available", "sold"]>;
+        soldToPlayerId: z.ZodOptional<z.ZodString>;
+        soldAt: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    }, {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    spaceId: string;
+    name: string;
+    priceUsd: number;
+    createdAt: string;
+    sale: {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    };
+    slot: 1 | 5 | 2 | 3 | 7 | 6 | 4 | 8 | 9;
+    model: string;
+    year: number;
+    colorHex: string;
+}, {
+    id: string;
+    spaceId: string;
+    name: string;
+    priceUsd: number;
+    createdAt: string;
+    sale: {
+        status: "available" | "sold";
+        soldToPlayerId?: string | undefined;
+        soldAt?: string | undefined;
+    };
+    slot: 1 | 5 | 2 | 3 | 7 | 6 | 4 | 8 | 9;
+    model: string;
+    year: number;
+    colorHex: string;
+}>;
+/** Runtime type for {@link CarWashCarSchema}. @public */
+type CarWashCar = z.infer<typeof CarWashCarSchema>;
+/**
+ * Default starting balance, in USD, seeded into every new player wallet.
+ *
+ * @remarks
+ * The session store seeds the wallet lazily on first read via
+ * {@link createInitialPlayerWallet} inside an atomic `MULTI`, so two
+ * simultaneous first reads still leave the balance at exactly `$70`.
+ *
+ * @defaultValue 70
+ * @public
+ */
+declare const DEFAULT_PLAYER_WALLET_BALANCE_USD = 70;
+/**
+ * Per-player wallet.
+ *
+ * @remarks
+ * Stored at `agent-play:${hostId}:player:${playerId}:wallet`. Mutated atomically
+ * by the `purchase` RPC (decrement) and by the optional AQL `SET WALLET`
+ * statement.
+ *
+ * @public
+ */
+declare const PlayerWalletSchema: z.ZodObject<{
+    playerId: z.ZodString;
+    balanceUsd: z.ZodNumber;
+    currency: z.ZodLiteral<"USD">;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    playerId: string;
+    balanceUsd: number;
+    currency: "USD";
+    updatedAt: string;
+}, {
+    playerId: string;
+    balanceUsd: number;
+    currency: "USD";
+    updatedAt: string;
+}>;
+/** Runtime type for {@link PlayerWalletSchema}. @public */
+type PlayerWallet = z.infer<typeof PlayerWalletSchema>;
+/**
+ * Build a fresh wallet seeded with the {@link DEFAULT_PLAYER_WALLET_BALANCE_USD}
+ * balance for an unseen player.
+ *
+ * @example
+ * ```ts
+ * const wallet = createInitialPlayerWallet({
+ *   playerId: "player-42",
+ *   now: new Date().toISOString(),
+ * });
+ * // → { playerId: "player-42", balanceUsd: 70, currency: "USD", updatedAt: ... }
+ * ```
+ *
+ * @public
+ */
+declare function createInitialPlayerWallet(input: {
+    playerId: string;
+    now: string;
+}): PlayerWallet;
+/**
+ * Audit record appended each time a player completes a purchase.
+ *
+ * @remarks
+ * Stored as a Redis list at `agent-play:${hostId}:player:${playerId}:purchases`
+ * with `LPUSH` so the newest entry is at index 0.
+ *
+ * @public
+ */
+declare const PurchaseRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    playerId: z.ZodString;
+    spaceId: z.ZodString;
+    amenityKind: z.ZodEnum<["shop", "supermarket", "car_wash"]>;
+    itemRef: z.ZodObject<{
+        kind: z.ZodEnum<["shop", "supermarket", "carwash"]>;
+        id: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        kind: "supermarket" | "shop" | "carwash";
+    }, {
+        id: string;
+        kind: "supermarket" | "shop" | "carwash";
+    }>;
+    priceUsd: z.ZodNumber;
+    at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    at: string;
+    id: string;
+    spaceId: string;
+    priceUsd: number;
+    playerId: string;
+    amenityKind: "supermarket" | "shop" | "car_wash";
+    itemRef: {
+        id: string;
+        kind: "supermarket" | "shop" | "carwash";
+    };
+}, {
+    at: string;
+    id: string;
+    spaceId: string;
+    priceUsd: number;
+    playerId: string;
+    amenityKind: "supermarket" | "shop" | "car_wash";
+    itemRef: {
+        id: string;
+        kind: "supermarket" | "shop" | "carwash";
+    };
+}>;
+/** Runtime type for {@link PurchaseRecordSchema}. @public */
+type PurchaseRecord = z.infer<typeof PurchaseRecordSchema>;
+/**
+ * Returns whether an amenity content record can still be purchased.
+ *
+ * @remarks
+ * Server-side, the `purchase` RPC calls this **after** re-reading the item
+ * inside the `WATCH`/`MULTI` block to make the check atomic. Client-side, the
+ * tooltip and sprite renderers call it to decide between the `Buy` button and
+ * the disabled `SOLD` pill.
+ *
+ * @example
+ * ```ts
+ * if (!isItemAvailableForPurchase(item)) {
+ *   // render the sold view
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function isItemAvailableForPurchase(item: {
+    sale: SaleState;
+}): boolean;
+/**
+ * Union of all three content kinds, useful for places where the carrier
+ * doesn't need to know the specific amenity.
+ *
+ * @public
+ */
+type SpaceContentItem = ShopItem | SupermarketItem | CarWashCar;
+/**
+ * Convert any 24-bit RGB color to its perceptual grey equivalent using the
+ * standard luminance coefficients (`Y = 0.299·R + 0.587·G + 0.114·B`).
+ *
+ * @remarks
+ * Used by every amenity sprite (shop card, grocery item, car) when the
+ * item's `sale.status === 'sold'`. Replacing original fills with the
+ * desaturated grey is the first step of the sold visual treatment;
+ * `drawSoldBadge` then paints the red `SOLD` banner on top.
+ *
+ * The function is bit-pure: it accepts a `0xRRGGBB` integer and returns a
+ * `0xGGGGGG` integer, so it composes cleanly with `pixi.js` color params.
+ *
+ * @example
+ * ```ts
+ * const grey = desaturateColor(0xff3344);
+ * // grey = 0x6e6e6e (approximate)
+ * ```
+ *
+ * @public
+ */
+declare function desaturateColor(hex: number): number;
+
+/**
+ * Parses **`playerChainNotify`** envelopes and merges {@link PlayerChainNodeResponse} slices into {@link AgentPlaySnapshot} (pure functions + fetch ordering for serialized RPC).
+ */
+
+declare function sortNodeRefsForSerializedFetch(nodes: ReadonlyArray<PlayerChainNotifyNodeRef>): PlayerChainNotifyNodeRef[];
+declare function parsePlayerChainFanoutNotify(raw: unknown): PlayerChainFanoutNotify | undefined;
+declare function parsePlayerChainFanoutNotifyFromSsePayload(sseData: unknown): PlayerChainFanoutNotify | undefined;
+declare function parsePlayerChainNodeRpcBody(json: unknown): PlayerChainNodeResponse;
+declare function mergeSnapshotWithPlayerChainNode(snapshot: AgentPlaySnapshot, node: PlayerChainNodeResponse): AgentPlaySnapshot;
+
+declare const PLAYER_CHAIN_GENESIS_STABLE_KEY: "__genesis__";
+declare const PLAYER_CHAIN_HEADER_STABLE_KEY: "__header__";
+
+export { type SaleState as $, type AgentPlaySnapshot as A, type PlayerChainFanoutNotify as B, CONTINUOUS_RENDER_OFFSET as C, DEFAULT_AGENT_SPAWN_MIN_DISTANCE as D, type PlayerChainGenesisNode as E, type PlayerChainHeaderNode as F, type PlayerChainNotifyNodeRef as G, type PlayerChainOccupantPresentNode as H, type PlayerChainOccupantRemovedNode as I, type Journey as J, type PlayerWallet as K, type LangChainAgentRegistration as L, MINIMUM_PLAY_WORLD_BOUNDS as M, PlayerWalletSchema as N, OCCUPANCY_POINT_MULTIPLIER as O, type PlayerChainNodeResponse as P, type PositionedStep as Q, type RemotePlayWorldInitAudioOptions as R, type PurchaseRecord as S, PurchaseRecordSchema as T, type RealtimeWebrtcClientSecret as U, type RegisteredAgentSummary as V, type WorldInteractionRole as W, type RemotePlayWorldOpenAiAudioOptions as X, SPATIAL_ZONE_INDEX_AGENTS as Y, SPATIAL_ZONE_INDEX_SPACES as Z, STREET_NAME_POOL as _, type AddAgentInput as a, SaleStateSchema as a0, type ShopItem as a1, ShopItemSchema as a2, type SpaceContentItem as a3, type Street as a4, type StreetPoolEntry as a5, type StructureJourneyStep as a6, type SupermarketItem as a7, SupermarketItemSchema as a8, type WorldBounds as a9, isItemAvailableForPurchase as aA, isSpaceAnchorOccupancyPointAvailable as aB, isSpaceAnchorOccupancyPointAvailableInRect as aC, isSpaceAnchorOccupancyPointAvailableInZone as aD, listAllowedOccupancyPoints as aE, listOccupancyPointsForSpatialZone as aF, listOccupancyPointsForZone as aG, listOccupancyPointsInRect as aH, mergeSnapshotWithPlayerChainNode as aI, migrateWorldLayoutBounds as aJ, nextStreetFromPool as aK, occupancyKeyForPosition as aL, occupancyPointsGroupedBySpatialZone as aM, occupancyPointsGroupedByZones as aN, parsePlayerChainFanoutNotify as aO, parsePlayerChainFanoutNotifyFromSsePayload as aP, parsePlayerChainNodeRpcBody as aQ, pickZoneForGroup as aR, pointCellInRect as aS, pointCellInSpatialZone as aT, pointCellInZone as aU, primaryZoneForGroup as aV, sortNodeRefsForSerializedFetch as aW, spatialZoneBounds as aX, spatialZoneCenter as aY, streetFromPoolEntry as aZ, zonesForGroup as a_, type WorldJourneyUpdate as aa, type WorldLayout as ab, type WorldLayoutBoundsField as ac, type YieldEventInfo as ad, type Zone as ae, type ZoneEventInfo as af, applyBoundsFieldUpdateToLayout as ag, availableCellsForZone as ah, boundingWorldRectForOccupancyPoints as ai, boundsContain as aj, buildRankedOccupancyPoints as ak, buildRankedOccupancyPointsForSpatialZone as al, buildRankedOccupancyPointsForZone as am, buildRankedOccupancyPointsInRect as an, cellsForZone as ao, centerOfZone as ap, clampWorldPosition as aq, createInitialPlayerWallet as ar, createVerticalStripSeedLayout as as, desaturateColor as at, enumerateIntegerCellsInRect as au, expandBoundsToMinimumPlayArea as av, getStreetPoolEntryById as aw, isAgentSpawnOccupancyPointAvailable as ax, isAgentSpawnOccupancyPointAvailableInRect as ay, isAgentSpawnOccupancyPointAvailableInZone as az, type RegisteredPlayer as b, type AddPlayerInput as c, type RecordInteractionInput as d, type AgentPlayWorldLayout as e, type AgentPlayWorldLayoutZone as f, type AgentPlayWorldMap as g, type AgentPlayWorldMapAgentOccupant as h, type AgentPlayWorldMapBounds as i, type AgentPlayWorldMapMcpOccupant as j, type AssistToolFieldType as k, type AssistToolParameterSpec as l, type AssistToolSpec as m, type CarWashCar as n, CarWashCarSchema as o, DEFAULT_PLAYER_WALLET_BALANCE_USD as p, type DestinationJourneyStep as q, type JourneyStep as r, type OccupancyGridPoint as s, type OccupantGroup as t, type OriginJourneyStep as u, type P2aEnableFlag as v, PLAYER_CHAIN_GENESIS_STABLE_KEY as w, PLAYER_CHAIN_HEADER_STABLE_KEY as x, type PlatformAgentInformation as y, type PlayAgentInformation as z };