@elizaos/plugin-phone 2.0.3-beta.2 → 2.0.3-beta.3

package/dist/companion/services/env.js

@@ -0,0 +1,20 @@
+function readEnv() {
+  const meta = import.meta;
+  return meta.env ?? {};
+}
+function agentUrl() {
+  const raw = readEnv().VITE_ELIZA_AGENT_URL?.trim();
+  return raw && raw.length > 0 ? raw : null;
+}
+function apnsEnabled() {
+  return readEnv().VITE_ELIZA_APNS_ENABLED === "1";
+}
+function isDev() {
+  return readEnv().MODE !== "production";
+}
+export {
+  agentUrl,
+  apnsEnabled,
+  isDev
+};
+//# sourceMappingURL=env.js.map

package/dist/companion/services/env.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/companion/services/env.ts"],"sourcesContent":["/**\n * Runtime environment for the phone-companion views.\n *\n * Values come from Vite's `import.meta.env`. Missing or empty configuration is\n * represented explicitly: `agentUrl()` returns `null` and `apnsEnabled()`\n * returns `false` rather than throwing, so callers can branch without try/catch.\n */\n\ninterface ViteEnv {\n  VITE_ELIZA_AGENT_URL?: string;\n  VITE_ELIZA_APNS_ENABLED?: string;\n  VITE_ELIZA_LOG_LEVEL?: string;\n  MODE?: string;\n}\n\nfunction readEnv(): ViteEnv {\n  const meta = import.meta as { env?: ViteEnv };\n  return meta.env ?? {};\n}\n\nexport function agentUrl(): string | null {\n  const raw = readEnv().VITE_ELIZA_AGENT_URL?.trim();\n  return raw && raw.length > 0 ? raw : null;\n}\n\nexport function apnsEnabled(): boolean {\n  return readEnv().VITE_ELIZA_APNS_ENABLED === \"1\";\n}\n\nexport function isDev(): boolean {\n  return readEnv().MODE !== \"production\";\n}\n"],"mappings":"AAeA,SAAS,UAAmB;AAC1B,QAAM,OAAO;AACb,SAAO,KAAK,OAAO,CAAC;AACtB;AAEO,SAAS,WAA0B;AACxC,QAAM,MAAM,QAAQ,EAAE,sBAAsB,KAAK;AACjD,SAAO,OAAO,IAAI,SAAS,IAAI,MAAM;AACvC;AAEO,SAAS,cAAuB;AACrC,SAAO,QAAQ,EAAE,4BAA4B;AAC/C;AAEO,SAAS,QAAiB;AAC/B,SAAO,QAAQ,EAAE,SAAS;AAC5B;","names":[]}

package/dist/companion/services/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Phone-companion surface — the iOS-paired-handset experience.
+ *
+ * Originally shipped as a standalone top-level app Capacitor project;
+ * folded into the main Eliza iOS bundle so one binary handles both the full
+ * Eliza UI and the pairing / chat-mirror / remote-session flow.
+ */
+export { ElizaIntent, type ElizaIntentPlugin, ElizaIntentWeb, type PairingStatus, type ReceiveIntentPayload, type ReceiveIntentResult, type ScheduleAlarmOptions, type ScheduleAlarmResult, type SetPairingStatusOptions, } from "./eliza-intent";
+export { agentUrl, apnsEnabled, isDev } from "./env";
+export { logger } from "./logger";
+export { type NavState, useNavigation, type ViewName } from "./navigation";
+export { type PushIntent, type RegisterPushHandle, type RegisterPushOptions, registerPush, type SessionStartIntent, } from "./push";
+export { decodePairingPayload, type InputButton, type InputEvent, type PairingPayload, SessionClient, type SessionState, type TouchGesture, type TouchSample, type TouchToInputOptions, touchToInput, } from "./session-client";
+//# sourceMappingURL=index.d.ts.map

package/dist/companion/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/companion/services/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,WAAW,EACX,KAAK,iBAAiB,EACtB,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,GAC7B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AACrD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,KAAK,QAAQ,EAAE,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EACL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,YAAY,EACZ,KAAK,kBAAkB,GACxB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,oBAAoB,EACpB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,YAAY,GACb,MAAM,kBAAkB,CAAC"}

package/dist/companion/services/index.js

@@ -0,0 +1,29 @@
+import {
+  ElizaIntent,
+  ElizaIntentWeb
+} from "./eliza-intent.js";
+import { agentUrl, apnsEnabled, isDev } from "./env.js";
+import { logger } from "./logger.js";
+import { useNavigation } from "./navigation.js";
+import {
+  registerPush
+} from "./push.js";
+import {
+  decodePairingPayload,
+  SessionClient,
+  touchToInput
+} from "./session-client.js";
+export {
+  ElizaIntent,
+  ElizaIntentWeb,
+  SessionClient,
+  agentUrl,
+  apnsEnabled,
+  decodePairingPayload,
+  isDev,
+  logger,
+  registerPush,
+  touchToInput,
+  useNavigation
+};
+//# sourceMappingURL=index.js.map

