elizaos--eliza/plugins/plugin-personal-assistant/CLAUDE.md

@elizaos/plugin-personal-assistant

Personal assistant plugin: chat-first owner operations, executive workflows, scheduled tasks, calendar, inbox, documents, reminders, money admin, approvals, and owner-facing views for an Eliza agent.

Purpose / role

LifeOps is the personal and executive assistant interface. It owns the assistant workspace, cross-domain planning, owner approvals, scheduled-task operating loops, calendar/inbox/document/reminder/money workflows, and the chat/voice-first UI that lets Eliza act like a chief-of-staff for the owner.

LifeOps must not become the implementation home for adjacent domains:

• Health / sleep / circadian / screen-time planning belongs in @elizaos/plugin-health. LifeOps may expose thin owner-access wrappers and assistant intents that call plugin-health factories.
• Connector, adapter, bridge, and transport clients belong in their relevant plugins (plugin-google, plugin-whatsapp, plugin-x, plugin-browser, plugin-phone, plugin-calendly, etc.). LifeOps may keep registries, owner policies, and normalized personal-assistant projections.
• Native Apple Calendar / Reminders bridge policy belongs in native packages (@elizaos/capacitor-calendar, @elizaos/macosreminders). LifeOps may call those helpers and map results into assistant DTOs.
• Personal assistant code, views, scenarios, default packs, owner policy, approvals, and executive workflows belong here.

The plugin is opt-in; add @elizaos/plugin-personal-assistant to the agent's plugin list. It depends on @elizaos/plugin-google for current calendar/inbox projections (auto-registered at init if absent).

Plugin surface

Actions (registered via promoteSubactionsToActions)

Action name	File	What it does
BLOCK	src/actions/block.ts	Website/app block and unblock (SelfControl + OS APIs)
CALENDAR	src/actions/calendar.ts	Calendar read/write, event creation, scheduling
CONNECTOR	src/actions/connector.ts	Personal-assistant connector status/control facade; connector clients live in their plugins
CREDENTIALS	src/actions/credentials.ts	Credential lookup and autofill
OWNER_DOCUMENTS	src/actions/document.ts	Document search, review, signature workflows
INBOX	src/actions/inbox.ts	Email/messaging inbox triage
OWNER_REMINDERS	src/actions/owner-surfaces.ts	Reminders (Apple Reminders, Google Tasks)
OWNER_ALARMS	src/actions/owner-surfaces.ts	Alarms
OWNER_GOALS	src/actions/owner-surfaces.ts	Goals CRUD
OWNER_TODOS	src/actions/owner-surfaces.ts	Todos
OWNER_ROUTINES	src/actions/owner-surfaces.ts	Daily routines
OWNER_HEALTH	src/actions/owner-surfaces.ts	Thin wrapper around @elizaos/plugin-health health actions
OWNER_SCREENTIME	src/actions/owner-surfaces.ts	Thin wrapper around @elizaos/plugin-health screen-time planning (macOS only; platform-gated)
OWNER_FINANCES	src/actions/owner-surfaces.ts	Finance dashboard, transactions
PERSONAL_ASSISTANT	src/actions/owner-surfaces.ts	Cross-domain assistant orchestration
ENTITY	src/actions/entity.ts	Entity (contact/person/org) CRUD
BRIEF	src/actions/brief.ts	Morning/evening brief generation
PRIORITIZE	src/actions/prioritize.ts	Priority-score day's tasks and commitments
CONFLICT_DETECT	src/actions/conflict-detect.ts	Detect scheduling conflicts
RESOLVE_REQUEST	src/actions/resolve-request.ts	Resolve owner approval requests
VOICE_CALL	src/actions/voice-call.ts	Initiate/manage voice calls via Twilio
REMOTE_DESKTOP	src/actions/remote-desktop.ts	Remote desktop session control
WORK_THREAD	src/actions/work-thread.ts	Long-running work thread lifecycle
SCHEDULED_TASKS	src/actions/scheduled-task.ts	Scheduled-task CRUD for owner

Providers

