refactor(plugin-sdk): add grouped host-hook facades

Eva (agent) · Eva (agent) · commit 564400622821 · 2026-05-10T17:55:12.000+07:00
diff --git a/docs/.generated/plugin-sdk-api-baseline.sha256 b/docs/.generated/plugin-sdk-api-baseline.sha256
@@ -1,2 +1,2 @@
-4d6c3407a896d12a453c5ba2069450db279e9cb9bed0722aa9e6f3deff69da8f  plugin-sdk-api-baseline.json
-33753fed10bd182a0314e4678e6d8d896c225a07fd5a2d6980ee7abd46640e7d  plugin-sdk-api-baseline.jsonl
+7cfa5421ebf3a7d9202ace45a2883bf132bb3ea827f48c169a4bdc3af584f3b0  plugin-sdk-api-baseline.json
+6a8dd879cddc41f722aa43cc4912b0cc67047435dfe782cfd2d73987cc9e9a92  plugin-sdk-api-baseline.jsonl
diff --git a/docs/plugins/sdk-overview.md b/docs/plugins/sdk-overview.md
@@ -146,6 +146,23 @@ plugins.
 | `api.registerSessionSchedulerJob(...)`                                   | Plugin-owned session scheduler job records with deterministic cleanup                                                             |
 | `api.sendSessionAttachment(...)`                                         | Bundled-only host-mediated file attachment delivery to the active direct-outbound session route                                   |
 
+Grouped aliases are also available for the host-hook-heavy parts of the SDK.
+They are additive aliases over the existing flat methods, not new runtime
+plumbing, so both styles remain valid:
+
+- `api.session.state.registerSessionExtension(...)`
+- `api.session.workflow.enqueueNextTurnInjection(...)`
+- `api.session.workflow.registerSessionSchedulerJob(...)`
+- `api.session.workflow.sendSessionAttachment(...)`
+- `api.session.workflow.scheduleSessionTurn(...)`
+- `api.session.workflow.unscheduleSessionTurnsByTag(...)`
+- `api.session.controls.registerSessionAction(...)`
+- `api.session.controls.registerControlUiDescriptor(...)`
+- `api.agent.events.registerAgentEventSubscription(...)`
+- `api.agent.events.emitAgentEvent(...)`
+- `api.runContext.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)`
+- `api.lifecycle.registerRuntimeLifecycle(...)`
+
 The contracts intentionally split authority:
 
 - External plugins can own session extensions, UI descriptors, commands, tool
diff --git a/src/plugin-sdk/plugin-test-api.ts b/src/plugin-sdk/plugin-test-api.ts
@@ -1,9 +1,10 @@
+import { attachPluginApiFacades } from "../plugins/api-facades.js";
 import type { OpenClawPluginApi } from "./plugin-runtime.js";
 
 export type TestPluginApiInput = Partial<OpenClawPluginApi>;
 
 export function createTestPluginApi(api: TestPluginApiInput = {}): OpenClawPluginApi {
-  return {
+  return attachPluginApiFacades({
     id: "test-plugin",
     name: "test-plugin",
     source: "test",
@@ -70,10 +71,6 @@ export function createTestPluginApi(api: TestPluginApiInput = {}): OpenClawPlugi
     sendSessionAttachment: async () => ({ ok: false, error: "test plugin api" }),
     scheduleSessionTurn: async () => undefined,
     unscheduleSessionTurnsByTag: async () => ({ removed: 0, failed: 0 }),
-    registerSessionAction() {},
-    sendSessionAttachment: async () => ({ ok: false, error: "test plugin api" }),
-    scheduleSessionTurn: async () => undefined,
-    unscheduleSessionTurnsByTag: async () => ({ removed: 0, failed: 0 }),
     registerMemoryCapability() {},
     registerMemoryPromptSection() {},
     registerMemoryPromptSupplement() {},
@@ -86,5 +83,5 @@ export function createTestPluginApi(api: TestPluginApiInput = {}): OpenClawPlugi
     },
     on() {},
     ...api,
-  };
+  });
 }
