@agent-play/sdk 3.3.2 → 3.3.3

package/dist/browser-BQR40I8R.d.ts

@@ -1,480 +0,0 @@
-/**
- * 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;
-};
-/**
- * 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;
-};
-/** 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)[];
-};
-/**
- * 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;
-    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;
-/** Bottom-left zone Q1 — agents (spatial rectangle). */
-declare const SPATIAL_ZONE_INDEX_AGENTS = 0;
-/** Top-left zone Q3 — spaces / amenities (spatial rectangle). */
-declare const SPATIAL_ZONE_INDEX_SPACES = 2;
-declare function spatialZoneBounds(quartileIndex: number): WorldBounds;
-declare function spatialZoneCenter(quartileIndex: number): OccupancyGridPoint;
-declare function pointCellInSpatialZone(wx: number, wy: number, zoneIndex: number): boolean;
-declare function listOccupancyPointsForSpatialZone(zoneIndex: number): readonly OccupancyGridPoint[];
-declare function occupancyPointsGroupedBySpatialZone(): readonly (readonly OccupancyGridPoint[])[];
-/** Agent spawns: Q1 only. */
-declare function listAllowedOccupancyPoints(): readonly OccupancyGridPoint[];
-declare function occupancyKeyForPosition(x: number, y: number): string;
-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 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;
-
-/**
- * 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 { isAgentSpawnOccupancyPointAvailable as $, type AgentPlaySnapshot as A, type PositionedStep as B, CONTINUOUS_RENDER_OFFSET as C, DEFAULT_AGENT_SPAWN_MIN_DISTANCE as D, type RealtimeWebrtcClientSecret as E, type RegisteredAgentSummary as F, type RemotePlayWorldOpenAiAudioOptions as G, SPATIAL_ZONE_INDEX_SPACES as H, type StructureJourneyStep as I, type Journey as J, type WorldBounds as K, type LangChainAgentRegistration as L, MINIMUM_PLAY_WORLD_BOUNDS as M, type WorldJourneyUpdate as N, OCCUPANCY_POINT_MULTIPLIER as O, type PlayerChainNodeResponse as P, boundingWorldRectForOccupancyPoints as Q, type RemotePlayWorldInitAudioOptions as R, SPATIAL_ZONE_INDEX_AGENTS as S, boundsContain as T, buildRankedOccupancyPoints as U, buildRankedOccupancyPointsForSpatialZone as V, type WorldInteractionRole as W, clampWorldPosition as X, type YieldEventInfo as Y, type ZoneEventInfo as Z, expandBoundsToMinimumPlayArea as _, type AddAgentInput as a, isSpaceAnchorOccupancyPointAvailable as a0, listAllowedOccupancyPoints as a1, listOccupancyPointsForSpatialZone as a2, mergeSnapshotWithPlayerChainNode as a3, occupancyKeyForPosition as a4, occupancyPointsGroupedBySpatialZone as a5, parsePlayerChainFanoutNotify as a6, parsePlayerChainFanoutNotifyFromSsePayload as a7, parsePlayerChainNodeRpcBody as a8, pointCellInSpatialZone as a9, sortNodeRefsForSerializedFetch as aa, spatialZoneBounds as ab, spatialZoneCenter as ac, type RegisteredPlayer as b, type AddPlayerInput as c, type RecordInteractionInput as d, type AgentPlayWorldMap as e, type AgentPlayWorldMapAgentOccupant as f, type AgentPlayWorldMapBounds as g, type AgentPlayWorldMapMcpOccupant as h, type AssistToolFieldType as i, type AssistToolParameterSpec as j, type AssistToolSpec as k, type DestinationJourneyStep as l, type JourneyStep as m, type OccupancyGridPoint as n, type OriginJourneyStep as o, type P2aEnableFlag as p, PLAYER_CHAIN_GENESIS_STABLE_KEY as q, PLAYER_CHAIN_HEADER_STABLE_KEY as r, type PlatformAgentInformation as s, type PlayAgentInformation as t, type PlayerChainFanoutNotify as u, type PlayerChainGenesisNode as v, type PlayerChainHeaderNode as w, type PlayerChainNotifyNodeRef as x, type PlayerChainOccupantPresentNode as y, type PlayerChainOccupantRemovedNode as z };