Provider name	File	What it injects
lifeops_browser	src/provider.ts	Browser companion projection; browser bridge implementation lives in @elizaos/plugin-browser
websiteBlocker	src/providers/website-blocker.ts	Current website-blocker status
appBlocker	src/providers/app-blocker.ts	Current app-blocker status
firstRun	src/providers/first-run.ts	First-run completion state and affordances
ftuGoal	src/providers/ftu-goal.ts	Post-first-run goal-discovery affordance; silent once the owner's primary goal is known
roomPolicy	src/providers/room-policy.ts	Per-room handoff/policy state
lifeops	src/providers/lifeops.ts	Aggregated owner context for assistant planning
delegationContracts	src/providers/delegation-contracts.ts	Active delegation contracts for thread ownership, tripwires, and sender-class SLAs
pendingPrompts	src/providers/pending-prompts.ts	Pending questions waiting for owner input
workThreads	src/providers/work-threads.ts	Active work-thread state
recentTaskStates	src/providers/recent-task-states.ts	Recent scheduled-task execution results
lifeops-health	src/providers/health.ts	Thin provider wrapper created by @elizaos/plugin-health
inboxTriage	src/providers/inbox-triage.ts	Unresolved inbox items for triage
crossChannelContext	src/providers/cross-channel-context.ts	Cross-channel conversation context
activity-profile	src/providers/activity-profile.ts	Owner activity/presence profile

Services

Service type	Class	File	Role
lifeops_browser_plugin	BrowserBridgePluginService	src/service.ts	Legacy LifeOps facade for browser companion state; implementation should continue moving to @elizaos/plugin-browser
website_blocker	WebsiteBlockerService	src/website-blocker/service.ts	Hosts-file blocking (SelfControl) lifecycle
activity_tracker	ActivityTrackerService	src/activity-profile/activity-tracker-service.ts	Legacy activity projection for assistant context; health/screen-time domain logic belongs in @elizaos/plugin-health
presence_signal_bridge	PresenceSignalBridgeService	src/activity-profile/presence-signal-bridge-service.ts	Device presence signal forwarding

The lifeops_scheduled_task_runner service (ScheduledTaskRunnerService) is now registered by the always-loaded @elizaos/plugin-scheduling, not PA. PA is a consumer: init() injects its production deps (DB-backed store, production dispatcher, owner-facts / channel-keys / host-capability probes, anchor registry) via registerLifeOpsScheduledTaskRunnerDeps(runtime) (see src/lifeops/scheduled-task/runtime-wiring.ts). src/lifeops/scheduled-task/service.ts is a back-compat re-export of the moved service.

Evaluators

Evaluator name	File	Role
owner.profile_extraction (response handler)	src/lifeops/owner/profile-extraction-evaluator.ts	Extracts owner facts from agent responses
threadOps (response handler field)	src/lifeops/work-threads/field-evaluator-thread-ops.ts	Propagates work-thread field ops from responses
ftu_goal_discovery (post-turn, merged call)	src/lifeops/ftu-goal/evaluator.ts	Extracts the owner's primary goal after first-run; persists the primaryGoal owner fact and closes discovery once confident
anticipation_feedback (post-turn, merged call)	src/lifeops/anticipation/evaluator.ts	Classifies the owner's reaction to proactive dispatches (accepted / rejected / ignored) into durable rolling stats

Views

No views — the LifeOps overview surface was removed (owner: "no need for an overview"). The personal assistant is the chat itself (the PERSONAL_ASSISTANT action); the GET /api/lifeops/overview route + getOverview() service stay (reused by the todos projection + reminder delivery). The domain views live in the per-domain plugins (plugin-todos, plugin-inbox, plugin-goals, plugin-health, plugin-calendar, plugin-documents, plugin-blocker, plugin-finances, plugin-relationships). PA also exports the Blocker settings cards via src/ui.ts.

Layout

