@openclaw/voice-call 2026.3.13 → 2026.5.1-beta.1

package/src/config.ts

@@ -1,11 +1,14 @@
+import { REALTIME_VOICE_AGENT_CONSULT_TOOL_POLICIES } from "openclaw/plugin-sdk/realtime-voice";
 import {
-  TtsAutoSchema,
-  TtsConfigSchema,
-  TtsModeSchema,
-  TtsProviderSchema,
-} from "openclaw/plugin-sdk/voice-call";
-import { z } from "zod";
+  buildSecretInputSchema,
+  hasConfiguredSecretInput,
+  normalizeResolvedSecretInputString,
+  type SecretInput,
+} from "openclaw/plugin-sdk/secret-input";
+import { z } from "openclaw/plugin-sdk/zod";
+import { TtsConfigSchema } from "../api.js";
 import { deepMergeDefined } from "./deep-merge.js";
+import { DEFAULT_VOICE_CALL_REALTIME_INSTRUCTIONS } from "./realtime-defaults.js";
 
 // -----------------------------------------------------------------------------
 // Phone Number Validation
@@ -15,7 +18,7 @@ import { deepMergeDefined } from "./deep-merge.js";
  * E.164 phone number format: +[country code][number]
  * Examples use 555 prefix (reserved for fictional numbers)
  */
-export const E164Schema = z
+const E164Schema = z
   .string()
   .regex(/^\+[1-9]\d{1,14}$/, "Expected E.164 format, e.g. +15550001234");
 
@@ -30,14 +33,15 @@ export const E164Schema = z
  * - "pairing": Unknown callers can request pairing (future)
  * - "open": Accept all inbound calls (dangerous!)
  */
-export const InboundPolicySchema = z.enum(["disabled", "allowlist", "pairing", "open"]);
-export type InboundPolicy = z.infer<typeof InboundPolicySchema>;
+const InboundPolicySchema = z.enum(["disabled", "allowlist", "pairing", "open"]);
 
 // -----------------------------------------------------------------------------
 // Provider-Specific Configuration
 // -----------------------------------------------------------------------------
 
