Extract client SDK package (#1052)

* Extract client SDK package * Polish SDK client identity defaults * Build client before dependent CI jobs * Restore daemon client server export * Extract protocol and client SDK packages * Fix provider override schema validation * Fix app test daemon client imports * Simplify workspace build targets * Fix CLI test server build bootstrap * Run SDK package tests in CI * Fix rebase package split drift * Restore lockfile registry metadata * Update SDK config test for prompt default * Move terminal stream router test to client package * Fix rebase drift for protocol imports * Fix SDK agent capability fixture * Restore legacy server client exports * Fix server export compatibility test * Advertise custom mode icon client capability * Remove server daemon-client exports * Format rebased mode control import * Fix rebase drift for protocol imports Files added by upstream PRs (#893, #1147, #1154) referenced the pre-split shared/ paths that this branch moves into @getpaseo/protocol. Redirect those imports to the protocol package so typecheck stays green after the rebase.
2026-05-28 01:58:18 +08:00
parent 0ea41378a4
commit 53c14d9855
403 changed files with 3193 additions and 1417 deletions
@@ -0,0 +1,18 @@
+# Paseo Client SDK Examples
+
+These examples use only the public SDK root:
+
+```ts
+import { createPaseoClient, type PaseoClient } from "@getpaseo/client";
+```
+
+Pass the daemon WebSocket URL into the exported functions. In worktree dev, read it
+from the portless banner or `portless get daemon`; for the desktop-managed daemon,
+use the URL for that daemon.
+
+- `workspaces.ts` covers creating, opening, refetching, and archiving a workspace.
+- `agents-and-providers.ts` covers creating agents and choosing providers with `client.providers.*`.
+- `events-and-timeline.ts` covers subscribing to workspace, agent, and timeline events, plus refetching a timeline page.
+- `provider-settings.ts` covers provider settings that are currently daemon config-backed.
+
+Provider profiles, provider env vars, custom binaries, and additional models are still raw daemon config behavior. The SDK exposes them through `client.config.get()` and `client.config.patch()` until first-class provider settings RPCs exist.
@@ -0,0 +1,56 @@
+import { createPaseoClient, type PaseoClient } from "@getpaseo/client";
+
+export function createClient(url: string): PaseoClient {
+  return createPaseoClient({
+    url,
+  });
+}
+
+export async function createCodexAgent(url: string, cwd: string): Promise<string> {
+  const client = createClient(url);
+
+  try {
+    await client.connect();
+
+    const agent = await client.agents.create({
+      config: {
+        ...client.providers.codex({
+          model: "gpt-5.2",
+          modeId: "full-auto",
+        }),
+        cwd,
+      },
+      initialPrompt: "Inspect this repository and summarize the next useful task.",
+    });
+
+    return agent.id;
+  } finally {
+    await client.close();
+  }
+}
+
+export async function chooseProviderFromSnapshot(url: string, cwd: string): Promise<string> {
+  const client = createClient(url);
+
+  try {
+    await client.connect();
+
+    const snapshot = await client.providers.snapshot({ cwd });
+    const readyProvider = snapshot.entries.find((provider) => provider.status === "ready");
+    const providerConfig = readyProvider
+      ? client.providers.config(readyProvider.provider)
+      : client.providers.claude();
+
+    const agent = await client.agents.create({
+      config: {
+        ...providerConfig,
+        cwd,
+      },
+      initialPrompt: "Start with a quick repository map.",
+    });
+
+    return agent.id;
+  } finally {
+    await client.close();
+  }
+}
@@ -0,0 +1,62 @@
+import { createPaseoClient, type PaseoClient } from "@getpaseo/client";
+
+export function createClient(url: string): PaseoClient {
+  return createPaseoClient({
+    url,
+  });
+}
+
+export async function subscribeToEvents(
+  url: string,
+  agentId: string,
+  workspaceId: string,
+): Promise<() => void> {
+  const client = createClient(url);
+  await client.connect();
+
+  await client.workspaces.list({
+    filter: { idPrefix: workspaceId },
+    subscribe: { subscriptionId: `workspace-${workspaceId}` },
+  });
+
+  const unsubscribeAgentUpdates = client.agents.subscribe((update) => {
+    if (update.kind === "upsert" && update.agent.id === agentId) {
+      void update.agent.status;
+    }
+  });
+
+  const unsubscribeWorkspaceUpdates = client.workspaces.subscribe((update) => {
+    if (update.kind === "upsert" && update.workspace.id === workspaceId) {
+      void update.workspace.workspaceDirectory;
+    }
+  });
+
+  const unsubscribeTimeline = client.agents.ref(agentId).timeline.subscribe((event) => {
+    void event.event;
+  });
+
+  return () => {
+    unsubscribeTimeline();
+    unsubscribeWorkspaceUpdates();
+    unsubscribeAgentUpdates();
+    void client.close();
+  };
+}
+
+export async function refetchTimeline(url: string, agentId: string): Promise<number> {
+  const client = createClient(url);
+
+  try {
+    await client.connect();
+
+    const timeline = await client.agents.ref(agentId).timeline.refetch({
+      direction: "before",
+      limit: 50,
+      projection: "projected",
+    });
+
+    return timeline.entries.length;
+  } finally {
+    await client.close();
+  }
+}
@@ -0,0 +1,62 @@
+import { createPaseoClient, type PaseoClient } from "@getpaseo/client";
+
+export function createClient(url: string): PaseoClient {
+  return createPaseoClient({
+    url,
+  });
+}
+
+export async function setSupportedProviderSettings(url: string): Promise<void> {
+  const client = createClient(url);
+
+  try {
+    await client.connect();
+
+    await client.config.patch({
+      providers: {
+        codex: {
+          enabled: true,
+          additionalModels: [
+            {
+              id: "gpt-5.2",
+              label: "GPT-5.2",
+              isDefault: true,
+            },
+          ],
+        },
+      },
+    });
+  } finally {
+    await client.close();
+  }
+}
+
+export async function addCustomCodexProfile(url: string): Promise<void> {
+  const client = createClient(url);
+
+  try {
+    await client.connect();
+
+    await client.config.patch({
+      providers: {
+        "codex-proxy": {
+          extends: "codex",
+          label: "Codex Proxy",
+          env: {
+            OPENAI_API_KEY: "sk-...",
+            OPENAI_BASE_URL: "https://example.test/v1",
+          },
+          models: [
+            {
+              id: "custom-model",
+              label: "Custom Model",
+              isDefault: true,
+            },
+          ],
+        },
+      },
+    });
+  } finally {
+    await client.close();
+  }
+}
@@ -0,0 +1,30 @@
+import { createPaseoClient, type PaseoClient } from "@getpaseo/client";
+
+export function createClient(url: string): PaseoClient {
+  return createPaseoClient({
+    url,
+  });
+}
+
+export async function createOpenAndArchiveWorkspace(url: string, cwd: string): Promise<void> {
+  const client = createClient(url);
+
+  try {
+    await client.connect();
+
+    const created = await client.workspaces.create(cwd);
+    if (!created.workspace) {
+      throw new Error(created.error ?? "Workspace creation failed");
+    }
+
+    const opened = await client.workspaces.open(cwd);
+    if (!opened.workspace) {
+      throw new Error(opened.error ?? "Workspace open failed");
+    }
+
+    await opened.workspace.refetch();
+    await opened.workspace.archive();
+  } finally {
+    await client.close();
+  }
+}