src/
  plugin.ts                     Plugin definition (actions, providers, services, init, dispose, views)
  index.ts                      Public exports (re-exports from plugin.ts + all submodules)
  service.ts                    BrowserBridgePluginService
  provider.ts                   browserBridgeProvider
  public.ts                     Additional public re-exports

  actions/
    block.ts                    BLOCK (website/app blocking umbrella)
    calendar.ts                 CALENDAR
    connector.ts                CONNECTOR facade over plugin-owned connector surfaces
    credentials.ts              CREDENTIALS
    document.ts                 OWNER_DOCUMENTS
    inbox.ts                    INBOX
    owner-surfaces.ts           OWNER_REMINDERS / OWNER_ALARMS / OWNER_GOALS / OWNER_TODOS
                                / OWNER_ROUTINES / health wrappers / screen-time wrappers
                                / OWNER_FINANCES / PERSONAL_ASSISTANT
    entity.ts                   ENTITY
    brief.ts                    BRIEF
    prioritize.ts               PRIORITIZE
    conflict-detect.ts          CONFLICT_DETECT
    resolve-request.ts          RESOLVE_REQUEST
    scheduled-task.ts           SCHEDULED_TASKS
    voice-call.ts               VOICE_CALL
    remote-desktop.ts           REMOTE_DESKTOP
    work-thread.ts              WORK_THREAD
    lib/                        Shared action helpers (calendly-handler, etc.)

  providers/                    All provider implementations (see table above)

  lifeops/
    scheduled-task/             Scheduled-task runner, state log, gates, escalation, runtime wiring
    entities/                   EntityStore + merge engine; voice-observer-bridge.ts
                                handles core VOICE_TURN_OBSERVED → VoiceObserver (merge
                                engine) → emits VOICE_ENTITY_BOUND back to the voice plugin
    relationships/              RelationshipStore
    registries/                 AnchorRegistry, EventKindRegistry, FamilyRegistry, BlockerRegistry
    channels/                   ChannelRegistry + priority-posture map
    connectors/                 ConnectorRegistry + owner policy projections.
                                Connector clients/adapters belong in their plugins.
    send-policy/                Per-connector send-policy contract + registry
    owner/                      OwnerFactStore, profile-extraction-evaluator
    first-run/                  FirstRunService, first-run state store
    pending-prompts/            PendingPromptsStore
    global-pause/               GlobalPauseStore
    handoff/                    Per-room HandoffStore
    i18n/                       MultilingualPromptRegistry, localized examples provider
    messaging/                  Assistant messaging projections and policies.
                                Transport adapters belong in connector plugins.
    checkin/                    CheckinService + schedule resolver
    work-threads/               WorkThreadStore + threadOps field evaluator
    service.ts                  LifeOpsService (large service composed from service-mixin-*.ts)
    repository.ts               LifeOpsRepository (DB access layer)
    runtime.ts                  Scheduler task worker + registration helpers
    schema.ts                   Drizzle schema for plugin tables
    approval-queue.ts           PgApprovalQueue (owner approval workflow)

  website-blocker/
    engine.ts                   SelfControl / hosts-file blocking engine
    service.ts                  WebsiteBlockerService + SelfControlBlockerService
    public.ts                   Public exports for website-blocker subsystem
    chat-integration/           Block-rule reconciler worker

  app-blocker/
    engine.ts                   OS-level app blocking engine (macOS)

  activity-profile/
    activity-tracker-service.ts ActivityTrackerService
    presence-signal-bridge-service.ts PresenceSignalBridgeService
    proactive-worker.ts         Proactive agent task (GM/GN/nudges)

  followup/                     Follow-up tracker task worker + overdue digest

  default-packs/                Default ScheduledTask packs
                                (daily-rhythm, morning-brief, quiet-user-watcher,
                                 habit-starters, inbox-triage-starter, followup-starter, ...)
  ../test/scenarios/            Executable LifeOps scenario-runner specs.
                                Executive-assistant scenarios should cover
                                chief-of-staff workflows beyond reminders:
                                schedule, follow-up, briefing, approvals,
                                messaging handoff, documents, money, and priority triage.

  platform/                     Platform detection helpers (isDarwin, etc.)
  routes/                       HTTP route handlers (lifeops, website-blocker, cloud-features, travel-relay)
  types/                        Shared TypeScript types
  widgets/                      Embeddable widgets (side-effectful entry)
  api/                          Client-side API helpers (client-lifeops.ts)
  components/                   React components
  ui.ts                         UI entry (side-effectful)