diff --git a/src/plugins/api-builder.ts b/src/plugins/api-builder.ts
@@ -1,4 +1,5 @@
 import type { OpenClawConfig } from "../config/types.openclaw.js";
+import { attachPluginApiFacades } from "./api-facades.js";
 import type { PluginRuntime } from "./runtime/types.js";
 import type { OpenClawPluginApi, PluginLogger } from "./types.js";
 
@@ -176,7 +177,7 @@ const noopOn: OpenClawPluginApi["on"] = () => {};
 export function buildPluginApi(params: BuildPluginApiParams): OpenClawPluginApi {
   const handlers = params.handlers ?? {};
   const registerCli = handlers.registerCli ?? noopRegisterCli;
-  return {
+  return attachPluginApiFacades({
     id: params.id,
     name: params.name,
     version: params.version,
@@ -260,9 +261,6 @@ export function buildPluginApi(params: BuildPluginApiParams): OpenClawPluginApi
     clearRunContext: handlers.clearRunContext ?? noopClearRunContext,
     registerSessionSchedulerJob:
       handlers.registerSessionSchedulerJob ?? noopRegisterSessionSchedulerJob,
-    scheduleSessionTurn: handlers.scheduleSessionTurn ?? noopScheduleSessionTurn,
-    unscheduleSessionTurnsByTag:
-      handlers.unscheduleSessionTurnsByTag ?? noopUnscheduleSessionTurnsByTag,
     registerSessionAction: handlers.registerSessionAction ?? noopRegisterSessionAction,
     sendSessionAttachment: handlers.sendSessionAttachment ?? noopSendSessionAttachment,
     scheduleSessionTurn: handlers.scheduleSessionTurn ?? noopScheduleSessionTurn,
@@ -283,5 +281,5 @@ export function buildPluginApi(params: BuildPluginApiParams): OpenClawPluginApi
       handlers.registerMemoryEmbeddingProvider ?? noopRegisterMemoryEmbeddingProvider,
     resolvePath: params.resolvePath,
     on: handlers.on ?? noopOn,
-  };
+  });
 }
