elizaos--eliza/plugins/plugin-native-shared-types/CLAUDE.md

@elizaos/native-plugin-shared-types

Shared TypeScript type contracts for elizaOS native plugin bridges (Capacitor and Electrobun).

Purpose / role

This is a type-only package — it exports no runtime code, no elizaOS Plugin object, and registers no actions, providers, services, or evaluators. Its sole purpose is to provide canonical shared type definitions used by native plugin bridges across elizaOS plugins that target Capacitor (mobile) or Electrobun (desktop) runtimes, as well as web-speech shims needed by plugins like Swabble and TalkMode.

It is consumed via workspace:* by sibling plugins in the monorepo; it is not published to npm and is "private": true.

Plugin surface

No runtime plugin surface. No actions, providers, services, evaluators, routes, or events.

Layout

plugins/plugin-native-shared-types/
  package.json        name: @elizaos/native-plugin-shared-types; type: module; private: true
  src/
    index.ts          All exported types (single file)

Exports from src/index.ts

Export	Kind	Description
EventCallback<T>	type alias	Generic event callback for Capacitor/Electrobun plugin bridges
ListenerEntry<TEventName, TEventData>	interface	Listener entry shape used by Electrobun plugin bridges
SpeechRecognitionInstance	interface	Minimal Web Speech API SpeechRecognition shim (not in all TS targets)
SpeechRecognitionResultEvent	interface	Result event shape from the Web Speech API
SpeechRecognitionResultList	interface	Result list shape (indexed, with isFinal and transcript)
SpeechRecognitionCtor	type alias	Constructor type for SpeechRecognitionInstance
SpeechRecognitionWindow	interface	Window augmentation declaring optional SpeechRecognition and webkitSpeechRecognition

Commands

Scripts are defined in package.json; run them from the repo root with bun run --cwd:

bun run --cwd plugins/plugin-native-shared-types typecheck     # TypeScript typecheck
bun run --cwd plugins/plugin-native-shared-types lint          # mutating Biome check
bun run --cwd plugins/plugin-native-shared-types lint:check    # read-only Biome check
bun run --cwd plugins/plugin-native-shared-types format        # write formatting
bun run --cwd plugins/plugin-native-shared-types format:check  # read-only formatting check
bun run --cwd plugins/plugin-native-shared-types test          # run package tests

Config / env vars

None. This package contains no runtime code.

How to extend

To add a new shared type contract:

1. Open plugins/plugin-native-shared-types/src/index.ts.
2. Export the new interface, type alias, or enum with a JSDoc comment explaining which plugin(s) consume it.
3. Import from @elizaos/native-plugin-shared-types in the consuming plugin (it resolves via workspace:*).

Do not add runtime logic, class implementations, or any code with side effects to this package.

Conventions / gotchas

• Type-only. Any addition must be a pure TypeScript type, interface, or const enum. No runtime values.
• Single file. All exports live in src/index.ts. Do not create subdirectories or split the module.
• "main": "./src/index.ts" and "exports": { ".": "./src/index.ts" } point directly at source. There is no build step and no dist/. Consumers rely on TypeScript resolving the source directly.
• private: true. This package is not published; it only exists as a workspace dependency.
• The Web Speech API shims exist because TypeScript's lib.dom.d.ts does not expose SpeechRecognition in all compiler targets. They are intentionally minimal — cover only what Swabble and TalkMode actually use.

⛔ NON-NEGOTIABLE — evidence, trajectories & real end-to-end tests

The binding, repo-wide standard is AGENTS.md. Read it. Nothing in this package is done until it is proven done — a reviewer must confirm it works without reading the code, from the artifacts you attach. This applies to every feature, fix, refactor, and chore here. "Tests pass" is not proof; "CI is green" is not proof.

• Record AND read model trajectories. Capture the actual inputs and outputs of the model from a live LLM — not the deterministic proxy, not a mock: the prompt, the providers/context, the raw model output, every tool/action call, and the result. Then open the trajectory and review it by hand. A captured-but-unread trajectory is not evidence (packages/scenario-runner/bin/eliza-scenarios run <scenario> --report <out>).
• Real, full-featured E2E — no larp. Every feature ships detailed end-to-end tests that drive the real path end to end. Not the happy "front door" only: cover error paths, edge/empty/invalid input, concurrency, roles/permissions, and adversarial input. A test that asserts against a mock/stub/fixture standing in for the thing under test does not count. If the real model/device/chain/connector/account is hard to reach, make it reachable — that is the work, not an excuse to mock. If the existing tests here are shallow or mocked, fixing them is part of your change.
• Screenshots + logs at every phase, plus a complete walkthrough video/run-through of the entire feature or view, start to finish (bun run test:e2e:record).
• Manually review every artifact the change touches — never just the green check: client logs (console + network), server logs ([ClassName] …), the model trajectories in and out, before/after full-page screenshots, and the domain artifacts listed below for this package.
• No residuals. No shortcuts. The goal is not "done" — it is everything done. Clear every blocker by the hard path: build the real architecture, stand up the real model/device/service, actually test it. Never leave a TODO, a stub, a stepping-stone, or a "follow-up." When unsure, research thoroughly, weigh the options, and ship the best, highest-effort, production-ready version. Keep going until every possibility is exhausted.

Artifacts → attached inline in the PR (MP4 video, JPG screenshots, logs in <details>); attach each evidence type or explicitly mark it N/A with a reason — never leave it blank. If develop moved and changed behavior, re-capture evidence; stale proof is worse than none.

Capture & manually review for this package — native / on-device bridge:

• The capability run on a real device or simulator — not desktop Chromium against a mocked bridge (see #9967/#9580): device logs + the captured output (photo, OCR text, detection boxes, transcript, sensor reading).
• Parity vs the reference implementation where one exists (e.g. the Python/Ultralytics reference), with the numeric tolerances actually met.
• Permission-denied, no-hardware, and background/foreground lifecycle paths.
• A short recording of the on-device run; confirm the build under test is yours (versionName / a known on-screen change), not a stale install.