@elizaos/plugin-personal-assistant 2.0.11-beta.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# `@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
+`src/lifeops/scheduled-task/runner.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:
+
+```ts
+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.
+
+## 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
+  `ScheduledTask`s 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/`.

package/package.json

@@ -0,0 +1,135 @@
+{
+  "name": "@elizaos/plugin-personal-assistant",
+  "version": "2.0.11-beta.7",
+  "type": "module",
+  "description": "Personal-assistant orchestration plugin: BRIEF, PRIORITIZE, PERSONAL_ASSISTANT cross-domain orchestration, scheduled-task owner CRUD, and default-pack composition. Slimmed from the legacy plugin-lifeops; domain-specific surfaces have moved to plugin-inbox, plugin-goals, plugin-calendar, plugin-blocker, plugin-finances, plugin-relationships, etc.",
+  "sideEffects": [
+    "./src/api/client-lifeops.ts",
+    "./dist/api/client-lifeops.js"
+  ],
+  "main": "./dist/index.js",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "eliza-source": {
+        "types": "./src/plugin.ts",
+        "import": "./src/plugin.ts",
+        "default": "./src/plugin.ts"
+      },
+      "import": "./dist/plugin.js",
+      "default": "./dist/plugin.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "eliza-source": {
+        "types": "./src/*.ts",
+        "import": "./src/*.ts",
+        "default": "./src/*.ts"
+      },
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "scripts": {
+    "lint:default-packs": "node scripts/lint-default-packs.mjs",
+    "verify": "bun run lint:default-packs && bun run build:types && bun run test",
+    "pretest": "node scripts/lint-default-packs.mjs",
+    "test": "vitest run --config vitest.config.ts",
+    "test:app-state": "vitest run --config vitest.config.ts eliza/plugins/plugin-personal-assistant/test/lifeops-app-state.test.ts",
+    "test:background-real": "vitest run --config vitest.background-real.config.ts test/scheduled-task-end-to-end.e2e.test.ts test/reminder-review-job.real.e2e.test.ts test/lifeops-scheduling.real.test.ts test/schedule-merged-state.real.test.ts",
+    "test:integration": "cd ../../.. && vitest run --config eliza/packages/test/vitest/integration.config.ts eliza/plugins/plugin-personal-assistant/test/life-smoke.integration.test.ts",
+    "test:scenarios": "cd ../.. && bun packages/scenario-runner/src/cli.ts list plugins/plugin-personal-assistant/test/scenarios",
+    "bench:work-threads": "cd ../.. && bun plugins/plugin-personal-assistant/scripts/work-thread-benchmark.ts",
+    "verify:live-schedule": "bun run ./scripts/verify-live-schedule-data.ts",
+    "build": "bun run build:js && bun run build:types",
+    "clean": "rm -rf dist",
+    "build:js": "bun run clean && tsup --config tsup.config.ts",
+    "build:types": "tsc --noCheck -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@capacitor/core": "8.4.0",
+    "@elizaos/agent": "2.0.11-beta.7",
+    "@elizaos/app-core": "2.0.11-beta.7",
+    "@elizaos/capacitor-calendar": "2.0.11-beta.7",
+    "@elizaos/capacitor-mobile-signals": "2.0.11-beta.7",
+    "@elizaos/core": "2.0.11-beta.7",
+    "@elizaos/macosreminders": "2.0.11-beta.7",
+    "@elizaos/native-activity-tracker": "2.0.11-beta.7",
+    "@elizaos/plugin-blocker": "2.0.11-beta.7",
+    "@elizaos/plugin-browser": "2.0.11-beta.7",
+    "@elizaos/plugin-calendar": "2.0.11-beta.7",
+    "@elizaos/plugin-calendly": "2.0.11-beta.7",
+    "@elizaos/plugin-discord": "2.0.11-beta.7",
+    "@elizaos/plugin-elizacloud": "2.0.11-beta.7",
+    "@elizaos/plugin-finances": "2.0.11-beta.7",
+    "@elizaos/plugin-goals": "2.0.11-beta.7",
+    "@elizaos/plugin-google": "2.0.11-beta.7",
+    "@elizaos/plugin-health": "2.0.11-beta.7",
+    "@elizaos/plugin-inbox": "2.0.11-beta.7",
+    "@elizaos/plugin-phone": "2.0.11-beta.7",
+    "@elizaos/plugin-reminders": "2.0.11-beta.7",
+    "@elizaos/plugin-remote-desktop": "2.0.11-beta.7",
+    "@elizaos/plugin-scheduling": "2.0.11-beta.7",
+    "@elizaos/plugin-whatsapp": "2.0.11-beta.7",
+    "@elizaos/plugin-x": "2.0.11-beta.7",
+    "@elizaos/shared": "2.0.11-beta.7",
+    "@elizaos/ui": "2.0.11-beta.7",
+    "drizzle-orm": "0.45.2",
+    "lucide-react": "^1.0.0",
+    "react-plaid-link": "^4.0.1",
+    "sharp": "^0.34.5",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.4.0",
+    "@types/jsdom": "^28.0.0",
+    "bun-types": "1.3.14",
+    "dotenv": "^17.2.3",
+    "google-auth-library": "^10.0.0",
+    "jsdom": "^29.0.0",
+    "json5": "^2.2.3",
+    "react-dom": "*",
+    "ts-morph": "28.0.0",
+    "tsup": "^8.5.1",
+    "vite": "^8.0.0",
+    "vitest": "^4.0.17"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-dom": "*"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {}
+  },
+  "elizaos": {
+    "app": {
+      "heroImage": "assets/hero.png",
+      "permissions": [
+        "reminders",
+        "calendar",
+        "notes"
+      ]
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "gitHead": "cdbc876f793d96073d7eb0d09715a031ce0cd32e"
+}