@elizaos/capacitor-eliza-tasks 2.0.3-beta.2

package/ElizaosCapacitorElizaTasks.podspec

@@ -0,0 +1,19 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name = 'ElizaosCapacitorElizaTasks'
+  s.version = package['version']
+  s.summary = package['description']
+  s.license = package['license'] || { :type => 'MIT' }
+  s.homepage = 'https://elizaos.ai'
+  s.authors = { 'elizaOS' => 'dev@elizaos.ai' }
+  s.source = { :git => 'https://github.com/elizaOS/eliza.git', :tag => s.version.to_s }
+  s.source_files = 'ios/Sources/**/*.{swift,h,m}'
+  s.ios.deployment_target = '15.0'
+  s.dependency 'Capacitor'
+  s.swift_version = '5.9'
+  # BackgroundTasks ships in the iOS SDK; only the framework needs declaring.
+  s.frameworks = 'UIKit', 'BackgroundTasks', 'UserNotifications'
+end

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,116 @@
+# @elizaos/capacitor-eliza-tasks
+
+Capacitor plugin that bridges iOS `BGTaskScheduler` background-wake events into the elizaOS Capacitor runtime.
+
+## What it does
+
+iOS suspends apps when they leave the foreground. This plugin registers two background task identifiers with `BGTaskScheduler` so the elizaOS iOS app can be woken by the OS on a schedule:
+
+- **`BGAppRefreshTask`** (`ai.eliza.tasks.refresh`) — short wake (~25s budget), network available. Used for polling the agent's loopback `/api/internal/wake` route.
+- **`BGProcessingTask`** (`ai.eliza.tasks.processing`) — long-running wake (~120s budget), requires device to be charging and idle. Used for local-LLM warmup passes.
+- **Silent APNs push** (`remote-push`) — optional; gated on `ELIZA_APNS_ENABLED` in `Info.plist`. Forwarded through `AppDelegate` via `ElizaCompanionRemotePush` `NSNotification`.
+
+All three wake paths emit the same `wake` event to the JS layer, so a single handler can drain them:
+
+```ts
+import { ElizaTasks } from "@elizaos/capacitor-eliza-tasks";
+
+await ElizaTasks.addListener("wake", (event) => {
+  console.log(event.kind, event.deadlineSec, event.firedAtMs);
+  // event.kind: "refresh" | "processing" | "remote-push"
+});
+
+// Arm the first wake
+await ElizaTasks.scheduleNext({ earliestBeginSec: 900 });
+```
+
+On web and non-iOS platforms the plugin returns `supported: false`; scheduling reports no iOS wake path, and cancellation reports that no web wake requests were cancelled. The app should call `getStatus()` and fall back to `@capacitor/background-runner` polling when `supported` is false.
+
+## Installation
+
+```bash
+npm install @elizaos/capacitor-eliza-tasks
+npx cap sync
+```
+
+### iOS setup
+
+Add both identifiers to `Info.plist`:
+
+```xml
+<key>BGTaskSchedulerPermittedIdentifiers</key>
+<array>
+  <string>ai.eliza.tasks.refresh</string>
+  <string>ai.eliza.tasks.processing</string>
+</array>
+```
+
+For silent-push support also add:
+
+```xml
+<key>ELIZA_APNS_ENABLED</key>
+<string>1</string>
+```
+
+And enable the **Background Modes** capability in Xcode: check `Background fetch` and `Remote notifications`.
+
+## API
+
+### `scheduleNext(options?)`
+
+Enqueues the next `BGAppRefreshTask`. Idempotent — replaces any pending request.
+
+```ts
+interface ElizaTasksScheduleOptions {
+  earliestBeginSec?: number;  // default 900 (15 min), floor 1
+  alsoProcessing?: boolean;   // also schedule a BGProcessingTask
+}
+```
+
+Returns `ElizaTasksScheduleResult` with `{ scheduled, identifier, earliestBeginAtMs, reason }`.
+
+### `getStatus()`
+
+Returns the plugin's view of `BGTaskScheduler` state:
+
+```ts
+interface ElizaTasksStatus {
+  supported: boolean;
+  platform: "ios" | "android" | "web";
+  refreshScheduled: boolean;
+  processingScheduled: boolean;
+  lastWakeFiredAtMs: number | null;
+  lastWakeKind: ElizaTaskKind | null;
+  reason: string | null;
+}
+```
+
+### `cancelAll()`
+
+Cancels all pending refresh and processing task requests.
+
+### `addListener("wake", fn)`
+
+Registers a listener for `ElizaTasksWakeEvent`:
+
+```ts
+interface ElizaTasksWakeEvent {
+  kind: "refresh" | "processing" | "remote-push";
+  identifier: string;
+  deadlineSec: number;
+  firedAtMs: number;
+  payload: Record<string, unknown>;
+}
+```
+
+### `removeAllListeners()`
+
+Removes all `wake` listeners.
+
+## Platform support
+
+| Platform | Support |
+|---|---|
+| iOS 15+ | Full — `BGTaskScheduler` + optional APNs |
+| Android | Unsupported in this iOS BGTaskScheduler bridge |
+| Web / Electron | Unsupported fallback (`supported: false`) |