package/dist/companion/services/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/companion/services/index.ts"],"sourcesContent":["/**\n * Phone-companion surface — the iOS-paired-handset experience.\n *\n * Originally shipped as a standalone top-level app Capacitor project;\n * folded into the main Eliza iOS bundle so one binary handles both the full\n * Eliza UI and the pairing / chat-mirror / remote-session flow.\n */\n\nexport {\n  ElizaIntent,\n  type ElizaIntentPlugin,\n  ElizaIntentWeb,\n  type PairingStatus,\n  type ReceiveIntentPayload,\n  type ReceiveIntentResult,\n  type ScheduleAlarmOptions,\n  type ScheduleAlarmResult,\n  type SetPairingStatusOptions,\n} from \"./eliza-intent.js\";\nexport { agentUrl, apnsEnabled, isDev } from \"./env.js\";\nexport { logger } from \"./logger.js\";\nexport { type NavState, useNavigation, type ViewName } from \"./navigation.js\";\nexport {\n  type PushIntent,\n  type RegisterPushHandle,\n  type RegisterPushOptions,\n  registerPush,\n  type SessionStartIntent,\n} from \"./push.js\";\nexport {\n  decodePairingPayload,\n  type InputButton,\n  type InputEvent,\n  type PairingPayload,\n  SessionClient,\n  type SessionState,\n  type TouchGesture,\n  type TouchSample,\n  type TouchToInputOptions,\n  touchToInput,\n} from \"./session-client.js\";\n"],"mappings":"AAQA;AAAA,EACE;AAAA,EAEA;AAAA,OAOK;AACP,SAAS,UAAU,aAAa,aAAa;AAC7C,SAAS,cAAc;AACvB,SAAwB,qBAAoC;AAC5D;AAAA,EAIE;AAAA,OAEK;AACP;AAAA,EACE;AAAA,EAIA;AAAA,EAKA;AAAA,OACK;","names":[]}

package/dist/companion/services/intent-bridge.d.ts

@@ -0,0 +1,11 @@
+import { type ReceiveIntentPayload, type ReceiveIntentResult } from "./eliza-intent";
+/**
+ * Intent bridge — single entry point used by UI layers to forward an
+ * agent-issued device-bus intent (see plan §6.24) to the native plugin.
+ *
+ * This is a thin wrapper, not an abstraction layer. It exists so that
+ * when push payloads land (T9c) there is one place to attach decoding +
+ * authentication rather than scattering `ElizaIntent.receiveIntent` calls.
+ */
+export declare function forwardIntent(payload: ReceiveIntentPayload): Promise<ReceiveIntentResult>;
+//# sourceMappingURL=intent-bridge.d.ts.map

package/dist/companion/services/intent-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent-bridge.d.ts","sourceRoot":"","sources":["../../../src/companion/services/intent-bridge.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,gBAAgB,CAAC;AAGxB;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAM9B"}

package/dist/companion/services/intent-bridge.js

@@ -0,0 +1,15 @@
+import {
+  ElizaIntent
+} from "./eliza-intent.js";
+import { logger } from "./logger.js";
+async function forwardIntent(payload) {
+  logger.debug("[IntentBridge] forward", {
+    kind: payload.kind,
+    issuedAtIso: payload.issuedAtIso
+  });
+  return ElizaIntent.receiveIntent(payload);
+}
+export {
+  forwardIntent
+};
+//# sourceMappingURL=intent-bridge.js.map

package/dist/companion/services/intent-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/companion/services/intent-bridge.ts"],"sourcesContent":["import {\n  ElizaIntent,\n  type ReceiveIntentPayload,\n  type ReceiveIntentResult,\n} from \"./eliza-intent.js\";\nimport { logger } from \"./logger.js\";\n\n/**\n * Intent bridge — single entry point used by UI layers to forward an\n * agent-issued device-bus intent (see plan §6.24) to the native plugin.\n *\n * This is a thin wrapper, not an abstraction layer. It exists so that\n * when push payloads land (T9c) there is one place to attach decoding +\n * authentication rather than scattering `ElizaIntent.receiveIntent` calls.\n */\nexport async function forwardIntent(\n  payload: ReceiveIntentPayload,\n): Promise<ReceiveIntentResult> {\n  logger.debug(\"[IntentBridge] forward\", {\n    kind: payload.kind,\n    issuedAtIso: payload.issuedAtIso,\n  });\n  return ElizaIntent.receiveIntent(payload);\n}\n"],"mappings":"AAAA;AAAA,EACE;AAAA,OAGK;AACP,SAAS,cAAc;AAUvB,eAAsB,cACpB,SAC8B;AAC9B,SAAO,MAAM,0BAA0B;AAAA,IACrC,MAAM,QAAQ;AAAA,IACd,aAAa,QAAQ;AAAA,EACvB,CAAC;AACD,SAAO,YAAY,cAAc,OAAO;AAC1C;","names":[]}

