@openclaw/facetime 0.0.0 → 2026.9.7

package/docs/phase1-verification.md

@@ -0,0 +1,37 @@
+# FaceTime verification contract
+
+## Automated proof
+
+```bash
+node scripts/run-vitest.mjs extensions/facetime
+for script in extensions/facetime/scripts/*.sh; do sh -n "$script"; done
+sh extensions/facetime/scripts/test-driver-transaction.sh
+sh extensions/facetime/scripts/test-uninstall-inventory.sh
+(cd extensions/facetime && npm pack --dry-run)
+```
+
+The automated boundary proves state/generation fencing, exact pending-dial
+persistence, helper authentication and bounds, typed native outcomes,
+closure-bound consult cancellation, provider response ownership, native
+protocol compatibility, driver rollback, and uninstall inventory. Package
+inspection must show no native source, generated driver, dylib, `.build`, or
+BlackHole artifact.
+
+The package test resolves the source runtime using only files selected by npm.
+The publication workflow separately builds and selects the compiled plugin
+runtime; source-package proof does not replace that release check. Provider
+boundary tests use the real realtime adapter with synthetic credentials and
+WebSocket traffic, while intercepting native audio before process execution.
+
+The playback-drain signal estimates when PCM handed to the separate SoX process
+should have reached `OpenClaw-Feed`. It does not prove Core Audio consumption or
+remote audibility.
+
+## Live proof gap
+
+A consensual inbound and outbound round trip is still required separately for
+FaceTime video and Phone-owned FaceTime Audio. Live proof must confirm remote
+input/output, barge-in, agent consultation, direct hangup, physical-speaker
+suppression, and child-process teardown. Automated validation must not place
+calls, change SIP, enable developer tools, install the driver, restart the
+operator Gateway, or modify operator configuration.

package/doctor-contract-api.ts

@@ -0,0 +1,95 @@
+// FaceTime doctor contract repairs retired prototype config before strict validation.
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
+import { asObjectRecord } from "openclaw/plugin-sdk/runtime-doctor-migrations";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/string-coerce-runtime";
+
+const CONFIG_PATH = ["plugins", "entries", "facetime", "config"] as const;
+const RETIRED_CONFIG_KEYS = ["helperHost", "helperPort"] as const;
+
+type LegacyConfigRule = {
+  path: string[];
+  message: string;
+};
+
+export const legacyConfigRules: LegacyConfigRule[] = [
+  {
+    path: [...CONFIG_PATH, "whitelistHandles"],
+    message:
+      'plugins.entries.facetime.config.whitelistHandles is legacy; use ownerHandles. Run "openclaw doctor --fix".',
+  },
+  ...RETIRED_CONFIG_KEYS.map((key) => ({
+    path: [...CONFIG_PATH, key],
+    message: `${[...CONFIG_PATH, key].join(".")} is retired; FaceTime now uses its local authenticated helper endpoint. Run "openclaw doctor --fix".`,
+  })),
+  {
+    path: [...CONFIG_PATH, "realtime", "brain"],
+    message:
+      'plugins.entries.facetime.config.realtime.brain is retired; FaceTime always consults the configured agent. Run "openclaw doctor --fix".',
+  },
+];
+
+function normalizeLegacyOwnerHandles(value: unknown): string[] | null {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+  return value
+    .map((entry) => normalizeOptionalString(entry))
+    .filter((entry): entry is string => Boolean(entry));
+}
+
+/** Moves or removes retired prototype keys so runtime sees only the canonical config shape. */
+export function normalizeCompatibilityConfig({ cfg }: { cfg: OpenClawConfig }): {
+  config: OpenClawConfig;
+  changes: string[];
+} {
+  const entry = asObjectRecord(cfg.plugins?.entries?.facetime);
+  const pluginConfig = asObjectRecord(entry?.config);
+  if (!pluginConfig) {
+    return { config: cfg, changes: [] };
+  }
+  const hasLegacyOwnerHandles = Object.hasOwn(pluginConfig, "whitelistHandles");
+  const retiredKeys = RETIRED_CONFIG_KEYS.filter((key) => Object.hasOwn(pluginConfig, key));
+  const realtime = asObjectRecord(pluginConfig.realtime);
+  const hasRetiredBrain = Boolean(realtime && Object.hasOwn(realtime, "brain"));
+  if (!hasLegacyOwnerHandles && retiredKeys.length === 0 && !hasRetiredBrain) {
+    return { config: cfg, changes: [] };
+  }
+
+  const nextConfig = structuredClone(cfg);
+  const nextEntry = asObjectRecord(nextConfig.plugins?.entries?.facetime);
+  const nextPluginConfig = asObjectRecord(nextEntry?.config);
+  if (!nextPluginConfig) {
+    return { config: cfg, changes: [] };
+  }
+  const changes: string[] = [];
+
+  if (hasLegacyOwnerHandles) {
+    const sourcePath = [...CONFIG_PATH, "whitelistHandles"].join(".");
+    const targetPath = [...CONFIG_PATH, "ownerHandles"].join(".");
+    if (Object.hasOwn(nextPluginConfig, "ownerHandles")) {
+      changes.push(`Removed ${sourcePath}; ${targetPath} is authoritative.`);
+    } else {
+      const handles = normalizeLegacyOwnerHandles(nextPluginConfig.whitelistHandles);
+      if (handles) {
+        nextPluginConfig.ownerHandles = handles;
+        changes.push(`Moved ${sourcePath} to ${targetPath}.`);
+      } else {
+        changes.push(`Removed invalid ${sourcePath}; configure ${targetPath}.`);
+      }
+    }
+    delete nextPluginConfig.whitelistHandles;
+  }
+
+  for (const key of retiredKeys) {
+    delete nextPluginConfig[key];
+    changes.push(`Removed retired ${[...CONFIG_PATH, key].join(".")}.`);
+  }
+
+  const nextRealtime = asObjectRecord(nextPluginConfig.realtime);
+  if (hasRetiredBrain && nextRealtime) {
+    delete nextRealtime.brain;
+    changes.push(`Removed retired ${[...CONFIG_PATH, "realtime", "brain"].join(".")}.`);
+  }
+
+  return { config: nextConfig, changes };
+}

