| import { asOptionalRecord } from "@openclaw/normalization-core/record-coerce"; |
| import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce"; |
| import type { TObject } from "typebox"; |
| import { ErrorCodes, errorShape } from "../../packages/gateway-protocol/src/schema/error-codes.js"; |
| import { |
| readNonNegativeIntegerParam, |
| readPositiveIntegerParam, |
| jsonResult, |
| } from "../agents/tools/common.js"; |
| import { callGatewayFromCli } from "../cli/gateway-rpc.js"; |
| import type { GatewayRequestHandlerOptions } from "../gateway/server-methods/types.js"; |
| import { formatErrorMessage } from "../infra/errors.js"; |
| import type { OpenClawPluginApi } from "../plugins/plugin-api.types.js"; |
| import type { OpenClawPluginConfigSchema } from "../plugins/plugin-config-schema.types.js"; |
| import type { OpenClawPluginNodeInvokePolicy } from "../plugins/plugin-registration.types.js"; |
| import { parseAgentSessionKey } from "../sessions/session-key-utils.js"; |
| import type { MeetingPluginConfig as SharedMeetingPluginConfig } from "./plugin-config.js"; |
| import type { MeetingPluginJoinRequest } from "./session-types.js"; |
| import { |
| createMeetingTranscriptSourceProvider, |
| type MeetingTranscriptSourceRuntime, |
| } from "./transcripts-bridge.js"; |
|
|
| type MeetingToolAction = "join" | "leave" | "status" | "transcript" | "speak"; |
| type MeetingMode = "agent" | "bidi" | "transcribe"; |
| type MeetingTransport = "chrome" | "chrome-node"; |
|
|
| export type MeetingJoinRequest = MeetingPluginJoinRequest<MeetingTransport, MeetingMode>; |
|
|
| export type MeetingPluginConfig = Pick<SharedMeetingPluginConfig, "enabled" | "chromeNode">; |
|
|
| export type MeetingPluginRuntime<Request extends MeetingJoinRequest> = |
| Partial<MeetingTranscriptSourceRuntime> & { |
| join(request: Request): Promise<unknown>; |
| leave(sessionId: string): Promise<unknown>; |
| ownsSession(agentId: string, sessionId: string): boolean; |
| setupStatus(params: { mode?: MeetingMode; transport?: MeetingTransport }): Promise<unknown>; |
| speak(sessionId: string, message?: string): Promise<unknown>; |
| status(sessionId?: string): Promise<unknown>; |
| statusForAgent(agentId: string, sessionId?: string): Promise<unknown>; |
| testListen(request: Request): Promise<unknown>; |
| testSpeech(request: Request): Promise<unknown>; |
| transcript(sessionId: string, options: { sinceIndex?: number }): Promise<unknown>; |
| }; |
|
|
| export type MeetingPluginEntryOptions< |
| Config extends MeetingPluginConfig, |
| Request extends MeetingJoinRequest, |
| Runtime extends MeetingPluginRuntime<Request>, |
| > = { |
| cap: string; |
| configSchema: OpenClawPluginConfigSchema & { parse(value: unknown): Config }; |
| createNodePolicy(config: Config): OpenClawPluginNodeInvokePolicy; |
| createRuntime(params: { api: OpenClawPluginApi; config: Config }): Runtime; |
| description: string; |
| disabledMessage: string; |
| gatewayMethodPrefix: string; |
| id: string; |
| invalidRequest(message: string): Error; |
| isInvalidRequest(error: unknown): boolean; |
| name: string; |
| nodeCommand: string; |
| nodeHandler(paramsJSON?: string | null): Promise<string>; |
| normalizeRequesterSessionKey(value: unknown, trustedOwner: boolean): string | undefined; |
| normalizeToolAgentId(agentId: string | undefined): string | undefined; |
| normalizeUrl(url: string): string; |
| registerCli(api: OpenClawPluginApi, config: Config): void; |
| registerNodeWhen(config: Config): boolean; |
| resolveGatewayTimeoutMs(config: Config): number; |
| resolveToolRuntime( |
| api: OpenClawPluginApi, |
| agentId: string | undefined, |
| ): Promise<OpenClawPluginApi["runtime"] | undefined>; |
| toolDescription: string; |
| toolLabel: string; |
| toolName: string; |
| toolParameters: TObject; |
| transcriptSource?: { |
| id: string; |
| aliases?: readonly string[]; |
| name: string; |
| }; |
| unknownActionMessage: string; |
| }; |
|
|
| function readErrorDetails(error: unknown): unknown { |
| return error && typeof error === "object" && "details" in error |
| ? (error as { details?: unknown }).details |
| : undefined; |
| } |
|
|
| export function createMeetingPluginEntryOptions< |
| Config extends MeetingPluginConfig, |
| Request extends MeetingJoinRequest, |
| Runtime extends MeetingPluginRuntime<Request>, |
| >(options: MeetingPluginEntryOptions<Config, Request, Runtime>) { |
| const invalidRequest = (message: string): never => { |
| throw options.invalidRequest(message); |
| }; |
| const normalizeTransport = (value: unknown): MeetingTransport | undefined => { |
| if (value === undefined) { |
| return undefined; |
| } |
| if (value === "chrome" || value === "chrome-node") { |
| return value; |
| } |
| return invalidRequest("transport must be chrome or chrome-node"); |
| }; |
| const normalizeMode = (value: unknown): MeetingMode | undefined => { |
| if (value === undefined) { |
| return undefined; |
| } |
| if (value === "agent" || value === "bidi" || value === "transcribe") { |
| return value; |
| } |
| return invalidRequest("mode must be agent, bidi, or transcribe"); |
| }; |
| const requireString = (value: unknown, name: string): string => { |
| const normalized = normalizeOptionalString(value); |
| return normalized ?? invalidRequest(`${name} required`); |
| }; |
| const readSinceIndex = (raw: Record<string, unknown>): number | undefined => { |
| try { |
| return readNonNegativeIntegerParam(raw, "sinceIndex"); |
| } catch (error) { |
| return invalidRequest(formatErrorMessage(error)); |
| } |
| }; |
| const keepTrustedToolContext = ( |
| raw: Record<string, unknown>, |
| client: GatewayRequestHandlerOptions["client"], |
| ): Record<string, unknown> => { |
| const { agentId: rawAgentId, requesterSessionKey: rawRequesterSessionKey, ...rest } = raw; |
| const trustedOwner = client?.internal?.pluginRuntimeOwnerId === options.id; |
| const agentId = trustedOwner ? normalizeOptionalString(rawAgentId) : undefined; |
| const requesterSessionKey = options.normalizeRequesterSessionKey( |
| rawRequesterSessionKey, |
| trustedOwner, |
| ); |
| return { |
| ...rest, |
| ...(agentId ? { agentId } : {}), |
| ...(requesterSessionKey ? { requesterSessionKey } : {}), |
| }; |
| }; |
| const trustedToolAgentId = ( |
| raw: Record<string, unknown>, |
| client: GatewayRequestHandlerOptions["client"], |
| ) => normalizeOptionalString(keepTrustedToolContext(raw, client).agentId); |
| const joinRequest = ( |
| raw: Record<string, unknown>, |
| joinOptions?: { allowTimeout?: boolean }, |
| ): Request => { |
| if (!joinOptions?.allowTimeout && raw.timeoutMs !== undefined) { |
| return invalidRequest("timeoutMs is supported only by testSpeech or testListen"); |
| } |
| try { |
| return { |
| url: options.normalizeUrl(requireString(raw.url, "url")), |
| transport: normalizeTransport(raw.transport), |
| mode: normalizeMode(raw.mode), |
| message: normalizeOptionalString(raw.message), |
| requesterSessionKey: normalizeOptionalString(raw.requesterSessionKey), |
| agentId: normalizeOptionalString(raw.agentId), |
| timeoutMs: readPositiveIntegerParam(raw, "timeoutMs"), |
| } as Request; |
| } catch (error) { |
| if (options.isInvalidRequest(error)) { |
| throw error; |
| } |
| return invalidRequest(formatErrorMessage(error)); |
| } |
| }; |
| const gatewayMethod = (action: MeetingToolAction) => `${options.gatewayMethodPrefix}.${action}`; |
| const callGatewayFromTool = async (params: { |
| action: MeetingToolAction; |
| config: Config; |
| raw: Record<string, unknown>; |
| runtime?: OpenClawPluginApi["runtime"]; |
| }) => { |
| try { |
| const timeoutMs = options.resolveGatewayTimeoutMs(params.config); |
| if (params.runtime) { |
| return await params.runtime.gateway.request(gatewayMethod(params.action), params.raw, { |
| timeoutMs, |
| scopes: ["operator.admin"], |
| }); |
| } |
| return await callGatewayFromCli( |
| gatewayMethod(params.action), |
| { json: true, timeout: String(timeoutMs) }, |
| params.raw, |
| { progress: false, scopes: ["operator.admin"] }, |
| ); |
| } catch (error) { |
| const details = readErrorDetails(error); |
| if (details && typeof details === "object") { |
| return details; |
| } |
| throw error; |
| } |
| }; |
|
|
| return { |
| id: options.id, |
| name: options.name, |
| description: options.description, |
| configSchema: options.configSchema, |
| register(api: OpenClawPluginApi) { |
| const config = options.configSchema.parse(api.pluginConfig) as Config; |
| let runtime: Runtime | undefined; |
| const ensureRuntime = async () => { |
| if (!config.enabled) { |
| throw new Error(options.disabledMessage); |
| } |
| runtime ??= options.createRuntime({ api, config }); |
| return runtime; |
| }; |
| if (options.transcriptSource) { |
| api.registerTranscriptSourceProvider( |
| createMeetingTranscriptSourceProvider({ |
| ...options.transcriptSource, |
| runtime: async () => { |
| const resolved = await ensureRuntime(); |
| if (!resolved.startTranscriptSource || !resolved.stopTranscriptSource) { |
| throw new Error(`${options.name} transcript source runtime is unavailable`); |
| } |
| return resolved as MeetingTranscriptSourceRuntime; |
| }, |
| }), |
| ); |
| } |
| const sendError = ( |
| respond: GatewayRequestHandlerOptions["respond"], |
| error: unknown, |
| code: Parameters<typeof errorShape>[0] = ErrorCodes.UNAVAILABLE, |
| ) => { |
| const payload = { error: formatErrorMessage(error) }; |
| respond(false, payload, errorShape(code, payload.error, { details: payload })); |
| }; |
| const sendRequestError = (respond: GatewayRequestHandlerOptions["respond"], error: unknown) => |
| sendError( |
| respond, |
| error, |
| options.isInvalidRequest(error) ? ErrorCodes.INVALID_REQUEST : ErrorCodes.UNAVAILABLE, |
| ); |
|
|
| api.registerGatewayMethod( |
| `${options.gatewayMethodPrefix}.join`, |
| async ({ params, client, respond }: GatewayRequestHandlerOptions) => { |
| try { |
| const raw = keepTrustedToolContext(asOptionalRecord(params) ?? {}, client); |
| respond(true, await (await ensureRuntime()).join(joinRequest(raw))); |
| } catch (error) { |
| sendRequestError(respond, error); |
| } |
| }, |
| ); |
| api.registerGatewayMethod( |
| `${options.gatewayMethodPrefix}.leave`, |
| async ({ params, client, respond }: GatewayRequestHandlerOptions) => { |
| try { |
| const raw = asOptionalRecord(params) ?? {}; |
| const agentId = trustedToolAgentId(raw, client); |
| const sessionId = requireString(raw.sessionId, "sessionId"); |
| const rt = await ensureRuntime(); |
| respond( |
| true, |
| agentId && !rt.ownsSession(agentId, sessionId) |
| ? { found: false } |
| : await rt.leave(sessionId), |
| ); |
| } catch (error) { |
| sendRequestError(respond, error); |
| } |
| }, |
| ); |
| api.registerGatewayMethod( |
| `${options.gatewayMethodPrefix}.status`, |
| async ({ params, client, respond }: GatewayRequestHandlerOptions) => { |
| try { |
| const raw = asOptionalRecord(params) ?? {}; |
| const agentId = trustedToolAgentId(raw, client); |
| const rt = await ensureRuntime(); |
| respond( |
| true, |
| agentId |
| ? await rt.statusForAgent(agentId, normalizeOptionalString(raw.sessionId)) |
| : await rt.status(normalizeOptionalString(raw.sessionId)), |
| ); |
| } catch (error) { |
| sendRequestError(respond, error); |
| } |
| }, |
| ); |
| api.registerGatewayMethod( |
| `${options.gatewayMethodPrefix}.transcript`, |
| async ({ params, client, respond }: GatewayRequestHandlerOptions) => { |
| try { |
| const raw = asOptionalRecord(params) ?? {}; |
| const sessionId = requireString(raw.sessionId, "sessionId"); |
| const sinceIndex = readSinceIndex(raw); |
| const agentId = trustedToolAgentId(raw, client); |
| const rt = await ensureRuntime(); |
| respond( |
| true, |
| agentId && !rt.ownsSession(agentId, sessionId) |
| ? { found: false } |
| : await rt.transcript(sessionId, sinceIndex === undefined ? {} : { sinceIndex }), |
| ); |
| } catch (error) { |
| sendRequestError(respond, error); |
| } |
| }, |
| ); |
| api.registerGatewayMethod( |
| `${options.gatewayMethodPrefix}.speak`, |
| async ({ params, client, respond }: GatewayRequestHandlerOptions) => { |
| try { |
| const raw = asOptionalRecord(params) ?? {}; |
| const sessionId = requireString(raw.sessionId, "sessionId"); |
| const agentId = trustedToolAgentId(raw, client); |
| const rt = await ensureRuntime(); |
| respond( |
| true, |
| agentId && !rt.ownsSession(agentId, sessionId) |
| ? { found: false, spoken: false } |
| : await rt.speak(sessionId, normalizeOptionalString(raw.message)), |
| ); |
| } catch (error) { |
| sendRequestError(respond, error); |
| } |
| }, |
| ); |
| api.registerGatewayMethod( |
| `${options.gatewayMethodPrefix}.setup`, |
| async ({ params, respond }: GatewayRequestHandlerOptions) => { |
| try { |
| respond( |
| true, |
| await ( |
| await ensureRuntime() |
| ).setupStatus({ |
| mode: normalizeMode(params?.mode), |
| transport: normalizeTransport(params?.transport), |
| }), |
| ); |
| } catch (error) { |
| sendRequestError(respond, error); |
| } |
| }, |
| ); |
| for (const [method, run] of [ |
| [ |
| `${options.gatewayMethodPrefix}.testSpeech`, |
| (rt: Runtime, raw: Record<string, unknown>) => |
| rt.testSpeech(joinRequest(raw, { allowTimeout: true })), |
| ], |
| [ |
| `${options.gatewayMethodPrefix}.testListen`, |
| (rt: Runtime, raw: Record<string, unknown>) => |
| rt.testListen(joinRequest(raw, { allowTimeout: true })), |
| ], |
| ] as const) { |
| api.registerGatewayMethod( |
| method, |
| async ({ params, client, respond }: GatewayRequestHandlerOptions) => { |
| try { |
| const raw = keepTrustedToolContext(asOptionalRecord(params) ?? {}, client); |
| respond(true, await run(await ensureRuntime(), raw)); |
| } catch (error) { |
| sendRequestError(respond, error); |
| } |
| }, |
| ); |
| } |
| api.registerTool( |
| (toolContext) => ({ |
| name: options.toolName, |
| label: options.toolLabel, |
| description: options.toolDescription, |
| parameters: options.toolParameters, |
| async execute(_toolCallId, params) { |
| const raw = asOptionalRecord(params) ?? {}; |
| const action = raw.action as MeetingToolAction; |
| const requesterSessionKey = normalizeOptionalString(toolContext.sessionKey); |
| const contextAgentId = |
| toolContext.agentId ?? parseAgentSessionKey(requesterSessionKey)?.agentId; |
| const agentId = options.normalizeToolAgentId(contextAgentId); |
| try { |
| if (!(["join", "leave", "status", "transcript", "speak"] as const).includes(action)) { |
| throw new Error(options.unknownActionMessage); |
| } |
| const runtimeForTool = await options.resolveToolRuntime(api, agentId); |
| return jsonResult( |
| await callGatewayFromTool({ |
| action, |
| config, |
| raw: { |
| ...raw, |
| ...(requesterSessionKey ? { requesterSessionKey } : {}), |
| ...(runtimeForTool && agentId ? { agentId } : {}), |
| }, |
| runtime: runtimeForTool, |
| }), |
| ); |
| } catch (error) { |
| return jsonResult({ error: formatErrorMessage(error) }); |
| } |
| }, |
| }), |
| { name: options.toolName }, |
| ); |
| if (options.registerNodeWhen(config)) { |
| api.registerNodeHostCommand({ |
| command: options.nodeCommand, |
| cap: options.cap, |
| dangerous: true, |
| handle: (paramsJSON) => options.nodeHandler(paramsJSON), |
| }); |
| api.registerNodeInvokePolicy(options.createNodePolicy(config)); |
| } |
| options.registerCli(api, config); |
| }, |
| }; |
| } |
|
|