package/dist/companion/services/logger.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Structured client logger for the phone-companion views.
+ *
+ * Client-side code cannot reach the server logger — this wrapper provides
+ * levelled, prefixed output routed through the browser console host.
+ * Prefix each call site with `[ClassName]` per repo convention.
+ */
+export declare const logger: {
+    debug(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/companion/services/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/companion/services/logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgDH,eAAO,MAAM,MAAM;mBACF,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;kBAGjD,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;kBAGhD,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;mBAG/C,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAGhE,CAAC"}

package/dist/companion/services/logger.js

@@ -0,0 +1,50 @@
+const LEVEL_ORDER = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40
+};
+function envLevel() {
+  const raw = typeof import.meta !== "undefined" ? import.meta.env?.VITE_ELIZA_LOG_LEVEL : void 0;
+  if (raw === "debug" || raw === "info" || raw === "warn" || raw === "error") {
+    return raw;
+  }
+  return "info";
+}
+const currentLevel = envLevel();
+function emit(level, message, context) {
+  if (LEVEL_ORDER[level] < LEVEL_ORDER[currentLevel]) return;
+  const line = `[ElizaCompanion] ${message}`;
+  const host = globalThis.console;
+  if (level === "error") {
+    host.error(line, context ?? {});
+    return;
+  }
+  if (level === "warn") {
+    host.warn(line, context ?? {});
+    return;
+  }
+  if (level === "info") {
+    host.info(line, context ?? {});
+    return;
+  }
+  host.debug(line, context ?? {});
+}
+const logger = {
+  debug(message, context) {
+    emit("debug", message, context);
+  },
+  info(message, context) {
+    emit("info", message, context);
+  },
+  warn(message, context) {
+    emit("warn", message, context);
+  },
+  error(message, context) {
+    emit("error", message, context);
+  }
+};
+export {
+  logger
+};
+//# sourceMappingURL=logger.js.map

package/dist/companion/services/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/companion/services/logger.ts"],"sourcesContent":["/**\n * Structured client logger for the phone-companion views.\n *\n * Client-side code cannot reach the server logger — this wrapper provides\n * levelled, prefixed output routed through the browser console host.\n * Prefix each call site with `[ClassName]` per repo convention.\n */\n\ntype LogLevel = \"debug\" | \"info\" | \"warn\" | \"error\";\n\nconst LEVEL_ORDER: Record<LogLevel, number> = {\n  debug: 10,\n  info: 20,\n  warn: 30,\n  error: 40,\n};\n\nfunction envLevel(): LogLevel {\n  const raw =\n    typeof import.meta !== \"undefined\"\n      ? (import.meta as { env?: Record<string, string> }).env\n          ?.VITE_ELIZA_LOG_LEVEL\n      : undefined;\n  if (raw === \"debug\" || raw === \"info\" || raw === \"warn\" || raw === \"error\") {\n    return raw;\n  }\n  return \"info\";\n}\n\nconst currentLevel = envLevel();\n\nfunction emit(\n  level: LogLevel,\n  message: string,\n  context?: Record<string, unknown>,\n): void {\n  if (LEVEL_ORDER[level] < LEVEL_ORDER[currentLevel]) return;\n  const line = `[ElizaCompanion] ${message}`;\n  const host = globalThis.console;\n  if (level === \"error\") {\n    host.error(line, context ?? {});\n    return;\n  }\n  if (level === \"warn\") {\n    host.warn(line, context ?? {});\n    return;\n  }\n  if (level === \"info\") {\n    host.info(line, context ?? {});\n    return;\n  }\n  host.debug(line, context ?? {});\n}\n\nexport const logger = {\n  debug(message: string, context?: Record<string, unknown>): void {\n    emit(\"debug\", message, context);\n  },\n  info(message: string, context?: Record<string, unknown>): void {\n    emit(\"info\", message, context);\n  },\n  warn(message: string, context?: Record<string, unknown>): void {\n    emit(\"warn\", message, context);\n  },\n  error(message: string, context?: Record<string, unknown>): void {\n    emit(\"error\", message, context);\n  },\n};\n"],"mappings":"AAUA,MAAM,cAAwC;AAAA,EAC5C,OAAO;AAAA,EACP,MAAM;AAAA,EACN,MAAM;AAAA,EACN,OAAO;AACT;AAEA,SAAS,WAAqB;AAC5B,QAAM,MACJ,OAAO,gBAAgB,cAClB,YAAiD,KAC9C,uBACJ;AACN,MAAI,QAAQ,WAAW,QAAQ,UAAU,QAAQ,UAAU,QAAQ,SAAS;AAC1E,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAEA,MAAM,eAAe,SAAS;AAE9B,SAAS,KACP,OACA,SACA,SACM;AACN,MAAI,YAAY,KAAK,IAAI,YAAY,YAAY,EAAG;AACpD,QAAM,OAAO,oBAAoB,OAAO;AACxC,QAAM,OAAO,WAAW;AACxB,MAAI,UAAU,SAAS;AACrB,SAAK,MAAM,MAAM,WAAW,CAAC,CAAC;AAC9B;AAAA,EACF;AACA,MAAI,UAAU,QAAQ;AACpB,SAAK,KAAK,MAAM,WAAW,CAAC,CAAC;AAC7B;AAAA,EACF;AACA,MAAI,UAAU,QAAQ;AACpB,SAAK,KAAK,MAAM,WAAW,CAAC,CAAC;AAC7B;AAAA,EACF;AACA,OAAK,MAAM,MAAM,WAAW,CAAC,CAAC;AAChC;AAEO,MAAM,SAAS;AAAA,EACpB,MAAM,SAAiB,SAAyC;AAC9D,SAAK,SAAS,SAAS,OAAO;AAAA,EAChC;AAAA,EACA,KAAK,SAAiB,SAAyC;AAC7D,SAAK,QAAQ,SAAS,OAAO;AAAA,EAC/B;AAAA,EACA,KAAK,SAAiB,SAAyC;AAC7D,SAAK,QAAQ,SAAS,OAAO;AAAA,EAC/B;AAAA,EACA,MAAM,SAAiB,SAAyC;AAC9D,SAAK,SAAS,SAAS,OAAO;AAAA,EAChC;AACF;","names":[]}