package/helper-endpoint.json

@@ -0,0 +1,5 @@
+{
+  "host": "127.0.0.1",
+  "basePort": 45670,
+  "maxPort": 65535
+}

package/index.ts

@@ -0,0 +1,222 @@
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import {
+  ErrorCodes,
+  errorShape,
+  type GatewayRequestHandlerOptions,
+} from "openclaw/plugin-sdk/gateway-runtime";
+import {
+  definePluginEntry,
+  type OpenClawPluginApi,
+  type OpenClawPluginDefinition,
+} from "openclaw/plugin-sdk/plugin-entry";
+import {
+  resolveFaceTimeConfig,
+  validateFaceTimeConfig,
+  type FaceTimeConfig,
+} from "./src/config.js";
+import { inspectFaceTimeDriver, uninstallFaceTimeDriver } from "./src/driver-setup.js";
+import { inspectFaceTimeNativePackage } from "./src/plugin-paths.js";
+import { stopRetainedRuntime } from "./src/runtime-lifecycle.js";
+import { runFaceTimeSetup } from "./src/setup.js";
+import { inspectFaceTimeStaticStatus } from "./src/static-status.js";
+import { createFaceTimeCallTool, resolveFaceTimeToolApproval } from "./src/tool.js";
+
+const faceTimeConfigSchema = {
+  parse(value: unknown): FaceTimeConfig {
+    return resolveFaceTimeConfig(value);
+  },
+};
+
+const faceTimePlugin: OpenClawPluginDefinition = definePluginEntry({
+  id: "facetime",
+  name: "FaceTime",
+  description: "Experimental private FaceTime realtime voice carrier for OpenClaw agents",
+  configSchema: faceTimeConfigSchema,
+  register(api: OpenClawPluginApi) {
+    const config = resolveFaceTimeConfig(api.pluginConfig);
+    const validation = validateFaceTimeConfig(config);
+    const pluginRoot = api.rootDir ?? api.resolvePath(".");
+    let runtimePromise: Promise<import("./runtime-api.js").FaceTimeRuntime> | undefined;
+    let uninstalling = false;
+
+    const ensureRuntime = async () => {
+      if (uninstalling) {
+        throw new Error("facetime native uninstall is in progress");
+      }
+      if (!config.enabled) {
+        throw new Error("facetime disabled in plugin config");
+      }
+      if (!validation.valid) {
+        throw new Error(validation.errors.join("; "));
+      }
+      runtimePromise ??= import("./runtime-api.js")
+        .then(({ createFaceTimeRuntime }) =>
+          createFaceTimeRuntime({
+            config,
+            fullConfig: api.config,
+            runtime: api.runtime,
+            logger: api.logger,
+            pluginRoot,
+          }),
+        )
+        .catch((error: unknown) => {
+          runtimePromise = undefined;
+          throw error;
+        });
+      return await runtimePromise;
+    };
+
+    const getStatus = async () => {
+      const current = runtimePromise;
+      if (current) {
+        try {
+          return await (await current).status();
+        } catch {
+          // Static status remains available after a failed or interrupted activation.
+        }
+      }
+      return await inspectFaceTimeStaticStatus({
+        config,
+        configErrors: validation.errors,
+        pluginRoot,
+        runCommandWithTimeout: api.runtime.system.runCommandWithTimeout,
+      });
+    };
+
+    api.registerTool(() => createFaceTimeCallTool({ ensureRuntime, getStatus }), {
+      name: "facetime_call",
+    });
+    api.on("before_tool_call", (event) => {
+      if (event.toolName !== "facetime_call") {
+        return undefined;
+      }
+      return resolveFaceTimeToolApproval(event.params);
+    });
+
+    api.registerService({
+      id: "facetime-runtime",
+      async start() {
+        if (!config.enabled || !validation.valid) {
+          return;
+        }
+        try {
+          await ensureRuntime();
+        } catch (error) {
+          api.logger.warn(`[facetime] startup skipped: ${formatErrorMessage(error)}`);
+        }
+      },
+      async stop() {
+        await stopRetainedRuntime(runtimePromise, (stopped) => {
+          if (runtimePromise === stopped) {
+            runtimePromise = undefined;
+          }
+        });
+      },
+    });
+
+    const registerGateway = (
+      name: string,
+      scope: "operator.read" | "operator.write" | "operator.admin",
+      handler: (options: GatewayRequestHandlerOptions) => Promise<unknown>,
+    ) => {
+      api.registerGatewayMethod(
+        name,
+        async (options: GatewayRequestHandlerOptions) => {
+          try {
+            options.respond(true, await handler(options));
+          } catch (error) {
+            options.respond(
+              false,
+              undefined,
+              errorShape(ErrorCodes.UNAVAILABLE, formatErrorMessage(error)),
+            );
+          }
+        },
+        { scope },
+      );
+    };
+
+    registerGateway("facetime.status", "operator.read", getStatus);
+    registerGateway("facetime.setup", "operator.admin", async () => {
+      const nativePackageReady = await inspectFaceTimeNativePackage();
+      if (!nativePackageReady) {
+        return await runFaceTimeSetup({
+          config,
+          nativePackageReady,
+          pluginRoot,
+          runCommandWithTimeout: api.runtime.system.runCommandWithTimeout,
+        });
+      }
+      let runtime: import("./runtime-api.js").FaceTimeRuntime;
+      try {
+        runtime = await ensureRuntime();
+      } catch (runtimeError) {
+        return await runFaceTimeSetup({
+          config,
+          nativePackageReady: await inspectFaceTimeNativePackage(),
+          pluginRoot,
+          runCommandWithTimeout: api.runtime.system.runCommandWithTimeout,
+          runtimeError: formatErrorMessage(runtimeError),
+        });
+      }
+      return await runtime.setup();
+    });
+    registerGateway("facetime.driverStatus", "operator.read", async () => ({
+      status: await inspectFaceTimeDriver({
+        pluginRoot,
+        runCommandWithTimeout: api.runtime.system.runCommandWithTimeout,
+      }),
+    }));
+    const installDriver = async () => ({
+      ok: true,
+      ...(await (await ensureRuntime()).installDriver()),
+    });
+    for (const name of ["facetime.installDriver", "facetime.updateDriver"]) {
+      registerGateway(name, "operator.admin", installDriver);
+    }
+    registerGateway("facetime.uninstall", "operator.admin", async () => {
+      if (uninstalling) {
+        throw new Error("facetime native uninstall is already in progress");
+      }
+      uninstalling = true;
+      try {
+        const current = runtimePromise;
+        if (current) {
+          await stopRetainedRuntime(current, (stopped) => {
+            if (runtimePromise === stopped) {
+              runtimePromise = undefined;
+            }
+          });
+        }
+        await uninstallFaceTimeDriver({
+          pluginRoot,
+          runCommandWithTimeout: api.runtime.system.runCommandWithTimeout,
+        });
+        return {
+          ok: true,
+          guidance: "Quit and reopen FaceTime and Phone before re-enabling this plugin.",
+        };
+      } finally {
+        uninstalling = false;
+      }
+    });
+    registerGateway(
+      "facetime.preflight",
+      "operator.admin",
+      async () => await (await ensureRuntime()).preflight(),
+    );
+    registerGateway("facetime.dial", "operator.write", async ({ params }) => {
+      const record = params && typeof params === "object" ? params : {};
+      const handle = "handle" in record ? record.handle : undefined;
+      const mode = "mode" in record ? record.mode : undefined;
+      return { ok: true, ...(await (await ensureRuntime()).dial({ handle, mode })) };
+    });
+    registerGateway("facetime.hangup", "operator.write", async ({ params }) => {
+      const callUUID =
+        params && typeof params === "object" && "callUUID" in params ? params.callUUID : undefined;
+      return { ok: true, ...(await (await ensureRuntime()).hangup({ callUUID })) };
+    });
+  },
+});
+
+export default faceTimePlugin;