Commands

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

bun run --cwd plugins/plugin-personal-assistant clean                         # remove build output
bun run --cwd plugins/plugin-personal-assistant build                         # build package artifacts
bun run --cwd plugins/plugin-personal-assistant build:js                      # js build lane
bun run --cwd plugins/plugin-personal-assistant build:types                   # types build lane
bun run --cwd plugins/plugin-personal-assistant typecheck                     # TypeScript typecheck
bun run --cwd plugins/plugin-personal-assistant verify                        # package verification lane
bun run --cwd plugins/plugin-personal-assistant lint                          # mutating Biome check
bun run --cwd plugins/plugin-personal-assistant lint:check                    # read-only Biome check
bun run --cwd plugins/plugin-personal-assistant lint:default-packs            # node scripts/lint-default-packs.mjs
bun run --cwd plugins/plugin-personal-assistant format                        # write formatting
bun run --cwd plugins/plugin-personal-assistant format:check                  # read-only formatting check
bun run --cwd plugins/plugin-personal-assistant test                          # run package tests
bun run --cwd plugins/plugin-personal-assistant pretest                       # pre-test generated checks
bun run --cwd plugins/plugin-personal-assistant test:integration              # integration test lane
bun run --cwd plugins/plugin-personal-assistant test:scenarios                # scenarios test lane
bun run --cwd plugins/plugin-personal-assistant test:scenarios:list           # scenarios:list test lane
bun run --cwd plugins/plugin-personal-assistant test:scenarios:lifeops-spine  # scenarios:lifeops-spine test lane
bun run --cwd plugins/plugin-personal-assistant test:app-state                # app-state test lane
bun run --cwd plugins/plugin-personal-assistant test:background-real          # background-real test lane
bun run --cwd plugins/plugin-personal-assistant bench:work-threads            # work-threads benchmark lane
bun run --cwd plugins/plugin-personal-assistant verify:live-schedule          # bun run ./scripts/verify-live-schedule-data.ts

Config / env vars

Variable	Required	Description
ELIZA_DISABLE_PROACTIVE_AGENT	No	Set to 1 to skip the proactive GM/GN/nudge task
ELIZA_DISABLE_LIFEOPS_SCHEDULER	No	Set to 1 to skip the LifeOps scheduler task
LIFEOPS_USE_MOCKOON	No	Set to 1 to redirect all connector base URLs to local Mockoon mock servers
LIFEOPS_DUFFEL_API_BASE	No	Override Duffel travel-booking API base URL
SELFCONTROL_HOSTS_FILE_PATH	No	Override hosts-file path for website blocking (default: /etc/hosts)
WEBSITE_BLOCKER_HOSTS_FILE_PATH	No	Alternative hosts-file path override
ELIZA_DISABLE_ACTIVITY_TRACKER	No	Set to 1 to skip native activity tracker
ELIZA_NATIVE_PERMISSIONS_DYLIB	No	Path to native permissions dylib (macOS screen-time)
ELIZA_HEALTHKIT_CLI_PATH	No	HealthKit CLI path consumed by plugin-health; LifeOps may only observe its projections
ELIZA_IMESSAGE_BACKEND	No	iMessage backend selector
ELIZA_REMOTE_ACCESS_TOKEN	No	Token for remote desktop access
ELIZA_REMOTE_LOCAL_MODE	No	Set to 1 for local-only remote desktop mode
ELIZA_BROWSER_BRIDGE_COMPANION_TOKEN_TTL_MS	No	TTL for browser-bridge companion tokens
ELIZA_WHATSAPP_ACCESS_TOKEN	No	WhatsApp API access token
ELIZA_WHATSAPP_PHONE_NUMBER_ID	No	WhatsApp phone number ID
ELIZA_GOOGLE_FIT_ACCESS_TOKEN	No	Google Fit token consumed by plugin-health
GOOGLE_MAPS_API_KEY	No	Google Maps API key (travel-time calculations)
TWILIO_SMS_COST_PER_SEGMENT_USD	No	Override Twilio SMS cost estimate
ELIZAOS_CLOUD_API_KEY	No	Eliza Cloud API key (cloud features route)
ELIZAOS_CLOUD_BASE_URL	No	Eliza Cloud base URL override
ELIZA_LIFEOPS_CONTEXT_WINDOW	No	Override provider context window size (tokens)