package/dist/companion/services/navigation.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Minimal stack navigator for the phone-companion surface.
+ *
+ * We intentionally avoid react-router / react-native-navigation: the companion
+ * has three screens and a linear push/pop model. This hook handles state,
+ * persists the current view across launches, and fires a Capacitor haptic on
+ * each transition when native haptics are available.
+ */
+export type ViewName = "chat" | "pairing" | "remote-session";
+export interface NavState {
+    view: ViewName;
+    ready: boolean;
+    push(next: ViewName): void;
+    pop(fallback: ViewName): void;
+}
+export declare function useNavigation(): NavState;
+//# sourceMappingURL=navigation.d.ts.map

package/dist/companion/services/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../../src/companion/services/navigation.ts"],"names":[],"mappings":"AAMA;;;;;;;GAOG;AAEH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,gBAAgB,CAAC;AAK7D,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC3B,GAAG,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC/B;AAED,wBAAgB,aAAa,IAAI,QAAQ,CAmExC"}

package/dist/companion/services/navigation.js

@@ -0,0 +1,104 @@
+import { Capacitor } from "@capacitor/core";
+import { Haptics, ImpactStyle } from "@capacitor/haptics";
+import { Preferences } from "@capacitor/preferences";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { logger } from "./logger.js";
+const STORAGE_KEY = "eliza.companion.nav.v1";
+const DEFAULT_VIEW = "chat";
+function useNavigation() {
+  const [view, setView] = useState(DEFAULT_VIEW);
+  const [stack, setStack] = useState([DEFAULT_VIEW]);
+  const [ready, setReady] = useState(false);
+  const stackRef = useRef(stack);
+  stackRef.current = stack;
+  useEffect(() => {
+    void (async () => {
+      try {
+        const result = await Preferences.get({ key: STORAGE_KEY });
+        if (result.value !== null) {
+          const parsed = parseStack(result.value);
+          if (parsed.length > 0) {
+            setStack(parsed);
+            setView(parsed[parsed.length - 1]);
+          }
+        }
+      } catch (err) {
+        logger.warn(
+          "[navigation] failed to restore navigation from preferences",
+          {
+            error: err instanceof Error ? err.message : String(err)
+          }
+        );
+        setStack([DEFAULT_VIEW]);
+        setView(DEFAULT_VIEW);
+      } finally {
+        setReady(true);
+      }
+    })();
+  }, []);
+  useEffect(() => {
+    if (!ready) return;
+    const serialized = JSON.stringify(stack);
+    Preferences.set({ key: STORAGE_KEY, value: serialized });
+  }, [stack, ready]);
+  const push = useCallback((next) => {
+    logger.info("[navigation] push", { next });
+    triggerHaptic();
+    setStack(
+      (current) => current[current.length - 1] === next ? current : [...current, next]
+    );
+    setView(next);
+  }, []);
+  const pop = useCallback((fallback) => {
+    logger.info("[navigation] pop", { fallback });
+    triggerHaptic();
+    const current = stackRef.current;
+    let nextStack;
+    let nextView;
+    if (current.length <= 1) {
+      nextStack = [fallback];
+      nextView = fallback;
+    } else {
+      nextStack = current.slice(0, -1);
+      nextView = nextStack[nextStack.length - 1];
+    }
+    stackRef.current = nextStack;
+    setStack(nextStack);
+    setView(nextView);
+  }, []);
+  return useMemo(() => ({ view, ready, push, pop }), [view, ready, push, pop]);
+}
+let hasLoggedInvalidStoredStack = false;
+function parseStack(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(isViewName);
+  } catch (err) {
+    if (!hasLoggedInvalidStoredStack) {
+      hasLoggedInvalidStoredStack = true;
+      logger.info(
+        "[navigation] invalid persisted stack; falling back to default view",
+        {
+          error: err instanceof Error ? err.message : String(err)
+        }
+      );
+    }
+    return [];
+  }
+}
+function isViewName(value) {
+  return value === "chat" || value === "pairing" || value === "remote-session";
+}
+function triggerHaptic() {
+  if (!Capacitor.isNativePlatform()) return;
+  Haptics.impact({ style: ImpactStyle.Light }).catch((err) => {
+    logger.debug("[navigation] haptic unavailable", {
+      error: err instanceof Error ? err.message : String(err)
+    });
+  });
+}
+export {
+  useNavigation
+};
+//# sourceMappingURL=navigation.js.map

