feat(pawapp): redesign the SDK and app control plane

.github/workflows/pawapp-contracts.yml

@@ -0,0 +1,46 @@
+name: PawApp Contract Conformance
+on:
+  push:
+    branches: [dev/pawapp-vnext]
+  pull_request:
+    paths:
+      - 'src/qwenpaw/pawapp/**'
+      - 'src/qwenpaw/plugins/validation.py'
+      - 'src/qwenpaw/config/utils.py'
+      - 'plugins/apps/**'
+      - 'console/src/plugins/pawapp-sdk/**'
+      - 'console/src/plugins/usePluginLoader*'
+      - 'console/src/api/modules/pawappTasks*'
+      - 'console/src/components/Chat/ToolCards/cards/PawAppTaskCard*'
+      - 'tests/**'
+      - 'scripts/*pawapp*'
+      - 'docs/design/pawapp-contract*'
+      - '.github/workflows/pawapp-contracts.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  conformance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: console/package-lock.json
+      - name: Install Host test environment
+        run: python -m pip install -e '.[test]'
+      - name: Check generated contract drift and Host conformance
+        run: |
+          python scripts/generate-pawapp-contracts.py --check
+          python -m pytest -q tests/unit/pawapp tests/unit/plugins/test_plugin_api_extensions.py tests/unit/cli/test_plugin_commands.py tests/unit/config/test_config_utils.py
+      - name: Check frontend contract clients and task cards
+        working-directory: console
+        run: |
+          npm ci --no-audit --no-fund
+          npx tsc -b --noEmit
+          npm run test:run -- src/plugins/pawapp-sdk src/plugins/usePluginLoader.test.ts src/api/modules/pawappTasks.test.ts src/components/Chat/ToolCards/cards/PawAppTaskCard.test.tsx

console/.prettierignore

@@ -16,3 +16,6 @@ node_modules/
 coverage/
 .vscode/
 .idea/
+
+# Generated by scripts/generate-pawapp-contracts.py
+src/plugins/pawapp-sdk/contracts.generated.ts

console/src/api/modules/pawappGrants.test.ts

@@ -0,0 +1,63 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../request", () => ({ request: vi.fn() }));
+
+import { request } from "../request";
+import { pawappGrantsApi } from "./pawappGrants";
+
+describe("pawappGrantsApi", () => {
+  beforeEach(() => vi.mocked(request).mockResolvedValue({ actions: [] }));
+
+  it("loads the selected workspace grant catalog", async () => {
+    const controller = new AbortController();
+
+    await pawappGrantsApi.list("agent / one", controller.signal);
+
+    expect(request).toHaveBeenCalledWith(
+      "/pawapps/workspaces/agent%20%2F%20one/task-grants",
+      { signal: controller.signal },
+    );
+  });
+
+  it("updates one action with the expected policy revision", async () => {
+    const body = {
+      expected_revision: 4,
+      enabled: true,
+      input_values: { datasource_id: ["sales"] },
+    };
+
+    await pawappGrantsApi.update(
+      "agent-1",
+      "qwenpaw-data",
+      "analyze records",
+      body,
+    );
+
+    expect(request).toHaveBeenCalledWith(
+      "/pawapps/workspaces/agent-1/task-grants/actions/qwenpaw-data/analyze%20records",
+      {
+        method: "PUT",
+        body: JSON.stringify(body),
+      },
+    );
+  });
+
+  it("updates one capability bundle atomically", async () => {
+    const body = { expected_revision: 4, enabled: true };
+
+    await pawappGrantsApi.updateCapability(
+      "agent-1",
+      "qwenpaw-creator",
+      "media_generation",
+      body,
+    );
+
+    expect(request).toHaveBeenCalledWith(
+      "/pawapps/workspaces/agent-1/task-grants/capabilities/qwenpaw-creator/media_generation",
+      {
+        method: "PUT",
+        body: JSON.stringify(body),
+      },
+    );
+  });
+});

console/src/api/modules/pawappGrants.ts