package/dist/esm/definitions.d.ts

@@ -0,0 +1,84 @@
+import type { PluginListenerHandle } from "@capacitor/core";
+/**
+ * Background task kinds the native plugin can wake the JS layer with.
+ *
+ *  - `refresh`     → iOS `BGAppRefreshTaskRequest` — short (~30s), network-OK
+ *                    foreground-equivalent wake. Used for the polling poke
+ *                    against `/api/internal/wake`.
+ *  - `processing`  → iOS `BGProcessingTaskRequest` — long-running (~minutes),
+ *                    runs while the device is charging and idle. Used for the
+ *                    local-LLM warmup pass that has no time pressure.
+ *  - `remote-push` → silent APNs `content-available:1` push (gated on
+ *                    `ELIZA_APNS_ENABLED` in Info.plist). Mirrors the BG-task
+ *                    contract so the JS side can treat all three uniformly.
+ */
+export type ElizaTaskKind = "refresh" | "processing" | "remote-push";
+export type ElizaTaskIdentifier = "ai.eliza.tasks.refresh" | "ai.eliza.tasks.processing";
+/**
+ * Wake event delivered to JS listeners. Mirrors the `addEventListener("wake")`
+ * contract in `runners/eliza-tasks.js` so the BackgroundRunner runner and the
+ * BGTaskScheduler-driven runner share one client-side handler.
+ */
+export interface ElizaTasksWakeEvent {
+    kind: ElizaTaskKind;
+    identifier: ElizaTaskIdentifier | "ai.eliza.tasks.remote-push";
+    deadlineSec: number;
+    /** When the OS dispatched the wake (epoch ms). */
+    firedAtMs: number;
+    /**
+     * For `remote-push`, the raw `userInfo` from APNs (minus `aps`). For
+     * BGTaskScheduler wakes, an empty object — wake-time payload lives in the
+     * agent's loopback HTTP route.
+     */
+    payload: Record<string, unknown>;
+}
+export interface ElizaTasksScheduleOptions {
+    /**
+     * Earliest begin date for the next wake, expressed as seconds from now.
+     * `BGTaskScheduler` treats this as a hint — the OS controls the actual
+     * dispatch time. Must be ≥ 1.
+     */
+    earliestBeginSec?: number;
+    /**
+     * If true, also enqueue the long-running BGProcessingTask. The processing
+     * variant only fires while the device is charging and idle.
+     */
+    alsoProcessing?: boolean;
+}
+export interface ElizaTasksScheduleResult {
+    scheduled: boolean;
+    identifier: ElizaTaskIdentifier;
+    earliestBeginAtMs: number | null;
+    reason: string | null;
+}
+export interface ElizaTasksStatus {
+    supported: boolean;
+    platform: "ios" | "android" | "web";
+    refreshScheduled: boolean;
+    processingScheduled: boolean;
+    lastWakeFiredAtMs: number | null;
+    lastWakeKind: ElizaTaskKind | null;
+    reason: string | null;
+}
+export interface ElizaTasksPlugin {
+    /**
+     * Enqueue the next BG refresh wake. Idempotent — calling repeatedly
+     * replaces the pending request rather than stacking.
+     */
+    scheduleNext(options?: ElizaTasksScheduleOptions): Promise<ElizaTasksScheduleResult>;
+    /**
+     * Snapshot of the plugin's view of BGTaskScheduler state. Used by the JS
+     * layer to decide whether to fall back to the BackgroundRunner repeat poll.
+     */
+    getStatus(): Promise<ElizaTasksStatus>;
+    /**
+     * Cancel any pending refresh + processing requests. Used during the
+     * `disable mobile background tasks` flow.
+     */
+    cancelAll(): Promise<{
+        cancelled: boolean;
+    }>;
+    addListener(eventName: "wake", listenerFunc: (event: ElizaTasksWakeEvent) => void): Promise<PluginListenerHandle>;
+    removeAllListeners(): Promise<void>;
+}
+//# sourceMappingURL=definitions.d.ts.map

package/dist/esm/definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,YAAY,GAAG,aAAa,CAAC;AAErE,MAAM,MAAM,mBAAmB,GAC3B,wBAAwB,GACxB,2BAA2B,CAAC;AAEhC;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,EAAE,mBAAmB,GAAG,4BAA4B,CAAC;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,mBAAmB,CAAC;IAChC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,KAAK,GAAG,SAAS,GAAG,KAAK,CAAC;IACpC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,YAAY,EAAE,aAAa,GAAG,IAAI,CAAC;IACnC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,YAAY,CACV,OAAO,CAAC,EAAE,yBAAyB,GAClC,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAErC;;;OAGG;IACH,SAAS,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEvC;;;OAGG;IACH,SAAS,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAE7C,WAAW,CACT,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GACjD,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEjC,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC"}

package/dist/esm/definitions.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+import type { ElizaTasksPlugin } from "./definitions";
+export * from "./definitions";
+export declare const ElizaTasks: ElizaTasksPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,cAAc,eAAe,CAAC;AAI9B,eAAO,MAAM,UAAU,kBAErB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,6 @@
+import { registerPlugin } from "@capacitor/core";
+export * from "./definitions";
+const loadWeb = () => import("./web").then((m) => new m.ElizaTasksWeb());
+export const ElizaTasks = registerPlugin("ElizaTasks", {
+    web: loadWeb,
+});