package/dist/companion/services/navigation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/companion/services/navigation.ts"],"sourcesContent":["import { Capacitor } from \"@capacitor/core\";\nimport { Haptics, ImpactStyle } from \"@capacitor/haptics\";\nimport { Preferences } from \"@capacitor/preferences\";\nimport { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport { logger } from \"./logger.js\";\n\n/**\n * Minimal stack navigator for the phone-companion surface.\n *\n * We intentionally avoid react-router / react-native-navigation: the companion\n * has three screens and a linear push/pop model. This hook handles state,\n * persists the current view across launches, and fires a Capacitor haptic on\n * each transition when native haptics are available.\n */\n\nexport type ViewName = \"chat\" | \"pairing\" | \"remote-session\";\n\nconst STORAGE_KEY = \"eliza.companion.nav.v1\";\nconst DEFAULT_VIEW: ViewName = \"chat\";\n\nexport interface NavState {\n  view: ViewName;\n  ready: boolean;\n  push(next: ViewName): void;\n  pop(fallback: ViewName): void;\n}\n\nexport function useNavigation(): NavState {\n  const [view, setView] = useState<ViewName>(DEFAULT_VIEW);\n  const [stack, setStack] = useState<ViewName[]>([DEFAULT_VIEW]);\n  const [ready, setReady] = useState(false);\n  const stackRef = useRef(stack);\n  stackRef.current = stack;\n\n  useEffect(() => {\n    void (async () => {\n      try {\n        const result = await Preferences.get({ key: STORAGE_KEY });\n        if (result.value !== null) {\n          const parsed = parseStack(result.value);\n          if (parsed.length > 0) {\n            setStack(parsed);\n            setView(parsed[parsed.length - 1]);\n          }\n        }\n      } catch (err) {\n        logger.warn(\n          \"[navigation] failed to restore navigation from preferences\",\n          {\n            error: err instanceof Error ? err.message : String(err),\n          },\n        );\n        setStack([DEFAULT_VIEW]);\n        setView(DEFAULT_VIEW);\n      } finally {\n        setReady(true);\n      }\n    })();\n  }, []);\n\n  useEffect(() => {\n    if (!ready) return;\n    const serialized = JSON.stringify(stack);\n    Preferences.set({ key: STORAGE_KEY, value: serialized });\n  }, [stack, ready]);\n\n  const push = useCallback((next: ViewName) => {\n    logger.info(\"[navigation] push\", { next });\n    triggerHaptic();\n    setStack((current) =>\n      current[current.length - 1] === next ? current : [...current, next],\n    );\n    setView(next);\n  }, []);\n\n  const pop = useCallback((fallback: ViewName) => {\n    logger.info(\"[navigation] pop\", { fallback });\n    triggerHaptic();\n    const current = stackRef.current;\n    let nextStack: ViewName[];\n    let nextView: ViewName;\n    if (current.length <= 1) {\n      nextStack = [fallback];\n      nextView = fallback;\n    } else {\n      nextStack = current.slice(0, -1);\n      nextView = nextStack[nextStack.length - 1];\n    }\n    stackRef.current = nextStack;\n    setStack(nextStack);\n    setView(nextView);\n  }, []);\n\n  return useMemo(() => ({ view, ready, push, pop }), [view, ready, push, pop]);\n}\n\nlet hasLoggedInvalidStoredStack = false;\n\nfunction parseStack(raw: string): ViewName[] {\n  try {\n    const parsed: unknown = JSON.parse(raw);\n    if (!Array.isArray(parsed)) return [];\n    return parsed.filter(isViewName);\n  } catch (err: unknown) {\n    if (!hasLoggedInvalidStoredStack) {\n      hasLoggedInvalidStoredStack = true;\n      logger.info(\n        \"[navigation] invalid persisted stack; falling back to default view\",\n        {\n          error: err instanceof Error ? err.message : String(err),\n        },\n      );\n    }\n    return [];\n  }\n}\n\nfunction isViewName(value: unknown): value is ViewName {\n  return value === \"chat\" || value === \"pairing\" || value === \"remote-session\";\n}\n\nfunction triggerHaptic(): void {\n  if (!Capacitor.isNativePlatform()) return;\n  Haptics.impact({ style: ImpactStyle.Light }).catch((err: unknown) => {\n    logger.debug(\"[navigation] haptic unavailable\", {\n      error: err instanceof Error ? err.message : String(err),\n    });\n  });\n}\n"],"mappings":"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","names":[]}

package/dist/companion/services/push.d.ts

@@ -0,0 +1,27 @@
+import { type PairingPayload } from "./session-client";
+/**
+ * APNs integration.
+ *
+ * On iOS native: requests notification permission, registers for APNs, and
+ * listens for `pushNotificationReceived`. When a `intent.session.start` push
+ * arrives, we decode its pairing payload and notify the caller so the app
+ * can navigate to the RemoteSession view.
+ *
+ * On web: unavailable — logged once. This lets `bun run build` + `bun run dev`
+ * work in a browser without a simulator.
+ */
+export interface SessionStartIntent {
+    kind: "session-start";
+    payload: PairingPayload;
+}
+export type PushIntent = SessionStartIntent;
+export interface RegisterPushOptions {
+    onIntent(intent: PushIntent): void;
+    onToken?(deviceToken: string): void;
+    onError?(error: Error): void;
+}
+export interface RegisterPushHandle {
+    unregister(): Promise<void>;
+}
+export declare function registerPush(options: RegisterPushOptions): Promise<RegisterPushHandle>;
+//# sourceMappingURL=push.d.ts.map

package/dist/companion/services/push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push.d.ts","sourceRoot":"","sources":["../../../src/companion/services/push.ts"],"names":[],"mappings":"AAOA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAE7E;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,MAAM,UAAU,GAAG,kBAAkB,CAAC;AAE5C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IACnC,OAAO,CAAC,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAKD,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CA8D7B"}

package/dist/companion/services/push.js