package/node_modules/typebox/build/compile/code.d.mts

@@ -0,0 +1,12 @@
+import { type TProperties, type TSchema } from '../type/index.mjs';
+import { type TExternal } from '../schema/index.mjs';
+export interface CodeResult {
+    /** External Variables  */
+    External: TExternal;
+    /** Generated Esm module. */
+    Code: string;
+}
+/** Creates a standalone ESM validation module for the given type. */
+export declare function Code<Type extends TSchema>(type: Type): CodeResult;
+/** Creates a standalone ESM validation module for the given type. */
+export declare function Code<Context extends TProperties, Type extends TSchema>(context: Context, type: Type): CodeResult;

package/node_modules/typebox/build/compile/code.mjs

@@ -0,0 +1,64 @@
+// deno-fmt-ignore-file
+import { Arguments } from '../system/arguments/index.mjs';
+import { Build } from '../schema/index.mjs';
+// ------------------------------------------------------------------
+// Comments and Formatting
+// ------------------------------------------------------------------
+function TsIgnore() {
+    return `// @ts-ignore`;
+}
+function Separator() {
+    return ``;
+}
+// ------------------------------------------------------------------
+// ImportSection
+// ------------------------------------------------------------------
+function ImportSection(build) {
+    const context = build.UseUnevaluated() ? [`import { CheckContext } from "typebox/schema"`] : [];
+    const hashing = `import { Hashing } from "typebox/system"`;
+    const guard = `import { Guard } from "typebox/guard"`;
+    return [...context, hashing, guard];
+}
+// ------------------------------------------------------------------
+// ExternalSection
+// ------------------------------------------------------------------
+function ExternalSection(build) {
+    const { identifier } = build.External();
+    return [
+        Separator(),
+        TsIgnore(),
+        `let ${identifier} = []`,
+        Separator(),
+        TsIgnore(),
+        `export function SetExternal(external) { ${identifier} = external.variables }`
+    ];
+}
+// ------------------------------------------------------------------
+// FunctionSection
+// ------------------------------------------------------------------
+function FunctionSection(build) {
+    return build.Functions().map((func) => [Separator(), TsIgnore(), `${func};`].join('\n'));
+}
+// ------------------------------------------------------------------
+// ExportSection
+// ------------------------------------------------------------------
+function ExportSection(build) {
+    const body = build.UseUnevaluated()
+        ? `const context = new CheckContext({}, {}); return ${build.Entry()}`
+        : `return ${build.Entry()}`;
+    return [
+        Separator(),
+        TsIgnore(),
+        `export function Check(value) { ${body} }`
+    ];
+}
+/** Creates a standalone ESM validation module for the given type. */
+export function Code(...args) {
+    const [context, type] = Arguments.Match(args, {
+        2: (context, type) => [context, type],
+        1: (type) => [{}, type]
+    });
+    const build = Build(context, type);
+    const code = [...ImportSection(build), ...ExternalSection(build), ...FunctionSection(build), ...ExportSection(build)].join('\n');
+    return { External: build.External(), Code: code };
+}

