elizaos--eliza/plugins/plugin-native-appblocker/AGENTS.md

@elizaos/capacitor-appblocker

Capacitor plugin that blocks selected apps on Android (Usage Access + system overlay) and iOS (Family Controls + ManagedSettings).

Purpose / role

This is a Capacitor native plugin — not an elizaOS action/service plugin. It exposes a JavaScript API (AppBlocker) that a Capacitor-based Eliza agent app can call to check permissions, let the user select apps to block, apply a block, and remove it. It has no runtime on the web: checkPermissions/requestPermissions return status: "not-applicable", getStatus returns status: "unavailable", blockApps/unblockApps return success: false, and getInstalledApps/selectApps return empty results. It is opt-in: the consuming app must register ElizaAppBlockerPlugin with Capacitor and call into the JS API.

Plugin surface

This is a Capacitor plugin, not an elizaOS plugin. It does not register elizaOS actions, providers, services, evaluators, routes, or events. The JS-side API exported from src/index.ts is:

Method	Description
AppBlocker.checkPermissions()	Returns current permission status and engine capabilities
AppBlocker.requestPermissions()	Opens system settings to grant Usage Access + overlay (Android) or triggers Family Controls auth (iOS)
AppBlocker.getInstalledApps()	Returns list of installed launcher apps (Android only; iOS returns [])
AppBlocker.selectApps()	iOS: opens FamilyActivityPicker and returns selected apps with tokenData. Android: returns { apps: [], cancelled: true } (no picker UI on Android — use getInstalledApps to build your own list)
AppBlocker.blockApps(options)	Activates blocking for given packageNames (Android) or appTokens (iOS); optional durationMinutes
AppBlocker.unblockApps()	Removes all active blocks
AppBlocker.getStatus()	Returns full AppBlockerStatus including active state, blocked count, engine, and permission details

src/backend.ts exports NativeAppBlockerBackend (interface) and createNativeAppBlockerBackend(plugin) (factory). Pass the registered AppBlocker Capacitor plugin to get an adapter shaped for @elizaos/plugin-blocker's registerNativeAppBlockerBackend(). This is the integration seam between the Capacitor native layer and the elizaOS blocker engine.

Layout

plugins/plugin-native-appblocker/
  src/
    index.ts               JS entry — registerPlugin("ElizaAppBlocker") + lazy web fallback
    definitions.ts         All TypeScript types: AppBlockerPlugin, AppBlockerStatus,
                           BlockAppsOptions, InstalledApp, SelectAppsResult, etc.
    web.ts                 Web fallback — all methods return not-applicable/unavailable
    web.test.ts            Vitest tests for web fallback contracts
    backend.ts             Backend adapter — wraps AppBlockerPlugin as NativeAppBlockerBackend
                           for registerNativeAppBlockerBackend() in @elizaos/plugin-blocker
    backend.test.ts        Vitest tests for the backend adapter
  android/src/main/
    AndroidManifest.xml    Declares permissions (PACKAGE_USAGE_STATS, SYSTEM_ALERT_WINDOW,
                           FOREGROUND_SERVICE, POST_NOTIFICATIONS) and ForegroundService
    java/ai/eliza/plugins/appblocker/
      AppBlockerPlugin.kt        Capacitor @PluginMethod handlers for Android
      AppBlockerForegroundService.kt  Polls UsageStatsManager every 500 ms; shows/hides overlay
      AppBlockerStateStore.kt    SharedPreferences persistence for blocked packages + expiry
  ios/Sources/AppBlockerPlugin/
    AppBlockerPlugin.swift       CAPPlugin with all method handlers for iOS
    AppBlockerShared.swift       ManagedSettingsStore shield apply/clear + UserDefaults state
    FamilyActivityPickerBridge.swift  SwiftUI FamilyActivityPicker presented as form sheet
  ElizaosCapacitorAppblocker.podspec  CocoaPods spec (links FamilyControls + ManagedSettings)
  rollup.config.mjs          Bundles dist/esm → dist/plugin.js (IIFE) + dist/plugin.cjs.js
  tsconfig.json              ES2022, strict, noImplicitAny, noUnusedLocals/Parameters

