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

@elizaos/plugin-personal-assistant

LifeOps is the elizaOS app that runs the user's day: routines, goals, calendar, email, messaging, follow-ups with people, blockers, watchers, and the operational glue around them. This README is the architecture summary for contributors.

Scheduled items, not generic tasks

Every reminder, check-in, follow-up, watcher, recap, approval surface, and nag-the-user-when-they-go-quiet flow is a LifeOps scheduled item stored as a ScheduledTask record and owned by the runner at 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). There is no second LifeOps scheduling mechanism.

ScheduledTask is intentionally not the repository-wide "task" primitive. Core runtime tasks are persisted Task rows handled by TaskService; coding agent work is orchestrator/task-coordinator state; project and feature tasks may have their own plugin-owned records. LifeOps integrates with those surfaces through public plugin/runtime contracts instead of importing or owning them as LifeOps primitives.

The shape:

interface ScheduledTask {
  taskId: string;
  kind: "reminder" | "checkin" | "followup" | "approval" | "recap" | "watcher" | "output" | "custom";
  promptInstructions: string;
  contextRequest?: { /* owner facts, entities, relationships, recent task states, event payload */ };
  trigger: /* once | cron | interval | relative_to_anchor | during_window | event | manual | after_task */;
  priority: "low" | "medium" | "high";
  shouldFire?: { compose: "all" | "any" | "first_deny"; gates: Array<{ kind: string; params? }> };
  completionCheck?: { kind: string; params?: ...; followupAfterMinutes? };
  escalation?: { ladderKey?: string; steps?: EscalationStep[] };
  output?: { destination: ...; target?: string; persistAs?: ... };
  pipeline?: { onComplete?, onSkip?, onFail? };
  subject?: { kind: "entity" | "relationship" | "thread" | "document" | "calendar_event" | "self"; id: string };
  idempotencyKey?: string;
  respectsGlobalPause: boolean;
  state: ScheduledTaskState;
  source: "default_pack" | "user_chat" | "first_run" | "plugin";
  createdBy: string;
  ownerVisible: boolean;
  metadata?: Record<string, unknown>;
}

The runner pattern-matches only on the structural fields above (kind, trigger, shouldFire, completionCheck, pipeline, output, subject, priority, respectsGlobalPause). It never inspects promptInstructions content. This is non-negotiable.

The frozen contract is defined in src/lifeops/scheduled-task/types.ts (the runner imports ScheduledTask from there). src/lifeops/wave1-types.ts is a slightly diverged copy consumed only by the first-run module.

No-reply semantics

Completion timeouts are structural scheduler behavior, not prompt text. For scheduled items that wait on a user reply, personal-assistant resolves a persisted no-reply contract from metadata.noReplyPolicy plus metadata.noReplyState and applies it in the single scheduler timeout pass:

metadata: {
  noReplyPolicy?: {
    maxRetries: number;
    retryCadenceMinutes: number[];
    terminalStatus: "skipped" | "expired" | "failed";
    terminalReason: string;
    sensitive: boolean;
    allowCrossChannel: boolean;
    allowNonOwnerNotification: boolean;
  };
  noReplyState?: {
    retryCount: number;
    lastTimedOutAt?: string;
    nextRetryAt?: string;
    terminalReason?: string;
    terminalOutcome?: "skipped" | "expired" | "failed" | "denied";
  };
}

Defaults are deliberately conservative:

• reminders retry once after 60 minutes, then skipped;
• check-ins retry once after 24 hours, then expired;
• non-sensitive approvals retry after 30 minutes and 2 hours, then expired;
• sensitive approvals retry once after 30 minutes, then expire with terminalOutcome: "denied";
• cross-channel escalation and non-owner notification default to false.

No no-reply path may auto-execute a sensitive output. Silence on money, data, or external-send approvals fails closed. No-reply expiry is not a user skip, so approval expiry does not fire pipeline.onSkip; authored skip pipelines remain reserved for explicit skip transitions.

Runtime layout

src/lifeops/
  scheduled-task/        Spine: runner, state log, gate registry,
                         completion-check registry, escalation, runtime
                         wiring.
  entities/              Entity primitive: store, merge engine, types.
  relationships/         Relationship edges: store, observation
                         extraction, types.
  registries/            AnchorRegistry, EventKindRegistry, FamilyRegistry,
                         BlockerRegistry, app/website blocker contributions.
  signals/               ActivitySignalBus.
  channels/              ChannelRegistry, priority-posture map, default
                         channel pack.
  connectors/            ConnectorRegistry + per-connector contributions
                         (calendly, discord, duffel, google, imessage,
                         signal, telegram, twilio, whatsapp, x).
  send-policy/           Per-connector send-policy contract + registry.
  owner/                 OwnerFactStore.
  first-run/             FirstRunService, state store, customize
                         questions, replay.
  pending-prompts/       PendingPromptsStore (the planner-visible
                         "questions waiting for the user" surface).
  global-pause/          GlobalPauseStore.
  handoff/               HandoffStore (per-room handoff state).
  i18n/                  MultilingualPromptRegistry.
  graph-migration/       Migration into the entity/relationship graph.
  seed-routine-migration/  Migration off legacy seed routines.
  ...other LifeOps-owned helpers (calendar, email, messaging, payments,
                                  subscriptions, assistant workflows, etc.)