package/node_modules/typebox/build/compile/compile.d.mts

@@ -0,0 +1,6 @@
+import { type TProperties, type TSchema } from '../type/index.mjs';
+import { Validator } from './validator.mjs';
+/** Compiles a type into a high performance Validator */
+export declare function Compile<const Type extends TSchema, Result extends Validator = Validator<{}, Type>>(type: Type): Result;
+/** Compiles a type into a high performance Validator */
+export declare function Compile<Context extends TProperties, const Type extends TSchema, Result extends Validator = Validator<Context, Type>>(context: Context, type: Type): Result;

package/node_modules/typebox/build/compile/compile.mjs

@@ -0,0 +1,12 @@
+// deno-lint-ignore-file ban-types
+// deno-fmt-ignore-file
+import { Arguments } from '../system/arguments/index.mjs';
+import { Validator } from './validator.mjs';
+/** Compiles a type into a high performance Validator */
+export function Compile(...args) {
+    const [context, type] = Arguments.Match(args, {
+        2: (context, type) => [context, type],
+        1: (type) => [{}, type]
+    });
+    return new Validator(context, type);
+}

package/node_modules/typebox/build/compile/index.d.mts

@@ -0,0 +1,8 @@
+export * from './code.mjs';
+export * from './compile.mjs';
+export * from './validator.mjs';
+import { Code } from './code.mjs';
+import { Compile } from './compile.mjs';
+import { Validator } from './validator.mjs';
+export { Code, Compile, Validator };
+export default Compile;

