fix(sdk): require session key for effective tools

packages/sdk/src/client.ts

@@ -29,6 +29,7 @@ import type {
   TasksGetResult,
   TasksListParams,
   TasksListResult,
+  ToolsEffectiveParams,
   ToolInvokeParams,
   ToolInvokeResult,
 } from "./types.js";
@@ -238,6 +239,18 @@ function requireArtifactQueryScope(api: string, params: unknown): ArtifactQuery
   return params;
 }
 
+function hasToolsEffectiveSessionKey(params: unknown): params is ToolsEffectiveParams {
+  const record = asRecord(params);
+  return typeof record.sessionKey === "string" && record.sessionKey.trim().length > 0;
+}
+
+function requireToolsEffectiveSessionKey(params: unknown): ToolsEffectiveParams {
+  if (!hasToolsEffectiveSessionKey(params)) {
+    throw new Error("oc.tools.effective requires sessionKey");
+  }
+  return params;
+}
+
 function readChatProjection(event: OpenClawEvent): ChatProjection | undefined {
   const raw = event.raw;
   if (event.type !== "raw" || raw?.event !== "chat") {
@@ -861,8 +874,8 @@ export class ToolsNamespace extends RpcNamespace {
     return await this.call("catalog", params === undefined ? {} : params);
   }
 
-  async effective(params?: unknown): Promise<unknown> {
-    return await this.call("effective", params);
+  async effective(params: ToolsEffectiveParams): Promise<unknown> {
+    return await this.call("effective", requireToolsEffectiveSessionKey(params));
   }
 
   async invoke(name: string, params?: ToolInvokeParams): Promise<ToolInvokeResult> {

packages/sdk/src/index.test.ts

@@ -739,6 +739,23 @@ describe("OpenClaw SDK", () => {
     ]);
   });
 
+  it("rejects tools.effective without a session key before RPC", async () => {
+    type EffectiveMethod = (this: unknown, params?: unknown) => Promise<unknown>;
+    const transport = new FakeTransport({
+      "tools.effective": { tools: [] },
+    });
+    const oc = new OpenClaw({ transport });
+
+    await expect((oc.tools.effective as unknown as EffectiveMethod).call(oc.tools)).rejects.toThrow(
+      "oc.tools.effective requires sessionKey",
+    );
+    await expect(
+      (oc.tools.effective as unknown as EffectiveMethod).call(oc.tools, {}),
+    ).rejects.toThrow("oc.tools.effective requires sessionKey");
+
+    expect(transport.calls).toEqual([]);
+  });
+
   it("keeps close terminal when it races a pending connect", async () => {
     const transport = new DelayedConnectTransport({
       "agents.list": { agents: [] },

packages/sdk/src/index.ts

@@ -56,6 +56,7 @@ export type {
   TasksGetResult,
   TasksListParams,
   TasksListResult,
+  ToolsEffectiveParams,
   ToolInvokeParams,
   ToolInvokeResult,
   WorkspaceSelection,

packages/sdk/src/types.ts

@@ -192,6 +192,11 @@ export type SDKError = {
 };
 
 /** Parameters for direct tool invocation through the SDK. */
+export type ToolsEffectiveParams = {
+  sessionKey: string;
+  agentId?: string;
+};
+
 export type ToolInvokeParams = {
   args?: JsonObject;
   sessionKey?: string;