package/dist/esm/web.d.ts

@@ -0,0 +1,17 @@
+import { WebPlugin } from "@capacitor/core";
+import type { ElizaTasksPlugin, ElizaTasksScheduleOptions, ElizaTasksScheduleResult, ElizaTasksStatus } from "./definitions";
+/**
+ * Web fallback for the ElizaTasks plugin.
+ *
+ * Browsers have no `BGTaskScheduler` equivalent. The plugin resolves to a
+ * `supported: false` status so the runtime knows to fall back to the
+ * BackgroundRunner repeat poll (already configured in `capacitor.config.ts`).
+ */
+export declare class ElizaTasksWeb extends WebPlugin implements ElizaTasksPlugin {
+    scheduleNext(_options?: ElizaTasksScheduleOptions): Promise<ElizaTasksScheduleResult>;
+    getStatus(): Promise<ElizaTasksStatus>;
+    cancelAll(): Promise<{
+        cancelled: boolean;
+    }>;
+}
+//# sourceMappingURL=web.d.ts.map

package/dist/esm/web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/web.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EACV,gBAAgB,EAChB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAEvB;;;;;;GAMG;AACH,qBAAa,aAAc,SAAQ,SAAU,YAAW,gBAAgB;IACtE,YAAY,CACV,QAAQ,CAAC,EAAE,yBAAyB,GACnC,OAAO,CAAC,wBAAwB,CAAC;IASpC,SAAS,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAYtC,SAAS,IAAI,OAAO,CAAC;QAAE,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;CAG7C"}

package/dist/esm/web.js

@@ -0,0 +1,32 @@
+import { WebPlugin } from "@capacitor/core";
+/**
+ * Web fallback for the ElizaTasks plugin.
+ *
+ * Browsers have no `BGTaskScheduler` equivalent. The plugin resolves to a
+ * `supported: false` status so the runtime knows to fall back to the
+ * BackgroundRunner repeat poll (already configured in `capacitor.config.ts`).
+ */
+export class ElizaTasksWeb extends WebPlugin {
+    scheduleNext(_options) {
+        return Promise.resolve({
+            scheduled: false,
+            identifier: "ai.eliza.tasks.refresh",
+            earliestBeginAtMs: null,
+            reason: "BGTaskScheduler is iOS-only; web has no background wake path.",
+        });
+    }
+    getStatus() {
+        return Promise.resolve({
+            supported: false,
+            platform: "web",
+            refreshScheduled: false,
+            processingScheduled: false,
+            lastWakeFiredAtMs: null,
+            lastWakeKind: null,
+            reason: "BGTaskScheduler is iOS-only; web has no background wake path.",
+        });
+    }
+    cancelAll() {
+        return Promise.resolve({ cancelled: false });
+    }
+}

package/dist/esm/web.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=web.test.d.ts.map

package/dist/esm/web.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.test.d.ts","sourceRoot":"","sources":["../../src/web.test.ts"],"names":[],"mappings":""}

package/dist/esm/web.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { ElizaTasksWeb } from "./web";
+describe("ElizaTasksWeb fallback", () => {
+    it("reports the browser as unsupported without throwing", async () => {
+        await expect(new ElizaTasksWeb().getStatus()).resolves.toEqual({
+            supported: false,
+            platform: "web",
+            refreshScheduled: false,
+            processingScheduled: false,
+            lastWakeFiredAtMs: null,
+            lastWakeKind: null,
+            reason: "BGTaskScheduler is iOS-only; web has no background wake path.",
+        });
+    });
+    it.each([
+        undefined,
+        {},
+        { earliestBeginSec: Number.NaN, alsoProcessing: true },
+        { earliestBeginSec: Number.POSITIVE_INFINITY, alsoProcessing: true },
+        { earliestBeginSec: -1, alsoProcessing: true },
+    ])("ignores schedule options on web %#", async (options) => {
+        await expect(new ElizaTasksWeb().scheduleNext(options)).resolves.toEqual({
+            scheduled: false,
+            identifier: "ai.eliza.tasks.refresh",
+            earliestBeginAtMs: null,
+            reason: "BGTaskScheduler is iOS-only; web has no background wake path.",
+        });
+    });
+    it("cancelAll reports that no web wake requests were cancelled", async () => {
+        await expect(new ElizaTasksWeb().cancelAll()).resolves.toEqual({
+            cancelled: false,
+        });
+    });
+});

package/dist/plugin.cjs.js