-export const TelnyxConfigSchema = z
+const SecretInputSchema = buildSecretInputSchema();
+
+const TelnyxConfigSchema = z
   .object({
     /** Telnyx API v2 key */
     apiKey: z.string().min(1).optional(),
@@ -49,17 +53,16 @@ export const TelnyxConfigSchema = z
   .strict();
 export type TelnyxConfig = z.infer<typeof TelnyxConfigSchema>;
 
-export const TwilioConfigSchema = z
+const TwilioConfigSchema = z
   .object({
     /** Twilio Account SID */
     accountSid: z.string().min(1).optional(),
     /** Twilio Auth Token */
-    authToken: z.string().min(1).optional(),
+    authToken: SecretInputSchema.optional(),
   })
   .strict();
-export type TwilioConfig = z.infer<typeof TwilioConfigSchema>;
 
-export const PlivoConfigSchema = z
+const PlivoConfigSchema = z
   .object({
     /** Plivo Auth ID (starts with MA/SA) */
     authId: z.string().min(1).optional(),
@@ -69,29 +72,13 @@ export const PlivoConfigSchema = z
   .strict();
 export type PlivoConfig = z.infer<typeof PlivoConfigSchema>;
 
-// -----------------------------------------------------------------------------
-// STT/TTS Configuration
-// -----------------------------------------------------------------------------
-
-export const SttConfigSchema = z
-  .object({
-    /** STT provider (currently only OpenAI supported) */
-    provider: z.literal("openai").default("openai"),
-    /** Whisper model to use */
-    model: z.string().min(1).default("whisper-1"),
-  })
-  .strict()
-  .default({ provider: "openai", model: "whisper-1" });
-export type SttConfig = z.infer<typeof SttConfigSchema>;
-
-export { TtsAutoSchema, TtsConfigSchema, TtsModeSchema, TtsProviderSchema };
 export type VoiceCallTtsConfig = z.infer<typeof TtsConfigSchema>;
 
 // -----------------------------------------------------------------------------
 // Webhook Server Configuration
 // -----------------------------------------------------------------------------
 
-export const VoiceCallServeConfigSchema = z
+const VoiceCallServeConfigSchema = z
   .object({
     /** Port to listen on */
     port: z.number().int().positive().default(3334),
@@ -102,9 +89,8 @@ export const VoiceCallServeConfigSchema = z
   })
   .strict()
   .default({ port: 3334, bind: "127.0.0.1", path: "/voice/webhook" });
-export type VoiceCallServeConfig = z.infer<typeof VoiceCallServeConfigSchema>;
 
-export const VoiceCallTailscaleConfigSchema = z
+const VoiceCallTailscaleConfigSchema = z
   .object({
     /**
      * Tailscale exposure mode:
@@ -118,13 +104,12 @@ export const VoiceCallTailscaleConfigSchema = z
   })
   .strict()
   .default({ mode: "off", path: "/voice/webhook" });
-export type VoiceCallTailscaleConfig = z.infer<typeof VoiceCallTailscaleConfigSchema>;
 
 // -----------------------------------------------------------------------------
 // Tunnel Configuration (unified ngrok/tailscale)
 // -----------------------------------------------------------------------------
 
-export const VoiceCallTunnelConfigSchema = z
+const VoiceCallTunnelConfigSchema = z
   .object({
     /**
      * Tunnel provider:
@@ -149,13 +134,12 @@ export const VoiceCallTunnelConfigSchema = z
   })
   .strict()
   .default({ provider: "none", allowNgrokFreeTierLoopbackBypass: false });
-export type VoiceCallTunnelConfig = z.infer<typeof VoiceCallTunnelConfigSchema>;
 
 // -----------------------------------------------------------------------------
 // Webhook Security Configuration
 // -----------------------------------------------------------------------------
 
-export const VoiceCallWebhookSecurityConfigSchema = z
+const VoiceCallWebhookSecurityConfigSchema = z
   .object({
     /**
      * Allowed hostnames for webhook URL reconstruction.
@@ -186,10 +170,10 @@ export type WebhookSecurityConfig = z.infer<typeof VoiceCallWebhookSecurityConfi
  * - "notify": Deliver message and auto-hangup after delay (one-way notification)
  * - "conversation": Stay open for back-and-forth until explicit end or timeout
  */
-export const CallModeSchema = z.enum(["notify", "conversation"]);
+const CallModeSchema = z.enum(["notify", "conversation"]);
 export type CallMode = z.infer<typeof CallModeSchema>;
 
-export const OutboundConfigSchema = z
+const OutboundConfigSchema = z
   .object({
     /** Default call mode for outbound calls */
     defaultMode: CallModeSchema.default("notify"),
@@ -198,28 +182,115 @@ export const OutboundConfigSchema = z
   })
   .strict()
   .default({ defaultMode: "notify", notifyHangupDelaySec: 3 });
-export type OutboundConfig = z.infer<typeof OutboundConfigSchema>;
 
 // -----------------------------------------------------------------------------
-// Streaming Configuration (OpenAI Realtime STT)
+// Realtime Voice Configuration
 // -----------------------------------------------------------------------------
 
-export const VoiceCallStreamingConfigSchema = z
+const RealtimeToolSchema = z
+  .object({
+    type: z.literal("function"),
+    name: z.string().min(1),
+    description: z.string(),
+    parameters: z.object({
+      type: z.literal("object"),
+      properties: z.record(z.string(), z.unknown()),
+      required: z.array(z.string()).optional(),
+    }),
+  })
+  .strict();
+type RealtimeToolConfig = z.infer<typeof RealtimeToolSchema>;
+
+const VoiceCallRealtimeProvidersConfigSchema = z
+  .record(z.string(), z.record(z.string(), z.unknown()))
+  .default({});
+
+const VoiceCallRealtimeToolPolicySchema = z.enum(REALTIME_VOICE_AGENT_CONSULT_TOOL_POLICIES);
+
+const VoiceCallRealtimeFastContextSourceSchema = z.enum(["memory", "sessions"]);
+
+const VoiceCallRealtimeFastContextConfigSchema = z
+  .object({
+    /** Enable bounded memory/session lookup before the full consult agent. */
+    enabled: z.boolean().default(false),
+    /** Hard deadline for the fast context lookup. */
+    timeoutMs: z.number().int().positive().default(800),
+    /** Maximum memory/session hits to inject into the realtime tool result. */
+    maxResults: z.number().int().positive().default(3),
+    /** Indexed sources used by the fast context lookup. */
+    sources: z
+      .array(VoiceCallRealtimeFastContextSourceSchema)
+      .min(1)
+      .default(["memory", "sessions"]),
+    /** Fall back to the full agent consult when fast context has no answer. */
+    fallbackToConsult: z.boolean().default(false),
+  })
+  .strict()
+  .default({
+    enabled: false,
+    timeoutMs: 800,
+    maxResults: 3,
+    sources: ["memory", "sessions"],
+    fallbackToConsult: false,
+  });
+export type VoiceCallRealtimeFastContextConfig = z.infer<
+  typeof VoiceCallRealtimeFastContextConfigSchema
+>;
+
+const VoiceCallStreamingProvidersConfigSchema = z
+  .record(z.string(), z.record(z.string(), z.unknown()))
+  .default({});
+
+const VoiceCallRealtimeConfigSchema = z
+  .object({
+    /** Enable realtime voice-to-voice mode. */
+    enabled: z.boolean().default(false),
+    /** Provider id from registered realtime voice providers. */
+    provider: z.string().min(1).optional(),
+    /** Optional override for the local WebSocket route path. */
+    streamPath: z.string().min(1).optional(),
+    /** System instructions passed to the realtime provider. */
+    instructions: z.string().default(DEFAULT_VOICE_CALL_REALTIME_INSTRUCTIONS),
+    /** Tool policy for the shared OpenClaw agent consult tool. */
+    toolPolicy: VoiceCallRealtimeToolPolicySchema.default("safe-read-only"),
+    /** Tool definitions exposed to the realtime provider. */
+    tools: z.array(RealtimeToolSchema).default([]),
+    /** Low-latency memory/session context for the consult tool. */
+    fastContext: VoiceCallRealtimeFastContextConfigSchema,
+    /** Provider-owned raw config blobs keyed by provider id. */
+    providers: VoiceCallRealtimeProvidersConfigSchema,
+  })
+  .strict()
+  .default({
+    enabled: false,
+    instructions: DEFAULT_VOICE_CALL_REALTIME_INSTRUCTIONS,
+    toolPolicy: "safe-read-only",
+    tools: [],
+    fastContext: {
+      enabled: false,
+      timeoutMs: 800,
+      maxResults: 3,
+      sources: ["memory", "sessions"],
+      fallbackToConsult: false,
+    },
+    providers: {},
+  });
+export type VoiceCallRealtimeConfig = z.infer<typeof VoiceCallRealtimeConfigSchema>;
+
+// -----------------------------------------------------------------------------
+// Streaming Configuration (Realtime Transcription)
+// -----------------------------------------------------------------------------
+
+const VoiceCallStreamingConfigSchema = z
   .object({
     /** Enable real-time audio streaming (requires WebSocket support) */
     enabled: z.boolean().default(false),
-    /** STT provider for real-time transcription */
-    sttProvider: z.enum(["openai-realtime"]).default("openai-realtime"),
-    /** OpenAI API key for Realtime API (uses OPENAI_API_KEY env if not set) */
-    openaiApiKey: z.string().min(1).optional(),
-    /** OpenAI transcription model (default: gpt-4o-transcribe) */
-    sttModel: z.string().min(1).default("gpt-4o-transcribe"),
-    /** VAD silence duration in ms before considering speech ended */
-    silenceDurationMs: z.number().int().positive().default(800),
-    /** VAD threshold 0-1 (higher = less sensitive) */
-    vadThreshold: z.number().min(0).max(1).default(0.5),
+    /** Provider id from registered realtime transcription providers. */
+    provider: z.string().min(1).optional(),
     /** WebSocket path for media stream connections */
     streamPath: z.string().min(1).default("/voice/stream"),
+    /** Provider-owned raw config blobs keyed by provider id. */
+    providers: VoiceCallStreamingProvidersConfigSchema,
     /**
      * Close unauthenticated media stream sockets if no valid `start` frame arrives in time.
      * Protects against pre-auth idle connection hold attacks.
@@ -235,17 +306,13 @@ export const VoiceCallStreamingConfigSchema = z
   .strict()
   .default({
     enabled: false,
-    sttProvider: "openai-realtime",
-    sttModel: "gpt-4o-transcribe",
-    silenceDurationMs: 800,
-    vadThreshold: 0.5,
     streamPath: "/voice/stream",
+    providers: {},
     preStartTimeoutMs: 5000,
     maxPendingConnections: 32,
     maxPendingConnectionsPerIp: 4,
     maxConnections: 128,
   });
-export type VoiceCallStreamingConfig = z.infer<typeof VoiceCallStreamingConfigSchema>;
 
 // -----------------------------------------------------------------------------
 // Main Voice Call Configuration
@@ -291,11 +358,10 @@ export const VoiceCallConfigSchema = z
 
     /**
      * Maximum age of a call in seconds before it is automatically reaped.
-     * Catches calls stuck in unexpected states (e.g., notify-mode calls that
-     * never receive a terminal webhook). Set to 0 to disable.
-     * Default: 0 (disabled). Recommended: 120-300 for production.
+     * Catches calls stuck before answer (for example, local mock calls that
+     * never receive provider webhooks). Set to 0 to disable.
      */
-    staleCallReaperSeconds: z.number().int().nonnegative().default(0),
+    staleCallReaperSeconds: z.number().int().nonnegative().default(120),
 
     /** Silence timeout for end-of-speech detection (ms) */
     silenceTimeoutMs: z.number().int().positive().default(800),
@@ -312,7 +378,7 @@ export const VoiceCallConfigSchema = z
     /** Webhook server configuration */
     serve: VoiceCallServeConfigSchema,
 
-    /** Tailscale exposure configuration (legacy, prefer tunnel config) */
+    /** @deprecated Prefer tunnel config. */
     tailscale: VoiceCallTailscaleConfigSchema,
 
     /** Tunnel configuration (unified ngrok/tailscale) */
@@ -324,23 +390,26 @@ export const VoiceCallConfigSchema = z
     /** Real-time audio streaming configuration */
     streaming: VoiceCallStreamingConfigSchema,
 
+    /** Realtime voice-to-voice configuration */
+    realtime: VoiceCallRealtimeConfigSchema,
+
     /** Public webhook URL override (if set, bypasses tunnel auto-detection) */
     publicUrl: z.string().url().optional(),
 
     /** Skip webhook signature verification (development only, NOT for production) */
     skipSignatureVerification: z.boolean().default(false),
 
-    /** STT configuration */
-    stt: SttConfigSchema,
-
     /** TTS override (deep-merges with core messages.tts) */
     tts: TtsConfigSchema,
 
     /** Store path for call logs */
     store: z.string().optional(),
 
-    /** Model for generating voice responses (e.g., "anthropic/claude-sonnet-4", "openai/gpt-4o") */
-    responseModel: z.string().default("openai/gpt-4o-mini"),
+    /** Agent ID to use for voice response generation. Defaults to "main". */
+    agentId: z.string().min(1).optional(),
+
+    /** Optional model override for generating voice responses. */
+    responseModel: z.string().optional(),
 
     /** System prompt for voice responses */
     responseSystemPrompt: z.string().optional(),
@@ -351,13 +420,15 @@ export const VoiceCallConfigSchema = z
   .strict();
 
 export type VoiceCallConfig = z.infer<typeof VoiceCallConfigSchema>;
-type DeepPartial<T> =
-  T extends Array<infer U>
+type DeepPartial<T> = T extends SecretInput
+  ? T
+  : T extends Array<infer U>
     ? DeepPartial<U>[]
     : T extends object
       ? { [K in keyof T]?: DeepPartial<T[K]> }
       : T;
 export type VoiceCallConfigInput = DeepPartial<VoiceCallConfig>;
+const TWILIO_AUTH_TOKEN_PATH = "plugins.entries.voice-call.config.twilio.authToken";
 
 // -----------------------------------------------------------------------------
 // Configuration Helpers
@@ -369,6 +440,29 @@ function cloneDefaultVoiceCallConfig(): VoiceCallConfig {
   return structuredClone(DEFAULT_VOICE_CALL_CONFIG);
 }
 
+function normalizeWebhookLikePath(pathname: string): string {
+  const trimmed = pathname.trim();
+  if (!trimmed) {
+    return "/";
+  }
+  const prefixed = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+  if (prefixed === "/") {
+    return prefixed;
+  }
+  return prefixed.endsWith("/") ? prefixed.slice(0, -1) : prefixed;
+}
+
+function defaultRealtimeStreamPathForServePath(servePath: string): string {
+  const normalized = normalizeWebhookLikePath(servePath);
+  if (normalized.endsWith("/webhook")) {
+    return `${normalized.slice(0, -"/webhook".length)}/stream/realtime`;
+  }
+  if (normalized === "/") {
+    return "/voice/stream/realtime";
+  }
+  return `${normalized}/stream/realtime`;
+}
+
 function normalizeVoiceCallTtsConfig(
   defaults: VoiceCallTtsConfig,
   overrides: DeepPartial<NonNullable<VoiceCallTtsConfig>> | undefined,
@@ -380,14 +474,50 @@ function normalizeVoiceCallTtsConfig(
   return TtsConfigSchema.parse(deepMergeDefined(defaults ?? {}, overrides ?? {}));
 }
 
+function sanitizeVoiceCallProviderConfigs(
+  value: Record<string, Record<string, unknown> | undefined> | undefined,
+): Record<string, Record<string, unknown>> {
+  if (!value) {
+    return {};
+  }
+  return Object.fromEntries(
+    Object.entries(value).filter(
+      (entry): entry is [string, Record<string, unknown>] => entry[1] !== undefined,
+    ),
+  );
+}
+
+export function resolveTwilioAuthToken(
+  config: Pick<VoiceCallConfig, "twilio">,
+): string | undefined {
+  return normalizeResolvedSecretInputString({
+    value: config.twilio?.authToken,
+    path: TWILIO_AUTH_TOKEN_PATH,
+  });
+}
+
 export function normalizeVoiceCallConfig(config: VoiceCallConfigInput): VoiceCallConfig {
   const defaults = cloneDefaultVoiceCallConfig();
+  const serve = { ...defaults.serve, ...config.serve };
+  const streamingProvider = config.streaming?.provider;
+  const streamingProviders = sanitizeVoiceCallProviderConfigs(
+    config.streaming?.providers ?? defaults.streaming.providers,
+  );
+  const realtimeProvider = config.realtime?.provider ?? defaults.realtime.provider;
+  const realtimeProviders = sanitizeVoiceCallProviderConfigs(
+    config.realtime?.providers ?? defaults.realtime.providers,
+  );
+  const realtimeFastContext = {
+    ...defaults.realtime.fastContext,
+    ...config.realtime?.fastContext,
+    sources: config.realtime?.fastContext?.sources ?? defaults.realtime.fastContext.sources,
+  };
   return {
     ...defaults,
     ...config,
     allowFrom: config.allowFrom ?? defaults.allowFrom,
     outbound: { ...defaults.outbound, ...config.outbound },
-    serve: { ...defaults.serve, ...config.serve },
+    serve,
     tailscale: { ...defaults.tailscale, ...config.tailscale },
     tunnel: { ...defaults.tunnel, ...config.tunnel },
     webhookSecurity: {
@@ -397,8 +527,24 @@ export function normalizeVoiceCallConfig(config: VoiceCallConfigInput): VoiceCal
       trustedProxyIPs:
         config.webhookSecurity?.trustedProxyIPs ?? defaults.webhookSecurity.trustedProxyIPs,
     },
-    streaming: { ...defaults.streaming, ...config.streaming },
-    stt: { ...defaults.stt, ...config.stt },
+    streaming: {
+      ...defaults.streaming,
+      ...config.streaming,
+      provider: streamingProvider,
+      providers: streamingProviders,
+    },
+    realtime: {
+      ...defaults.realtime,
+      ...config.realtime,
+      provider: realtimeProvider,
+      streamPath:
+        config.realtime?.streamPath ??
+        defaultRealtimeStreamPathForServePath(serve.path ?? defaults.serve.path),
+      tools:
+        (config.realtime?.tools as RealtimeToolConfig[] | undefined) ?? defaults.realtime.tools,
+      fastContext: realtimeFastContext,
+      providers: realtimeProviders,
+    },
     tts: normalizeVoiceCallTtsConfig(defaults.tts, config.tts),
   };
 }
@@ -420,6 +566,7 @@ export function resolveVoiceCallConfig(config: VoiceCallConfigInput): VoiceCallC
 
   // Twilio
   if (resolved.provider === "twilio") {
+    resolved.fromNumber = resolved.fromNumber ?? process.env.TWILIO_FROM_NUMBER;
     resolved.twilio = resolved.twilio ?? {};
     resolved.twilio.accountSid = resolved.twilio.accountSid ?? process.env.TWILIO_ACCOUNT_SID;
     resolved.twilio.authToken = resolved.twilio.authToken ?? process.env.TWILIO_AUTH_TOKEN;
@@ -474,7 +621,11 @@ export function validateProviderConfig(config: VoiceCallConfig): {
   }
 
   if (!config.fromNumber && config.provider !== "mock") {
-    errors.push("plugins.entries.voice-call.config.fromNumber is required");
+    errors.push(
+      config.provider === "twilio"
+        ? "plugins.entries.voice-call.config.fromNumber is required (or set TWILIO_FROM_NUMBER env)"
+        : "plugins.entries.voice-call.config.fromNumber is required",
+    );
   }
 
   if (config.provider === "telnyx") {
@@ -501,7 +652,7 @@ export function validateProviderConfig(config: VoiceCallConfig): {
         "plugins.entries.voice-call.config.twilio.accountSid is required (or set TWILIO_ACCOUNT_SID env)",
       );
     }
-    if (!config.twilio?.authToken) {
+    if (!hasConfiguredSecretInput(config.twilio?.authToken)) {
       errors.push(
         "plugins.entries.voice-call.config.twilio.authToken is required (or set TWILIO_AUTH_TOKEN env)",
       );
@@ -521,5 +672,23 @@ export function validateProviderConfig(config: VoiceCallConfig): {
     }
   }
 
+  if (config.realtime.enabled && config.inboundPolicy === "disabled") {
+    errors.push(
+      'plugins.entries.voice-call.config.inboundPolicy must not be "disabled" when realtime.enabled is true',
+    );
+  }
+
+  if (config.realtime.enabled && config.streaming.enabled) {
+    errors.push(
+      "plugins.entries.voice-call.config.realtime.enabled and plugins.entries.voice-call.config.streaming.enabled cannot both be true",
+    );
+  }
+
+  if (config.realtime.enabled && config.provider && config.provider !== "twilio") {
+    errors.push(
+      'plugins.entries.voice-call.config.provider must be "twilio" when realtime.enabled is true',
+    );
+  }
+
   return { valid: errors.length === 0, errors };
 }

package/src/core-bridge.ts

@@ -1,6 +1,4 @@
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import type { OpenClawPluginApi } from "../api.js";
 import type { VoiceCallTtsConfig } from "./config.js";
 
 export type CoreConfig = {
@@ -13,147 +11,4 @@ export type CoreConfig = {
   [key: string]: unknown;
 };
 
-type CoreAgentDeps = {
-  resolveAgentDir: (cfg: CoreConfig, agentId: string) => string;
-  resolveAgentWorkspaceDir: (cfg: CoreConfig, agentId: string) => string;
-  resolveAgentIdentity: (
-    cfg: CoreConfig,
-    agentId: string,
-  ) => { name?: string | null } | null | undefined;
-  resolveThinkingDefault: (params: {
-    cfg: CoreConfig;
-    provider?: string;
-    model?: string;
-  }) => string;
-  runEmbeddedPiAgent: (params: {
-    sessionId: string;
-    sessionKey?: string;
-    messageProvider?: string;
-    sessionFile: string;
-    workspaceDir: string;
-    config?: CoreConfig;
-    prompt: string;
-    provider?: string;
-    model?: string;
-    thinkLevel?: string;
-    verboseLevel?: string;
-    timeoutMs: number;
-    runId: string;
-    lane?: string;
-    extraSystemPrompt?: string;
-    agentDir?: string;
-  }) => Promise<{
-    payloads?: Array<{ text?: string; isError?: boolean }>;
-    meta?: { aborted?: boolean };
-  }>;
-  resolveAgentTimeoutMs: (opts: { cfg: CoreConfig }) => number;
-  ensureAgentWorkspace: (params?: { dir: string }) => Promise<void>;
-  resolveStorePath: (store?: string, opts?: { agentId?: string }) => string;
-  loadSessionStore: (storePath: string) => Record<string, unknown>;
-  saveSessionStore: (storePath: string, store: Record<string, unknown>) => Promise<void>;
-  resolveSessionFilePath: (
-    sessionId: string,
-    entry: unknown,
-    opts?: { agentId?: string },
-  ) => string;
-  DEFAULT_MODEL: string;
-  DEFAULT_PROVIDER: string;
-};
-
-let coreRootCache: string | null = null;
-let coreDepsPromise: Promise<CoreAgentDeps> | null = null;
-
-function findPackageRoot(startDir: string, name: string): string | null {
-  let dir = startDir;
-  for (;;) {
-    const pkgPath = path.join(dir, "package.json");
-    try {
-      if (fs.existsSync(pkgPath)) {
-        const raw = fs.readFileSync(pkgPath, "utf8");
-        const pkg = JSON.parse(raw) as { name?: string };
-        if (pkg.name === name) {
-          return dir;
-        }
-      }
-    } catch {
-      // ignore parse errors and keep walking
-    }
-    const parent = path.dirname(dir);
-    if (parent === dir) {
-      return null;
-    }
-    dir = parent;
-  }
-}
-
-function resolveOpenClawRoot(): string {
-  if (coreRootCache) {
-    return coreRootCache;
-  }
-  const override = process.env.OPENCLAW_ROOT?.trim();
-  if (override) {
-    coreRootCache = override;
-    return override;
-  }
-
-  const candidates = new Set<string>();
-  if (process.argv[1]) {
-    candidates.add(path.dirname(process.argv[1]));
-  }
-  candidates.add(process.cwd());
-  try {
-    const urlPath = fileURLToPath(import.meta.url);
-    candidates.add(path.dirname(urlPath));
-  } catch {
-    // ignore
-  }
-
-  for (const start of candidates) {
-    for (const name of ["openclaw"]) {
-      const found = findPackageRoot(start, name);
-      if (found) {
-        coreRootCache = found;
-        return found;
-      }
-    }
-  }
-
-  throw new Error("Unable to resolve core root. Set OPENCLAW_ROOT to the package root.");
-}
-
-async function importCoreExtensionAPI(): Promise<{
-  resolveAgentDir: CoreAgentDeps["resolveAgentDir"];
-  resolveAgentWorkspaceDir: CoreAgentDeps["resolveAgentWorkspaceDir"];
-  DEFAULT_MODEL: string;
-  DEFAULT_PROVIDER: string;
-  resolveAgentIdentity: CoreAgentDeps["resolveAgentIdentity"];
-  resolveThinkingDefault: CoreAgentDeps["resolveThinkingDefault"];
-  runEmbeddedPiAgent: CoreAgentDeps["runEmbeddedPiAgent"];
-  resolveAgentTimeoutMs: CoreAgentDeps["resolveAgentTimeoutMs"];
-  ensureAgentWorkspace: CoreAgentDeps["ensureAgentWorkspace"];
-  resolveStorePath: CoreAgentDeps["resolveStorePath"];
-  loadSessionStore: CoreAgentDeps["loadSessionStore"];
-  saveSessionStore: CoreAgentDeps["saveSessionStore"];
-  resolveSessionFilePath: CoreAgentDeps["resolveSessionFilePath"];
-}> {
-  // Do not import any other module. You can't touch this or you will be fired.
-  const distPath = path.join(resolveOpenClawRoot(), "dist", "extensionAPI.js");
-  if (!fs.existsSync(distPath)) {
-    throw new Error(
-      `Missing core module at ${distPath}. Run \`pnpm build\` or install the official package.`,
-    );
-  }
-  return await import(pathToFileURL(distPath).href);
-}
-
-export async function loadCoreAgentDeps(): Promise<CoreAgentDeps> {
-  if (coreDepsPromise) {
-    return coreDepsPromise;
-  }
-
-  coreDepsPromise = (async () => {
-    return await importCoreExtensionAPI();
-  })();
-
-  return coreDepsPromise;
-}
+export type CoreAgentDeps = OpenClawPluginApi["runtime"]["agent"];