@@ -0,0 +1,101 @@
+import { Capacitor } from "@capacitor/core";
+import {
+  PushNotifications
+} from "@capacitor/push-notifications";
+import { logger } from "./logger.js";
+import { decodePairingPayload } from "./session-client.js";
+const INTENT_KEY = "intent";
+const SESSION_START_INTENT = "session.start";
+async function registerPush(options) {
+  if (!Capacitor.isNativePlatform()) {
+    logger.info("[push] skipping registration; non-native platform", {
+      platform: Capacitor.getPlatform()
+    });
+    return { unregister: async () => {
+    } };
+  }
+  const permission = await PushNotifications.requestPermissions();
+  if (permission.receive !== "granted") {
+    const error = new Error(
+      `[push] APNs permission not granted: ${permission.receive}`
+    );
+    logger.warn(error.message, { permission: permission.receive });
+    options.onError?.(error);
+    return { unregister: async () => {
+    } };
+  }
+  const tokenHandle = await PushNotifications.addListener(
+    "registration",
+    (token) => {
+      logger.info("[push] APNs token received", {
+        tokenLength: token.value.length
+      });
+      options.onToken?.(token.value);
+    }
+  );
+  const errorHandle = await PushNotifications.addListener(
+    "registrationError",
+    (err) => {
+      const error = new Error(`[push] APNs registration failed: ${err.error}`);
+      logger.error(error.message, {});
+      options.onError?.(error);
+    }
+  );
+  const receiveHandle = await PushNotifications.addListener(
+    "pushNotificationReceived",
+    (notification) => {
+      handleNotification(notification, options);
+    }
+  );
+  const actionHandle = await PushNotifications.addListener(
+    "pushNotificationActionPerformed",
+    (action) => {
+      handleNotification(action.notification, options);
+    }
+  );
+  await PushNotifications.register();
+  logger.info("[push] registered for APNs", {});
+  return {
+    unregister: async () => {
+      await tokenHandle.remove();
+      await errorHandle.remove();
+      await receiveHandle.remove();
+      await actionHandle.remove();
+    }
+  };
+}
+function handleNotification(notification, options) {
+  const data = notification.data ?? {};
+  const intent = data[INTENT_KEY];
+  if (intent !== SESSION_START_INTENT) {
+    logger.debug("[push] non-session intent ignored", { intent });
+    return;
+  }
+  const encoded = data.pairing;
+  if (typeof encoded !== "string") {
+    const error = new Error(
+      "[push] session.start missing `pairing` payload field"
+    );
+    logger.error(error.message, {});
+    options.onError?.(error);
+    return;
+  }
+  try {
+    const payload = decodePairingPayload(encoded);
+    logger.info("[push] session.start intent received", {
+      agentId: payload.agentId
+    });
+    options.onIntent({ kind: "session-start", payload });
+  } catch (cause) {
+    const error = cause instanceof Error ? cause : new Error("[push] failed to decode session.start pairing payload");
+    logger.error("[push] failed to decode session.start pairing payload", {
+      error: error.message,
+      encodedLength: encoded.length
+    });
+    options.onError?.(error);
+  }
+}
+export {
+  registerPush
+};
+//# sourceMappingURL=push.js.map