@@ -0,0 +1,48 @@
+'use strict';
+
+var core = require('@capacitor/core');
+
+const loadWeb = () => Promise.resolve().then(function () { return web; }).then((m) => new m.ElizaTasksWeb());
+const ElizaTasks = core.registerPlugin("ElizaTasks", {
+    web: loadWeb,
+});
+
+/**
+ * Web fallback for the ElizaTasks plugin.
+ *
+ * Browsers have no `BGTaskScheduler` equivalent. The plugin resolves to a
+ * `supported: false` status so the runtime knows to fall back to the
+ * BackgroundRunner repeat poll (already configured in `capacitor.config.ts`).
+ */
+class ElizaTasksWeb extends core.WebPlugin {
+    scheduleNext(_options) {
+        return Promise.resolve({
+            scheduled: false,
+            identifier: "ai.eliza.tasks.refresh",
+            earliestBeginAtMs: null,
+            reason: "BGTaskScheduler is iOS-only; web has no background wake path.",
+        });
+    }
+    getStatus() {
+        return Promise.resolve({
+            supported: false,
+            platform: "web",
+            refreshScheduled: false,
+            processingScheduled: false,
+            lastWakeFiredAtMs: null,
+            lastWakeKind: null,
+            reason: "BGTaskScheduler is iOS-only; web has no background wake path.",
+        });
+    }
+    cancelAll() {
+        return Promise.resolve({ cancelled: false });
+    }
+}
+
+var web = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    ElizaTasksWeb: ElizaTasksWeb
+});
+
+exports.ElizaTasks = ElizaTasks;
+//# sourceMappingURL=plugin.cjs.js.map

package/dist/plugin.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.cjs.js","sources":["esm/index.js","esm/web.js"],"sourcesContent":["import { registerPlugin } from \"@capacitor/core\";\nexport * from \"./definitions\";\nconst loadWeb = () => import(\"./web\").then((m) => new m.ElizaTasksWeb());\nexport const ElizaTasks = registerPlugin(\"ElizaTasks\", {\n    web: loadWeb,\n});\n","import { WebPlugin } from \"@capacitor/core\";\n/**\n * Web fallback for the ElizaTasks plugin.\n *\n * Browsers have no `BGTaskScheduler` equivalent. The plugin resolves to a\n * `supported: false` status so the runtime knows to fall back to the\n * BackgroundRunner repeat poll (already configured in `capacitor.config.ts`).\n */\nexport class ElizaTasksWeb extends WebPlugin {\n    scheduleNext(_options) {\n        return Promise.resolve({\n            scheduled: false,\n            identifier: \"ai.eliza.tasks.refresh\",\n            earliestBeginAtMs: null,\n            reason: \"BGTaskScheduler is iOS-only; web has no background wake path.\",\n        });\n    }\n    getStatus() {\n        return Promise.resolve({\n            supported: false,\n            platform: \"web\",\n            refreshScheduled: false,\n            processingScheduled: false,\n            lastWakeFiredAtMs: null,\n            lastWakeKind: null,\n            reason: \"BGTaskScheduler is iOS-only; web has no background wake path.\",\n        });\n    }\n    cancelAll() {\n        return Promise.resolve({ cancelled: false });\n    }\n}\n"],"names":["registerPlugin","WebPlugin"],"mappings":";;;;AAEA,MAAM,OAAO,GAAG,MAAM,mDAAe,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,aAAa,EAAE,CAAC;AAC5D,MAAC,UAAU,GAAGA,mBAAc,CAAC,YAAY,EAAE;AACvD,IAAI,GAAG,EAAE,OAAO;AAChB,CAAC;;ACJD;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAM,aAAa,SAASC,cAAS,CAAC;AAC7C,IAAI,YAAY,CAAC,QAAQ,EAAE;AAC3B,QAAQ,OAAO,OAAO,CAAC,OAAO,CAAC;AAC/B,YAAY,SAAS,EAAE,KAAK;AAC5B,YAAY,UAAU,EAAE,wBAAwB;AAChD,YAAY,iBAAiB,EAAE,IAAI;AACnC,YAAY,MAAM,EAAE,+DAA+D;AACnF,SAAS,CAAC;AACV,IAAI;AACJ,IAAI,SAAS,GAAG;AAChB,QAAQ,OAAO,OAAO,CAAC,OAAO,CAAC;AAC/B,YAAY,SAAS,EAAE,KAAK;AAC5B,YAAY,QAAQ,EAAE,KAAK;AAC3B,YAAY,gBAAgB,EAAE,KAAK;AACnC,YAAY,mBAAmB,EAAE,KAAK;AACtC,YAAY,iBAAiB,EAAE,IAAI;AACnC,YAAY,YAAY,EAAE,IAAI;AAC9B,YAAY,MAAM,EAAE,+DAA+D;AACnF,SAAS,CAAC;AACV,IAAI;AACJ,IAAI,SAAS,GAAG;AAChB,QAAQ,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AACpD,IAAI;AACJ;;;;;;;;;"}

package/dist/plugin.js

