@pstdio/sdk 0.25.0 → 0.36.0

package/README.md

@@ -32,6 +32,29 @@ Page targets change location. Panel targets preserve it. Compound targets contai
 
 Use `qualifyRef(owner, ref)` in provider contract modules. Keep definitions local and pass qualified refs between extensions. For webviews, declare capabilities and call the typed `GuestHost`; `placement.close` closes the calling placement through the normal tab controller.
 
+## Workspace creation
+
+Workspace creation belongs to the host. Use `ctx.workspaces.listProviders()` to
+check whether additional workspaces can be created. The existing project
+workspace is returned separately by `ctx.workspaces.getDefault()`.
+
+A tree action can call the public host command `workbench.workspace.create`:
+
+```ts
+const createWorkspace = commandRef<CreateWorkspaceCommandParams>({
+  extensionId: "pstdio",
+  id: "workbench.workspace.create",
+});
+```
+
+It accepts optional `anchors` and `shorthand_base` parameters. The host shows the available providers and their
+declared inputs, then creates the workspace with those resource links. Provider
+parameters stay nested and are passed unchanged. Cloud providers do not need Git
+or a local directory; creation may return while provisioning is still running.
+
+For programmatic creation, call `ctx.workspaces.create()` with an explicit
+`provider_id` and provider `params`.
+
 ## Dashboard URLs
 
 Use `serializePageUrl({ projectId, page, resource })` to return a dashboard link from a command. The page descriptor contains its `id`, qualified `ref`, and declared `path`; `resource` is optional. The workbench uses the same route and resource codec.
@@ -42,6 +65,11 @@ Page and panel navigation targets remain the API for opening views and tabs.
 
 ## Webview change subscriptions
 
+To run webview commands in a selected workspace, pass `{ workspaceId }` to
+`createWebviewClient(host, options)`. Without that option, commands use the project's
+default workspace. The host resolves the workspace target and checks project ownership.
+The low-level `commands.execute` bridge accepts the same `workspaceId` field.
+
 Use the typed client's `events.subscribe(event, listener)` to refetch after a command changes data:
 
 ```ts
@@ -63,3 +91,31 @@ The host delivers only events matching the view's project. Projectless events re
 Development and installed consumers both load built SDK entries. Repository development builds this package before starting the source CLI. Builds stage release files under `.publish` through the shared release script. Package verification installs those same staged artifacts into a temporary directory outside the monorepo and checks every entry point.
 
 Host authors should use the [workbench guide](https://github.com/pufflyai/prompt-studio/blob/main/packages/pstdio-workbench/README.md). Extension authors should use this SDK and public UI packages.
+
+## Workspace contracts
+
+The alpha.13 host opens one folder per project and uses workspace APIs for execution and files.
+Use `ctx.projectFiles` for the project's default workspace and `ctx.workspaceFiles`
+for the invocation's working files. Project file operations check the current workspace
+readiness and file capabilities. Remote workspaces never fall back to local files.
+
+`ctx.workspaces.getDefault()` returns the project workspace.
+`ctx.workspaces.listProviders()` returns available providers, their optional `icon`, and their parameters.
+Render these declared parameters after the user selects a workspace type. The Git
+provider supplies a **Base branch** selection; cloud providers supply their own fields.
+Local setup failures reject creation with the saved workspace ID and setup error.
+The workspace remains available for diagnosis and retry.
+Workspace context records expose `root_path` for a local directory. Remote workspaces have no local root.
+
+The SDK client exposes `client.workspaces.listProviders(projectId)` and
+`client.filesystem.createDirectory({ parent_path, name })`.
+Directory creation accepts one child name under an existing parent.
+
+Webviews can set `workspaceId` in `createWebviewClient(host, { workspaceId })`
+to run commands in that workspace. The host validates project ownership.
+
+Extensions that work with both host contracts can declare the exact versions
+`1.0.0-alpha.12 || 1.0.0-alpha.13` in `engines.pstdio`.
+General version ranges and wildcards remain unsupported.
+The compatible extension release must precede the host cutover.
+See [the staged release ADR](../../.pstdio/docs/adrs/0030-temporary-workspace-contract-release-bridge.md).