package/node_modules/typebox/build/compile/index.mjs

@@ -0,0 +1,14 @@
+// ------------------------------------------------------------------
+// Barrel
+// ------------------------------------------------------------------
+export * from './code.mjs';
+export * from './compile.mjs';
+export * from './validator.mjs';
+// ------------------------------------------------------------------
+// Default
+// ------------------------------------------------------------------
+import { Code } from './code.mjs';
+import { Compile } from './compile.mjs';
+import { Validator } from './validator.mjs';
+export { Code, Compile, Validator };
+export default Compile;

package/node_modules/typebox/build/compile/validator.d.mts

@@ -0,0 +1,35 @@
+import { type TLocalizedValidationError } from '../error/index.mjs';
+import { type StaticDecode, type StaticEncode, type TProperties, type TSchema } from '../type/index.mjs';
+export declare class Validator<Context extends TProperties = TProperties, Type extends TSchema = TSchema, Encode extends unknown = StaticEncode<Type, Context>, Decode extends unknown = StaticDecode<Type, Context>> {
+    private readonly hasCodec;
+    private readonly buildResult;
+    private readonly evaluateResult;
+    /** Constructs a Validator. */
+    constructor(context: Context, type: Type);
+    /** Returns true if this Validator is using JIT acceleration. */
+    IsAccelerated(): boolean;
+    /** Returns the Context for this validator. */
+    Context(): Context;
+    /** Returns the underlying Type used to construct this Validator. */
+    Type(): Type;
+    /** Returns the generated code for this validator. */
+    Code(): string;
+    /** Performs a type-guard check on the provided value. */
+    Check(value: unknown): value is Encode;
+    /** Validates a value and returns it. Will throw if invalid. */
+    Parse(value: unknown): Encode;
+    /** Returns an array of validation errors for the given value. */
+    Errors(value: unknown): TLocalizedValidationError[];
+    /** Cleans a value using the Validator type. */
+    Clean(value: unknown): unknown;
+    /** Converts a value using the Validator type. */
+    Convert(value: unknown): unknown;
+    /** Creates a value using the Validator type. */
+    Create(): Encode;
+    /** Creates defaults using the Validator type. */
+    Default(value: unknown): unknown;
+    /** Decodes a value */
+    Decode(value: unknown): Decode;
+    /** Encodes a value */
+    Encode(value: unknown): Encode;
+}