diff --git a/src/plugins/api-facades.ts b/src/plugins/api-facades.ts
@@ -0,0 +1,36 @@
+import type { OpenClawPluginApi } from "./types.js";
+
+export function attachPluginApiFacades<T extends OpenClawPluginApi>(api: T): T {
+  api.session = {
+    state: {
+      registerSessionExtension: (...args) => api.registerSessionExtension(...args),
+    },
+    workflow: {
+      enqueueNextTurnInjection: (...args) => api.enqueueNextTurnInjection(...args),
+      registerSessionSchedulerJob: (...args) => api.registerSessionSchedulerJob(...args),
+      sendSessionAttachment: (...args) => api.sendSessionAttachment(...args),
+      scheduleSessionTurn: (...args) => api.scheduleSessionTurn(...args),
+      unscheduleSessionTurnsByTag: (...args) => api.unscheduleSessionTurnsByTag(...args),
+    },
+    controls: {
+      registerSessionAction: (...args) => api.registerSessionAction(...args),
+      registerControlUiDescriptor: (...args) => api.registerControlUiDescriptor(...args),
+    },
+  };
+  api.agent = {
+    events: {
+      registerAgentEventSubscription: (...args) =>
+        api.registerAgentEventSubscription(...args),
+      emitAgentEvent: (...args) => api.emitAgentEvent(...args),
+    },
+  };
+  api.runContext = {
+    setRunContext: (...args) => api.setRunContext(...args),
+    getRunContext: (...args) => api.getRunContext(...args),
+    clearRunContext: (...args) => api.clearRunContext(...args),
+  };
+  api.lifecycle = {
+    registerRuntimeLifecycle: (...args) => api.registerRuntimeLifecycle(...args),
+  };
+  return api;
+}
diff --git a/src/plugins/api-lifecycle.ts b/src/plugins/api-lifecycle.ts
@@ -0,0 +1,36 @@
+import type { OpenClawPluginApi } from "./types.js";
+
+type FunctionPropertyNames<T> = Extract<
+  {
+    [K in keyof T]-?: Exclude<T[K], undefined> extends (
+      ...args: unknown[]
+    ) => unknown
+      ? K
+      : never;
+  }[keyof T],
+  string
+>;
+
+export type PluginApiMethodName = FunctionPropertyNames<OpenClawPluginApi>;
+
+export type PluginApiLifecyclePolicy = {
+  phase: "registration" | "runtime";
+  lateCallable: boolean;
+};
+
+const PLUGIN_API_METHOD_POLICIES: Partial<Record<PluginApiMethodName, PluginApiLifecyclePolicy>> =
+  {
+    sendSessionAttachment: { phase: "runtime", lateCallable: true },
+    scheduleSessionTurn: { phase: "runtime", lateCallable: true },
+    unscheduleSessionTurnsByTag: { phase: "runtime", lateCallable: true },
+  };
+
+export function getPluginApiMethodLifecyclePolicy(
+  methodName: string,
+): PluginApiLifecyclePolicy | undefined {
+  return PLUGIN_API_METHOD_POLICIES[methodName as PluginApiMethodName];
+}
+
+export function isLateCallablePluginApiMethod(methodName: string): methodName is PluginApiMethodName {
+  return getPluginApiMethodLifecyclePolicy(methodName)?.lateCallable === true;
+}
diff --git a/src/plugins/captured-registration.ts b/src/plugins/captured-registration.ts
@@ -114,7 +114,6 @@ export function createCapturedPluginRegistration(params?: {
   const sessionSchedulerJobs: PluginSessionSchedulerJobRegistration[] = [];
   const sessionActions: PluginSessionActionRegistration[] = [];
   let capturedSessionTurnCount = 0;
-  const sessionActions: PluginSessionActionRegistration[] = [];
   const tools: AnyAgentTool[] = [];
   const modelCatalogProviders: UnifiedModelCatalogProviderPlugin[] = [];
   const pluginId = params?.id ?? "captured-plugin-registration";
diff --git a/src/plugins/contracts/run-context-lifecycle.contract.test.ts b/src/plugins/contracts/run-context-lifecycle.contract.test.ts
@@ -57,7 +57,7 @@ describe("plugin run context lifecycle", () => {
     setActivePluginRegistry(createEmptyPluginRegistry());
 
     expect(
-      capturedApi?.setRunContext({
+      capturedApi?.runContext?.setRunContext({
         runId: "stale-run",
         namespace: "state",
         value: { stale: true },
@@ -76,7 +76,7 @@ describe("plugin run context lifecycle", () => {
         patch: { runId: "stale-run", namespace: "state", value: { live: true } },
       }),
     ).toBe(true);
-    capturedApi?.clearRunContext({ runId: "stale-run", namespace: "state" });
+    capturedApi?.runContext?.clearRunContext({ runId: "stale-run", namespace: "state" });
     expect(
       getPluginRunContext({
         pluginId: "stale-run-context-plugin",
@@ -104,16 +104,16 @@ describe("plugin run context lifecycle", () => {
     setActivePluginRegistry(registry.registry);
 
     expect(
-      capturedApi?.setRunContext({
+      capturedApi?.runContext?.setRunContext({
         runId: "restored-run",
         namespace: "state",
         value: { restored: true },
       }),
     ).toBe(true);
     expect(
-      getPluginRunContext({
-        pluginId: "restored-run-context-plugin",
-        get: { runId: "restored-run", namespace: "state" },
+      capturedApi?.runContext?.getRunContext({
+        runId: "restored-run",
+        namespace: "state",
       }),
     ).toEqual({ restored: true });
   });
diff --git a/src/plugins/contracts/session-actions.contract.test.ts b/src/plugins/contracts/session-actions.contract.test.ts
@@ -801,7 +801,7 @@ describe("plugin session actions", () => {
 
     try {
       expect(
-        bundledApi?.emitAgentEvent({
+        bundledApi?.agent?.events.emitAgentEvent({
           runId: "run-emit",
           sessionKey: " agent:main:main ",
           stream: "approval",
diff --git a/src/plugins/loader.test.ts b/src/plugins/loader.test.ts
@@ -1476,6 +1476,7 @@ describe("loadOpenClawPlugins", () => {
         "keeps sendSessionAttachment callable after register closes while blocking registration-only APIs",
       run: () => {
         const registerGatewayMethod = vi.fn();
+        const registerSessionExtension = vi.fn();
         const sendSessionAttachment = vi.fn(async () => ({
           ok: true as const,
           channel: "proofchat",
@@ -1498,6 +1499,7 @@ describe("loadOpenClawPlugins", () => {
           resolvePath: (input) => input,
           handlers: {
             registerGatewayMethod,
+            registerSessionExtension,
             sendSessionAttachment,
           },
         });
@@ -1521,14 +1523,23 @@ describe("loadOpenClawPlugins", () => {
           text: "attachment ready",
         };
         const lateResult = capturedApi?.sendSessionAttachment(attachmentParams);
+        const lateWorkflowResult = capturedApi?.session?.workflow.sendSessionAttachment(
+          attachmentParams,
+        );
+        capturedApi?.session?.state.registerSessionExtension({
+          namespace: "late",
+          description: "late extension should stay blocked",
+        });
 
         expect(lateResult).toBe(sendSessionAttachment.mock.results[0]?.value);
+        expect(lateWorkflowResult).toBe(sendSessionAttachment.mock.results[1]?.value);
         expect(sendSessionAttachment).toHaveBeenCalledWith({
           sessionKey: "agent:main:main",
           files: [{ path: "./proof-report.txt" }],
           text: "attachment ready",
         });
-        expect(sendSessionAttachment).toHaveBeenCalledTimes(1);
+        expect(sendSessionAttachment).toHaveBeenCalledTimes(2);
+        expect(registerSessionExtension).not.toHaveBeenCalled();
       },
     },
     {
diff --git a/src/plugins/loader.ts b/src/plugins/loader.ts
@@ -26,6 +26,8 @@ import {
 import { resolveUserPath } from "../utils.js";
 import { resolvePluginActivationSourceConfig } from "./activation-source-config.js";
 import { buildPluginApi } from "./api-builder.js";
+import { attachPluginApiFacades } from "./api-facades.js";
+import { isLateCallablePluginApiMethod } from "./api-lifecycle.js";
 import { inspectBundleMcpRuntimeSupport } from "./bundle-mcp.js";
 import {
   clearPluginCommands,
@@ -448,39 +450,29 @@ function createGuardedPluginRegistrationApi(api: OpenClawPluginApi): {
   close: () => void;
 } {
   let closed = false;
-  type LateCallablePluginApiMethod = keyof Pick<
-    OpenClawPluginApi,
-    "sendSessionAttachment" | "scheduleSessionTurn" | "unscheduleSessionTurnsByTag"
-  >;
-  const lateCallableMethods = new Set<LateCallablePluginApiMethod>([
-    "sendSessionAttachment",
-    "scheduleSessionTurn",
-    "unscheduleSessionTurnsByTag",
-  ]);
-  return {
-    api: new Proxy(api, {
+  const guardedApi = attachPluginApiFacades(
+    new Proxy(api, {
       get(target, prop, receiver) {
         const value = Reflect.get(target, prop, receiver);
         if (typeof value !== "function") {
           return value;
         }
-        if (
-          typeof prop === "string" &&
-          lateCallableMethods.has(prop as LateCallablePluginApiMethod)
-        ) {
+        if (typeof prop === "string" && isLateCallablePluginApiMethod(prop)) {
           return (...args: unknown[]) => Reflect.apply(value, target, args);
         }
         return (...args: unknown[]) => {
           const isLateCallableMethod =
-            typeof prop === "string" &&
-            lateCallableMethods.has(prop as Extract<keyof OpenClawPluginApi, string>);
+            typeof prop === "string" && isLateCallablePluginApiMethod(prop);
           if (closed && !isLateCallableMethod) {
             return undefined;
           }
           return Reflect.apply(value, target, args);
         };
       },
     }),
+  );
+  return {
+    api: guardedApi,
     close: () => {
       closed = true;
     },
diff --git a/src/plugins/types.ts b/src/plugins/types.ts
@@ -2449,6 +2449,60 @@ export type PluginSetupAutoEnableProbe = (
   ctx: PluginSetupAutoEnableContext,
 ) => string | string[] | null | undefined;
 
+export type OpenClawPluginSessionStateApi = {
+  registerSessionExtension: (extension: PluginSessionExtensionRegistration) => void;
+};
+
+export type OpenClawPluginSessionWorkflowApi = {
+  enqueueNextTurnInjection: (
+    injection: PluginNextTurnInjection,
+  ) => Promise<PluginNextTurnInjectionEnqueueResult>;
+  registerSessionSchedulerJob: (
+    job: PluginSessionSchedulerJobRegistration,
+  ) => PluginSessionSchedulerJobHandle | undefined;
+  sendSessionAttachment: (
+    params: PluginSessionAttachmentParams,
+  ) => Promise<PluginSessionAttachmentResult>;
+  scheduleSessionTurn: (
+    params: PluginSessionTurnScheduleParams,
+  ) => Promise<PluginSessionSchedulerJobHandle | undefined>;
+  unscheduleSessionTurnsByTag: (
+    params: PluginSessionTurnUnscheduleByTagParams,
+  ) => Promise<PluginSessionTurnUnscheduleByTagResult>;
+};
+
+export type OpenClawPluginSessionControlsApi = {
+  registerSessionAction: (action: PluginSessionActionRegistration) => void;
+  registerControlUiDescriptor: (descriptor: PluginControlUiDescriptor) => void;
+};
+
+export type OpenClawPluginSessionApi = {
+  state: OpenClawPluginSessionStateApi;
+  workflow: OpenClawPluginSessionWorkflowApi;
+  controls: OpenClawPluginSessionControlsApi;
+};
+
+export type OpenClawPluginAgentEventsApi = {
+  registerAgentEventSubscription: (
+    subscription: PluginAgentEventSubscriptionRegistration,
+  ) => void;
+  emitAgentEvent: (params: PluginAgentEventEmitParams) => PluginAgentEventEmitResult;
+};
+
+export type OpenClawPluginAgentApi = {
+  events: OpenClawPluginAgentEventsApi;
+};
+
+export type OpenClawPluginRunContextApi = {
+  setRunContext: (patch: PluginRunContextPatch) => boolean;
+  getRunContext: (params: PluginRunContextGetParams) => PluginJsonValue | undefined;
+  clearRunContext: (params: { runId: string; namespace?: string }) => void;
+};
+
+export type OpenClawPluginLifecycleApi = {
+  registerRuntimeLifecycle: (lifecycle: PluginRuntimeLifecycleRegistration) => void;
+};
+
 /** Main registration API injected into native plugin entry files. */
 export type OpenClawPluginApi = {
   id: string;
@@ -2468,6 +2522,17 @@ export type OpenClawPluginApi = {
    */
   runtime: PluginRuntime;
   logger: PluginLogger;
+  /**
+   * Additive grouped aliases over the existing flat session-related plugin API.
+   * Flat methods remain supported.
+   */
+  session?: OpenClawPluginSessionApi;
+  /** Additive grouped aliases for agent-event workflow seams. */
+  agent?: OpenClawPluginAgentApi;
+  /** Additive grouped aliases for run-scoped plugin scratch state. */
+  runContext?: OpenClawPluginRunContextApi;
+  /** Additive grouped aliases for plugin-owned lifecycle cleanup hooks. */
+  lifecycle?: OpenClawPluginLifecycleApi;
   registerTool: (
     tool: AnyAgentTool | OpenClawPluginToolFactory,
     opts?: OpenClawPluginToolOptions,