package/dist/companion/services/push.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/companion/services/push.ts"],"sourcesContent":["import { Capacitor } from \"@capacitor/core\";\nimport {\n  type PushNotificationSchema,\n  PushNotifications,\n  type Token,\n} from \"@capacitor/push-notifications\";\nimport { logger } from \"./logger.js\";\nimport { decodePairingPayload, type PairingPayload } from \"./session-client.js\";\n\n/**\n * APNs integration.\n *\n * On iOS native: requests notification permission, registers for APNs, and\n * listens for `pushNotificationReceived`. When a `intent.session.start` push\n * arrives, we decode its pairing payload and notify the caller so the app\n * can navigate to the RemoteSession view.\n *\n * On web: unavailable — logged once. This lets `bun run build` + `bun run dev`\n * work in a browser without a simulator.\n */\n\nexport interface SessionStartIntent {\n  kind: \"session-start\";\n  payload: PairingPayload;\n}\n\nexport type PushIntent = SessionStartIntent;\n\nexport interface RegisterPushOptions {\n  onIntent(intent: PushIntent): void;\n  onToken?(deviceToken: string): void;\n  onError?(error: Error): void;\n}\n\nexport interface RegisterPushHandle {\n  unregister(): Promise<void>;\n}\n\nconst INTENT_KEY = \"intent\";\nconst SESSION_START_INTENT = \"session.start\";\n\nexport async function registerPush(\n  options: RegisterPushOptions,\n): Promise<RegisterPushHandle> {\n  if (!Capacitor.isNativePlatform()) {\n    logger.info(\"[push] skipping registration; non-native platform\", {\n      platform: Capacitor.getPlatform(),\n    });\n    return { unregister: async () => {} };\n  }\n\n  const permission = await PushNotifications.requestPermissions();\n  if (permission.receive !== \"granted\") {\n    const error = new Error(\n      `[push] APNs permission not granted: ${permission.receive}`,\n    );\n    logger.warn(error.message, { permission: permission.receive });\n    options.onError?.(error);\n    return { unregister: async () => {} };\n  }\n\n  const tokenHandle = await PushNotifications.addListener(\n    \"registration\",\n    (token: Token) => {\n      logger.info(\"[push] APNs token received\", {\n        tokenLength: token.value.length,\n      });\n      options.onToken?.(token.value);\n    },\n  );\n\n  const errorHandle = await PushNotifications.addListener(\n    \"registrationError\",\n    (err: { error: string }) => {\n      const error = new Error(`[push] APNs registration failed: ${err.error}`);\n      logger.error(error.message, {});\n      options.onError?.(error);\n    },\n  );\n\n  const receiveHandle = await PushNotifications.addListener(\n    \"pushNotificationReceived\",\n    (notification: PushNotificationSchema) => {\n      handleNotification(notification, options);\n    },\n  );\n\n  const actionHandle = await PushNotifications.addListener(\n    \"pushNotificationActionPerformed\",\n    (action: { notification: PushNotificationSchema }) => {\n      handleNotification(action.notification, options);\n    },\n  );\n\n  await PushNotifications.register();\n  logger.info(\"[push] registered for APNs\", {});\n\n  return {\n    unregister: async () => {\n      await tokenHandle.remove();\n      await errorHandle.remove();\n      await receiveHandle.remove();\n      await actionHandle.remove();\n    },\n  };\n}\n\nfunction handleNotification(\n  notification: PushNotificationSchema,\n  options: RegisterPushOptions,\n): void {\n  const data = notification.data ?? {};\n  const intent = data[INTENT_KEY];\n  if (intent !== SESSION_START_INTENT) {\n    logger.debug(\"[push] non-session intent ignored\", { intent });\n    return;\n  }\n  const encoded = data.pairing;\n  if (typeof encoded !== \"string\") {\n    const error = new Error(\n      \"[push] session.start missing `pairing` payload field\",\n    );\n    logger.error(error.message, {});\n    options.onError?.(error);\n    return;\n  }\n  try {\n    const payload = decodePairingPayload(encoded);\n    logger.info(\"[push] session.start intent received\", {\n      agentId: payload.agentId,\n    });\n    options.onIntent({ kind: \"session-start\", payload });\n  } catch (cause) {\n    const error =\n      cause instanceof Error\n        ? cause\n        : new Error(\"[push] failed to decode session.start pairing payload\");\n    logger.error(\"[push] failed to decode session.start pairing payload\", {\n      error: error.message,\n      encodedLength: encoded.length,\n    });\n    options.onError?.(error);\n  }\n}\n"],"mappings":"AAAA,SAAS,iBAAiB;AAC1B;AAAA,EAEE;AAAA,OAEK;AACP,SAAS,cAAc;AACvB,SAAS,4BAAiD;AA+B1D,MAAM,aAAa;AACnB,MAAM,uBAAuB;AAE7B,eAAsB,aACpB,SAC6B;AAC7B,MAAI,CAAC,UAAU,iBAAiB,GAAG;AACjC,WAAO,KAAK,qDAAqD;AAAA,MAC/D,UAAU,UAAU,YAAY;AAAA,IAClC,CAAC;AACD,WAAO,EAAE,YAAY,YAAY;AAAA,IAAC,EAAE;AAAA,EACtC;AAEA,QAAM,aAAa,MAAM,kBAAkB,mBAAmB;AAC9D,MAAI,WAAW,YAAY,WAAW;AACpC,UAAM,QAAQ,IAAI;AAAA,MAChB,uCAAuC,WAAW,OAAO;AAAA,IAC3D;AACA,WAAO,KAAK,MAAM,SAAS,EAAE,YAAY,WAAW,QAAQ,CAAC;AAC7D,YAAQ,UAAU,KAAK;AACvB,WAAO,EAAE,YAAY,YAAY;AAAA,IAAC,EAAE;AAAA,EACtC;AAEA,QAAM,cAAc,MAAM,kBAAkB;AAAA,IAC1C;AAAA,IACA,CAAC,UAAiB;AAChB,aAAO,KAAK,8BAA8B;AAAA,QACxC,aAAa,MAAM,MAAM;AAAA,MAC3B,CAAC;AACD,cAAQ,UAAU,MAAM,KAAK;AAAA,IAC/B;AAAA,EACF;AAEA,QAAM,cAAc,MAAM,kBAAkB;AAAA,IAC1C;AAAA,IACA,CAAC,QAA2B;AAC1B,YAAM,QAAQ,IAAI,MAAM,oCAAoC,IAAI,KAAK,EAAE;AACvE,aAAO,MAAM,MAAM,SAAS,CAAC,CAAC;AAC9B,cAAQ,UAAU,KAAK;AAAA,IACzB;AAAA,EACF;AAEA,QAAM,gBAAgB,MAAM,kBAAkB;AAAA,IAC5C;AAAA,IACA,CAAC,iBAAyC;AACxC,yBAAmB,cAAc,OAAO;AAAA,IAC1C;AAAA,EACF;AAEA,QAAM,eAAe,MAAM,kBAAkB;AAAA,IAC3C;AAAA,IACA,CAAC,WAAqD;AACpD,yBAAmB,OAAO,cAAc,OAAO;AAAA,IACjD;AAAA,EACF;AAEA,QAAM,kBAAkB,SAAS;AACjC,SAAO,KAAK,8BAA8B,CAAC,CAAC;AAE5C,SAAO;AAAA,IACL,YAAY,YAAY;AACtB,YAAM,YAAY,OAAO;AACzB,YAAM,YAAY,OAAO;AACzB,YAAM,cAAc,OAAO;AAC3B,YAAM,aAAa,OAAO;AAAA,IAC5B;AAAA,EACF;AACF;AAEA,SAAS,mBACP,cACA,SACM;AACN,QAAM,OAAO,aAAa,QAAQ,CAAC;AACnC,QAAM,SAAS,KAAK,UAAU;AAC9B,MAAI,WAAW,sBAAsB;AACnC,WAAO,MAAM,qCAAqC,EAAE,OAAO,CAAC;AAC5D;AAAA,EACF;AACA,QAAM,UAAU,KAAK;AACrB,MAAI,OAAO,YAAY,UAAU;AAC/B,UAAM,QAAQ,IAAI;AAAA,MAChB;AAAA,IACF;AACA,WAAO,MAAM,MAAM,SAAS,CAAC,CAAC;AAC9B,YAAQ,UAAU,KAAK;AACvB;AAAA,EACF;AACA,MAAI;AACF,UAAM,UAAU,qBAAqB,OAAO;AAC5C,WAAO,KAAK,wCAAwC;AAAA,MAClD,SAAS,QAAQ;AAAA,IACnB,CAAC;AACD,YAAQ,SAAS,EAAE,MAAM,iBAAiB,QAAQ,CAAC;AAAA,EACrD,SAAS,OAAO;AACd,UAAM,QACJ,iBAAiB,QACb,QACA,IAAI,MAAM,uDAAuD;AACvE,WAAO,MAAM,yDAAyD;AAAA,MACpE,OAAO,MAAM;AAAA,MACb,eAAe,QAAQ;AAAA,IACzB,CAAC;AACD,YAAQ,UAAU,KAAK;AAAA,EACzB;AACF;","names":[]}

