Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

extensions/phone-control/index.ts

@@ -0,0 +1,482 @@
+// Phone Control plugin entrypoint registers its OpenClaw integration.
+import {
+  asDateTimestampMs,
+  resolveExpiresAtMsFromDurationMs,
+} from "openclaw/plugin-sdk/number-runtime";
+import {
+  normalizeLowercaseStringOrEmpty,
+  normalizeOptionalLowercaseString,
+  normalizeStringEntries,
+  sortUniqueStrings,
+} from "openclaw/plugin-sdk/string-coerce-runtime";
+import {
+  definePluginEntry,
+  type OpenClawPluginApi,
+  type OpenClawPluginService,
+} from "./runtime-api.js";
+
+type ArmGroup = "camera" | "screen" | "writes" | "all";
+
+type ArmStateFileV1 = {
+  version: 1;
+  armedAtMs: number;
+  expiresAtMs: number | null;
+  removedFromDeny: string[];
+};
+
+type ArmStateFileV2 = {
+  version: 2;
+  armedAtMs: number;
+  expiresAtMs: number | null;
+  group: ArmGroup;
+  armedCommands: string[];
+  addedToAllow: string[];
+  removedFromDeny: string[];
+};
+
+type ArmStateFile = ArmStateFileV1 | ArmStateFileV2;
+type PhoneControlConfigView = {
+  readonly gateway?: {
+    readonly nodes?: {
+      readonly allowCommands?: readonly string[];
+      readonly denyCommands?: readonly string[];
+    };
+  };
+};
+
+const STATE_VERSION = 2;
+const ARM_STATE_NAMESPACE = "armed";
+const ARM_STATE_KEY = "current";
+const PHONE_ADMIN_SCOPE = "operator.admin";
+
+const GROUP_COMMANDS: Record<Exclude<ArmGroup, "all">, string[]> = {
+  camera: ["camera.snap", "camera.clip"],
+  screen: ["screen.record"],
+  writes: ["calendar.add", "contacts.add", "reminders.add", "sms.send"],
+};
+const PHONE_CONTROL_COMMANDS = Object.values(GROUP_COMMANDS).flat();
+
+function uniqSorted(values: string[]): string[] {
+  return sortUniqueStrings(normalizeStringEntries(values));
+}
+
+function resolveCommandsForGroup(group: ArmGroup): string[] {
+  if (group === "all") {
+    return uniqSorted(Object.values(GROUP_COMMANDS).flat());
+  }
+  return uniqSorted(GROUP_COMMANDS[group]);
+}
+
+function formatGroupList(): string {
+  return ["camera", "screen", "writes", "all"].join(", ");
+}
+
+function parseDurationMs(input: string | undefined): number | null {
+  const raw = normalizeOptionalLowercaseString(input);
+  if (!raw) {
+    return null;
+  }
+  const m = raw.match(/^(\d+)(s|m|h|d)$/);
+  if (!m) {
+    return null;
+  }
+  const n = Number.parseInt(m[1] ?? "", 10);
+  if (!Number.isFinite(n) || n <= 0) {
+    return null;
+  }
+  const unit = m[2];
+  const mult = unit === "s" ? 1000 : unit === "m" ? 60_000 : unit === "h" ? 3_600_000 : 86_400_000;
+  const durationMs = n * mult;
+  return Number.isSafeInteger(durationMs) ? durationMs : null;
+}
+
+function formatDuration(ms: number): string {
+  const s = Math.max(0, Math.floor(ms / 1000));
+  if (s < 60) {
+    return `${s}s`;
+  }
+  const m = Math.floor(s / 60);
+  if (m < 60) {
+    return `${m}m`;
+  }
+  const h = Math.floor(m / 60);
+  if (h < 48) {
+    return `${h}h`;
+  }
+  const d = Math.floor(h / 24);
+  return `${d}d`;
+}
+
+function openArmStateStore(api: OpenClawPluginApi) {
+  return api.runtime.state.openKeyedStore<ArmStateFile>({
+    namespace: ARM_STATE_NAMESPACE,
+    maxEntries: 1,
+  });
+}
+
+async function readArmState(api: OpenClawPluginApi): Promise<ArmStateFile | null> {
+  return (await openArmStateStore(api).lookup(ARM_STATE_KEY)) ?? null;
+}
+
+async function writeArmState(api: OpenClawPluginApi, state: ArmStateFile | null): Promise<void> {
+  const store = openArmStateStore(api);
+  if (!state) {
+    await store.delete(ARM_STATE_KEY);
+    return;
+  }
+  await store.register(ARM_STATE_KEY, state);
+}
+
+function normalizeDenyList(cfg: PhoneControlConfigView): string[] {
+  return uniqSorted([...(cfg.gateway?.nodes?.denyCommands ?? [])]);
+}
+
+function normalizeAllowList(cfg: PhoneControlConfigView): string[] {
+  return uniqSorted([...(cfg.gateway?.nodes?.allowCommands ?? [])]);
+}
+
+function hasPhoneControlAllowOverride(cfg: PhoneControlConfigView): boolean {
+  const allow = new Set(normalizeAllowList(cfg));
+  return PHONE_CONTROL_COMMANDS.some((cmd) => allow.has(cmd));
+}
+
+function patchConfigNodeLists(
+  cfg: OpenClawPluginApi["config"],
+  next: { allowCommands: string[]; denyCommands: string[] },
+): OpenClawPluginApi["config"] {
+  return {
+    ...cfg,
+    gateway: {
+      ...cfg.gateway,
+      nodes: {
+        ...cfg.gateway?.nodes,
+        allowCommands: next.allowCommands,
+        denyCommands: next.denyCommands,
+      },
+    },
+  };
+}
+
+async function disarmNow(params: {
+  api: OpenClawPluginApi;
+  reason: string;
+}): Promise<{ changed: boolean; restored: string[]; removed: string[] }> {
+  const { api, reason } = params;
+  const state = await readArmState(api);
+  if (!state) {
+    return { changed: false, restored: [], removed: [] };
+  }
+  const cfg = api.runtime.config.current();
+  const allow = new Set(normalizeAllowList(cfg));
+  const deny = new Set(normalizeDenyList(cfg));
+  const removed: string[] = [];
+  const restored: string[] = [];
+
+  if (state.version === 1) {
+    for (const cmd of state.removedFromDeny) {
+      if (!deny.has(cmd)) {
+        deny.add(cmd);
+        restored.push(cmd);
+      }
+    }
+  } else {
+    for (const cmd of state.addedToAllow) {
+      if (allow.delete(cmd)) {
+        removed.push(cmd);
+      }
+    }
+    for (const cmd of state.removedFromDeny) {
+      if (!deny.has(cmd)) {
+        deny.add(cmd);
+        restored.push(cmd);
+      }
+    }
+  }
+
+  if (removed.length > 0 || restored.length > 0) {
+    await api.runtime.config.mutateConfigFile({
+      afterWrite: { mode: "auto" },
+      mutate: (draft) => {
+        const next = patchConfigNodeLists(draft, {
+          allowCommands: uniqSorted([...allow]),
+          denyCommands: uniqSorted([...deny]),
+        });
+        Object.assign(draft, next);
+      },
+    });
+  }
+  await writeArmState(api, null);
+  api.logger.info(`phone-control: disarmed (${reason})`);
+  return {
+    changed: removed.length > 0 || restored.length > 0,
+    removed: uniqSorted(removed),
+    restored: uniqSorted(restored),
+  };
+}
+
+function formatHelp(): string {
+  return [
+    "Phone control commands:",
+    "",
+    "/phone status",
+    "/phone arm <group> [duration]",
+    "/phone disarm",
+    "",
+    "Groups:",
+    `- ${formatGroupList()}`,
+    "",
+    "Duration format: 30s | 10m | 2h | 1d (default: 10m).",
+    "",
+    "Notes:",
+    "- This only toggles what the gateway is allowed to invoke on phone nodes.",
+    "- iOS will still ask for permissions (camera, photos, contacts, etc.) on first use.",
+  ].join("\n");
+}
+
+function parseGroup(raw: string | undefined): ArmGroup | null {
+  const value = normalizeOptionalLowercaseString(raw) ?? "";
+  if (!value) {
+    return null;
+  }
+  if (value === "camera" || value === "screen" || value === "writes" || value === "all") {
+    return value;
+  }
+  return null;
+}
+
+function lacksAdminToMutatePhoneControl(params: {
+  senderIsOwner?: boolean;
+  gatewayClientScopes?: readonly string[];
+}): boolean {
+  const { senderIsOwner, gatewayClientScopes } = params;
+  if (Array.isArray(gatewayClientScopes)) {
+    return !gatewayClientScopes.includes(PHONE_ADMIN_SCOPE);
+  }
+  return senderIsOwner !== true;
+}
+
+function resolveArmExpiryStatus(state: ArmStateFile, nowRaw = Date.now()): string {
+  if (state.expiresAtMs == null) {
+    return "manual disarm required";
+  }
+  const now = asDateTimestampMs(nowRaw);
+  if (now === undefined) {
+    return "expiry unavailable";
+  }
+  const expiresAt = asDateTimestampMs(state.expiresAtMs);
+  if (expiresAt === undefined || expiresAt <= now) {
+    return "expired";
+  }
+  return `expires in ${formatDuration(expiresAt - now)}`;
+}
+
+function isArmStateExpired(state: ArmStateFile, nowRaw = Date.now()): boolean {
+  if (state.expiresAtMs == null) {
+    return false;
+  }
+  const now = asDateTimestampMs(nowRaw);
+  if (now === undefined) {
+    return false;
+  }
+  const expiresAt = asDateTimestampMs(state.expiresAtMs);
+  return expiresAt === undefined || expiresAt <= now;
+}
+
+function formatStatus(state: ArmStateFile | null): string {
+  if (!state) {
+    return "Phone control: disarmed.";
+  }
+  const until = resolveArmExpiryStatus(state);
+  const cmds = uniqSorted(
+    state.version === 1
+      ? state.removedFromDeny
+      : state.armedCommands.length > 0
+        ? state.armedCommands
+        : [...state.addedToAllow, ...state.removedFromDeny],
+  );
+  const cmdLabel = cmds.length > 0 ? cmds.join(", ") : "none";
+  return `Phone control: armed (${until}).\nTemporarily allowed: ${cmdLabel}`;
+}
+
+export default definePluginEntry({
+  id: "phone-control",
+  name: "Phone Control",
+  description: "Temporary allowlist control for phone automation commands",
+  register(api: OpenClawPluginApi) {
+    let expiryInterval: ReturnType<typeof setInterval> | null = null;
+    let initialExpiryTick: ReturnType<typeof setImmediate> | null = null;
+
+    const timerService: OpenClawPluginService = {
+      id: "phone-control-expiry",
+      start: async (ctx) => {
+        const tick = async () => {
+          const state = await readArmState(api);
+          if (!state || state.expiresAtMs == null) {
+            return;
+          }
+          if (!isArmStateExpired(state)) {
+            return;
+          }
+          await disarmNow({
+            api,
+            reason: "expired",
+          });
+        };
+
+        expiryInterval = setInterval(() => {
+          tick().catch(() => {});
+        }, 15_000);
+        expiryInterval.unref?.();
+
+        if (hasPhoneControlAllowOverride(ctx.config)) {
+          // Active dangerous command allows must be reconciled before gateway
+          // readiness; otherwise an expired phone-control window can survive.
+          await tick().catch(() => {});
+        } else {
+          // With no active phone-control allowlist, startup can avoid opening
+          // plugin state before readiness; cleanup still runs before the interval.
+          initialExpiryTick = setImmediate(() => {
+            initialExpiryTick = null;
+            tick().catch(() => {});
+          });
+          initialExpiryTick.unref?.();
+        }
+      },
+      stop: async () => {
+        if (initialExpiryTick) {
+          clearImmediate(initialExpiryTick);
+          initialExpiryTick = null;
+        }
+        if (expiryInterval) {
+          clearInterval(expiryInterval);
+          expiryInterval = null;
+        }
+      },
+    };
+
+    api.registerService(timerService);
+
+    api.registerCommand({
+      name: "phone",
+      description: "Arm/disarm high-risk phone node commands (camera/screen/writes).",
+      acceptsArgs: true,
+      exposeSenderIsOwner: true,
+      handler: async (ctx) => {
+        const args = ctx.args?.trim() ?? "";
+        const tokens = args.split(/\s+/).filter(Boolean);
+        const action = normalizeLowercaseStringOrEmpty(tokens[0]);
+
+        if (!action || action === "help") {
+          const state = await readArmState(api);
+          return { text: `${formatStatus(state)}\n\n${formatHelp()}` };
+        }
+
+        if (action === "status") {
+          const state = await readArmState(api);
+          return { text: formatStatus(state) };
+        }
+
+        if (action === "disarm") {
+          if (
+            lacksAdminToMutatePhoneControl({
+              senderIsOwner: ctx.senderIsOwner,
+              gatewayClientScopes: ctx.gatewayClientScopes,
+            })
+          ) {
+            return {
+              text: "⚠️ /phone disarm requires operator.admin.",
+            };
+          }
+          const res = await disarmNow({
+            api,
+            reason: "manual",
+          });
+          if (!res.changed) {
+            return { text: "Phone control: disarmed." };
+          }
+          const restoredLabel = res.restored.length > 0 ? res.restored.join(", ") : "none";
+          const removedLabel = res.removed.length > 0 ? res.removed.join(", ") : "none";
+          return {
+            text: `Phone control: disarmed.\nRemoved allowlist: ${removedLabel}\nRestored denylist: ${restoredLabel}`,
+          };
+        }
+
+        if (action === "arm") {
+          if (
+            lacksAdminToMutatePhoneControl({
+              senderIsOwner: ctx.senderIsOwner,
+              gatewayClientScopes: ctx.gatewayClientScopes,
+            })
+          ) {
+            return {
+              text: "⚠️ /phone arm requires operator.admin.",
+            };
+          }
+          const group = parseGroup(tokens[1]);
+          if (!group) {
+            return { text: `Usage: /phone arm <group> [duration]\nGroups: ${formatGroupList()}` };
+          }
+          const durationMs = tokens[2] === undefined ? 10 * 60_000 : parseDurationMs(tokens[2]);
+          if (durationMs === null) {
+            return { text: "Invalid duration. Use values like 30s, 10m, 2h, or 1d." };
+          }
+          const armedAtMs = asDateTimestampMs(Date.now());
+          const expiresAtMs =
+            armedAtMs === undefined
+              ? undefined
+              : resolveExpiresAtMsFromDurationMs(durationMs, { nowMs: armedAtMs });
+          if (armedAtMs === undefined || expiresAtMs === undefined) {
+            return { text: "Invalid duration. Use values like 30s, 10m, 2h, or 1d." };
+          }
+
+          const commands = resolveCommandsForGroup(group);
+          const cfg = api.runtime.config.current();
+          const allowSet = new Set(normalizeAllowList(cfg));
+          const denySet = new Set(normalizeDenyList(cfg));
+
+          const addedToAllow: string[] = [];
+          const removedFromDeny: string[] = [];
+          for (const cmd of commands) {
+            if (!allowSet.has(cmd)) {
+              allowSet.add(cmd);
+              addedToAllow.push(cmd);
+            }
+            if (denySet.delete(cmd)) {
+              removedFromDeny.push(cmd);
+            }
+          }
+          await api.runtime.config.mutateConfigFile({
+            afterWrite: { mode: "auto" },
+            mutate: (draft) => {
+              const next = patchConfigNodeLists(draft, {
+                allowCommands: uniqSorted([...allowSet]),
+                denyCommands: uniqSorted([...denySet]),
+              });
+              Object.assign(draft, next);
+            },
+          });
+
+          await writeArmState(api, {
+            version: STATE_VERSION,
+            armedAtMs,
+            expiresAtMs,
+            group,
+            armedCommands: uniqSorted(commands),
+            addedToAllow: uniqSorted(addedToAllow),
+            removedFromDeny: uniqSorted(removedFromDeny),
+          });
+
+          const allowedLabel = uniqSorted(commands).join(", ");
+          return {
+            text:
+              `Phone control: armed for ${formatDuration(durationMs)}.\n` +
+              `Temporarily allowed: ${allowedLabel}\n` +
+              `To disarm early: /phone disarm`,
+          };
+        }
+
+        return { text: formatHelp() };
+      },
+    });
+  },
+});