@openclaw/facetime 0.0.0 → 2026.9.7

package/src/plugin-paths.ts

@@ -0,0 +1,201 @@
+import { constants } from "node:fs";
+import { access, readFile, readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import type { PluginRuntime } from "openclaw/plugin-sdk/plugin-runtime";
+
+const NATIVE_PROTOCOL = "NATIVE_PROTOCOL_VERSION=1";
+const NATIVE_DIRS = [
+  "/opt/homebrew/opt/openclaw-facetime/libexec",
+  "/usr/local/opt/openclaw-facetime/libexec",
+] as const;
+const INSTALL_COMMAND = "brew install openclaw/tap/openclaw-facetime";
+
+function resolveHelperDylib(): string {
+  return resolve(
+    homedir(),
+    "Library",
+    "Containers",
+    "com.apple.FaceTime",
+    "Data",
+    "tmp",
+    "FaceTimeHelper.dylib",
+  );
+}
+
+function resolveHelperIpcKey(): string {
+  return resolve(
+    homedir(),
+    "Library",
+    "Application Support",
+    "OpenClaw",
+    "FaceTime",
+    "helper-ipc-key",
+  );
+}
+
+function resolveHelperBuildStamp(): string {
+  return resolve(
+    homedir(),
+    "Library",
+    "Application Support",
+    "OpenClaw",
+    "FaceTime",
+    "helper-build.sha256",
+  );
+}
+
+async function resolveNativeInstall(params: {
+  access?: typeof access;
+  readFile?: typeof readFile;
+}): Promise<{ buildId: string; capture: string; directory: string; helper: string }> {
+  const checkAccess = params.access ?? access;
+  const loadFile = params.readFile ?? readFile;
+  for (const directory of NATIVE_DIRS) {
+    const capture = resolve(directory, "facetime-audio-capture");
+    const helper = resolve(directory, "FaceTimeHelper.dylib");
+    const buildIdFile = resolve(directory, "FaceTimeHelper.build-id");
+    const protocolFile = resolve(directory, "native-protocol.env");
+    try {
+      await Promise.all([
+        checkAccess(capture, constants.X_OK),
+        checkAccess(helper, constants.R_OK),
+        checkAccess(buildIdFile, constants.R_OK),
+        checkAccess(protocolFile, constants.R_OK),
+      ]);
+      const [buildId, protocol] = await Promise.all([
+        loadFile(buildIdFile, "utf8").then((value) => value.trim()),
+        loadFile(protocolFile, "utf8").then((value) => value.trim()),
+      ]);
+      if (!/^[\da-f]{64}$/u.test(buildId) || protocol !== NATIVE_PROTOCOL) {
+        continue;
+      }
+      return { buildId, capture, directory, helper };
+    } catch {
+      // Try the other supported Homebrew prefix.
+    }
+  }
+  throw new Error(`Compatible FaceTime native helpers are not installed. Run: ${INSTALL_COMMAND}`);
+}
+
+export async function inspectFaceTimeNativePackage(
+  params: {
+    access?: typeof access;
+    readFile?: typeof readFile;
+  } = {},
+): Promise<boolean> {
+  return await resolveNativeInstall(params).then(
+    () => true,
+    () => false,
+  );
+}
+
+export async function inspectFaceTimeArtifacts(params: {
+  access?: typeof access;
+  readFile?: typeof readFile;
+}): Promise<{
+  nativeInstall: boolean;
+  stagedHelper: boolean;
+  helperKey: boolean;
+  helperBuildStamp: boolean;
+  stagedHelperDylibs: number;
+  cachedDriver: boolean;
+}> {
+  const checkAccess = params.access ?? access;
+  const readable = async (file: string, mode: number) => {
+    try {
+      await checkAccess(file, mode);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  const helperTempDirs = ["com.apple.FaceTime", "com.apple.mobilephone"].map((bundle) =>
+    resolve(homedir(), "Library", "Containers", bundle, "Data", "tmp"),
+  );
+  const countHelpers = async (directory: string) => {
+    try {
+      return (await readdir(directory)).filter(
+        (name) => name.startsWith("FaceTimeHelper") && name.endsWith(".dylib"),
+      ).length;
+    } catch {
+      return 0;
+    }
+  };
+  const [
+    nativeInstall,
+    stagedHelper,
+    helperKey,
+    helperBuildStamp,
+    stagedHelperDylibs,
+    cachedDriver,
+  ] = await Promise.all([
+    inspectFaceTimeNativePackage(params),
+    readable(resolveHelperDylib(), constants.R_OK),
+    readable(resolveHelperIpcKey(), constants.R_OK),
+    readable(resolveHelperBuildStamp(), constants.R_OK),
+    Promise.all(helperTempDirs.map(countHelpers)).then((counts) =>
+      counts.reduce((total, count) => total + count, 0),
+    ),
+    readable(
+      resolve(
+        homedir(),
+        "Library",
+        "Caches",
+        "OpenClaw",
+        "FaceTime",
+        "driver",
+        "OpenClawBridge.driver",
+      ),
+      constants.R_OK,
+    ),
+  ]);
+  return {
+    nativeInstall,
+    stagedHelper,
+    helperKey,
+    helperBuildStamp,
+    stagedHelperDylibs,
+    cachedDriver,
+  };
+}
+
+export async function ensureCaptureBinary(
+  params: {
+    access?: typeof access;
+    readFile?: typeof readFile;
+  } = {},
+): Promise<string> {
+  return (await resolveNativeInstall(params)).capture;
+}
+
+export async function ensureHelperArtifacts(params: {
+  pluginRoot: string;
+  runCommandWithTimeout: PluginRuntime["system"]["runCommandWithTimeout"];
+  access?: typeof access;
+  readFile?: typeof readFile;
+}): Promise<{ buildId: string; dylib: string; ipcKey: string }> {
+  const installation = await resolveNativeInstall(params);
+  const stageScript = resolve(params.pluginRoot, "scripts", "stage-helper.sh");
+  const result = await params.runCommandWithTimeout(["/bin/bash", stageScript, "--if-needed"], {
+    timeoutMs: 120_000,
+  });
+  if (result.code !== 0) {
+    throw new Error(
+      `FaceTime native helper staging failed: ${result.stderr || result.stdout || `exit ${result.code}`}`,
+    );
+  }
+  const checkAccess = params.access ?? access;
+  const loadFile = params.readFile ?? readFile;
+  const dylib = resolveHelperDylib();
+  await checkAccess(dylib, constants.R_OK);
+  const ipcKey = (await loadFile(resolveHelperIpcKey(), "utf8")).trim();
+  const stagedBuildId = (await loadFile(resolveHelperBuildStamp(), "utf8")).trim();
+  if (!/^[\da-f]{64}$/u.test(ipcKey)) {
+    throw new Error("FaceTime helper produced an invalid IPC authentication key");
+  }
+  if (stagedBuildId !== installation.buildId) {
+    throw new Error("Staged FaceTime helper does not match the installed native package");
+  }
+  return { buildId: installation.buildId, dylib, ipcKey };
+}

package/src/preflight.ts

@@ -0,0 +1,295 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import type { PluginRuntime, RuntimeLogger } from "openclaw/plugin-sdk/plugin-runtime";
+import { asRecord, normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
+import { FACETIME_FEED_DEVICE_NAME, FACETIME_MIC_DEVICE_NAME } from "./audio-pump.js";
+import type { FaceTimeConfig } from "./config.js";
+import { agentIdFromSessionKey, resolveFaceTimeRealtimeProvider } from "./talk-driver-config.js";
+
+type RunCommandWithTimeout = PluginRuntime["system"]["runCommandWithTimeout"];
+
+type AudioDeviceDescription = {
+  isAggregate: boolean;
+  name: string;
+  uid: string;
+};
+
+type DefaultAudioDevices = {
+  input: AudioDeviceDescription;
+  output: AudioDeviceDescription;
+};
+
+type CoreAudioDeviceProfile = {
+  name: string;
+  virtual: boolean;
+};
+
+function parseDefaultAudioDevices(raw: string): DefaultAudioDevices {
+  const parsed: unknown = JSON.parse(raw);
+  const record = asRecord(parsed);
+  const input = asRecord(record.input);
+  const output = asRecord(record.output);
+  if (
+    typeof input.isAggregate !== "boolean" ||
+    typeof input.name !== "string" ||
+    typeof input.uid !== "string" ||
+    typeof output.isAggregate !== "boolean" ||
+    typeof output.name !== "string" ||
+    typeof output.uid !== "string"
+  ) {
+    throw new Error("invalid audio-device shape");
+  }
+  return {
+    input: { isAggregate: input.isAggregate, name: input.name, uid: input.uid },
+    output: { isAggregate: output.isAggregate, name: output.name, uid: output.uid },
+  };
+}
+
+export type FaceTimePreflightCheck = {
+  id: string;
+  label: string;
+  ok: boolean;
+  required: boolean;
+  message?: string;
+};
+
+export type FaceTimePreflightResult = {
+  ok: boolean;
+  helperConnected: boolean;
+  currentAudioDefaults?: DefaultAudioDevices;
+  currentAudioError?: string;
+  checks: FaceTimePreflightCheck[];
+};
+
+function firstLine(value: unknown) {
+  return typeof value === "string" ? value.trim().split(/\r?\n/u)[0] || undefined : undefined;
+}
+
+function pushCheck(
+  checks: FaceTimePreflightCheck[],
+  check: Omit<FaceTimePreflightCheck, "required"> & { required?: boolean },
+) {
+  checks.push({ required: true, ...check });
+}
+
+function parseCoreAudioDevices(systemProfilerOutput: string): CoreAudioDeviceProfile[] {
+  try {
+    const parsed = asRecord(JSON.parse(systemProfilerOutput));
+    const entries = Array.isArray(parsed.SPAudioDataType) ? parsed.SPAudioDataType : [];
+    const deviceEntries = entries.flatMap((entry): unknown[] => {
+      const record = asRecord(entry);
+      const items = record["_items"];
+      return Array.isArray(items) ? items : [record];
+    });
+    const devices = deviceEntries.flatMap((entry): CoreAudioDeviceProfile[] => {
+      const record = asRecord(entry);
+      const name = record["_name"];
+      return typeof name === "string"
+        ? [
+            {
+              name,
+              virtual: record.coreaudio_device_transport === "coreaudio_device_type_virtual",
+            },
+          ]
+        : [];
+    });
+    if (devices.length > 0) {
+      return devices;
+    }
+  } catch {
+    // Older test fixtures and unusual system_profiler failures can still
+    // provide the human-readable device list without transport metadata.
+  }
+  const devices: CoreAudioDeviceProfile[] = [];
+  for (const line of systemProfilerOutput.split(/\r?\n/u)) {
+    const match = line.match(/^\s{8}(.+):\s*$/u);
+    if (match?.[1]) {
+      devices.push({ name: match[1].trim(), virtual: false });
+    }
+  }
+  return [...new Map(devices.map((device) => [device.name, device])).values()];
+}
+
+function findPhysicalOutputProblem(
+  defaults: DefaultAudioDevices,
+  devices: readonly CoreAudioDeviceProfile[],
+): string | undefined {
+  if (defaults.output.isAggregate) {
+    return `system output is aggregate device ${defaults.output.name}`;
+  }
+  if (
+    devices.some((device) => device.name === defaults.output.name && device.virtual) ||
+    /BlackHole|OpenClaw-(?:Feed|Mic)/iu.test(defaults.output.name)
+  ) {
+    return `system output is virtual device ${defaults.output.name}`;
+  }
+  return undefined;
+}
+
+async function checkCallApp(params: {
+  runCommandWithTimeout: RunCommandWithTimeout;
+  checks: FaceTimePreflightCheck[];
+}) {
+  for (const app of ["FaceTime", "Phone"]) {
+    const result = await params.runCommandWithTimeout(["/usr/bin/pgrep", "-x", app], {
+      timeoutMs: 5_000,
+    });
+    if (result.code === 0) {
+      pushCheck(params.checks, {
+        id: "call-app-running",
+        label: "FaceTime or Phone process",
+        ok: true,
+        message: app,
+      });
+      return;
+    }
+  }
+  pushCheck(params.checks, {
+    id: "call-app-running",
+    label: "FaceTime or Phone process",
+    ok: false,
+    message: "open FaceTime for video calls or Phone for FaceTime audio calls",
+  });
+}
+
+export async function runFaceTimePreflight(params: {
+  config: FaceTimeConfig;
+  fullConfig: OpenClawConfig;
+  runtime: PluginRuntime;
+  logger?: RuntimeLogger;
+  helperConnected: boolean;
+  captureBinary: string;
+}): Promise<FaceTimePreflightResult> {
+  const runCommandWithTimeout = params.runtime.system.runCommandWithTimeout;
+  const checks: FaceTimePreflightCheck[] = [];
+  pushCheck(checks, {
+    id: "helper-connected",
+    label: "FaceTime helper socket",
+    ok: params.helperConnected,
+    message: params.helperConnected
+      ? "helper connected"
+      : "no authenticated helper connected on the local UID-derived endpoint",
+  });
+
+  const executable = await runCommandWithTimeout(["/bin/test", "-x", params.captureBinary], {
+    timeoutMs: 5_000,
+  });
+  pushCheck(checks, {
+    id: "capture-binary",
+    label: "FaceTime process-tap capture helper",
+    ok: executable.code === 0,
+    message:
+      executable.code === 0
+        ? params.captureBinary
+        : "capture helper is missing; reinstall with brew install openclaw/tap/openclaw-facetime",
+  });
+
+  await checkCallApp({ runCommandWithTimeout, checks });
+
+  const profiler = await runCommandWithTimeout(
+    ["/usr/sbin/system_profiler", "SPAudioDataType", "-json"],
+    { timeoutMs: 10_000 },
+  );
+  const audioDevices = profiler.code === 0 ? parseCoreAudioDevices(profiler.stdout ?? "") : [];
+  const deviceNames = new Set(audioDevices.map((device) => device.name));
+  for (const [id, label, deviceName] of [
+    ["paired-driver-mic", "OpenClaw microphone device", FACETIME_MIC_DEVICE_NAME],
+    ["paired-driver-feed", "OpenClaw feed device", FACETIME_FEED_DEVICE_NAME],
+  ] as const) {
+    const found = deviceNames.has(deviceName);
+    pushCheck(checks, {
+      id,
+      label,
+      ok: found,
+      message: found
+        ? deviceName
+        : `missing ${deviceName}; run openclaw gateway call facetime.installDriver --json`,
+    });
+  }
+
+  let currentAudioDefaults: DefaultAudioDevices | undefined;
+  let currentAudioError: string | undefined;
+  if (executable.code === 0) {
+    const defaults = await runCommandWithTimeout([params.captureBinary, "--default-devices"], {
+      timeoutMs: 5_000,
+    });
+    if (defaults.code === 0) {
+      try {
+        currentAudioDefaults = parseDefaultAudioDevices(defaults.stdout ?? "");
+        const problem = findPhysicalOutputProblem(currentAudioDefaults, audioDevices);
+        pushCheck(checks, {
+          id: "physical-output",
+          label: "Physical call output",
+          ok: !problem,
+          message: problem ?? currentAudioDefaults.output.name,
+        });
+      } catch (error) {
+        currentAudioError = `invalid audio-device JSON: ${formatErrorMessage(error)}`;
+      }
+    } else {
+      currentAudioError = firstLine(defaults.stderr) ?? firstLine(defaults.stdout);
+    }
+    if (currentAudioError) {
+      pushCheck(checks, {
+        id: "physical-output",
+        label: "Physical call output",
+        ok: false,
+        message: currentAudioError,
+      });
+    }
+
+    const capture = await runCommandWithTimeout([params.captureBinary, "--check"], {
+      timeoutMs: 8_000,
+    });
+    pushCheck(checks, {
+      id: "process-tap",
+      label: "FaceTime app-audio process tap",
+      ok: capture.code === 0,
+      message:
+        firstLine(capture.stderr) ??
+        firstLine(capture.stdout) ??
+        "grant Screen & System Audio Recording permission",
+    });
+  } else {
+    pushCheck(checks, {
+      id: "physical-output",
+      label: "Physical call output",
+      ok: false,
+      message: "capture helper unavailable",
+    });
+    pushCheck(checks, {
+      id: "process-tap",
+      label: "FaceTime app-audio process tap",
+      ok: false,
+      message: "capture helper unavailable",
+    });
+  }
+
+  let providerReady = false;
+  let providerMessage: string;
+  try {
+    const resolved = await resolveFaceTimeRealtimeProvider({
+      config: params.config,
+      fullConfig: params.fullConfig,
+      agentId: agentIdFromSessionKey(params.config.realtime.sessionKey, params.fullConfig),
+    });
+    providerReady = true;
+    providerMessage = `${resolved.provider.id}:${normalizeOptionalString(resolved.providerConfig.model) ?? "provider default"}`;
+  } catch (error) {
+    providerMessage = formatErrorMessage(error);
+  }
+  pushCheck(checks, {
+    id: "realtime-provider",
+    label: "Realtime provider readiness",
+    ok: providerReady,
+    message: providerMessage,
+  });
+
+  return {
+    ok: checks.every((check) => check.ok || !check.required),
+    helperConnected: params.helperConnected,
+    currentAudioDefaults,
+    currentAudioError,
+    checks,
+  };
+}