package/node_modules/typebox/build/compile/validator.mjs

@@ -0,0 +1,95 @@
+// deno-fmt-ignore-file
+import { EnableParseErrors, DisableParseErrors } from '../system/settings/internal.mjs';
+import { Settings } from '../system/settings/index.mjs';
+import { Errors, Clean, Convert, Create, Default, Decode, Encode, HasCodec, Parser, ParseError } from '../value/index.mjs';
+import { Build } from '../schema/index.mjs';
+// ------------------------------------------------------------------
+// Validator<...>
+// ------------------------------------------------------------------
+export class Validator {
+    /** Constructs a Validator. */
+    constructor(context, type) {
+        this.hasCodec = HasCodec(context, type);
+        this.buildResult = Build(context, type);
+        this.evaluateResult = this.buildResult.Evaluate();
+    }
+    // ----------------------------------------------------------------
+    // IsAccelerated
+    // ----------------------------------------------------------------
+    /** Returns true if this Validator is using JIT acceleration. */
+    IsAccelerated() {
+        return this.evaluateResult.IsAccelerated();
+    }
+    // ----------------------------------------------------------------
+    // Context & Type
+    // ----------------------------------------------------------------
+    /** Returns the Context for this validator. */
+    Context() {
+        return this.buildResult.Context();
+    }
+    /** Returns the underlying Type used to construct this Validator. */
+    Type() {
+        return this.buildResult.Schema();
+    }
+    // ----------------------------------------------------------------
+    // Code
+    // ----------------------------------------------------------------
+    /** Returns the generated code for this validator. */
+    Code() {
+        return this.evaluateResult.Code();
+    }
+    // ----------------------------------------------------------------
+    // Standard Validator
+    // ----------------------------------------------------------------
+    /** Performs a type-guard check on the provided value. */
+    Check(value) {
+        return this.evaluateResult.Check(value);
+    }
+    /** Validates a value and returns it. Will throw if invalid. */
+    Parse(value) {
+        const checked = this.Check(value);
+        if (checked)
+            return value;
+        if (Settings.Get().correctiveParse)
+            return Parser(this.Context(), this.Type(), value);
+        EnableParseErrors();
+        const errors = this.Errors(value);
+        DisableParseErrors();
+        throw new ParseError(value, errors);
+    }
+    /** Returns an array of validation errors for the given value. */
+    Errors(value) {
+        if (this.IsAccelerated() && this.Check(value))
+            return [];
+        return Errors(this.Context(), this.Type(), value);
+    }
+    // ----------------------------------------------------------------
+    // Value.* Operations
+    // ----------------------------------------------------------------
+    /** Cleans a value using the Validator type. */
+    Clean(value) {
+        return Clean(this.Context(), this.Type(), value);
+    }
+    /** Converts a value using the Validator type. */
+    Convert(value) {
+        return Convert(this.Context(), this.Type(), value);
+    }
+    /** Creates a value using the Validator type. */
+    Create() {
+        return Create(this.Context(), this.Type());
+    }
+    /** Creates defaults using the Validator type. */
+    Default(value) {
+        return Default(this.Context(), this.Type(), value);
+    }
+    /** Decodes a value */
+    Decode(value) {
+        const result = this.hasCodec ? Decode(this.Context(), this.Type(), value) : this.Parse(value);
+        return result;
+    }
+    /** Encodes a value */
+    Encode(value) {
+        const result = this.hasCodec ? Encode(this.Context(), this.Type(), value) : this.Parse(value);
+        return result;
+    }
+}