@@ -0,0 +1,106 @@
+import { request } from "../request";
+
+export interface PawAppGrantAction {
+  app_id: string;
+  action_id: string;
+  summary: string;
+  descriptor_digest: string;
+  input_schema: {
+    properties?: Record<string, unknown>;
+  };
+  permissions: string[];
+  effects: string[];
+  settings_entry: string | null;
+  enabled: boolean;
+  stale: boolean;
+  input_values: Record<string, string[]>;
+}
+
+export interface PawAppGrantCapability {
+  schema_version: 1;
+  capability_id: string;
+  app_id: string;
+  label: string;
+  summary: string;
+  action_ids: string[];
+  permissions: string[];
+  effects: string[];
+  risk: "read" | "write" | "generation" | "analysis" | "other";
+  enabled: boolean;
+  partial: boolean;
+  stale: boolean;
+}
+
+export interface PawAppHostSkillImportStatus {
+  app_id: string;
+  skill_id: string;
+  description: string;
+  tool_refs: string[];
+  missing_tool_refs: string[];
+  installed: boolean;
+  enabled: boolean;
+  available: boolean;
+  status:
+    | "available"
+    | "disabled"
+    | "not_installed"
+    | "unavailable"
+    | "tool_dependency_unavailable";
+}
+
+export interface PawAppGrantCatalog {
+  revision: number;
+  actions: PawAppGrantAction[];
+  capabilities?: PawAppGrantCapability[];
+  host_skill_imports?: PawAppHostSkillImportStatus[];
+}
+
+export interface PawAppGrantUpdate {
+  expected_revision: number;
+  enabled: boolean;
+  input_values: Record<string, string[]>;
+}
+
+function catalogPath(workspaceId: string): string {
+  return `/pawapps/workspaces/${encodeURIComponent(workspaceId)}/task-grants`;
+}
+
+export const pawappGrantsApi = {
+  list(workspaceId: string, signal?: AbortSignal) {
+    return request<PawAppGrantCatalog>(catalogPath(workspaceId), { signal });
+  },
+
+  update(
+    workspaceId: string,
+    appId: string,
+    actionId: string,
+    body: PawAppGrantUpdate,
+  ) {
+    return request<PawAppGrantCatalog>(
+      `${catalogPath(workspaceId)}/actions/${encodeURIComponent(
+        appId,
+      )}/${encodeURIComponent(actionId)}`,
+      {
+        method: "PUT",
+        body: JSON.stringify(body),
+      },
+    );
+  },
+
+  updateCapability(
+    workspaceId: string,
+    appId: string,
+    capabilityId: string,
+    body: Omit<PawAppGrantUpdate, "input_values">,
+  ) {
+    return request<PawAppGrantCatalog>(
+      `${catalogPath(workspaceId)}/capabilities/${encodeURIComponent(
+        appId,
+      )}/${encodeURIComponent(capabilityId)}`,
+      {
+        method: "PUT",
+        body: JSON.stringify(body),
+      },
+    );
+  },
+};

console/src/api/modules/pawappTasks.test.ts

@@ -0,0 +1,104 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../request", () => ({ request: vi.fn() }));
+
+import { request } from "../request";
+import { answerPawAppTask, openPawAppSetup } from "./pawappTasks";
+
+const setupAction = {
+  schema_version: 1 as const,
+  app_id: "qwenpaw-creator",
+  request_id: "setup/1",
+  entry_id: "creator.video-model-settings",
+  presentation: "app_entry" as const,
+  path: "/apps/qwenpaw-creator?setup=video&setupRequest=setup-1",
+};
+
+beforeEach(() => {
+  vi.mocked(request).mockReset();
+});
+
+describe("PawApp task interactions", () => {
+  it("opens setup through the scoped Host route", async () => {
+    vi.mocked(request).mockResolvedValue({ open_action: setupAction });
+
+    await expect(
+      openPawAppSetup("qwenpaw-creator", "main agent", "setup/1"),
+    ).resolves.toEqual(setupAction);
+    expect(request).toHaveBeenCalledWith(
+      "/pawapps/qwenpaw-creator/workspaces/main%20agent/setup-requests/setup%2F1/open",
+      { method: "POST", headers: { "X-Agent-Id": "main agent" } },
+    );
+  });
+
+  it.each([
+    "https://untrusted.test/apps/qwenpaw-creator",
+    "/apps/qwenpaw-creator/../other",
+    "/apps/other?setup=video",
+  ])("rejects unsafe setup path %s", async (path) => {
+    vi.mocked(request).mockResolvedValue({
+      open_action: { ...setupAction, path },
+    });
+
+    await expect(
+      openPawAppSetup("qwenpaw-creator", "main", "setup/1"),
+    ).rejects.toThrow("invalid_open_setup_response");
+  });
+
+  it("submits an exact answer command and validates its identity", async () => {
+    const command = {
+      protocol_version: 1 as const,
+      task_id: "task/1",
+      command_id: "command-1",
+      kind: "answer" as const,
+      request_id: "approval-1",
+      state: "accepted" as const,
+      reason: null,
+    };
+    const answers = [
+      {
+        question: "Run this generation?",
+        selected_options: ["Approve once"],
+        custom_text: null,
+      },
+    ];
+    vi.mocked(request).mockResolvedValue({ command });
+
+    await expect(
+      answerPawAppTask(
+        "qwenpaw-creator",
+        "main agent",
+        "task/1",
+        "command-1",
+        "approval-1",
+        answers,
+      ),
+    ).resolves.toEqual(command);
+    expect(request).toHaveBeenCalledWith(
+      "/pawapps/qwenpaw-creator/workspaces/main%20agent/tasks/task%2F1/answer",
+      {
+        method: "POST",
+        headers: { "X-Agent-Id": "main agent" },
+        body: JSON.stringify({
+          command_id: "command-1",
+          request_id: "approval-1",
+          answers,
+        }),
+      },
+    );
+
+    vi.mocked(request).mockResolvedValue({
+      command: { ...command, request_id: "other" },
+    });
+    await expect(
+      answerPawAppTask(
+        "qwenpaw-creator",
+        "main agent",
+        "task/1",
+        "command-1",
+        "approval-1",
+        answers,
+      ),
+    ).rejects.toThrow("invalid_task_answer_response");
+  });
+});