ELIZA_DEVICE_KIND (desktop / mobile) is read for device-specific gating. ELIZA_DEVICE_ID is the stable device identifier.

How to extend

Add a new action

1. Create src/actions/<name>.ts. Export a const implementing Action from @elizaos/core. Use promoteSubactionsToActions if the action has named sub-operations.
2. Import and spread it into the actions array in src/plugin.ts.
3. Re-export from src/index.ts if it needs to be publicly importable.

Add a new provider

1. Create src/providers/<name>.ts. Export a Provider object.
2. Add it to the providers array in src/plugin.ts.
3. Re-export from src/index.ts if needed.

Add a new default pack

1. Add src/default-packs/<name>.ts exporting a DefaultPack (use compileTaskDefinition / compileTaskDefinitions — never construct raw ScheduledTaskSeed).
2. Import and register it in src/default-packs/index.ts inside getAllDefaultPacks().
3. List in getDefaultEnabledPacks() to auto-seed, or getOfferedDefaultPacks() for first-run opt-in.
4. Run bun run --cwd plugins/plugin-personal-assistant lint:default-packs to validate.

Add a new connector

1. Add src/lifeops/connectors/<name>.ts implementing the connector contract from src/lifeops/connectors/contract.ts.
2. Register it in src/lifeops/connectors/index.ts inside registerDefaultConnectorPack.

Conventions / gotchas

• OWNER_SCREENTIME is macOS-only. It is platform-gated via isDarwin() in src/plugin.ts (platformGatedActionUmbrellas). Do not add it unconditionally.
• Scheduler task init is deferred. Task workers are registered inside init(), but ensureTask calls are scheduled via runtime.initPromise so they run after the runtime finishes initializing. Failures are non-fatal to plugin load; check LIFEOPS_TASK_INIT_FAILURE_CACHE_KEY in the runtime cache for diagnostics.
• The runner never inspects promptInstructions. Routing is done purely on structural ScheduledTask fields. The runner lives in plugins/plugin-scheduling/src/scheduled-task/runner.ts; the personal-assistant side wires it in via src/lifeops/scheduled-task/{service,scheduler,runtime-wiring}.ts.
• Approval flows require an approval queue. Outbound message sends and document signatures go through PgApprovalQueue before any external dispatch. Never dispatch directly from action handlers.
• LifeOpsService is composed from mixins. Core logic lives in src/lifeops/service-mixin-*.ts files. src/lifeops/service.ts composes them. Add a new domain capability as a mixin.
• Default packs must pass lint. bun run lint:default-packs (also pretest) enforces the rules embedded in scripts/lint-default-packs.mjs. CI blocks packs that fail.
• plugin-google is auto-registered. If @elizaos/plugin-google is not already in the runtime's plugin list, init() dynamically imports and registers it. Ensure it is installed in the workspace.
• See root AGENTS.md for repo-wide architecture commandments, logger conventions, ESM rules, and naming.

⛔ 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 — agent behavior / app plugin:

• A live-LLM scenario trajectory showing the behavior end to end and asserting the outcome, not just that routing/an action was selected (see #9970).
• The artifacts the behavior creates — memories, knowledge, scheduled-task rows, relationships, documents, outputs — inspected after the run.
• Backend [ClassName] logs of the action/service/runner firing, plus error/edge/permission paths.
• The empty-state and adversarial-input behavior, not just one happy scenario.