# openalice-agent-protocol

> TS half of the polyglot agent-protocol pair (the Rust half is openalice-agent-protocol-rs). Wire contract — ConnectorEvent / ToolCall / AgentRuntime / cooldown — published as @openalicelabs/agent-protocol npm package. JSON shape kept identical with the Rust mirror; changes must land in both repos same commit window.

## At a glance
| field | value |
|---|---|
| kind | `service` |
| priority | `—` |
| default branch | `mvp` |
| last activity | 2026-06-02T10:33:49+00:00 |
| features catalogued | **5** |
| runtime deps declared | **0** |

## Manifest
`.atlas-deps.yml` — parsed cleanly: **yes**

### Exposes
- `npm_package` — @openalicelabs/agent-protocol

## Features (5)

### agent-protocol/contract
- **`agent-protocol.contract.entry-point`** — Central re-export barrel for the entire wire contract. Consumers import exclusively from this module; internal modules are an implementation detail. `PROTOCOL_VERSION` is the semver of the contract itself — bump on any breaking shape change.  
  *src/index.ts:14*

### agent-protocol/cooldown
- **`agent-protocol.cooldown.middleware`** — In-memory token-bucket rate limiter keyed on `(channel_id, tool_name)`. Platform-side safety net that sits between `AgentTurnOutput.calls` and the dispatcher — protects Twitch chat, YouTube Live, and VRM scene controllers from misbehaving runtimes. Injectable `now` parameter makes the clock deterministic in tests. Swap for a Redis-backed implementation that exposes the same `check(): Decision` interface for multi-replica deployments without any changes to callsites.  
  *src/cooldown.ts:26*

### agent-protocol/events
- **`agent-protocol.events.connector-event`** — Discriminated union of all six inbound event kinds. Connectors on every platform (Twitch IRC, YouTube polling, WebRTC voice, Persona iframe, World 3D presence) normalize raw transport frames into one of these before handing off to the agent runtime. Type-guard helpers (`isChatMessage` et al.) are co-exported to avoid scattered `kind ===` checks in consumers. @feature agent-protocol.events.chat-feed-split Deliberate split between `chat_message` (one user, one message, always delivered, high-signal) and `chat_feed` (30 s mechanical aggregation — topics, mood, highlight quotes — no LLM tokens). Enables agents to stay aware of room tempo without burning a full inference call on every message; silence is a valid response to a feed event.  
  *src/events.ts:13*
- **`agent-protocol.events.perception`** — `visual_perception` (what the agent sees — camera / screen / scene, a VLM caption plus optional detections) and `spatial_perception` (where the agent and its neighbours are in the scene). Camera vision is consent-gated *by contract*: a `visual_perception` whose `origin` is `"camera"` MUST carry a granted `consent` — camera stays off until the human opts in (the Persona consent model). Scene-origin vision is our own render and needs none. Spatial coordinates share the `Vec3` frame used by the `move_to` / `teleport_to` / `look_at` actuators, so perception feeds action with no translation.  
  *src/events.ts:225*

### agent-protocol/tools
- **`agent-protocol.tools.tool-call`** — Discriminated union of all eight outbound tool calls. Name constants (`ToolRespond`, `ToolChangeScene`, etc.) and `BUILTIN_TOOL_NAMES` are exported so consumers reference stable identifiers rather than string literals. The protocol is open — custom runtimes may add tool kinds beyond these eight built-ins. `ToolResult` closes the loop: the platform echoes the `call_id` and outcome on the next turn so the runtime can reason about success or failure.  
  *src/tools.ts:12*

---

*Generated by [openalice-atlas](https://atlas.blal.pro) — single source of truth for the openalicelabs ecosystem.*