API versioning
The extension API has its own semver version. This page explains version ranges, breaking changes, and how old APIs are retired.
The decision is recorded in ADR 0047.
App, SDK, and extension API versions
Three version numbers matter when you build or install an extension. They answer different questions.
| Version | What it is | Where to see it |
|---|---|---|
| App version | The Prompt Studio release you run: the desktop app, the pstdio CLI, and the runtime and dashboard inside them. Core extensions install from the same release. |
Help at the bottom of the dashboard sidebar shows the version of the running runtime. pst --version shows the version of the pst you ran. |
| SDK package version | The @pstdio/sdk package in your extension’s package.json. It gives your code its types and helpers. |
version in node_modules/@pstdio/sdk/package.json. |
| Extension API version | EXTENSION_API_VERSION, the extension contract that a host supports. Your manifest’s engines.pstdio names the API versions your extension works with. |
pst extensions check prints the API version of the pst you ran. The runtime’s version is not printed; find it from the app version. @pstdio/sdk/extensions exports the constant. |
Stable app and SDK releases share the same number. SDK and UI previews can be published separately, with versions ending in -preview.sha-<commit>. Pin exact preview versions in extension dependencies. Each new SDK package records its extension API in pstdio.extensionApiVersion in its package manifest. The extension API has its own number, because it changes only when the contract changes. For example, release 0.43.1 ships extension API 0.1.6.
The host decides what loads. It compares its own extension API version with engines.pstdio. Updating @pstdio/sdk in your extension does not update the app. A newer SDK can compile code that calls APIs your app does not have yet.
An installed extension outside the host’s supported API range keeps its identity and compatibility diagnostic, but contributes no commands, views, hooks, or other runtime capabilities. The host does not import its entry module or build its webviews. Other compatible extensions continue running. The host preserves the user’s enabled choice, configuration, and stored data. Installing or reloading a compatible extension release makes its contributions available again. Authoring checks and new installs still reject unsupported API ranges.
Versions in current releases
| Release | Extension API | Notes |
|---|---|---|
| 0.43.1 | 0.1.6 | Use ranges such as ^0.1.0. A manifest that needs ^0.2.0 does not load. |
| 0.44.0 | 0.2.0 | A breaking step. See Extension file storage in API 0.2. |
| 0.45.0 | 0.2.1 | Adds independent panel permissions and the /client device login methods. Existing ^0.2.0 ranges still load. |
| 0.46.0 | 0.3.0 | A breaking step. See Storage size limits in API 0.3. Manifests need ^0.3.0. It also has the additions listed for API 0.2.2, which no release shipped: account feature grants, full project-scoped ctx.sessions operations, indexed record queries and batches, optional paged collection views, device performance capture and Developer settings contributions, project recovery methods on /client, app-wide and device settings, and Kanban dragging in every column. |
main, after 0.46.0 |
0.4.0 | Changes structured record merging to relay order, with explicit collaborative text and append-only logs. It includes the Cloud sync progress, sign-in recovery and manifest icon additions previously planned for unreleased API 0.3.1. Manifests need ^0.4.0. |
Pages that describe APIs from main say so and name the first release that has them.
API 0.4.2, after 0.47.0, adds collection-scoped index declarations with item-relative
field paths and the SDK readCollectionRecords helper. Extensions using these
must require ^0.4.2 and pin a supporting published SDK. Index declarations are
installed before commands become available. See storage.
The unreleased API 0.5.0 step makes views using the new SDK collection-query
helpers paged by default. Existing custom defineView callbacks retain their
full-result contract, including when rebuilt with the new SDK. Custom bounded
providers explicitly declare queryMode: "paged"; fixed collections explicitly
declare queryMode: "static" and a row limit. The host rejects whole-collection reads from bounded view
callbacks, including nested commands. Existing providers retain their legacy contract. This step also includes the indexed related-query,
derived projection, column-statistics and collection-view helpers used by Planner.
Record queries accept limit: 0 for validated revision checks without selecting
resource rows; empty collection pages use this path.
Planner requires this host API. Its independent release must follow publication
of the matching SDK and host; a local development link only proves the candidate.
The native terminal view body
shares the coordinated API 0.4.0 step on main. It requires a published SDK exporting
TerminalViewBody and a compatible host advertising view.terminal.v1 (planned
for the release after 0.46.0). A packed candidate SDK proves development
compatibility; it does not satisfy the publication gate for a production
extension. Qualify the installed consumer against the delivered host and record
both released versions before adopting the surface.
Status bar items on main can also declare a popover view through the additive
status-bar-item.popover.v1 host capability. This shares the planned API 0.3.0 release.
API 0.3.1 on main, after 0.46.0, adds project-scoped ctx.extensions.list/install and declarative projectSetup.
These additions share the existing post-0.46.0 patch step with Cloud sync changes.
Publish the host and SDK containing them before separately released extensions adopt them;
SDK 0.46.0 provides API 0.3.0 and does not contain these additions.
The optional HarnessProvider.fork(ctx, input) method is additive in API 0.3.1 on main. It copies native history without starting a turn and returns a different agentSessionId. When input.messageId is provided, copy through that projected message, inclusive, and omit later history. Reject unsupported boundaries instead of copying later context. The host reads and reconciles the copied native history to adopt its message IDs. Existing providers keep working without it. Publish the SDK and host before separately released harnesses adopt this method.
The page and panel additions share the planned API 0.3.0 release: page-owned empty views and landing slots, non-rendering page groups with default children, closable fixed tabs, tabless Main presentation, independent panel views, declarative slot replacements, caller-relative viewer navigation, mode-owned fullscreen permission, and collection badge navigation actions. They do not add another version step before that release.
Hosts on main, after 0.46.0, read the optional manifest icon field and show it in Extensions. This additive metadata shares the API 0.4.0 release. Existing manifests remain valid without the icon field. Older hosts ignore the field, so declaring an icon does not require a higher minimum API version.
The native chat view body also shares the coordinated API 0.4.0 step. Released extensions must use a published SDK containing that declaration and a host that supports it before adopting it.
Scoped query ownership and invalidation metadata, host-supplied webview query scope,
command-backed shared editing, storage/session metadata observation and optional
HarnessProvider.watchCommandState also share this API 0.4.0 step. These additions
preserve the existing query, event and editing methods. The matching SDK adds
createQueryLifecycleFixture under /testing. See the
state and project lifetime guide.
Publish the supporting host/SDK/UI before independent consumer releases; local
tarballs and a widened manifest range are not published compatibility evidence.
The optional HarnessStartInput.turns channel also shares API 0.4.0. A harness whose run stays open between turns reports idle and busy turns through it, and a supporting host delivers queued replies to idle turns. Older hosts omit the channel, so providers must treat it as optional.
Read-only host-retained command queries also share API 0.4.0. A supporting host
provides commands.query; the SDK exposes client.commands.read.query(...),
client.queries.command(...) and useWebviewCommandQuery. These retain finite
accepted results across recreated webview frames. Existing guest callback queries
remain available with their guest lifetime. Publish the supporting host and SDK
before independent consumers adopt this addition.
Infinite tree scrolling also shares API 0.4.0 on main. Tree sections and child collections can return
nextCursor; their page callback returns TreeNodePage for automatic sibling appends. A supporting host
advertises view.tree.pages.v1. Publish the SDK and host before separately releasing an extension that uses it.
Optional workspace provider discovery and provider-bound ctx.localDirectory()
share the coordinated API 0.4.0 step on main. They expose current project choices
and owned local preparation before readiness. Publish the host and SDK before
separately released providers adopt them; SDK 0.46.0 does not include them. See
local workspace providers.
Paged table and board bodies on main, after 0.46.0, accept optional initialPageSize, and paged providers may receive page limits up to 500. The MAX_COLLECTION_PAGE_SIZE and DEFAULT_COLLECTION_PAGE_SIZE constants expose the bounds. These additions share the coordinated API 0.4.0 step. Older hosts cap pages at 100 and ignore board initialPageSize, so existing manifests and providers keep working.
Inline data-table sparkline and bar-chart renderers and the optional saved
rowHeight setting also share the coordinated API 0.4.0 step. Existing columns
and saved views keep their behavior. See inline charts and row height.
Command, settings panel, settings section and appearance records on main include optional localId metadata so clients can resolve historical references from structured identity without parsing runtime IDs. Registered UI theme options can supply historical choices through optional aliases; pickers still expose one canonical option. These additions share API 0.5.0.
The CLI globalAliases declaration is removed in API 0.5.0. Root shortcuts such as pst tickets write and pst reports write are replaced by pst pstdio.planner write-ticket and pst pstdio.reports reports write. Deprecated namespace migration paths are separate and remain available.
The shorter first-party extension identities also share API 0.5.0. Canonical discovery and output use names such as pstdio.notes; historical invocations remain deprecated aliases. Ship the migration-capable host before renamed packages. See identity upgrades.
Data-table image columns, resource list subGroupings (any number of levels) with children nested to any depth, and tree row tags are additive and share API 0.5.0. Existing columns, saved views and tree rows keep their behavior. Publish the supporting host, SDK and UI before independent extensions adopt them. See image columns and resource lists.
ctx.resources.allocateMany also shares API 0.5.0. It numbers 1 to 100 resources of one kind in one save, so imports do not allocate one number per call.
The optional files.download webview capability and typed client.files.download
also share API 0.5.0 on main. They deliver bytes the extension already holds to
the user’s browser download UI, without adding sandbox permissions or file read
access. Publish the host and SDK before independent extensions adopt it. See
webview files.
The optional resources.actions.register capability and registerWebviewResourceAction
also share API 0.5.0. They attach live reader actions to native resource menus,
bound to the calling extension, project, placement and resource. Closing or
replacing that reader removes its actions and cancels pending work.
migration.moveCollection and the keyPrefix option of storage index declarations also share API 0.5.0. Older hosts do not provide either; see move a collection to records.
The optional HarnessStartInput.approvals channel also shares API 0.5.0. A supporting host passes the session’s approval channel on a session’s first turn as well as on resume. Hosts up to 0.47 pass it only on resume, so providers must treat it as optional on start.
The optional durable-automation notBefore deadline also shares API 0.5.0 on main. Waiting runs remain queued across restart until the deadline. See delayed execution.
Which version each check uses
| Check | Where it runs | Extension API version it compares with |
|---|---|---|
pst extensions check <path> |
Inside the pst you ran. It does not contact the runtime. |
The API version built into that pst. Its error says “this pst provides” that version. On 0.43.x it says “this host provides”, even when your runtime is a different release. |
pst extensions check with no path |
The connected runtime checks its installed user and repo extensions. | The runtime’s API version. The version lines at the top come from the pst you ran, not from the runtime. |
pst extensions add, dashboard install, Reload, and Upgrade |
The connected runtime. | The runtime’s API version. |
tsc in your extension folder |
Your computer. | None. It checks your code against the @pstdio/sdk types you installed. It cannot tell whether your app has those APIs. |
pst extensions check never reports the runtime’s own app or extension API version. Read the app version in Help, then find its extension API version in Versions in current releases.
From the release after 0.43.x, the check output names what it checked:
| Check | Text output | --json |
|---|---|---|
pst extensions check <path> |
Checked: source folder <path>, then This pst: extension API <version> (pst <version>, SDK <version>) and Manifest engines.pstdio: <range>. When the range rejects this pst’s API version, a last line explains what to do. |
target: { kind: "source", path }, versions: { cli, extensionApi, sdk, manifestRange }, and the result in check. |
pst extensions check with no path |
Checked: extensions installed on the host at <URL> for project <id>, then the This pst line and one section per scope. |
target: { kind: "installed", projectId, host }, versions: { cli, extensionApi, sdk }, and one result per checked folder in checks, each with its scope (user or repo). |
In 0.43.x, the installed check prints CLI, Extension API, SDK, and Dashboard (bundled) lines, which all describe the pst you ran. The source check prints only the result in text mode. Its --json has versions with a dashboard field, and the result in check. Installed --json has no target, and its checks entries have no scope.
When the pst you run and the runtime come from the same install, these checks agree. The desktop app includes its own pst. If you also installed pstdio with Bun, command -v pst on macOS and Linux, or where.exe pst on Windows, shows which one runs.
Align the app and your tools
- Find the app version in Help, or with
pst --versionfrom the same install. - Install the matching SDK in your extension folder, for example
bun add @pstdio/[email protected]. Its types then match the APIs your app has. - Declare an
engines.pstdiorange that includes the app’s extension API version, such as^0.1.0for API 0.1.6. - After you update the app, restart the runtime so the new version runs. Quit and reopen the desktop app. If you started the runtime from a terminal, run
pst closeand thenpst.
Do not widen engines.pstdio to make a check pass. A range is a promise that your extension works with that API version. Add a range only after you ran the extension on a host with that version. If a check says your extension needs a newer API, update Prompt Studio, or use only the APIs your release has.
Host version
EXTENSION_API_VERSION is a plain semver number with no prerelease or build tag. @pstdio/sdk/extensions exports it, and pst extensions check prints it.
The version stays on 0.x until the maintainers declare the API settled. That release sets it to 1.0.0. Semver defines major version zero as initial development, so the leading 0 tells authors that the API may still break.
engines.pstdio declaration
An extension declares one or more caret ranges joined by ||:
declaration = term *( "||" term )
term = "^" MAJOR "." MINOR "." PATCH
Whitespace around || is allowed. Numbers follow semver rules, so leading zeros are refused.
| Declaration | Result |
|---|---|
^0.1.0 |
Valid. |
^0.4.2 |
Valid. Needs API 0.4.2 or newer, below 0.5.0. |
^0.4.2 || ^0.5.0 |
Valid. One build for two breaking lines. |
^1.2.0 |
Valid after 1.0.0. Needs API 1.2.0 or newer, below 2.0.0. |
0.4.0 |
Refused. An exact version pins one host release. |
~0.4.0, 0.x, *, >=0.4.0 |
Refused. |
1.0.0-alpha.14, ^1.0.0-alpha.1 |
Refused. Prerelease tags are not accepted. |
Only caret ranges are accepted because each one stops below the next breaking version. On 0.x that is the next minor. From 1.0.0 it is the next major. A declaration can never claim support for a breaking version that did not exist when it was written. Exact versions and tilde ranges would force an edit after each additive release.
The host accepts an extension when Bun.semver.satisfies(EXTENSION_API_VERSION, declaration) is true. The parser lives in api-versions.ts. The runtime and pst extensions check both use it.
Diagnostic
A refused extension gets one extension_manifest_unsupported_api_version diagnostic. The message names the extension, its declaration, and the host version, then gives one repair:
| Case | Repair |
|---|---|
| The declaration is not caret ranges | Shows the accepted form, with ^<host> as the example. |
| Every term’s minimum is below the host, catalog source | Upgrade the extension to its build for this host. |
| Every term’s minimum is below the host, other source | Make it work with API <host>, then add ^<host> to engines.pstdio. |
| Otherwise, the extension needs a newer API | Update Prompt Studio, or use an extension build for this host. |
Keep an extension compatible
Declare a caret range that starts at the lowest API version your extension needs, such as ^0.1.0. The extension then keeps loading across additive and fix releases. Raise the minimum only when the extension starts using a newer API.
On 0.x, a new minor version is a breaking release. When one arrives, update the extension’s code for the new API. Then declare ^0.1.0 || ^0.2.0 if one build supports both versions, or ^0.2.0 if it supports only the new one.
What counts as the extension API
Anything an extension author writes code or manifest content against:
- Types and runtime contracts of the public SDK subpaths listed below.
- Manifest fields:
package.jsonidentity fields,engines.pstdio, and thepstdiometadata block. - Contribution validation rules that the host and
pst extensions checkapply. - Webview bridge capabilities and payloads.
- Command, middleware, hook, and event payloads that the host sends or accepts.
- Documented runtime behavior that extensions rely on, such as what the host does with a command result.
Public SDK subpaths
Every public subpath follows the same change levels and deprecation window. The API report covers
all of them. Public means a supported consumer outside this repository may import it; usage by an
extension is not the only test. In particular, Granite uses /client, and published UI and
workbench packages use /api and /resources.
| Subpath | Status | Purpose |
|---|---|---|
/extensions |
Public, reported | Extension definitions, contexts and typed webview clients. |
/extensions/react |
Public, reported | React helpers for extensions. |
/testing |
Public, reported | Test contexts and in-memory service implementations. |
/data |
Public, reported | Pure frontmatter, draft-layout and name helpers. |
/prompts |
Public, reported | Prompt rendering helpers. |
/client |
Public, reported | Typed HTTP clients for agents, scripts and hosts. |
/api |
Public, reported | HTTP request/response and terminal transport contracts. |
/resources |
Public, reported | Shared resource records, including assets and notifications. |
/hooks |
Host-only, deprecated in 0.44 | Old filesystem-hook contexts. Use typed hooks from /extensions; removal is planned for 0.45. |
The report entry inventory is packages/sdk/api-report-entries.json. Adding a public subpath also
adds it there. /testing, /data, /prompts and /client are versioned APIs even when a change
has no manifest or bridge effect. A missing in-repo caller does not permit removal of a published
method. Deprecate it first, then remove it in the next breaking release.
/resources owns shared asset and notification type names. The older /client, /api and
/extensions paths keep deprecated aliases through 0.44. /api owns the renderer terminal
adapter; the separate extension terminal bridge is deprecated with the typed webview cleanup.
Host routing, event resolution, capability tables and artifact mount normalization belong to
pstdio-api-contracts. Hosts import them there. Their old /extensions exports are deprecated
aliases through 0.44. Keyboard forwarding is a private guest operation; an extension cannot
declare it or invoke it through the public typed capability union.
The dashboard uses the typed HTTP client. Only transport URL resolution (such as its terminal WebSocket) remains outside that client; dashboard code does not build paths for JSON requests.
Change levels
Direction matters. The host provides some types, such as ctx and HarnessEventSink, and extensions call them. Extensions provide other types, such as contributions, handlers, and harness adapters, and the host calls or validates them.
Breaking:
- Remove or rename an export, member, contribution key, capability, or event.
- Change a type so that old code no longer compiles or old values no longer validate.
- Add a required field to anything extensions provide.
- Add a validation rule that refuses a manifest or contribution that loaded before.
- Change documented runtime behavior that extensions rely on.
- Remove APIs that were deprecated in an earlier release.
Additive:
- Add an export, a
ctxmethod, a capability, an event, or a contribution kind. - Add a member to an object the host provides.
- Add an optional field to anything extensions provide.
- Mark an API as deprecated. The old API keeps working until a breaking release removes it.
Fix:
- Fix host behavior so it matches the documented contract, with no type change.
No change:
- Documentation, comments, and internal changes that change neither the public types nor behavior.
If in doubt, it is breaking. A breaking change released as additive lets broken extensions load and then fail one contribution at a time.
| Level | On 0.x |
From 1.0.0 |
|---|---|---|
| Breaking | Minor, 0.4.2 to 0.5.0 |
Major, 1.4.2 to 2.0.0 |
| Additive | Patch, 0.4.2 to 0.4.3 |
Minor, 1.4.2 to 1.5.0 |
| Fix | Patch, 0.4.2 to 0.4.3 |
Patch, 1.4.2 to 1.4.3 |
One step per release
The version moves at most one step between two releases. The highest change level merged since the last release sets the step. The number of changes does not matter. For example, a release with several additive changes and one breaking change moves the API one breaking step, from 0.4.2 to 0.5.0.
The only exception is the release that declares the API settled. It moves any 0.x version to 1.0.0.
Deprecate first, remove together
Extensions depend on the API, so an API is never removed in the release that replaces it:
- Add the new API next to the old one. That is an additive change.
- Mark the old API
@deprecatedand name the replacement. - Remove deprecated APIs together in one breaking release, either one that already breaks the API or one planned for the removals. List each removal and its replacement in the release notes.
Repository checks enforce these rules: each tracked manifest must accept the host version, and the API version must move when the public API report changes.
Optional queued-input capability
The optional HarnessSession.steer capability and host-provided ctx.sessions queue methods are additive. Existing adapters keep loading without steering. These additions shipped in API 0.1.2. Publish the SDK contract before adopting it in harness extensions.
Extension file storage in API 0.2
API 0.2 shipped in 0.44.0. Release 0.43.x provides API 0.1.6 and the old layout.
API 0.2 moves ctx.extensionFiles from .pstdio/ext/<publisher>.<name>/ to .pstdio/extension-storage/<package-name>/.publishers/<publisher>/. Publishers with the same package name keep separate files. Artifact mount paths cannot start with the reserved .publishers segment, including case variants. This is a breaking filesystem layout change; relative file operations stay the same. Move existing allocated files using the storage migration guide. Extensions that work with both layouts can declare ^0.1.0 || ^0.2.0.
Prompt Studio 0.46 roots extension storage at
.pstdio/extension-storage/<publisher>.<name>/. Relative file operations stay
the same. 0.46 starts with an empty database and does not move or read earlier
<package-name>/ folders, so each extension starts fresh. Extensions that build
storage paths themselves must use the full-ID folder. Name-only CLI namespaces
and resource-kind references remain deprecated aliases when unambiguous;
full-ID forms replace them. API 0.5.0 removes extension-defined global shortcuts. Replace globalAliases with qualified command examples and use cli.path only for paths inside the owning extension namespace.
Storage size limits in API 0.3
API 0.3 is on main and is planned for 0.46. Earlier releases have no limits.
Records hold small structured data. The host now refuses a storage save over either limit:
| Limit | Size | What counts |
|---|---|---|
| One record | 256 KiB | UTF-8 bytes of the JSON of the saved record’s value and shared content. Asset references do not count. |
| One commit | 4 MiB | The sum for every record in one records.commit group, one collection write, or one set. |
The whole save fails and nothing in it is written. The error has code: "storage_limit_exceeded" and names the record, its size, the limit, and what to use instead. Deleting a record is never refused. createMemoryStorage from @pstdio/sdk/testing applies the same limits, so tests fail the same way.
This is a breaking change, because writes that saved before are now refused. The additive part is storageLimits and isStorageLimitError in @pstdio/sdk/extensions.
Move large content out of records before you declare ^0.3.0:
- Attachments of an item, such as file bodies and images:
ctx.storage.files, or the files of a resource scope. Keep the returned ID in the record. - Files that people or agents open, such as drafts, logs and generated pages:
ctx.extensionFilesor an artifact mount. - Large imports: several smaller commits.
An extension whose records already stay small can declare ^0.2.0 || ^0.3.0. See Size limits.
Ordered records in API 0.4
API 0.4 changes documented storage behavior and therefore takes one breaking version step from the last released API 0.3 line. It includes all intervening additions; there is no separate release step for each new method.
Ordinary strings, including multiline strings, and arrays are whole values. Objects
merge by the fields an author changed, in the encrypted relay’s order. An explicit
expectedRevision is an atomic condition on the group’s observed paths and record
lifetimes; an earlier overlapping change refuses the entire group, including its
text edits. observedRevision supplies a replacement baseline without making it a
condition. set and unset use JSON Pointer field addresses.
Declare collaborative record text in storage.records.text, then edit it with
storage.text(recordId, field).edit(...) or the native editor for that bound field.
Declare append-only storage.logs for event history and open them with
storage.log(name, options). These additions do not remove deprecated shared or
conflict signatures. Maintained consumers migrate to ordinary fields and explicitly
declared text; old explicit shared-text edits remain text during their compatibility
period. See Grouped storage for methods, limits and outcomes.
Update the SDK and host together before adopting the new methods. A manifest’s
^0.4.0 minimum must be checked against an SDK providing API 0.4; widening a version
range or substituting local declarations does not prove a published dependency works.
Independent panel permissions in API 0.2.1
API 0.2.1 also adds optional HarnessProvider.releaseSession(ctx, { sessionId }) for host-managed idle-resource cleanup. The host retains open tabs, active work, and sessions used within 30 minutes. Return true after releasing idle resources and false while native work or delivery remains uncertain. Preserve history and recreate resources on the next call. Existing providers keep working. Publish the SDK and host before separately released harnesses adopt it.
ModeRegionSettings adds optional canOpen, canClose, acceptsTabs, movable, resizable and Side floatable permissions. floatingPanels and panel collapsible are deprecated, with their old behavior retained. Published extension header and tab behavior stays compatible until the coordinated breaking release. Publish the SDK and host before separately released extensions use these additions.
Local editing sessions in API 0.2.1
The additive editing.session capability and client.editing.open share local document edits
across isolated webviews before persistence completes. The host scopes sessions to their project
and extension. See local editing sessions.
This is on main and ships after 0.44.0. Existing public APIs remain available.
Storage conflict members deprecated in API 0.2.1
Edits from several devices are moving to automatic merging. The storage API stops promising conflicts. These changes are additive and ship in the release after 0.44.0:
StorageSaveOutcomeaddsstate:saved-locally,waiting-to-sync,synced,offline, orneeds-attention.records.commitandrecords.outcomereturn it. The host always setsstate, so a hand-written test double of an outcome must add it.expectedRevisionon arecords.commitedit is optional. Without it, the edit applies to the record’s current value.records.conflicts,records.inspect,records.resolve, thebranchargument ofrecords.read, the outcome’sstatus,checkpoint,conflictIdandconflictRevision, and theStorageConflict,StorageConflictInspectionandStorageResolutiontypes are deprecated.storage.assetsno longer documents retained versions or unresolved alternatives.
The next breaking release removes the deprecated members together. See Deprecated conflict members.
Storage IDs and positions in API 0.2.1
storage.ids.create(), storage.positions.between(), and the second migration
callback argument, migration.id(key), are additive. Existing migration callbacks
keep working. The test storage options add optional workbenchId, extensionId,
and deviceId values for simulating the same owner on two devices. These additions
ship in the release after 0.44.0. See the
storage guide.
These ID helpers also accept an optional lowercase prefix. A supplied prefix selects
a lossless 22-character Base62 UUID body; omitting it keeps canonical UUID text.
resources.allocate({ kind, idPrefix? }) uses the same generator and preserves its
existing UUID output when idPrefix is omitted. Compact IDs are case-sensitive;
extension adoption must keep ID lookup exact and shorthand lookup separate. These
options do not rewrite existing IDs or change existing shorthand declarations.
The migration callback also exposes additive migration.position(rank, key) for
deterministic initial ordering. Existing callback arguments and methods stay
available. Publish the host and SDK before extension migrations use it. The helper
accepts a nonnegative safe integer rank and stable unique item key, separating
equal ranks from different offline source lists. It produces a position compatible with
ordinary storage.positions.between moves. It has no device or random suffix;
use it only to migrate an order derived from stable source data.
Retained service queries in API 0.4.2
On main, after the API 0.4.1 release, the additive 0.4.2 step adds readonly retained account, Performance and preference queries and optional cancellation on scoped reads. Existing methods and payloads remain supported. The accompanying UI supports controlled DiffViewer selection. Publish compatible host/SDK/UI support before independent extensions adopt these methods or raise their declared minimum to 0.4.2. See shared state and project lifetimes.
Personal device references in API 0.2.1
Workspace/session read results and resource references may include device: { ownerId, id, name }. A synced record is readable on its owner’s other devices. Execution stays on its source device. Shared personal references contain only owner and device details; another user cannot open the underlying record. This additive field ships in the release after 0.44.0.
Cloud account and sync status in API 0.2.1
On main, planned for API 0.3.0, the account service address becomes optional in ctx.account.login, the webview account client and /client account login. Omitting it uses the host’s environment setting or the hosted default. Explicit addresses keep their existing behavior.
ctx.account, the account.read and account.manage webview capabilities, client.account on the typed webview client, and the accountEvents.projectSyncChanged host event are additive. They ship in the release after 0.44.0. The /client account methods add cancelLogin and projectSyncStatus. AccountDevice adds online, AccountStatus adds cloudProjectsLoaded, and DeviceLogin adds an optional email. makeCommandContext from @pstdio/sdk/testing provides a signed-out account whose projects are local. Publish the SDK and host before separately released extensions use these additions. See Cloud account and sync status.
Kanban dragging in API 0.2
Every board column allows cards to be dragged in and out. This includes groups for missing or unknown values. canDragIn and canDragOut remain as deprecated input fields, but their values are ignored. Remove these fields from column configurations. This alpha change stays on the 0.2 API line; manifests need no new version range. The next coordinated removal of deprecated APIs can remove the fields themselves.
Paged collection views in API 0.2.2
dataTable and kanban view bodies can opt into queryMode: "paged". Their
query input adds an optional page request, and their result adds optional page
revision, cursor, count, group, and statistics metadata. Both additions are
required only for opted-in providers. Existing providers keep their full-result
contract. Storage queries also accept optional offset and expected revision
for direct page jumps. This shares the next compatible release step with indexed
storage queries; it does not add another API version step before that release.
See paged tables and boards.
Project recovery in API 0.2.2
The /client project methods add recoveryPoints(projectId) and restore(projectId, input).
The /api entry exports ProjectRecoveryPoint, RestoreProjectInput and RestoreProjectResult.
Agents use them to list and restore the same recovery points as project settings. These
additions ship in the release after 0.45.0. See Restore project data.
Cloud sync progress and sign-in recovery in API 0.3.1
Cloud status adds optional ProjectSyncStatus.pendingItems, ProjectSyncStatus.download,
and AccountStatus.signInRequired in API 0.3.1. Existing state values and methods stay available.
accountEvents.changed announces public account changes, including sign-in recovery, independently of project sync events.
Counts and progress use verified sync documents, including their files; unknown directories
leave the count absent and the download total null. Publish the SDK and matching host before
extensions consume these fields. See Cloud account and sync status.
After 0.47.0, optional source/file activity in ProjectSyncStatus.sources, the source/file
types, and retryProjectSyncSource through ctx.account, the typed webview client and
/client were prepared as API 0.4.1. They share the coordinated API 0.5.0 release with
the breaking identity change above; the version advances once for that release. Existing
methods and aggregate state values remain supported. Publish a matching SDK and host
before Cloud or other separately released extensions consume these additions.
App-wide and device settings in API 0.3.0
workbenchSlots.globalSettings and the "device" extension setting scope are
additive. They join the planned API 0.3.0 release after 0.45.0. Existing
project/global settings, extension detail panels, and published custom global
slots keep working. Device settings use ctx.settings and the existing typed
webview settings capabilities. Publish the SDK and host before extensions adopt
them. See app-wide settings.
Workspace file observations in API 0.4.2
The additive /client method workspaces.watchFiles observes local file changes
on the existing shared client transport, including project folders without Git.
Its callbacks provide change hints; finite file listings remain authoritative.
Existing workspace methods and observers remain supported. Publish the matching
SDK and host before separately released clients adopt this method.
Host delete confirmation on main
Optional command confirmation declarations share the coordinated API 0.4.2 step.
kind: "delete" uses the host’s standard destructive confirmation, including pending,
error and retry behavior. subjectParam names the parameter displayed beside the
command title; description and buttonLabel customize its message and action.
After confirmation, the dashboard sets the declared confirmedParam to true.
CLI and API invocations remain unchanged: commands must keep their explicit consent
validation or existing presentation path when that parameter is absent. Older hosts
omit this optional declaration and never synthesize consent.
Resource Activity in API 0.4.2
Optional resource Activity declarations, ctx.activity discussion/outcome methods, owner-only historical import and client.activity are additive in API 0.4.2. The current [email protected] API-report baseline contains API 0.4.1. Existing ctx.activity.record remains supported. Publish the supporting host, SDK, UI and workbench before releasing independent consumers. See resource Activity.
Optional navigation views in API 0.4.2
NavigationTreeContribution.optionalView lets a tool attach a tree supplied by an independently installed view provider. An absent foreign provider keeps the tree inactive; missing local views, missing views in a present provider, and non-tree views still fail validation. Publish a compatible SDK and host before consumers adopt this additive contract. The published 0.47.0 SDK does not include it. See navigation trees.
Native action bars on main
ActionBarViewBody, ActionBarSnapshot, ActionBarAction and ActionBarMenu
add native tool rails and command menus through body.kind: "actionBar".
They share the coordinated unreleased API step on main. Hosts advertise
view.actionBar.v1; existing view bodies and activity items remain supported.
Publish the supporting SDK and host before independent extension adoption.
See native action bars.
Project composition adoption in API 0.4.2
The host retires its fixed Start/Home/Workspaces presentation aliases. Projects choose an ordinary default page and public resource openers. Paths, parents, navigation order, and workspace presentation decisions belong to extensions. Existing presentation links may become unavailable; shared workspace and session records keep their identity and storage. Deprecated SDK reference exports remain available during consumer migration; their removal belongs to a separate coordinated breaking release.
ctx.resources.resolveOpenings and the SDK project composition client require the
matching published SDK and host. Validate consumer PRs against that SDK and declare
their published dependency ranges before release. See
project composition.
Updated at: 2026-11-18