@@ -0,0 +1,51 @@
+var capacitorElizaTasks = (function (exports, core) {
+    'use strict';
+
+    const loadWeb = () => Promise.resolve().then(function () { return web; }).then((m) => new m.ElizaTasksWeb());
+    const ElizaTasks = core.registerPlugin("ElizaTasks", {
+        web: loadWeb,
+    });
+
+    /**
+     * Web fallback for the ElizaTasks plugin.
+     *
+     * Browsers have no `BGTaskScheduler` equivalent. The plugin resolves to a
+     * `supported: false` status so the runtime knows to fall back to the
+     * BackgroundRunner repeat poll (already configured in `capacitor.config.ts`).
+     */
+    class ElizaTasksWeb extends core.WebPlugin {
+        scheduleNext(_options) {
+            return Promise.resolve({
+                scheduled: false,
+                identifier: "ai.eliza.tasks.refresh",
+                earliestBeginAtMs: null,
+                reason: "BGTaskScheduler is iOS-only; web has no background wake path.",
+            });
+        }
+        getStatus() {
+            return Promise.resolve({
+                supported: false,
+                platform: "web",
+                refreshScheduled: false,
+                processingScheduled: false,
+                lastWakeFiredAtMs: null,
+                lastWakeKind: null,
+                reason: "BGTaskScheduler is iOS-only; web has no background wake path.",
+            });
+        }
+        cancelAll() {
+            return Promise.resolve({ cancelled: false });
+        }
+    }
+
+    var web = /*#__PURE__*/Object.freeze({
+        __proto__: null,
+        ElizaTasksWeb: ElizaTasksWeb
+    });
+
+    exports.ElizaTasks = ElizaTasks;
+
+    return exports;
+
+})({}, capacitorExports);
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sources":["esm/index.js","esm/web.js"],"sourcesContent":["import { registerPlugin } from \"@capacitor/core\";\nexport * from \"./definitions\";\nconst loadWeb = () => import(\"./web\").then((m) => new m.ElizaTasksWeb());\nexport const ElizaTasks = registerPlugin(\"ElizaTasks\", {\n    web: loadWeb,\n});\n","import { WebPlugin } from \"@capacitor/core\";\n/**\n * Web fallback for the ElizaTasks plugin.\n *\n * Browsers have no `BGTaskScheduler` equivalent. The plugin resolves to a\n * `supported: false` status so the runtime knows to fall back to the\n * BackgroundRunner repeat poll (already configured in `capacitor.config.ts`).\n */\nexport class ElizaTasksWeb extends WebPlugin {\n    scheduleNext(_options) {\n        return Promise.resolve({\n            scheduled: false,\n            identifier: \"ai.eliza.tasks.refresh\",\n            earliestBeginAtMs: null,\n            reason: \"BGTaskScheduler is iOS-only; web has no background wake path.\",\n        });\n    }\n    getStatus() {\n        return Promise.resolve({\n            supported: false,\n            platform: \"web\",\n            refreshScheduled: false,\n            processingScheduled: false,\n            lastWakeFiredAtMs: null,\n            lastWakeKind: null,\n            reason: \"BGTaskScheduler is iOS-only; web has no background wake path.\",\n        });\n    }\n    cancelAll() {\n        return Promise.resolve({ cancelled: false });\n    }\n}\n"],"names":["registerPlugin","WebPlugin"],"mappings":";;;IAEA,MAAM,OAAO,GAAG,MAAM,mDAAe,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,aAAa,EAAE,CAAC;AAC5D,UAAC,UAAU,GAAGA,mBAAc,CAAC,YAAY,EAAE;IACvD,IAAI,GAAG,EAAE,OAAO;IAChB,CAAC;;ICJD;IACA;IACA;IACA;IACA;IACA;IACA;IACO,MAAM,aAAa,SAASC,cAAS,CAAC;IAC7C,IAAI,YAAY,CAAC,QAAQ,EAAE;IAC3B,QAAQ,OAAO,OAAO,CAAC,OAAO,CAAC;IAC/B,YAAY,SAAS,EAAE,KAAK;IAC5B,YAAY,UAAU,EAAE,wBAAwB;IAChD,YAAY,iBAAiB,EAAE,IAAI;IACnC,YAAY,MAAM,EAAE,+DAA+D;IACnF,SAAS,CAAC;IACV,IAAI;IACJ,IAAI,SAAS,GAAG;IAChB,QAAQ,OAAO,OAAO,CAAC,OAAO,CAAC;IAC/B,YAAY,SAAS,EAAE,KAAK;IAC5B,YAAY,QAAQ,EAAE,KAAK;IAC3B,YAAY,gBAAgB,EAAE,KAAK;IACnC,YAAY,mBAAmB,EAAE,KAAK;IACtC,YAAY,iBAAiB,EAAE,IAAI;IACnC,YAAY,YAAY,EAAE,IAAI;IAC9B,YAAY,MAAM,EAAE,+DAA+D;IACnF,SAAS,CAAC;IACV,IAAI;IACJ,IAAI,SAAS,GAAG;IAChB,QAAQ,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACpD,IAAI;IACJ;;;;;;;;;;;;;;;"}

package/ios/Sources/ElizaTasksPlugin/ElizaTasksPlugin.swift

