From bbb41289c22455ab7340dcab7fee48b92688b0e3 Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Tue, 4 Aug 2026 03:30:26 +0800
Subject: [PATCH] test(qa): register external app SDK proof (#118829)

---
 .../app-sdk-gateway-conversations.yaml        | 34 +++++++++++++++++++
 .../runtime/app-sdk-package-entrypoints.yaml  | 25 ++++++++++++++
 .../runtime/app-sdk-unsupported-calls.yaml    | 24 +++++++++++++
 3 files changed, 83 insertions(+)
 create mode 100644 qa/scenarios/runtime/app-sdk-gateway-conversations.yaml
 create mode 100644 qa/scenarios/runtime/app-sdk-package-entrypoints.yaml
 create mode 100644 qa/scenarios/runtime/app-sdk-unsupported-calls.yaml

diff --git a/qa/scenarios/runtime/app-sdk-gateway-conversations.yaml b/qa/scenarios/runtime/app-sdk-gateway-conversations.yaml
new file mode 100644
index 000000000000..803544e6d90b
--- /dev/null
+++ b/qa/scenarios/runtime/app-sdk-gateway-conversations.yaml
@@ -0,0 +1,34 @@
+title: Source-internal App SDK preview Gateway conversation evidence
+
+scenario:
+  id: app-sdk-gateway-conversations
+  surface: app-sdk
+  coverage:
+    primary:
+      - app-sdk.namespace-layout
+      - app-sdk.gateway-connect
+      - app-sdk.url-and-token-config
+      - app-sdk.agent-handles
+      - app-sdk.agent-runs
+      - app-sdk.session-creation
+      - app-sdk.session-send
+      - app-sdk.session-controls
+      - app-sdk.toolspace
+      - app-sdk.tasks
+  objective: Exercise the source-internal App SDK preview across isolated Gateway WebSocket connections, conversation handles, and the supported resource namespaces without treating the private package as published.
+  successCriteria:
+    - Explicit Gateway URLs and tokens complete the WebSocket challenge and connection handshake.
+    - Agent handles start runs, wait for completion, and cancel through Gateway RPC.
+    - Session helpers create, resolve, send, abort, patch, and compact reusable conversations.
+    - Agent, tool, and task namespaces issue the expected Gateway methods and return SDK-level results.
+  docsRefs:
+    - docs/gateway/external-apps.md
+    - docs/gateway/protocol.md
+  codeRefs:
+    - packages/sdk/src/client.ts
+    - packages/sdk/src/transport.ts
+    - packages/sdk/src/index.e2e.test.ts
+  execution:
+    kind: vitest
+    path: packages/sdk/src/index.e2e.test.ts
+    summary: Run the source-internal App SDK preview over fake and isolated Gateway WebSocket boundaries.
diff --git a/qa/scenarios/runtime/app-sdk-package-entrypoints.yaml b/qa/scenarios/runtime/app-sdk-package-entrypoints.yaml
new file mode 100644
index 000000000000..6aa2cf604c09
--- /dev/null
+++ b/qa/scenarios/runtime/app-sdk-package-entrypoints.yaml
@@ -0,0 +1,25 @@
+title: Source-internal App SDK preview package entrypoint evidence
+
+scenario:
+  id: app-sdk-package-entrypoints
+  surface: app-sdk
+  category: app-sdk.client-api
+  coverage:
+    primary:
+      - app-sdk.sdk-entrypoints
+  objective: Verify a clean temporary consumer can install the source-built preview @openclaw/sdk artifact and execute its root entrypoint without treating the private package as published.
+  successCriteria:
+    - The private SDK preview and its workspace dependencies build and pack as npm artifacts without workspace-only dependency references.
+    - A temporary consumer installs the source-built preview artifacts through an isolated local registry.
+    - The preview package root exports GatewayClientTransport, OpenClaw, and normalizeGatewayEvent, and event normalization executes from the installed artifact.
+  docsRefs:
+    - docs/gateway/external-apps.md
+    - docs/gateway/protocol.md
+  codeRefs:
+    - packages/sdk/package.json
+    - packages/sdk/src/index.ts
+    - packages/sdk/src/package.e2e.test.ts
+  execution:
+    kind: vitest
+    path: packages/sdk/src/package.e2e.test.ts
+    summary: Pack the source-internal App SDK preview and import its root from a clean temporary consumer.
diff --git a/qa/scenarios/runtime/app-sdk-unsupported-calls.yaml b/qa/scenarios/runtime/app-sdk-unsupported-calls.yaml
new file mode 100644
index 000000000000..a0f67a2314a5
--- /dev/null
+++ b/qa/scenarios/runtime/app-sdk-unsupported-calls.yaml
@@ -0,0 +1,24 @@
+title: Source-internal App SDK preview unsupported call evidence
+
+scenario:
+  id: app-sdk-unsupported-calls
+  surface: app-sdk
+  category: app-sdk.compatibility
+  coverage:
+    primary:
+      - app-sdk.unsupported-calls
+  objective: Verify the source-internal App SDK preview rejects unsupported per-run execution options before dispatching a Gateway request.
+  successCriteria:
+    - Provider-qualified model references are translated into supported provider and model request fields.
+    - Workspace, runtime, environment, and approval overrides are rejected before transport dispatch.
+    - The rejection identifies every unsupported option so callers receive an actionable result.
+  docsRefs:
+    - docs/gateway/external-apps.md
+    - docs/gateway/protocol.md
+  codeRefs:
+    - packages/sdk/src/client.ts
+    - packages/sdk/src/index.test.ts
+  execution:
+    kind: vitest
+    path: packages/sdk/src/index.test.ts
+    summary: Run the preview SDK request-shaping assertions for supported model refs and unsupported per-run options.