{"id":50912216,"url":"https://github.com/unbug/cyber-agent","last_synced_at":"2026-06-16T11:01:40.699Z","repository":{"id":350823394,"uuid":"1208302845","full_name":"unbug/cyber-agent","owner":"unbug","description":"The agnet platform that rocks the robot world.","archived":false,"fork":false,"pushed_at":"2026-06-08T10:56:52.000Z","size":2727,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T12:27:52.108Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://unbug.github.io/cyber-agent/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unbug.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-12T05:00:09.000Z","updated_at":"2026-06-08T10:56:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/unbug/cyber-agent","commit_stats":null,"previous_names":["unbug/cyber-agent"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/unbug/cyber-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbug%2Fcyber-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbug%2Fcyber-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbug%2Fcyber-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbug%2Fcyber-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unbug","download_url":"https://codeload.github.com/unbug/cyber-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbug%2Fcyber-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34402663,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-16T11:01:40.001Z","updated_at":"2026-06-16T11:01:40.683Z","avatar_url":"https://github.com/unbug.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CyberAgent\n\n\u003e Give your robot a soul.\n\nAn open-source platform for creating character-driven AI agents that bring physical robots to life. Pick a personality, connect your robot, and watch it come alive.\n\n**Live Demo:** https://unbug.github.io/cyber-agent/\n\n## Quick Start\n\n```bash\ngit clone https://github.com/unbug/cyber-agent.git\ncd cyber-agent\nnpm install\nnpm run dev\n```\n\nOpen http://localhost:5173/cyber-agent/\n\n## Scripts\n\n| Command | Description |\n|---------|-------------|\n| `npm run dev` | Start dev server |\n| `npm run build` | Production build to `dist/` |\n| `npm test` | Run tests |\n| `npm run test:watch` | Run tests in watch mode |\n| `npm run preview` | Preview production build |\n\n## Tech Stack\n\n- **Vite** + **React 18** + **TypeScript**\n- **Behavior Tree Engine** — custom runtime with 9 node types\n- **CSS Modules** with CSS Custom Properties (dark-first design system)\n- **Framer Motion** for animations\n- **React Router** for SPA routing\n- **Vitest** + **Testing Library** for tests\n- **GitHub Actions** → **GitHub Pages** for deployment\n\n## Project Structure\n\n```\nsrc/\n  engine/       # Behavior Tree Engine\n    types.ts        # Core types: Blackboard, NodeDef, RobotAdapter\n    executor.ts     # Hydrate definitions → tick tree each frame\n    builtins.ts     # Standard actions \u0026 conditions library\n    runner.ts       # Lifecycle manager (start/stop/pause/resume)\n    canvas-adapter.ts  # Browser renderer (trail, glow, bounce)\n    behaviors.ts    # 6 character behavior tree definitions\n  hooks/        # React hooks (useBehaviorTree)\n  components/   # Shared UI (Layout, etc.)\n  data/         # Character definitions + helpers\n  pages/        # Route pages (Home, Gallery, Agent, Docs)\n  styles/       # Global CSS + design tokens\n  test/         # Test files + setup\n```\n\n## Behavior Tree Engine\n\nThe engine at `src/engine/` runs character AI in the browser via a standard behavior tree architecture:\n\n- **Blackboard** — shared state (position, emotion, energy, pointer) accessible to all nodes\n- **9 Node Types** — Sequence, Selector, Parallel, Inverter, Repeater, Cooldown, Condition, Action, Wait\n- **RobotAdapter Interface** — abstract hardware layer; implement `init()`, `update()`, `sendCommand()` to connect any robot\n- **CanvasAdapter** — built-in browser renderer with emotion glow, movement trails, and energy visualization\n\n### Extending\n\n```typescript\nimport { registerAction } from './engine'\n\n// Add a custom action\nregisterAction('myAction', (bb, args, adapter) =\u003e {\n  adapter.sendCommand({ type: 'move', payload: { x: bb.x, y: bb.y } })\n  return 'success'\n})\n```\n\nImplement `RobotAdapter` to connect physical hardware (ESP32, Raspberry Pi, Arduino, etc.).\n\n## Roadmap\n\n\u003e **North Star (immutable)**: _Give your robot a soul._ Make every physical\n\u003e toy / robot scriptable as a believable, character-driven agent.\n\u003e\n\u003e **Two non-negotiable axes** every release must satisfy:\n\u003e\n\u003e 1. **Debuggability** — every behavior, perception, decision and motor\n\u003e    command must be inspectable, replayable and visualizable.\n\u003e 2. **Real embodiment** — features land only with a real-hardware\n\u003e    demonstration. Sim-only work ships behind an `experimental/` flag.\n\n### Where CyberAgent fits in the landscape\n\n| Project | Personality / Character | Hardware abstraction | Hobby toys (\u003c$100) | First-class debugger |\n| --- | --- | --- | --- | --- |\n| **CyberAgent** (this repo) | ✅ 55+ characters + BT | ✅ adapter contract | ✅ mBot / ESP32 / RoboMaster | ✅ time-travel + replay (planned) |\n| HuggingFace LeRobot | ❌ policies, no character | ✅ Python `Robot` interface | ⚠️ research arms (SO-100, ALOHA) | ⚠️ training plots only |\n| elizaOS | ✅ rich personas | ❌ chat / web only | ❌ no embodiment | ✅ web dashboard |\n| NVIDIA Isaac Lab / GR00T | ❌ skill policies | ✅ Isaac Sim | ❌ humanoid-only | ⚠️ sim-side only |\n| ROS 2 / Nav2 / MoveIt | ❌ | ✅ industrial | ❌ | ⚠️ rqt / RViz |\n| Sony aibo / Anki Vector SDK | ✅ closed | ✅ closed | ⚠️ discontinued | ❌ |\n\nThe unique slot we own is **soul + cheap toys + radical debuggability**.\n\n### Versioned task breakdown\n\nEach version is a hard release with a `git tag`. The autonomous Cron picks\nthe **first unchecked, unblocked** item in the **earliest unreleased\nversion** and ships it end-to-end (code + test + debugger surface + docs +\nHIL evidence when hardware is touched). It never invents scope outside this\nlist, and never skips a version.\n\n#### v0.3 — Tracer foundation _(now → +1 month)_\n\nMake the existing surface observable.\n\n- [x] `src/engine/tracer.ts` — structured event stream\n      (`tick.start`, `node.enter`, `node.exit`, `action.dispatch`,\n      `adapter.tx`, `adapter.rx`, `bb.set`, `error`).\n- [x] Wire tracer into `executor.ts`, `runner.ts`, `CanvasAdapter`,\n      `WebSocketAdapter`, `MBotAdapter`,\n      `RoboMasterAdapterV2`.\n- [x] Persist last 1 000 events per session in IndexedDB.\n- [x] CI: `tests/hil-emulator/` runs 1 character × 5 adapters for 60 s on\n      mock hardware; fail on any `error` event.\n- [x] Coverage gate ≥ 80 % on `src/engine/` and `src/adapters/`.\n      (engine: 81.3%, adapters: 85.5%)\n- [x] `CONTRIBUTING.md` documents debug + embodiment invariants.\n\n**Release gate**: tracer emits in production build; CI emulator green\n7 days; HEARTBEAT shows 0 unresolved adapter errors.\n\nReleased: 2026-04-26\n\n#### v0.4 — `/debug` page MVP _(+1 → +2 months)_\n\nA debugger you can hand to a contributor.\n\n- [x] `/debug` page split-view: BT graph (current node highlighted, last\n      50-node breadcrumb) ｜ actuator timeline ｜ blackboard inspector.\n  - `src/pages/DebugPage.tsx` — split-view with BT tree panel, actuator timeline, blackboard inspector\n  - `TreeNode` — recursive BT renderer with active node highlighting, type-color coding, status dots\n  - `Breadcrumb` — last N node-enter events as breadcrumb trail\n  - `ActuatorTimeline` — TX/RX event streams with time-stamped messages\n  - `BlackboardInspector` — field listing with diff highlighting via `diffBlackboards`\n- [x] Live tick-rate / latency widgets.\n  - `PerformancePanel` — live tick-rate sparkline + latency histogram\n  - Top stats bar: tick rate (fps), avg latency (ms), event count\n  - Tick-rate warning threshold at 8 fps (below = yellow)\n- [x] Diff highlighting on every blackboard write (`src/hooks/useDebug.ts` → `diffBlackboards`).\n- [x] Capability discovery — read `adapter.capabilities()` and grey out\n      incompatible BT nodes in the editor.\n- [ ] One end-to-end demo video: bug → fix → re-run on real RoboMaster.\n\n**Release gate**: a maintainer reproduces a contributor-reported bug\nlocally with no hardware, using only the live `/debug` view.\n\n#### v0.5 — Time-travel \u0026 `.cybertrace` _(+2 → +3 months)_\n\n- [x] `.cybertrace` format spec (`sdk/src/trace/schema.ts`) — gzipped\n      JSONL, versioned, with migration registry.\n- [x] `/debug` scrubber: rewind / step / fast-forward an in-memory\n      session OR an uploaded trace.\n- [x] Breakpoints by BT node, blackboard predicate, or adapter event.\n- [x] CLI: `cyber-agent record \u003cadapter\u003e` / `cyber-agent replay \u003cfile\u003e`.\n- [x] Pull a trace off a real device over WebSocket.\n- [x] `npx @cyber-agent/sdk trace lint` validates schema.\n\n**Release gate**: a third party shares a `.cybertrace` from a real robot;\nmaintainer single-steps through it locally to root-cause a bug.\n\n#### v0.6 — Adapter contract v2 _(+3 → +4 months)_\n\n- [x] `sdk/src/adapter/contract.ts` v2:\n      `connect / disconnect / sendCommand / onTelemetry / capabilities() /\n      selfTest()` returning a structured report.:\n      `connect / disconnect / sendCommand / onTelemetry / capabilities() /\n      selfTest()` returning a structured report.\n- [x] Hardware-in-Loop (HIL) checklist a contributor can run with a $50\n      mBot to certify a new adapter (`docs/hil/mbot/CHECKLIST.md`).\n- [x] Migrate existing 5 adapters to v2; deprecate v1 with a 1-version\n      grace.\n- [x] Safety supervisor node: kill switch on \u003e200 ms heartbeat loss,\n      watt-dog on motor stall.\n\n**Release gate**: 5 in-house adapters certified; one community-contributed\nadapter accepted using only the v2 contract.\n\n#### v0.7 — Embodiment Pack expansion _(+4 → +6 months)_\n\nWidth of real toys — every adapter ships with HIL evidence under\n`docs/hil/\u003cadapter\u003e/`.\n\n- [x] LEGO SPIKE / Mindstorms (Bluetooth LE).\n- [x] Generic ESP32 + reference firmware (WebSocket protocol v2).\n  - `src/adapters/esp32.ts` — `ESP32Adapter` implementing `RobotAdapterV2`\n  - WebSocket protocol v2 spec (typed JSON messages: move, motors, led, sound, gesture, emergency_stop)\n  - Telemetry parser (battery, IMU, distance, bump, motor_state, heartbeat, ack)\n  - Auto-reconnect with exponential backoff, heartbeat, command queue\n  - 47 unit tests covering serialization, parsing, lifecycle, queueing\n  - Reference firmware: `firmware/esp32/CyberAgentESP32.ino` (Arduino, WiFi AP/station, WS server)\n  - HIL checklist: `docs/hil/esp32/CHECKLIST.md`\n- [x] Unitree Go1 / Go2 high-level SDK with documented safety envelope.\n  - `src/adapters/unitree-go1.ts` — `UnitreeGo1Adapter` implementing `RobotAdapterV2`\n  - Relay server WebSocket protocol (browser → relay → UDP/DDS → robot)\n  - High-level API: `move`, `setBodyHeight`, `setGait`, `setPose`, `damping`, `standUp`, `sit`, `standDown`, `dance`, `jump`, `flip`, `emergencyStop`\n  - Telemetry parsing: battery, IMU, joint_state, terrain, foot_force, state, position, heartbeat, ack\n  - Safety envelope: speed clamping, body height limits, angle limits, battery thresholds\n  - Enums: `GaitType` (0-4), `MotionMode` (0-13), `SpeedLevel` (0-2), `RobotModel` ('go1' | 'go2')\n  - 75 unit tests covering serialization, parsing, lifecycle, queueing\n  - HIL checklist: `docs/hil/unitree-go1/CHECKLIST.md`\n  - ADAPTER_INFO entry + character compatibleAdapters updated\n- [x] iRobot Create 3 / Roomba SDK.\n  - `src/adapters/irobot-create3.ts` — `IRobotCreate3Adapter` implementing `RobotAdapterV2`\n  - WebSocket protocol v2 (move, drive, velocity, stop, led, sound, play_song, sensors)\n  - Telemetry parsing: battery, cliff, wall, bump, wheel_drop, distance, angle, charge_state, heartbeat, ack\n  - Auto-reconnect with exponential backoff, command queue\n  - 32 unit tests\n  - HIL checklist: `docs/hil/irobot-create3/CHECKLIST.md`\n- [x] DJI Tello / Tello EDU (drone, indoor only).\n  - `src/adapters/tello.ts` — `TelloAdapter` implementing `RobotAdapterV2`\n  - WebSocket protocol v2 (takeoff, land, move, rotate, speed, flip, go, waypoint)\n  - Telemetry parsing: battery, temperature, barometer, tof, attitude, flight_data, wifi, flight_status\n  - Convenience methods: takeoff, land, move, rotate, setSpeed, flip, goTo, startWaypoint, endWaypoints\n  - INDOOR ONLY safety warning throughout\n  - 31 unit tests\n  - HIL checklist: `docs/hil/tello/CHECKLIST.md`\n- [x] Marketplace UI surfaces adapter compatibility per character.\n\n**Release gate**: 10 adapters total, every character page lists which\ntoys can run it. ✅ **MET** — Released: 2026-04-30\n\n#### v1.0 — First stable release _(+6 → +7 months)_\n\nThe \"1.0\" promise: anything `npm install @cyber-agent/sdk@1` will keep\nworking until v2.0.\n\n- [x] Stable SDK API surface (TypeScript types frozen, semver).\n  - `sdk/src/public-api.ts` — exact public API boundary\n  - `sdk/CHANGELOG.md` — version history\n- [x] Stable `.cybertrace` schema v1.\n  - `sdk/src/trace/schema.ts` — versioned with `TRACE_SCHEMA_VERSION`\n  - `validateTrace()` / `migrateTrace()` included\n- [x] Documentation site (`/docs`) covers every public API.\n  - Updated `Docs.tsx` with v1.0 API reference, adapter contract v2, migration guide\n- [x] Migration guide from 0.x.\n  - `sdk/MIGRATION.md` — adapter v2, trace schema, import paths\n- [x] Performance budget: \u003c16 ms tick on a $50 mBot.\n  - `src/engine/performance.test.ts` — 4 benchmarks all pass \u003c16ms\n\n**Release gate**: passes a 24-hour soak test (1 character × 5 adapters,\nzero crash, zero memory leak).\n\n#### v1.1 — Perception bus _(+7 → +9 months)_\n\nSensors close the loop.\n\n- [x] `src/perception/` — typed event stream\n      (`see.face`, `see.object.\u003cid\u003e`, `hear.word.\u003cid\u003e`, `near.\u003cdistance\u003e`,\n      `tilt`, `bump`).\n      - `src/perception/types.ts` — PerceptionEvent union type + category interfaces\n      - `src/perception/bus.ts` — PerceptionBus pub/sub with circular buffer\n      - `src/perception/nodes.ts` — BT conditions (perceive.*) + actions (memorize.*)\n- [x] Webcam adapter (browser + WebRTC) with face / hand / object\n      detection; `/debug` overlays bounding boxes on the timeline.\n      - `src/adapters/webcam.ts` — WebcamAdapter with simulate mode\n      - `/debug` Perception panel shows face/object detection events\n- [x] Microphone adapter (VAD + keyword spotting).\n      - `src/adapters/microphone.ts` — MicrophoneAdapter with VAD + keyword spotting\n- [x] On-device option: ESP32 / RPi relay perception events to browser.\n      - `src/adapters/esp32-perception-relay.ts` — ESP32PerceptionRelay\n      - `firmware/esp32-perception-relay/CyberAgentPerceptionRelay.ino` — reference firmware\n      - `docs/hil/esp32-perception-relay/CHECKLIST.md` — HIL checklist\n- [x] BT primitives: `Perceive`, `Memorize`.\n      - `perceive.face`, `perceive.object`, `perceive.word`, `perceive.sound`, `perceive.near`, `perceive.bump`\n      - `memorize`, `memorize.face`, `memorize.object`, `memorize.word`\n- [x] 5 sample characters that only make sense with perception\n      (e.g. cat hides on face).\n      - `shy-cat` — hides from faces, warms to familiar\n      - `playful-dog` — chases objects, reacts to sounds\n      - `guardian-bot` — patrols, alerts on detection\n      - `musician-bot` — dances to sounds, sings when alone\n      - `curious-bird` — flies toward objects, avoids faces\n\n**Release gate**: real toy reacts in \u003c200 ms to a webcam stimulus; trace\nshows the full perception → BT → motor chain. _(requires real hardware test)_\n\n#### v1.2 — Episodic memory _(+9 → +10 months)_\n\n- [x] `src/memory/` — episodic store keyed by `(event, emotion, time)`.\n  - `src/memory/types.ts` — EpisodicMemory, RecallQuery, RecallResult, EpisodicStoreBackend, MemoryStats, ForgettingCurveParams\n  - `src/memory/episodic-store.ts` — InMemoryEpisodicStore with Ebbinghaus forgetting curve, semantic/emotional recall, purge\n  - `src/memory/recall.ts` — BT primitives: `memorize.episodic`, `recall(query)`, `hasMemory(keyword)`\n  - `src/memory/index.ts` — barrel exports\n- [x] SQLite-WASM in-browser; pluggable to OpenClaw memory in dev.\n  - `EpisodicStoreBackend` interface enables backend swap (InMemoryEpisodicStore default)\n- [x] BT primitive `Recall(query)` returns top-K events to blackboard.\n  - `recall` action writes `recentMemories` + `recallStats` to blackboard\n- [x] `/debug` adds a \"memories\" panel.\n  - `src/pages/MemoriesPanel.tsx` — stats, relevance histogram, search, sort, simulate forgetting, purge\n  - `src/hooks/useDebug.ts` — encodeMemory, purgeMemories, simulateForgetting hooks\n- [x] Forgetting curve + manual purge tools.\n  - Ebbinghaus curve: `relevance = initialRelevance * 2^(-age/halfLife) * recallBoost * salienceFactor`\n  - `simulateForgetting(elapsedMs)` in debug, `purge()` to remove pruned memories\n\n**Release gate**: a character demonstrably treats a returning face\ndifferently from a new face on real hardware.\n\n#### v1.3 — Affect engine (VAL)\n\nReleased: 2026-05-10 _(+10 → +12 months)_\n\n- [x] Per-agent VAL state (Valence / Arousal / Dominance) with decay.\n- [x] BT priors: nodes declare `bias: { whenArousal: \"\u003e0.7\" }`; selector\n      reorders by current affect.\n- [x] Adapter expressions: LED color / sound / motion style modulated by\n      VAL (default mappings + per-character override).\n- [x] `/debug` adds VAL trajectory aligned with timeline.\n  - `src/pages/VALTimelinePanel.tsx` — unified canvas: VAL curve + perception markers + adapter tx/rx markers on shared time axis\n  - Hover crosshair shows time, VAL state (V/A/D), and event details\n  - `src/pages/VALTimelinePanel.test.tsx` — 8 tests\n- [x] Authoring DSL: `emotion: anxious | playful | stoic` composable.\n\n**Release gate**: blind A/B test (n=30) prefers VAL-biased character over\nflat baseline ≥70 %.\n\n#### v2.0 — Sim ↔ Real bridge _(+12 → +18 months)_\n\nThe \"train cheap, deploy real\" milestone.\n\n- [x] Browser-embedded sim (2D rigid-body physics engine) on `/agent` page.\n  - ⚠️ **experimental** — sim-only, requires real hardware for full validation\n- [x] One-shot `simulate → record → replay-on-real` workflow.\n  - `Sim2RealReplay` — maps sim commands (move/rotate/stop/gesture/led/sound/emergency_stop) to adapter payloads\n  - `exportCyberSim`/`importCyberSim` — `.cybersim` format with `$schema: cybersim/v1` header\n  - `useSimMode.replayOnReal(adapter, config)` + `abortReplayOnReal()` hook APIs\n  - HIL checklist: `docs/hil/sim2real/CHECKLIST.md`\n- [x] Domain-randomization sliders (mass, friction, latency, sensor\n      noise) wired into the debugger.\n  - `src/pages/DomainRandomizationPanel.tsx` — mass, friction, latency, sensor-noise sliders\n  - `src/sim/engine.ts` — `applyMassRandomization()` + `applySensorNoise()` helpers\n  - `useSimMode` exposes `randomization` / `setRandomization` / `resetRandomization`\n  - 15 unit tests (7 engine + 8 component)\n  - `experimental` — sim-only, requires real hardware for transfer validation\n- [x] `dataset/` — record episodes in `.cybertrace`-compatible format,\n      optional one-click upload to HuggingFace Hub.\n  - `EpisodeRecorder` — start/stop/pause/resume/export/delete lifecycle\n  - `exportCyberTrace/exportEpisodeAsCyberTrace/exportDatasetAsCyberTrace`\n  - `uploadToHub/uploadDatasetFiles/checkHubToken` — HuggingFace Hub integration\n  - `DatasetPanel` — UI for browsing episodes/datasets in simulator\n  - `useSimMode` exposes dataset APIs via `sim.*`\n  - 13 unit tests (all passing)\n- [x] Bench `bench/sim2real.json` — 10 canonical behaviors, ≥90 %\n      transfer accuracy.\n  - 10 behaviors: forward, backward, rotate-90, rotate-180, led-color,\n    sound-tone, gesture, emergency, complex-patrol, angle-movement\n  - `src/bench/sim2real.test.ts` — 13 tests validating sim→adapter mapping\n  - All behaviors achieve 1.0 sim accuracy (≥90% threshold met)\n  - `experimental` — sim accuracy only; real-hardware transfer validation pending\n- [ ] Optional: import LeRobot policies (`@cyber-agent/sdk-lerobot`\n      bridge) for users who want learned skills under the BT director.\n\n**Release gate**: a contributor authors a behavior in sim and it lands\nunchanged on a real RoboMaster; published bench numbers hold.\n\n#### v2.1 — Multi-agent stage _(+18 → +21 months)_\n\n\u003e Detailed plan + competitive research (AI Town / Smallville / Isaac Sim\n\u003e Mega) in [MULTI-AGENT-PLAYGROUND-PLAN.md](MULTI-AGENT-PLAYGROUND-PLAN.md).\n\u003e An MVP is being prototyped during Q2 W7-W8 as an experimental flag —\n\u003e see [TODO-Q2-2026.md](TODO-Q2-2026.md).\n\n- [x] Shared blackboard / pub-sub bus over WebSocket (host elects).\n- [x] Social BT primitives: `BroadcastEmotion`, `Negotiate`, `Mirror`,\n      `RoleSwap`, `findNearestAgent`, `greet`, `follow`, `flee`,\n      `emitSignal` / `onSignal`.\n      - `src/engine/builtins-multi.ts` — 5 conditions + 10 actions\n      - `src/pages/SocialEventsPanel.tsx` — debug panel for social events\n      - `src/engine/tracer.ts` — `social.event` tracer event type\n      - `src/hooks/useDebug.ts` — `socialEvents` state + event subscription\n      - 35 unit tests (`builtins-multi.test.ts`)\n- [x] `World` + `SpatialIndex` + `MultiExecutor` (deterministic, seeded\n      RNG, 100% replay parity).\n- [x] Scene library: playground / park / campus / schoolyard with POIs\n      (slide, swing, sandbox, classroom door, …); Tiled importer.\n  - `src/engine/scenes/` — types, registry, importer\n  - 4 scenes: playground (13 POIs), park (16 POIs), campus (26 POIs), schoolyard (20 POIs)\n  - `importTiledMap()` — Tiled JSON map → Scene with objmap/bgtiles/spawns layers\n  - `validateScene()` / `requireScene()` — validation helpers\n  - 23 unit tests\n- [x] `/playground` page: drag agents from Gallery into a scene, freeze /\n      replay / share-link a session.\n- [x] N-track timeline + agent diff in `/debug`.\n  - `src/pages/MultiAgentTimelinePanel.tsx` — N-track canvas timeline with hover crosshair\n  - `src/pages/AgentDiffPanel.tsx` — blackboard diff across agents\n  - `src/hooks/useMultiAgentDebug.ts` — per-agent debug state aggregation\n  - 7 unit tests (MultiAgentTimelinePanel + AgentDiffPanel)\n  - Wired into `/debug` page via `useMultiAgentDebug`\n- [x] `MultiBroadcastAdapter` — fan-out commands to N physical robots\n      with NTP-style time sync (≤5 ms drift) and global e-stop.\n  - `src/adapters/multi-broadcast.ts` — `MultiBroadcastAdapter` implementing `RobotAdapterV2`\n  - Command fan-out to all connected adapters\n  - NTP-style time sync with drift tracking (≤5 ms threshold)\n  - Global e-stop propagation to all robots\n  - Per-robot health monitoring (connection, latency, heartbeat)\n  - Self-test with structured report\n  - `docs/hil/multi-broadcast/CHECKLIST.md` — HIL checklist\n  - 20 unit tests (`multi-broadcast.test.ts`)\n- [x] **Two-robot demo (cat × dog) with believable interaction**\n  - `src/agents/cat-dog-demo/` — demo characters + behaviors\n  - `demo-cat`: shy cat (flee, mirror, broadcast calm)\n  - `demo-dog`: playful dog (seek, greet, back off)\n  - Leverages social BT primitives: `isCloseTo`, `isFarFrom`, `flee`, `mirror`, `broadcastEmotion`, `findNearestAgent`, `greet`\n  - 'Demo' button in playground toolbar for one-click load\n  - Characters registered in gallery under 'companion' category\n- [x] 3+ robots, 30-minute soak, no cross-talk drops.\n  - `CrossTalkPanel` — real-time per-robot command stats, drop rates,\n    drift, health in `/debug` page\n  - `PerformancePanel` — live tick-rate sparkline + latency histogram\n    with canvas rendering\n  - `MultiBroadcastAdapter` cross-talk detection with per-robot sequence\n    tracking, pending timeout, and `getCrossTalkReport()`\n  - `multi-broadcast-soak.test.ts` — 10K-command soak test across 4\n    robots with zero cross-talk verification\n  - `docs/hil/multi-broadcast/SOAK-CHECKLIST.md` — 30-minute HIL soak\n    procedure for 3+ physical robots\n  - 25 unit tests (CrossTalkPanel + PerformancePanel + soak)\n\n**Release gate**: 3-robot soak test green; one community-recorded\nmulti-agent trace replayable; ≥2 RoboMaster S1 follow a browser-authored\nplayground session with \u003c10 cm / \u003c100 ms sim→physical error.\n\n#### v2.2 — VLA / policy slot-in _(+21 → +24 months)_\n\nMake CyberAgent the orchestration layer over modern policies.\n\n- [x] Action node `RunPolicy(\u003cHF model id\u003e, observation_spec)` — calls a\n      VLA / diffusion policy for one motion primitive.\n  - `src/engine/policy.ts` — `PolicyConfig` / `ObservationSpec` / `ActionSpec` / `PolicyResult` types\n  - `PolicyClient` interface with `RestPolicyClient`, `SimPolicyClient`, `MockPolicyClient` implementations\n  - `runPolicyAction()` — BT action node: extracts observations from blackboard, calls policy, maps action vector to commands\n  - `applyPolicyAction()` — action vector → nested robot command payload\n  - `registerPolicyNodes()` — registers `runPolicy` + `whenPolicyConfident` with BT engine\n  - `src/engine/policy.test.ts` — 25 tests (registry, clients, mappings, action node, condition)\n  - `experimental` — sim-only; real-hardware transfer validation pending\n- [x] `WhenPolicyConfident` selector branch.\n- [x] Reference integration: Pi0 / SmolVLA / GR00T via LeRobot bridge.\n  - `src/engine/lerobot-bridge.ts` — `LeRobotPolicyClient` with WebSocket handshake,\n    observation send, camera frame support, task switching, auto-reconnect\n  - `LEROBOT_MODELS` registry with `pi0`, `smolvla`, `gr00t` pre-configured\n  - `createLeRobotClient()` factory with camera config derivation\n  - `generateLeRobotHILChecklist()` for HIL docs\n  - `docs/hil/lerobot-bridge/CHECKLIST.md` — HIL verification checklist\n  - 22 unit tests\n  - ⚠️ `experimental` — sim-only; real-hardware transfer validation pending\n- [x] `/debug` shows policy input frames + action vector alongside BT.\n  - `src/pages/PolicyInputPanel.tsx` — observation grid + action bar chart + confidence indicator\n  - Frame selector slider for inspecting historical policy invocations\n  - Triggered-by source node attribution\n  - `src/pages/PolicyInputPanel.module.css` — panel styling\n  - Wired into `/debug` page via `useDebug` policy events\n- [x] Cookbook: how to ship a learned skill inside a hand-authored\n      character.\n  - `docs/cookbook/v2.2/hybrid-character-cookbook.md` — comprehensive guide\n    - Architecture overview: BT as director, policy as action node\n    - Sample VLA-Hybrid Guardian character with interleaved BT + policy\n    - Pi0 / SmolVLA / GR00T config examples with observation/action specs\n    - LeRobot bridge setup (Python server + browser client + camera capture)\n    - Debugging tips (PolicyInputPanel, tracer events, blackboard fields)\n    - Safety considerations and interleaving strategy\n  - `src/agents/vla-hybrid-guardian/` — sample hybrid character\n    - `character.ts` — VLA-Hybrid Guardian (guard category, experimental)\n    - `behavior.ts` — BT with whenPolicyConfident → runPolicy → rule patrol\n    - `index.ts` — barrel export\n  - Registered in `src/agents/index.ts` gallery and character map\n\n**Release gate**: one published character that interleaves authored BT\nbehavior with a learned VLA primitive on real hardware.\n\n#### v3.0 — Studio _(+24 months)_\n\nThe \"everyone can author a soul\" release.\n\n- [x] No-code character editor with VAL / memory / perception wired in.\n  - `src/pages/CharacterEditor.tsx` — full no-code editor with VAL affect, episodic memory, and perception config panels\n  - `src/pages/CharacterConfigPanel.tsx` — debug panel showing live character config\n  - `ValEngine` — respects valConfig initial/baseline/decay/perception overrides\n  - `BehaviorTreeRunner` — passes valConfig/memoryConfig/perceptionConfig to engine\n  - `loadCharacterFromJSON` — v3.0 format loader with custom agent registration\n  - `InMemoryEpisodicStore` — accepts MemoryConfig constructor param\n  - `PerceptionBus` — accepts PerceptionConfig enabled/categories/bufferSize\n  - `useDebug` — exposes character config state + setCharacterConfig\n- [x] One-click publish to Marketplace + signed character bundles.\n  - `src/utils/character-bundle.ts` — ES256 signing via Web Crypto API (P-256), deterministic signature input\n  - `src/utils/bundle-store.ts` — IndexedDB-backed BundleStore (publish/get/list/delete/reverify/import)\n  - `src/utils/bundle-store.test.ts` — 7 tests (parse, verify, summary)\n  - `src/pages/MarketplacePage.tsx` — \"My Published Bundles\" section with verification badges, re-verify/download/delete actions\n  - Import modal with paste + drag-and-drop bundle JSON, signature verification feedback\n  - CharacterEditor Publish button → signed bundle download\n  - i18n translations (en/zh)\n- [x] Hosted `/debug` (share a session URL with a teammate).\n  - `src/utils/session-share.ts` — encode/decode session state with deflate+base64url\n  - `src/components/ShareSessionPanel.tsx` — ShareSessionPanel with generate/copy/close buttons\n  - Auto-load shared session from URL hash on mount\n  - 7 tests for session-share + 5 tests for ShareSessionPanel\n- [x] Plugin SDK (third-party BT nodes / adapters / sensors).\n  - `sdk/src/plugin/types.ts` — PluginManifest, PluginRegistration, PluginRegistry, PluginSandbox, PluginRegistrationContext types\n  - `sdk/src/plugin/registry.ts` — PluginRegistryImpl with register/get/list/unload/clear/capability checks\n  - `sdk/src/plugin/loader.ts` — PluginLoader with manifest validation, dependency resolution, discovery\n  - `sdk/src/plugin/sandbox.ts` — createPluginContext + executePluginCode with dangerous-pattern blocking\n  - `src/pages/PluginManagerPage.tsx` — debug panel for browsing/managing plugins\n  - `src/pages/PluginManagerPage.module.css` — panel styling\n  - `docs/cookbook/v3.0/plugin-sdk.md` — comprehensive plugin authoring guide\n  - 67 unit tests (registry + loader + sandbox)\n- [x] Stable `@cyber-agent/sdk@3` with breaking-change migration guide.\n  - `sdk/package.json` version bumped to `3.0.0`\n  - `sdk/src/public-api.ts` marks v3.0 stable surface with full import examples\n  - `sdk/MIGRATION.md` — comprehensive 1.x → 3.0 migration guide:\n    - Plugin SDK adoption guide\n    - Adapter v1 shim deprecation timeline (removed in v4.0)\n    - New stable exports (plugin, session sharing, marketplace)\n    - Full v1→v2 migration examples\n  - `sdk/CHANGELOG.md` — v3.0.0 entry documenting all major features\n  - Stability guarantee: APIs in public-api.ts stable until 4.0\n\n**Release gate**: a non-engineer publishes a working character driving a\nreal toy without writing TypeScript.\n\n### Cross-cutting standing rules\n\nThese apply to **every** version and are enforced by the cron:\n\n1. **No feature without a debugger story** — the PR adds tracer events,\n   a `/debug` panel, or a replay capability.\n2. **No feature without a real-hardware test** — sim-only changes ship\n   behind `experimental/`.\n3. **HEARTBEAT.md cites the current version + the exact checkbox(es) in\n   flight.**\n4. **Trace schema is versioned** — breaking changes ship with a migration\n   script.\n5. **SDK backwards-compat for 1 minor version** at minimum; 1 major for\n   `@cyber-agent/sdk@1`.\n\n## Contributing\n\nSee the [Docs page](https://unbug.github.io/cyber-agent/docs) for guidelines.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funbug%2Fcyber-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funbug%2Fcyber-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funbug%2Fcyber-agent/lists"}