jb/paseo

Files

T

Mohamed BoudraandGitHub 7954babca6 Publish the TypeScript SDK and integration guides (#3141 )

* feat(client): publish the TypeScript SDK surface

Make the high-level client API usable for external integrations and document complete agent, workspace, provider, event, and recipe flows.

* fix(client): correlate provider snapshots by daemon cwd

Return the daemon's canonical snapshot identity so waitForReady can match updates for relative, tilde, and otherwise non-canonical paths without duplicating filesystem rules in the SDK.

* test(server): make snapshot cwd assertion portable

* fix(client): gate canonical provider snapshot waits

Older daemons do not expose the canonical snapshot identity needed to correlate workspace updates safely. Require the advertised capability and fail with an update-host message instead of guessing across workspaces.

2026-08-10 13:22:20 +02:00

2.9 KiB

Raw Blame History

title, description, nav, order, category

title	description	nav	order	category
Workspaces with the SDK	Open directories as Paseo workspaces, place agents in them, follow changes, and archive them.	Workspaces	53	TypeScript SDK

Workspaces with the SDK

Use a workspace when an integration needs a durable place in the Paseo app for agents, terminals, browsers, and files related to one task.

Open a directory

const workspace = await client.workspaces.open("/Users/me/dev/storefront");

console.log(workspace.id);
console.log(workspace.directory);

open() creates the project when needed and reuses the active workspace for that exact directory. Use it when the directory is the identity you care about.

Create a fresh workspace

create() always creates a new workspace, even when another workspace already uses the directory:

const workspace = await client.workspaces.create({
  source: {
    kind: "directory",
    path: "/Users/me/dev/storefront",
  },
  title: "Checkout issue 42",
});

Create a Paseo-owned worktree when concurrent work needs an isolated checkout:

const workspace = await client.workspaces.create({
  source: {
    kind: "worktree",
    cwd: "/Users/me/dev/storefront",
    action: "branch-off",
    refName: "main",
    branchName: "fix/checkout-42",
  },
  title: "Checkout issue 42",
});

You can pass projectId in either source when you already have one. Most integrations should omit it; the daemon finds or creates the project from the directory.

Start an agent in a workspace

Create through the workspace handle:

const agent = await workspace.agents.create({
  config: {
    provider: "claude/claude-sonnet-5",
  },
  prompt: "Map the checkout flow before changing anything.",
});

The handle supplies both the workspace identity and its actual directory. This avoids mismatched placement arguments.

For a one-off agent, you can skip the workspace call:

const agent = await client.agents.create({
  config: {
    provider: "claude/claude-sonnet-5",
  },
  cwd: "/Users/me/dev/storefront",
  prompt: "Map the checkout flow before changing anything.",
});

The daemon still creates a project and a fresh workspace. Read agent.workspaceId when you need the generated workspace ID.

List workspaces

let cursor: string | undefined;

do {
  const page = await client.workspaces.list({
    filter: { query: "storefront" },
    page: { limit: 50, cursor },
  });

  for (const workspace of page.entries) {
    console.log(workspace.id, workspace.name, workspace.status);
  }

  cursor = page.pageInfo.nextCursor ?? undefined;
} while (cursor);

Refresh and archive a handle

const workspace = client.workspaces.ref(savedWorkspaceId);
const snapshot = await workspace.refresh();

if (snapshot) {
  await workspace.archive();
}

Workspace archive is separate from agent archive. Archive each resource according to the lifecycle your integration owns.

2.9 KiB Raw Blame History