Default packs

Default packs are bundles of typed scheduled-item definitions compiled into ScheduledTask records (and sometimes anchor-consolidation policies, escalation ladders, autofill whitelists). LifeOps-owned packs live in src/default-packs/:

• daily-rhythm — gm, gn, daily check-in.
• morning-brief — fired on wake.confirmed.
• quiet-user-watcher — daily watcher.
• habit-starters — eight habits, offered (not auto-seeded).
• executive-assistant — twenty-five scheduled records covering twenty personal/executive assistant scenario families, offered (not auto-seeded).
• inbox-triage-starter — opt-in, gated on Gmail.
• followup-starter — watcher firing per overdue relationship.
• autofill-whitelist-pack, consolidation-policies, escalation-ladders — policy-only packs.

@elizaos/plugin-health ships bedtime, wake-up, sleep-recap and registers them when a health connector pairs.

Adding a new default pack

1. Add a file under src/default-packs/<name>.ts that exports a DefaultPack matching registry-types.ts.
2. Define ReminderTaskDefinition, CheckInTaskDefinition, WatcherTaskDefinition, ApprovalTaskDefinition, RecapTaskDefinition, or OutputTaskDefinition values and compile them with compileTaskDefinition / compileTaskDefinitions. Pack files should not construct raw ScheduledTaskSeed records.
3. Import and append it to DEFAULT_PACKS in src/default-packs/index.ts.
4. If the pack should be auto-enabled, list it in getDefaultEnabledPacks. If it should be offered during first-run customize, list it in getOfferedDefaultPacks. If neither, the pack only seeds when invoked explicitly.
5. Run bun run lint:default-packs (also runs as pretest). The lint rules are embedded in scripts/lint-default-packs.mjs. CI rejects packs that violate them, including raw ScheduledTask construction.
6. Add a record-id constant export so consumers can target the records by stable ID.

The runtime never seeds packs by name string-match; everything goes through getAllDefaultPacks().

Knowledge graph

EntityStore (nodes) and RelationshipStore (edges) at src/lifeops/entities/ and src/lifeops/relationships/. The graph is per-agent. The entityId === "self" row is bootstrapped on first use.

• Cadence lives on the edge. "Pat — every 14 days" is a Relationship, not an Entity attribute. Cadence-bearing ScheduledTasks use subject.kind = "relationship".
• Identities are observed. (platform, handle) pairs route through observeIdentity; the merge engine in entities/merge.ts collapses entities with high-confidence identity matches. Manual merges go through POST /api/lifeops/entities/merge and are audited.
• REST surface — routes live in src/routes/.

Pause and handoff

• Global pause (global-pause/store.ts) — stops every ScheduledTask with respectsGlobalPause: true. Toggleable via UI or /api/lifeops/app-state.
• Per-room handoff (handoff/store.ts) — flips a multi-party room into handoff after the agent says "I'll let you take it from here." Typed resume conditions (mention | explicit_resume | silence_minutes | user_request_help). The RoomPolicyProvider reads HandoffStore.status(roomId).active and gates further agent contributions.

Plugin dependencies

LifeOps consumes @elizaos/plugin-health for sleep/circadian/health metrics, screen-time action planning, health action planning, health-context formatting, and health connector contributions. The plugin contributes through the registries listed above (AnchorRegistry, ConnectorRegistry, FamilyRegistry, default packs) and public factories such as createHealthActionRunner, createScreenTimeActionRunner, and createHealthProvider. LifeOps does not import directly into the health internals; it consumes the plugin's public exports only. See plugins/plugin-health/README.md.

Cross-agent invariants

1. The runner never pattern-matches promptInstructions.
2. subject.kind = "relationship" for cadence-bearing tasks.
3. Identities are observed, not assigned.
4. Connectors and channels return typed DispatchResult. No boolean.
5. shouldFire.gates is always an array.
6. acknowledged ≠ completed. Pipeline onComplete only fires on completed.
7. Snooze resets the escalation ladder.
8. Global pause skips tasks with respectsGlobalPause: true.

Where to look next

• Frozen interface types: src/lifeops/scheduled-task/types.ts.
• Prompt-content lint rules: scripts/lint-default-packs.mjs.
• Health domain: plugins/plugin-health/README.md.
• REST routes: src/routes/.