openalice-agent-protocol
[Atlas card](https://atlas.blal.pro/repos/openalice-agent-protocol)
Architecture rating
Valid manifest with clear polyglot-pairing note, AGENTS.md onboarding guide, 5 @feature annotations, and rich in-code architecture comments (e.g. RestAgentRuntime rationale); dragged only by 73 missing docstrings and a thin README that defers to the Atlas card, plus roadmap 30/100.
Strong substrate adoption — valid .atlas-deps.yml, AGENTS.md, @feature blocks, drift 100, code_health 100, avg complexity 1.08; one tools→events→tools circular dependency and 5 god-modules are the only uniformity blemishes in an otherwise clean, convention-following package.
17 tests across 3 files (protocol 7, cooldown 6, perception 4) under vitest covering the core contract, cooldown middleware, and perception split — solid for the surface area, but no tests exercise RestAgentRuntime's fetch/stream-parsing path, the riskiest code.
Owns zero tables (manifest_owns_tables empty), no migrations or persistence — N/A by design; graded conservatively since the only 'schema' is the TS type contract, which is well-typed but carries no DB/RLS/GDPR concerns to evaluate.
Wire-contract lib with no authn/secrets surface of its own; RestAgentRuntime passes caller-supplied Authorization headers verbatim and uses an injectable fetch with no URL/SSRF validation, no timeout, and no scheme allowlist — fine for a contract package but no input hardening exists.
RestAgentRuntime does a network fetch with NO timeout/AbortController, no retry, and 1 broad/bare except flagged by inspector; cooldown middleware adds backpressure but stream-collapse error handling is thin — acceptable for a thin client, but no graceful-failure guarantees.
No metrics, tracing, structured logging, or health probes (Atlas health: 'no https endpoint' — none expected for an npm lib); zero console statements, so the package emits nothing observable by design — graded conservatively as absent.
source · auto-grader-2026-06-16
Ecosystem manifest
.atlas-deps.ymlTS 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.
- npm_package: @openalicelabs/agent-protocol
Code composition
tokei · loc- TypeScript95.1%
- JSON4.9%
- TypeScript95.1%
- JSON4.9%
- TypeScript95.1%· 1,036
- JSON4.9%· 53
| Language | % code | code | comments | blanks | files |
|---|---|---|---|---|---|
| TypeScript | 95.1% | 1,036 | 510 | 115 | 10 |
| JSON | 4.9% | 53 | 0 | 0 | 2 |
| Markdown | 0.0% | 0 | 245 | 74 | 3 |
Telemetry ribbon · last 90 days
3 eventsagent-protocol/contract
1 feature- agent-protocol.contract.entry-pointsrc/index.ts:14Central 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.
agent-protocol/cooldown
1 feature- agent-protocol.cooldown.middlewaresrc/cooldown.ts:26In-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.
agent-protocol/events
2 features- agent-protocol.events.connector-eventsrc/events.ts:13Discriminated 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.
- agent-protocol.events.perceptionsrc/events.ts:225`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.
agent-protocol/tools
1 feature- agent-protocol.tools.tool-callsrc/tools.ts:12Discriminated 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.