package/dist/companion/services/session-client.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Remote session WebSocket client + touch-to-input translator.
+ *
+ * The companion opens a single WebSocket to the session ingress
+ * (`wss://<ingress>/input`) and relays serialized input events. The host-side
+ * session bridge (T9a data plane) forwards those events into the noVNC /
+ * input-channel pipeline on the paired Mac.
+ *
+ * This module is pure — no React, no Capacitor. Makes it directly unit-testable
+ * under jsdom/node.
+ */
+export type InputButton = "left" | "right" | "middle";
+export type InputEvent = {
+    type: "mouse-move";
+    x: number;
+    y: number;
+} | {
+    type: "mouse-down";
+    x: number;
+    y: number;
+    button: InputButton;
+} | {
+    type: "mouse-up";
+    x: number;
+    y: number;
+    button: InputButton;
+} | {
+    type: "mouse-click";
+    x: number;
+    y: number;
+    button: InputButton;
+} | {
+    type: "mouse-drag";
+    fromX: number;
+    fromY: number;
+    toX: number;
+    toY: number;
+};
+export type SessionState = "idle" | "connecting" | "open" | "closed";
+export interface TouchSample {
+    /** Pointer X in VNC-viewport pixel coordinates. */
+    x: number;
+    /** Pointer Y in VNC-viewport pixel coordinates. */
+    y: number;
+    /** Milliseconds since epoch (or any monotonic reference). */
+    t: number;
+    /** Distinct finger ID. 0 = primary touch, 1 = second finger, etc. */
+    pointerId: number;
+}
+export interface TouchGesture {
+    /**
+     * Per-pointer samples, in time order. `samples[0]` is always the primary
+     * pointer (`pointerId: 0`). Multi-finger taps have one sample per pointer.
+     */
+    pointers: readonly (readonly TouchSample[])[];
+    /** true if the gesture ended with all fingers lifted. */
+    ended: boolean;
+}
+export interface TouchToInputOptions {
+    /**
+     * Maximum movement in CSS pixels for a sample sequence to still count as a
+     * tap (vs a pan). Default 6px matches iOS Human Interface Guidelines for
+     * tap slop.
+     */
+    tapSlopPx?: number;
+    /**
+     * Duration in ms above which a single-finger hold becomes a long-press
+     * (right click). Default 500ms.
+     */
+    longPressMs?: number;
+}
+interface SessionEventMap {
+    state: SessionState;
+    error: Error;
+    message: unknown;
+}
+type Listener<T> = (value: T) => void;
+export declare class SessionClient {
+    private readonly webSocketFactory;
+    private socket;
+    private state;
+    private readonly listeners;
+    constructor(webSocketFactory?: (url: string) => WebSocket);
+    getState(): SessionState;
+    connect(ingressUrl: string, sessionToken: string): void;
+    sendInput(event: InputEvent): void;
+    close(): void;
+    on<K extends keyof SessionEventMap>(event: K, handler: Listener<SessionEventMap[K]>): () => void;
+    private setState;
+}
+/**
+ * Translate a completed touch gesture into a sequence of input events for
+ * the remote host. Pure function.
+ *
+ * Rules (matches T9c spec):
+ *   - single-finger tap (<= tapSlop, < longPress)          → left click
+ *   - single-finger long-press (>= longPressMs, <= slop)   → right click
+ *   - two-finger tap (2 simultaneous pointers, no drag)    → middle click
+ *   - single-finger pan (> tapSlop)                        → mouse drag
+ */
+export declare function touchToInput(gesture: TouchGesture, options?: TouchToInputOptions): InputEvent[];
+/**
+ * Parse a pairing QR code payload. The QR contains base64(JSON).
+ * Throws on malformed input — the caller (UI) shows a user-facing error.
+ */
+export interface PairingPayload {
+    agentId: string;
+    pairingCode: string;
+    ingressUrl: string;
+    sessionToken: string;
+}
+export declare function decodePairingPayload(raw: string): PairingPayload;
+export {};
+//# sourceMappingURL=session-client.d.ts.map

package/dist/companion/services/session-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-client.d.ts","sourceRoot":"","sources":["../../../src/companion/services/session-client.ts"],"names":[],"mappings":"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"}