Commands

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

bun run --cwd plugins/plugin-native-appblocker clean           # remove build output
bun run --cwd plugins/plugin-native-appblocker build           # build package artifacts
bun run --cwd plugins/plugin-native-appblocker typecheck       # TypeScript typecheck
bun run --cwd plugins/plugin-native-appblocker lint            # mutating Biome check
bun run --cwd plugins/plugin-native-appblocker lint:check      # read-only Biome check
bun run --cwd plugins/plugin-native-appblocker format          # write formatting
bun run --cwd plugins/plugin-native-appblocker format:check    # read-only formatting check
bun run --cwd plugins/plugin-native-appblocker test            # run package tests
bun run --cwd plugins/plugin-native-appblocker prepublishOnly  # publish-time build hook
bun run --cwd plugins/plugin-native-appblocker build:unlocked  # bun run clean && tsc && bunx rollup -c rollup.config.mjs

Config / env vars

This plugin reads no environment variables. It requires OS-level permissions granted at runtime by the user:

• Android: PACKAGE_USAGE_STATS (Usage Access) and SYSTEM_ALERT_WINDOW (Draw Over Other Apps) — must both be granted for blockApps to succeed.
• iOS: Family Controls authorization (AuthorizationCenter.shared.requestAuthorization) — requires a developer provisioning profile with com.apple.developer.family-controls entitlement. Timed blocks (durationMinutes > 0) require a DeviceActivity extension and return an explicit unsupported-capability error in this package.

How to extend

Add a new method (JS → native):

1. Add the method signature to AppBlockerPlugin interface in src/definitions.ts.
2. Add an unavailable/error implementation in src/web.ts (AppBlockerWeb).
3. Add @PluginMethod fun myMethod(call: PluginCall) to android/.../AppBlockerPlugin.kt.
4. Add @objc func myMethod(_ call: CAPPluginCall) to ios/.../AppBlockerPlugin.swift and register it in pluginMethods.
5. Run bun run --cwd plugins/plugin-native-appblocker build to rebuild dist/.

Conventions / gotchas

• Instrumented test (issue #9967). The launchable-app enumeration (PackageManager.queryIntentActivities(MAIN/LAUNCHER)) lives in InstalledAppsReader; getInstalledApps delegates to it (JS shape unchanged) so an on-device androidTest drives the real PackageManager (permission-free positive read). Complements the AppBlockerStateStore block-state device test.
• Capacitor plugin, not elizaOS plugin: this has no Plugin object shaped for AgentRuntime. Do not wire it into elizaOS plugin loading. The consuming app imports and uses AppBlocker from JS.
• Android blocking engine: a foreground service (AppBlockerForegroundService) polls UsageStatsManager.queryEvents every 500 ms and shows a full-screen system overlay when a blocked app moves to foreground. The service is START_STICKY; it self-terminates if the block state is cleared or the timer expires.
• iOS engine: uses ManagedSettingsStore to set store.shield.applications. No polling; the OS enforces the shield. getInstalledApps always returns [] on iOS because Family Controls does not expose an app list — use selectApps to let the user pick via FamilyActivityPicker.
• iOS timed blocks: require a DeviceActivity extension. blockApps with durationMinutes > 0 returns success: false with an explanatory unsupported-capability error. An indefinite block + manual unblockApps is the current iOS path.
• Build output: tsc writes to dist/esm/; rollup bundles that into dist/plugin.js (IIFE for CDN/unpkg) and dist/plugin.cjs.js (CJS for Node consumers). The exports field in package.json points directly to src/index.ts for Bun/development consumers.
• Capacitor version: peer dep @capacitor/core ^8.3.1. Keep in sync with the consuming app's Capacitor version or Capacitor's JS ↔ native bridge will misroute calls.
• iOS deployment target: iOS 15.0 (set in podspec). FamilyControls authorization API differs between iOS < 16 and >= 16; AppBlockerPlugin.swift handles both paths.

⛔ 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.