@@ -0,0 +1,326 @@
+import BackgroundTasks
+import Capacitor
+import Foundation
+import UIKit
+import UserNotifications
+
+/// ElizaTasksPlugin — Capacitor bridge for iOS `BGTaskScheduler`.
+///
+/// Registers two namespaced identifiers in `BGTaskScheduler.shared.register`:
+///
+///   - `ai.eliza.tasks.refresh`     → `BGAppRefreshTask` (≤ ~30s, network-OK)
+///   - `ai.eliza.tasks.processing`  → `BGProcessingTask` (long-running,
+///                                     requires charger, no network)
+///
+/// On wake, the plugin emits a `wake` event to the JS layer carrying
+/// `{kind, identifier, deadlineSec, firedAtMs, payload}`. The Wave 3D JS
+/// runner under `runners/eliza-tasks.js` consumes the same event shape from
+/// the `@capacitor/background-runner` repeat poll, so the JS-side handler is
+/// shared between the two wake paths.
+///
+/// Silent-push wake (`remote-notification` UIBackgroundMode) is plumbed
+/// through `AppDelegate.application:didReceiveRemoteNotification:` which
+/// posts an `ElizaCompanionRemotePush` `NSNotification`. This plugin
+/// observes that notification and forwards the payload as a third wake
+/// `kind: "remote-push"` event. APNs registration is still gated on the
+/// `ELIZA_APNS_ENABLED` Info.plist flag and defaults off.
+///
+/// JS-callable methods:
+///   - `scheduleNext({ earliestBeginSec, alsoProcessing })`
+///   - `getStatus()`
+///   - `cancelAll()`
+@objc(ElizaTasksPlugin)
+public class ElizaTasksPlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "ElizaTasksPlugin"
+    public let jsName = "ElizaTasks"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "scheduleNext", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "getStatus", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "cancelAll", returnType: CAPPluginReturnPromise),
+    ]
+
+    // The identifiers MUST match the values declared in Info.plist's
+    // `BGTaskSchedulerPermittedIdentifiers` array. If they drift, `register`
+    // returns false and the OS refuses to dispatch tasks.
+    private static let refreshIdentifier = "ai.eliza.tasks.refresh"
+    private static let processingIdentifier = "ai.eliza.tasks.processing"
+    private static let remotePushIdentifier = "ai.eliza.tasks.remote-push"
+
+    // Default earliestBegin if the JS caller does not supply one. Apple's
+    // documented practical minimum is 15 minutes; we honor that as the floor.
+    private static let defaultEarliestBeginSec: Double = 15 * 60
+
+    // Apple's WWDC guidance: BGAppRefreshTask gets ~30s, BGProcessingTask
+    // gets minutes. The JS runner consumes deadlineSec to size its own
+    // hard-deadline race.
+    private static let refreshDeadlineSec: Double = 25
+    private static let processingDeadlineSec: Double = 120
+
+    // Persistence keys — used by `getStatus` so the JS side can observe wake
+    // events that landed before the webview was ready to receive listeners.
+    private static let lastWakeFiredAtKey = "ai.eliza.tasks.lastWakeFiredAtMs"
+    private static let lastWakeKindKey = "ai.eliza.tasks.lastWakeKind"
+    private static let refreshScheduledKey = "ai.eliza.tasks.refreshScheduled"
+    private static let processingScheduledKey = "ai.eliza.tasks.processingScheduled"
+
+    private var remotePushObserver: NSObjectProtocol?
+
+    public override func load() {
+        registerBackgroundTasks()
+        observeRemotePush()
+    }
+
+    deinit {
+        if let observer = remotePushObserver {
+            NotificationCenter.default.removeObserver(observer)
+        }
+    }
+
+    // MARK: - JS-callable surface
+
+    @objc func scheduleNext(_ call: CAPPluginCall) {
+        let earliestBeginSec = call.getDouble("earliestBeginSec")
+            ?? Self.defaultEarliestBeginSec
+        let alsoProcessing = call.getBool("alsoProcessing") ?? false
+
+        // Floor at 1s — BGTaskScheduler returns an error for negative or
+        // zero values, and very small intervals are silently coerced anyway.
+        let normalizedBegin = max(1.0, earliestBeginSec)
+        let beginDate = Date(timeIntervalSinceNow: normalizedBegin)
+
+        let refreshResult = submitRefreshRequest(beginDate: beginDate)
+        if alsoProcessing {
+            _ = submitProcessingRequest(beginDate: beginDate)
+        }
+
+        call.resolve([
+            "scheduled": refreshResult.scheduled,
+            "identifier": Self.refreshIdentifier,
+            "earliestBeginAtMs": refreshResult.scheduled
+                ? Int64(beginDate.timeIntervalSince1970 * 1000)
+                : NSNull(),
+            "reason": refreshResult.reason as Any? ?? NSNull(),
+        ])
+    }
+
+    @objc func getStatus(_ call: CAPPluginCall) {
+        let defaults = UserDefaults.standard
+        let lastWakeMs = defaults.object(forKey: Self.lastWakeFiredAtKey) as? Int64
+        let lastKind = defaults.string(forKey: Self.lastWakeKindKey)
+
+        call.resolve([
+            "supported": true,
+            "platform": "ios",
+            "refreshScheduled": defaults.bool(forKey: Self.refreshScheduledKey),
+            "processingScheduled": defaults.bool(forKey: Self.processingScheduledKey),
+            "lastWakeFiredAtMs": lastWakeMs.map { $0 as Any } ?? NSNull(),
+            "lastWakeKind": lastKind as Any? ?? NSNull(),
+            "reason": NSNull(),
+        ])
+    }
+
+    @objc func cancelAll(_ call: CAPPluginCall) {
+        BGTaskScheduler.shared.cancelAllTaskRequests()
+        let defaults = UserDefaults.standard
+        defaults.set(false, forKey: Self.refreshScheduledKey)
+        defaults.set(false, forKey: Self.processingScheduledKey)
+        call.resolve(["cancelled": true])
+    }
+
+    // MARK: - BGTaskScheduler registration
+
+    /// Register the two BG task handlers. Must run before
+    /// `application:didFinishLaunchingWithOptions:` returns. CAPPlugin.load()
+    /// runs after `didFinishLaunching` but BGTaskScheduler tolerates this if
+    /// the identifier is in Info.plist's permitted list — the OS queues the
+    /// dispatch until a handler is registered. Confirmed on iOS 15+.
+    private func registerBackgroundTasks() {
+        let scheduler = BGTaskScheduler.shared
+
+        let refreshRegistered = scheduler.register(
+            forTaskWithIdentifier: Self.refreshIdentifier,
+            using: nil
+        ) { [weak self] task in
+            guard let self = self else {
+                task.setTaskCompleted(success: false)
+                return
+            }
+            self.handleRefreshTask(task)
+        }
+
+        let processingRegistered = scheduler.register(
+            forTaskWithIdentifier: Self.processingIdentifier,
+            using: nil
+        ) { [weak self] task in
+            guard let self = self else {
+                task.setTaskCompleted(success: false)
+                return
+            }
+            self.handleProcessingTask(task)
+        }
+
+        if !refreshRegistered {
+            NSLog(
+                "[ElizaTasksPlugin] BGTaskScheduler.register(%@) returned false — verify Info.plist BGTaskSchedulerPermittedIdentifiers",
+                Self.refreshIdentifier
+            )
+        }
+        if !processingRegistered {
+            NSLog(
+                "[ElizaTasksPlugin] BGTaskScheduler.register(%@) returned false — verify Info.plist BGTaskSchedulerPermittedIdentifiers",
+                Self.processingIdentifier
+            )
+        }
+    }
+
+    // MARK: - Task handlers
+
+    private func handleRefreshTask(_ task: BGTask) {
+        // Always set an expiration handler before doing async work, otherwise
+        // iOS escalates the task termination to a force-kill.
+        task.expirationHandler = { [weak task] in
+            task?.setTaskCompleted(success: false)
+        }
+
+        let firedAtMs = Int64(Date().timeIntervalSince1970 * 1000)
+        persistWake(kind: "refresh", firedAtMs: firedAtMs)
+
+        // BG refresh consumers are expected to re-enqueue the next wake before
+        // resolving — without this the chain dies after one fire.
+        let nextBegin = Date(timeIntervalSinceNow: Self.defaultEarliestBeginSec)
+        _ = submitRefreshRequest(beginDate: nextBegin)
+
+        emitWake(
+            kind: "refresh",
+            identifier: Self.refreshIdentifier,
+            deadlineSec: Self.refreshDeadlineSec,
+            firedAtMs: firedAtMs,
+            payload: [:]
+        )
+
+        // The JS handler runs in the webview, which may be backgrounded. We
+        // signal completion eagerly — the runner's HTTP poke is fire-and-forget
+        // from the OS's perspective; the agent's loopback `/api/internal/wake`
+        // route owns durability.
+        task.setTaskCompleted(success: true)
+    }
+
+    private func handleProcessingTask(_ task: BGTask) {
+        task.expirationHandler = { [weak task] in
+            task?.setTaskCompleted(success: false)
+        }
+
+        let firedAtMs = Int64(Date().timeIntervalSince1970 * 1000)
+        persistWake(kind: "processing", firedAtMs: firedAtMs)
+
+        emitWake(
+            kind: "processing",
+            identifier: Self.processingIdentifier,
+            deadlineSec: Self.processingDeadlineSec,
+            firedAtMs: firedAtMs,
+            payload: [:]
+        )
+
+        // Processing tasks are not auto-rescheduled — the JS layer requests
+        // the next processing wake explicitly when a warmup window is needed.
+        task.setTaskCompleted(success: true)
+    }
+
+    // MARK: - Submit helpers
+
+    private struct SubmitResult {
+        let scheduled: Bool
+        let reason: String?
+    }
+
+    private func submitRefreshRequest(beginDate: Date) -> SubmitResult {
+        let request = BGAppRefreshTaskRequest(identifier: Self.refreshIdentifier)
+        request.earliestBeginDate = beginDate
+        do {
+            try BGTaskScheduler.shared.submit(request)
+            UserDefaults.standard.set(true, forKey: Self.refreshScheduledKey)
+            return SubmitResult(scheduled: true, reason: nil)
+        } catch {
+            UserDefaults.standard.set(false, forKey: Self.refreshScheduledKey)
+            let message = "BGTaskScheduler.submit(refresh) failed: \(error.localizedDescription)"
+            NSLog("[ElizaTasksPlugin] %@", message)
+            return SubmitResult(scheduled: false, reason: message)
+        }
+    }
+
+    private func submitProcessingRequest(beginDate: Date) -> SubmitResult {
+        let request = BGProcessingTaskRequest(identifier: Self.processingIdentifier)
+        request.earliestBeginDate = beginDate
+        // Eliza's processing task is the local-LLM warmup pass. Real-world
+        // semantics: only run while plugged in, no network needed (the agent
+        // is reachable on loopback inside the app process).
+        request.requiresExternalPower = true
+        request.requiresNetworkConnectivity = false
+        do {
+            try BGTaskScheduler.shared.submit(request)
+            UserDefaults.standard.set(true, forKey: Self.processingScheduledKey)
+            return SubmitResult(scheduled: true, reason: nil)
+        } catch {
+            UserDefaults.standard.set(false, forKey: Self.processingScheduledKey)
+            let message = "BGTaskScheduler.submit(processing) failed: \(error.localizedDescription)"
+            NSLog("[ElizaTasksPlugin] %@", message)
+            return SubmitResult(scheduled: false, reason: message)
+        }
+    }
+
+    // MARK: - Remote push plumbing
+
+    /// AppDelegate's `application:didReceiveRemoteNotification:` posts an
+    /// `ElizaCompanionRemotePush` notification with the userInfo dictionary
+    /// in `object`. We surface that to JS as a third wake kind so the same
+    /// `wake` event handler can drain it. Gated on the operator flipping
+    /// `ELIZA_APNS_ENABLED=1` in Info.plist — silent until then.
+    private func observeRemotePush() {
+        remotePushObserver = NotificationCenter.default.addObserver(
+            forName: Notification.Name("ElizaCompanionRemotePush"),
+            object: nil,
+            queue: .main
+        ) { [weak self] notification in
+            guard let self = self else { return }
+            let userInfo = (notification.object as? [AnyHashable: Any]) ?? [:]
+            var payload: [String: Any] = [:]
+            for (key, value) in userInfo {
+                guard let stringKey = key as? String, stringKey != "aps" else { continue }
+                payload[stringKey] = value
+            }
+            let firedAtMs = Int64(Date().timeIntervalSince1970 * 1000)
+            self.persistWake(kind: "remote-push", firedAtMs: firedAtMs)
+            self.emitWake(
+                kind: "remote-push",
+                identifier: Self.remotePushIdentifier,
+                deadlineSec: Self.refreshDeadlineSec,
+                firedAtMs: firedAtMs,
+                payload: payload
+            )
+        }
+    }
+
+    // MARK: - Event emission
+
+    private func emitWake(
+        kind: String,
+        identifier: String,
+        deadlineSec: Double,
+        firedAtMs: Int64,
+        payload: [String: Any]
+    ) {
+        notifyListeners("wake", data: [
+            "kind": kind,
+            "identifier": identifier,
+            "deadlineSec": deadlineSec,
+            "firedAtMs": firedAtMs,
+            "payload": payload,
+        ])
+    }
+
+    private func persistWake(kind: String, firedAtMs: Int64) {
+        let defaults = UserDefaults.standard
+        defaults.set(firedAtMs, forKey: Self.lastWakeFiredAtKey)
+        defaults.set(kind, forKey: Self.lastWakeKindKey)
+    }
+}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@elizaos/capacitor-eliza-tasks",
+  "version": "2.0.3-beta.2",
+  "description": "Bridges iOS BGTaskScheduler (BGAppRefreshTask + BGProcessingTask) wake events into the Eliza Capacitor runtime.",
+  "keywords": [
+    "background",
+    "bgtaskscheduler",
+    "ios",
+    "wake",
+    "eliza"
+  ],
+  "main": "./dist/plugin.cjs.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "bun": "./src/index.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/plugin.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "unpkg": "dist/plugin.js",
+  "files": [
+    "android/src/main/",
+    "android/build.gradle",
+    "dist/",
+    "ios/Sources/",
+    "*.podspec",
+    "dist"
+  ],
+  "author": "elizaOS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elizaOS/eliza"
+  },
+  "scripts": {
+    "build": "node ../../packages/scripts/with-package-build-lock.mjs plugins/plugin-native-eliza-tasks -- bun run build:unlocked",
+    "clean": "node ../../packages/scripts/rm-path-recursive.mjs dist",
+    "prepublishOnly": "bun run build",
+    "test": "vitest run --passWithNoTests",
+    "watch": "tsc --watch",
+    "build:unlocked": "bun run clean && bunx tsc -p tsconfig.json && bunx rollup -c rollup.config.mjs"
+  },
+  "devDependencies": {
+    "@capacitor/core": "^8.3.1",
+    "@rollup/plugin-node-resolve": "^16.0.0",
+    "rollup": "^4.60.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.17"
+  },
+  "peerDependencies": {
+    "@capacitor/core": "^8.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "capacitor": {
+    "ios": {
+      "src": "ios",
+      "podName": "ElizaosCapacitorElizaTasks"
+    },
+    "android": {
+      "src": "android"
+    }
+  },
+  "elizaos": {
+    "platforms": [
+      "browser",
+      "node"
+    ],
+    "runtime": "both",
+    "platformDetails": {
+      "browser": "Unsupported web fallback; BGTaskScheduler is iOS-only.",
+      "node": "No desktop equivalent; runtime ignores this plugin off-mobile.",
+      "ios": true,
+      "android": false
+    }
+  },
+  "gitHead": "82fe0f44215954c2417328203f5bd6510985c1fc"
+}