P1: Define SDK-facing Gateway RPC tools.invoke

[BunsDev]

Goal

Define and eventually implement an SDK-facing Gateway RPC for generic tool invocation.

There is currently an HTTP /tools/invoke path, but the app SDK wants a clean Gateway RPC method with the same policy and approval semantics.

Proposed method

tools.invoke

type ToolsInvokeParams = {
  name: string;
  args?: Record<string, unknown>;
  sessionKey?: string;
  agentId?: string;
  confirm?: boolean;
  idempotencyKey?: string;
};

Acceptance criteria

• Runs through the normal Gateway tool policy pipeline.
• Preserves plugin confirmation / approval semantics.
• Supports session/agent scoping.
• Returns typed refusal/approval-needed state.
• Has tests for interactive refusal without confirmation.

References

• https://github.com/OpenCoven/open-meow-sdk/blob/main/docs/rpc-contract-proposals.md#toolsinvoke
• https://github.com/OpenCoven/open-meow-sdk/blob/main/docs/gateway-rpc-gap-map.md

[BunsDev]

Dogfood update from 2026-05-02:

Desktop-use bridge status is mixed:

What works:

• Direct HTTP POST /tools/invoke can invoke desktop_use successfully with shared-secret Gateway auth.
• desktop_use doctor returned success.
• Adapter/backend summary from the successful probe:
  • adapter: coven-desktop-use
  • platform: macos
  • backend: peekaboo
  • permission doctor exited successfully

What does not work yet:

• SDK-facing JSON-RPC oc.tools.invoke("desktop_use", ...) failed against the live installed Gateway with unknown method: tools.invoke.
• oc.tools.list() returned no catalog entries in that live path.

Auth/config note:

• The local shared-secret credentials appear inconsistent across Gateway surfaces. Password-style shared-secret auth worked for HTTP /tools/invoke; token-style auth did not. No secret values were exposed in the dogfood evidence.

Assessment:

• Keep this issue open.
• Next fix should align the live Gateway SDK/RPC tool invocation path with the working HTTP /tools/invoke path, then make OpenMeow choose the credential mode that works consistently for HTTP tool calls.