Mohamed BoudraandGitHub
7954babca6
* 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.
115 lines
2.9 KiB
Markdown
115 lines
2.9 KiB
Markdown
---
|
|
title: Workspaces with the SDK
|
|
description: Open directories as Paseo workspaces, place agents in them, follow changes, and archive them.
|
|
nav: Workspaces
|
|
order: 53
|
|
category: 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
|
|
|
|
```ts
|
|
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:
|
|
|
|
```ts
|
|
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:
|
|
|
|
```ts
|
|
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:
|
|
|
|
```ts
|
|
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:
|
|
|
|
```ts
|
|
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
|
|
|
|
```ts
|
|
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
|
|
|
|
```ts
|
|
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.
|