Contributions
Contributions are what an extension adds to Prompt Studio. This page lists every contribution kind and explains the UI contributions.
Contribution Surfaces
| Surface | Product role |
|---|---|
commands |
User-triggered, CLI-triggered, scheduled, or automation-triggered operations. |
keybindings |
Global app-level shortcuts that run a navigation action, using TanStack Hotkeys syntax. |
middlewares |
Pre-command checks that may continue, patch params, replace invocation data, or reject. |
hooks |
Event observers that run after a product event is emitted. |
schedules |
Cron-driven command invocation. |
views |
Reusable webview, tree, file, controls, chat, terminal, table, and Kanban bodies. |
viewMenus |
View bodies attached as menus owned by another view. |
pages |
Routed screens with resource constraints, Main presentation, and extra panel slots. |
placements |
Mode-wide static views or resource bindings. |
navigationItems, navigationTrees |
Explicit actions and Sidenav trees owned by a mode or page. |
resourceKinds |
Domain resource identity, labels, icons, menus, and hierarchy. |
resourceHierarchyProviders |
Domain parent lookup for resources. Page targets supply breadcrumb destinations. |
statusBarItems |
Views in the host status bar with device-local user order and alignment. |
statuses |
Deprecated workflow providers; use query-owned enums and an extension settings panel. |
settings, settingsSections |
Extension setting definitions and grouped settings sections. |
templateTypes |
Commands and metadata for extension-owned template editing. |
commandPaletteResources |
Searchable resources with explicit activation targets and optional accessible status indicator (icon, color, label). Declare resourceKind to supply matching resource-parameter pickers. |
translations, defaultLocale |
Localized contribution labels and the fallback locale. |
settingsPanels |
References that place views in host-owned settings slots. |
modes |
Typed Workbench mode contributions. |
activityItems |
Activity-rail entries that select a Workbench mode. |
templates, skills, themes, fileIconThemes |
Packaged catalog assets. |
artifactMounts |
Safe repo-local file access under .pstdio/extension-storage/<publisher>.<name>/. watch: true adds change events. |
workspaceTypes, harnesses |
Provider integrations owned by the extension runtime. |
connections |
Host-managed HTTP access to a declared remote control plane. |
UI contributions attach to targets that the host owns. Workbench composition explains how views, pages, modes, and panels fit together.
Native chat provides immediate composers and canonical conversations with scoped callbacks to the existing session services.
Configure project composition
Extension API 0.4 treats Home, Workspaces, and Cloud as ordinary optional tools. The project chooses a fully qualified, resource-free page as its default. Page names, paths, parents, panels, and navigation order belong to extensions.
Read or replace the same public configuration from the CLI or SDK:
pst projects composition
pst projects composition --value '{"defaultPage":{"kind":"page","extensionId":"example.space","id":"desk"},"resourceOpeners":[{"resourceKind":{"kind":"resource-kind","extensionId":"pstdio","id":"workspace"},"opener":{"kind":"command","extensionId":"example.reader","id":"inspect"}}]}'
The SDK client exposes projects.composition(projectId) and
projects.setComposition(projectId, value). The HTTP endpoints are
GET and PUT /v1/projects/{projectId}/composition. Configuration is synced with
the existing project information. An explicit empty configuration stays empty.
Catalog defaults are editable distribution data; enabling an extension preserves
an existing choice.
The default opens when there is no explicit destination or valid saved location.
A missing, disabled, or resource-bound default leaves the existing empty workbench.
Extension management and other available navigation remain usable. The public
workbenchCommands.openDefaultPage command opens the configured default explicitly.
Each resourceOpeners entry binds a fully qualified resource kind to an ordinary
page or command. An opener command reads ctx.resource and returns a normal page,
panel, or compound navigation target. It can belong to another extension than the
data owner. A missing opener or unavailable target makes the operation unavailable.
Explicit navigation targets keep their declared destination.
Use ctx.resources.resolveOpenings(refs) or the SDK client’s
projects.resolveResourceOpenings(projectId, refs) for bare resource links.
resolveMany remains the data-owner metadata API. An opener can present an ordinary
kind without a batch metadata resolver. Its command owns any further data lookup.
A binding can also name a relatedOpenings command returning
RelatedResourceOpenings. This selects automatic previews through the same saved
workbench preferences. Workspaces owns its workspace page choices and related
session selection. It declares scoped conversation navigation through the public
Sessions renderer. Cloud uses normal status/settings slots and the public account
API. Core keeps execution, records, account services, sync, and extension management
independent of those presentation contributions.
This alpha host change removes the old Start/Home/Workspaces presentation aliases, selectors and redirects. Update callers to configured openers or explicit ordinary targets. Existing presentation URLs and saved page references may become unavailable. Workspace and session data stay in their existing stores. Deprecated SDK reference exports remain available until their separate coordinated breaking removal. Native terminal views bind an interactive PTY to a view through a serializable launch callback. The host owns the renderer, workspace validation, transport, and process lifetime.
Kanban create results
A successful createRow result with string id and title is passed to the renderer’s declared onRowActivate callback. That callback owns navigation through ctx.navigation.open with an explicit page or panel target. Creating a resource does not choose its presentation. Use the same activation callback for opening an existing row and a newly created row.
Do not return metadata.resourceParent or infer a view from a resource type. Resource hierarchy and page destinations are separate contracts. See the Kanban host and the workbench cookbook.
Settings
settings.properties declares values that the host stores for one project or for all projects, as set by scope. The Settings tab on the extension’s page shows a field for each boolean, number, and string setting. Array and object settings need the extension’s own view, placed with settingsPanels.
Use workbenchSlots.extensionSettings for native controls in the owning extension’s Settings tab. A controls view supplies fields to the shared parameter editor, next to the extension’s ordinary settings. It follows normal page flow and shares the settings page’s scrollbar. It does not add an entry to project settings navigation. Use workbenchSlots.projectSettings for a separate project settings entry, such as a shared status editor. A project settings panel without section appears in the host’s Project group.
A string setting can offer choices in two ways:
enumlists fixed values. The host refuses any other value.optionsloads the choices from a command when the Settings tab opens. It uses the sameParamOptionSourceas command params:command,valueField,labelField, and optionalparams. The command returns a list of rows. A{ kind: "param-value", key }param passes the current value of another setting.
A setting with options shows as a searchable dropdown, with the same loading and error states as command dialogs. Clearing it removes the saved value, so the setting falls back to its default. The host does not check saved values against the options, because choices such as remote branches can disappear after a value is saved. The dropdown keeps showing a saved value that the command no longer lists. Check the value where the extension uses it.
"implementation.defaultTargetBranch": {
type: "string",
scope: "project",
default: "",
title: "Default target branch",
options: { command: implementationTargetsCommand.ref, valueField: "branch", labelField: "branch" },
},
Only string settings accept options; on other types the host ignores options and reports a warning. The option command must belong to the same extension. A command ref that names no command of the extension is reported as unknown_setting_option_command. Setting options needs extension API 0.1.2.
Authoring Boundaries
Extensions declare metadata and handlers; the host owns installation, project enablement, command routing, workbench chrome, trusted context keys, and layout primitives.
App-wide settings
On main (planned extension API 0.3.0, after 0.45.0), a settings panel can target
workbenchSlots.globalSettings. The host registers it with global scope in every
project where the extension is enabled. Use workbenchSlots.projectSettings for
project settings and workbenchSlots.extensionSettings for the owner’s extension
detail Settings tab. Panel placement does not change a setting’s storage scope.
const panel = defineSettingsPanel({
id: "device",
view: deviceView.ref,
slot: workbenchSlots.globalSettings,
});
Each property in settings.properties declares scope: "project", "global", or
"device". Project values belong to the project extension instance. Global values
belong to the installed extension. Device values belong to the extension identity
on this host, so they are shared across its projects and installed copies, persist
across restarts, and never enter synced project data. Another device starts with
the declared default. A remote host stores values on that host, not in the browser.
Every installed copy with the same extension ID reads the same device values, so
store only values that any copy of the extension may read.
Commands use ctx.settings.all(), get(key), set(key, value), and delete(key).
Webviews use the same methods on client.settings and declare the matching
extension.settings.* capabilities. The host selects storage from the property’s
declared scope. Deleting an override restores its default.
Extension code should not:
- define package identity inside
defineExtension() - invent dashboard target ids outside the SDK target registry
- import Prompt Studio packages other than
@pstdio/sdkand@pstdio/ui - write outside package assets, API-owned storage, or declared artifact mounts
- assume a target maps to a fixed physical location across dashboard implementations
When extension UI needs dashboard placement, attach it to a host-owned target and optionally add a when expression. The dashboard decides how that target maps to current UI.
Keybindings
Keybindings bind app-level keyboard shortcuts to a navigation action. The action is any navigation target: a command, a page, a panel, an href, or a compound target. Pages and panels bind directly; no wrapper command is needed. Chords use @tanstack/hotkeys syntax and are validated by the extension runtime. Invalid chords, modifier-only chords, direct chords whose first step types text (a printable key or Space, alone or with only Shift), and duplicate platform-aware chords are reported by extension checks and dropped from metadata. Single keys belong in a shortcut-mode layer.
Help → Keyboard shortcuts manages assigned, inactive, disabled, and unassigned actions. It supports personal bindings, disabling, resetting, Leader, and extension aliases. Menus, the command palette, and navigation items supply readable action labels. Repeated placements of the same target and parameters share one row. Different parameters remain separate. The reference updates when extensions change. Hidden row actions release label space; labels truncate only when visible content needs that space. Navigation rows show effective shortcut hints while keyboard mode is active. Row actions use the existing hover fade and remain visible while keyboard focus is inside the row. Command shortcuts without supplied parameters open the shared parameter form before execution.
Layered bindings add layer (view, go, create, current, or settings; extensions and help are deprecated and join current) and targetScope (project, resource, or panel). Their keys are letters or numbers relative to the group. Shared keys open an action or target chooser. Completed actions exit shortcut mode; tab navigation remains active until Enter or Escape. The deprecated sticky field is accepted for older declarations but no longer retains mode after completion. Existing direct bindings can declare allowInInputs; use it only for explicit workbench chords that must be consumed before editors. It applies only to chords that hold Alt, Ctrl, or Cmd; plain keys always reach the editor. See Keyboard shortcuts for navigation, target rules, preferences, and nested webviews.
The main destinations use Alt+Shift: Sessions S, Workspaces W, Notes O, Tickets P, and Artifacts A. Notes uses O because notifications already uses N. Creation uses Mod+Alt: session S, workspace W, note N, and ticket P. Settings uses Mod+,. Command palette placements use their source command and exact parameters to resolve shortcut hints. Sessions, Workspaces, and Tickets bind their existing open commands so the command palette shows their navigation shortcuts. These extension defaults live in their own contributions; the host does not assign shortcuts to third-party tools.
Prefer Mod+... so the chord maps to Cmd on macOS and Ctrl on Windows/Linux without an override. Avoid chords already claimed by browsers, OSes, or developer tooling (Mod+T, Mod+W, Mod+R, Mod+P, Mod+S, Mod+Shift+P, Mod+Shift+I, F5, F11, F12, …); the extension runtime emits a reserved_keybinding_chord warning when a contribution hits a reserved chord on any platform. Reach for multi-step chords like mod+k mod+t if no single chord is safe.
import { defineCommand, defineExtension, defineKeybinding } from "@pstdio/sdk/extensions";
const preview = defineCommand({
id: "preview",
title: "Preview",
async run(_ctx, _commandParams) {
return { opened: true };
},
});
export default defineExtension({
commands: [preview],
keybindings: [
defineKeybinding({
id: "preview",
key: "mod+shift+y",
mac: "cmd+shift+y",
win: "ctrl+shift+y",
linux: "ctrl+shift+y",
action: { kind: "command", target: { command: preview.ref } },
when: { resourceType: [{ extensionId: "pstdio.marp", kind: "resource-kind", id: "presentation" }] },
}),
],
});
A command action may pass params with target: { command: preview.ref, params: { ... } }. Use action: { kind: "page", page: somePage.ref } or action: { kind: "panel", panel: somePage.panels.someSlot } to open a page or panel directly.
Dashboard UI Contributions
Native controls views can declare a harness field with { id: "agent", name: "Model", type: "harness", defaultValue: { harnessId, model, params } }. Its value is the same object accepted by ctx.sessions.create({ harness: value }). The host renders its harness, model and model options inline using the command-form picker. Use onApply to save the choice or onValueChange to save each edit. This control requires API 0.1.3.
Controls with onApply keep edited values during background refreshes. Apply saves the draft; a rejected save shows its error beside the unchanged inputs. Reset discards the draft and uses the latest saved values. An optional onReset also lets the extension reset its stored values. Each resource owns a separate draft.
Dashboard UI contributions have one ownership model:
- a view owns its body and may use
webview,tree,file,controls,dataTable,kanban, orresourceList - a page owns a route, mode, optional resource constraint, Main presentation, and extra slots
- a non-rendering parent uses
main: { kind: "group", default: child.ref }; the default child opens without a resource in the same mode, while the group remains a breadcrumb label and navigation-tree owner - a placement owns a shared mode panel with a static-view or resource-binding item
- a navigation item uses a typed action instead of encoded route or command fields
- a navigation tree adds a tree view to a mode or page in the shared Sidenav
- a view menu references its owner view and menu view
- status-bar and settings contributions reference views; they do not duplicate view bodies
Local ids are explicit. The runtime normalizes them as
${extensionId}.${contributionKind}.${localId}. Use the ref returned by each define*
helper instead of rebuilding that id. Resources still identify domain objects such as
tickets, workspaces, and sessions. Paths belong to pages, never views.
import { defineExtension, defineNavigationTree, defineView, workbenchModes } from "@pstdio/sdk/extensions";
const files = defineView({
id: "files",
title: "Files",
body: {
kind: "tree",
structure: [{ id: "files", label: "Files" }],
body: async () => [{ id: "files", label: "Files", nodes: [] }],
},
});
export default defineExtension({
views: [files],
navigationTrees: [
defineNavigationTree({
id: "project-files",
owner: workbenchModes.project,
slot: "content",
view: files.ref,
resourceScope: "project",
}),
],
});
body and optional footer return TreeViewSection[]. Optional children returns TreeNode[] for lazy child
content. Renderer callbacks receive the active project, resource, renderer id, tree state, filter text, and selected
node context.
For long collections, set nextCursor on a section or on a node with its first children page, and provide
page(ctx, input). It receives the cursor, the same renderer/filter scope, and either
parent: { kind: "section", id } or parent: { kind: "node", node }. Return { nodes, nextCursor? }.
The host appends these nodes as siblings when the collection’s end enters the viewport. Omit the cursor when
exhausted. Keep node IDs stable across pages, including date headings. Collapsed collections do not load pages.
The host preserves existing rows and focus, prevents concurrent duplicate reads, cancels pages after query/resource
changes or refresh, and shows failures with inline Retry. Do not add a synthetic “More” node or a pagination button.
This additive API shares the coordinated API 0.4.0 step on main and requires a supporting published SDK and
host capability view.tree.pages.v1.
Optional structure declares body section IDs, labels, and collapse and visibility settings in view metadata. The host renders this layout synchronously, then starts content reads after that render commits. Pending sections show a spinner rather than an empty result. The callback’s final sections replace the structure, including sections that turn out to be empty or absent. Use the same IDs in both declarations so expansion and customization stay attached to the section. A structure section can include resourceNode: { id, icon } to show the bound resource using its already-known label without a callback.
Navigation trees default to resourceScope: "selection", so selecting a different resource starts a new read. Use resourceScope: "project" when the tree reads project data independently of the selected resource, such as a shared notes list. Its callbacks receive the project and no resource; selection changes keep its rows visible. Declared refresh events still update its data. The owner still controls where the tree appears.
Kanban query rows can include a page target. Clicking such a row opens that target immediately, without an activation callback. Include any conditional destination in the query result, using the data already loaded for that row. A target takes precedence over onRowActivate; rows without a target retain their callback behavior. Targets and their resources are scoped to the contributing extension and project.
Set selected: true on the current node when several rows share a resource, such as
documents within one ticket. The declaration stays on the node when trees are combined
and their IDs are scoped. While its resource or page is active, it takes precedence
over saved row selection and automatic page or resource matching. A contextual parent
tree’s declared document selection does not override the open workspace.
Rows without a resource or navigation target keep their declared selection.
Set tooltip to show text while the pointer rests on a row or the row has keyboard focus, such as the full path of a file whose row shows only its name. iconTooltip shows text only over the row icon. Use one of the two on a row, not both.
Set badge: { label: "3", color: "orange" } for a trailing count beside a tree row. It uses the notification count badge style. Omit it when there is no count to show.
Set tags to show display-only labels after a tree row’s label, such as a region or a draft state. Each tag has an id, a label and optional icon, color and tooltip, the same shape as kanban badge-list items without an action. Two tags show; the rest collapse into a “+N” chip whose tooltip lists them, and screen readers read every tag. Long tags truncate at a fixed width, and the count badge stays last. Clicking a tag activates the row. Available on main in API 0.5.0; publish the host and SDK before an independent extension adopts it.
Kanban attributes with display: { kind: "badge-list", itemsAttributeId: "items" } read their badges from the named row attribute. Each item has an id, label, and optional icon, color, tooltip, and action. The action accepts any navigation target, including a page-owned panel that opens beside the collection without changing its route. Page, panel, and resource references are scoped to the contributing extension and project. Actions run without activating the card. The older page-only target remains supported and is deprecated in favor of action; when both are present, action wins. This addition shares the planned extension API 0.3.0 release in Prompt Studio 0.46. Publish the SDK and host before extensions adopt it.
Tree rows use resource as their action subject and target as their normal-click destination. Right-clicking
a row resolves the registered actions for its resource kind and adds its contextMenuActions. The command and
any parameter dialog keep the clicked resource as their context, even when another resource is open.
Declare resource operations once through a menu slot on the resource kind. The same contributions appear in navigation, tab, and breadcrumb resource menus. Owner-only slots keep their existing access rules; public slots accept other extensions’ contributions. The host preserves the subject for visibility, parameters, confirmation, and execution. A command can have several distinct menu contributions with different parameters.
Use disabledWhen with the same subject conditions as when to keep an unavailable action visible. Supply a localized disabledReason for its explanation. For example, disabledWhen: { metadata: { writable: false } } disables a note mutation when its owner reports read-only access. The command must still check current permissions before writing.
Custom menu sections
Use placement tab presentation for view-specific navigation or controls. It supplements resource actions and does not choose the action subject. A group has id, an optional localized label, and rows. Tab controls follow custom groups; breadcrumbs add location actions instead.
menu: [{
id: "documents",
label: l10n("menus.documents", "Documents"),
rows: [newDocumentRow, switchDocumentRow, viewAllDocumentsRow],
}]
Use custom rows for view-specific controls and navigation. Move resource operations to resource-owned slots rather than copying them into each menu.
The host refreshes the tree after a section or row action runs. An action command calls
ctx.navigation.open(target) to move the page, for example back to the ticket body after deleting an open
document. The host applies explicit requests once after a successful command. Returned values remain data.
Set resource explicitly on ticket, workspace, and other resource rows. Reuse the same reference in target
when the destination represents that resource. A ticket file can instead open its parent ticket page and use
row actions with explicit ticket and file IDs. It must not use the parent ticket as its action subject.
Resource menus work in the Sidenav and standalone trees. A row menu takes precedence over Sidenav customization. Right-clicking the background or a plain navigation row still opens the customization menu. Workspace rows use current host capability data, including default-workspace restrictions, when resolving their actions.
The owner can be a mode or page ref. A mode-owned tree adds sections to that mode’s navigation. A page-owned
content tree starts a Sidenav level instead. The Sidenav renders one tree with pinned
header and footer slots and one scrolling content slot.
On main (API 0.4.0), a navigation tree can declare optionalOwner: true when its page or mode
belongs to another extension. The tree stays inactive while that extension is absent, disabled, or removed,
and attaches through normal registration when the provider returns. This supports independent installation
and default-install ordering. Declare optionalView: true separately when the tree view belongs to another
extension: the tree stays inactive while that view provider is absent and attaches when it returns.
Missing local owners and missing pages/modes in a present foreign extension remain validation errors.
Missing local views, missing views in a present provider, and references to non-tree views also remain errors.
Without the corresponding opt-in, missing owners and views retain their existing validation errors.
Inside a command declaration, use a typed menu slot and limit visibility with when. Import workspaceSlots and workbenchResourceKinds from @pstdio/sdk/extensions:
menus: [
{
slot: workspaceSlots.headerOverflow,
label: "Run review",
when: { resourceType: [workbenchResourceKinds.workspace] },
},
];
Workspace resources use the host project mode. Target workspace actions with
workbenchResourceKinds.workspace; the SDK does not export a host workspace mode.
The host adds Copy link to the breadcrumb menu on every page. It copies the page URL, including the selected document. Do not add a separate copy-link action or view to an extension.
A resource kind’s resolveMany command returns current ResourceResolution records with owner page targets.
When no single-resource resolve command is declared, the dashboard also uses this resolver for the open
resource after navigation and owner events. When the target
matches the open page, resource, and selected document, its parent chain restores the breadcrumb ancestry.
The open page keeps its params, section, and source position. Keep document-selection metadata in the returned
reference. For a file inside another resource, return a file-labeled target with the resource’s body target as
its parent. This keeps copied links and renamed files consistent with sidebar navigation.
See Workbench composition and Modes and layout for the full rules.
Status bar widgets
Status widgets use workbenchSlots.statusBarLeading, statusBarCenter or
statusBarTrailing as their initial alignment. People can drag the widget
surface or use its alignment menu. Inline iframe controls keep their pointer
input, so their surrounding padding is the drag surface. The host retains the
chosen alignment and order when an extension reloads. An optional popover view
makes the host own the indicator’s click and keyboard activation. Inline controls
remain available in status widgets without a popover. Keep the indicator’s
background transparent so the host can paint one surface across the widget,
including its hover and focus states.
Native action bars
A view can declare body.kind: "actionBar". Use it for tool rails and
compact command bars whose labels and menus must remain readable beside isolated
webviews. The workbench renders the buttons, tooltips and menus in its document.
Canvas, inspector and other custom content keep their iframe isolation.
An action bar in the activity region follows its dock: top and bottom use a
horizontal row and left and right use a vertical rail. Tooltips, menu placement
and arrow-key navigation follow that axis. Other placements use the view body’s
optional orientation.
const tools = defineView({
id: "tools",
title: "Tools",
body: {
kind: "actionBar",
refreshEvents: [documentChanged],
query: async (ctx, { renderer }) => {
const state = await readDocument(ctx, renderer.resource);
const move = {
id: "move",
label: "Move tool",
icon: "Move",
selected: state.tool === "move",
action: { kind: "command" as const, target: {
command: selectTool.ref, params: { tool: "move" },
} },
};
return { items: [
move,
{ id: "document", label: "Document actions", icon: "Ellipsis",
items: [{ ...move, selected: false }] },
] };
},
},
});
Set mode.chrome.activity to the view’s ref for a native rail. The same view can
be placed in a page or panel. Outside the activity region, orientation defaults
to vertical; use horizontal for a command row. Snapshot order sets the
default order. People can drag top-level buttons or reorder the focused button
with Alt and the arrow keys along the bar. The host saves their order per
project and view using the item IDs. Menu actions can declare group to separate
related commands.
Queries return actions with stable IDs, labels, icons, navigation targets and
optional selected and disabled state. A menu has an items array of actions
instead of an action. Return only actions available in the current context.
The host resolves local command refs against the contributing extension and
shows hints from the shared keybinding system. Bound command parameters stay
the same for people and agents.
Chrome follows the active page’s primary resource. A resource-bound placement uses its own resource. Declared refresh events update the snapshot; changing the resource releases the old read and closes its menus. Disabling or removing the contribution disposes its view. Arrow keys, Home and End move through enabled buttons. Escape, outside click and clicking the open trigger dismiss a menu.
This additive surface requires host capability view.actionBar.v1 and a
supporting published SDK. Publish platform support before releasing independent
extensions that adopt it. Older view kinds and activity items stay supported.
Native view toolbar actions
Both dataTable and kanban bodies accept toolbarActions. These actions stay
visible when a query returns no rows. Use them for commands such as creating a
record or starting an experiment.
The host renders visible actions as xs buttons, with one vertical separator
before the action group. It omits the separator when no actions are visible.
const experiments = defineView({
id: "experiments",
title: "Experiments",
body: {
kind: "dataTable",
query: () => ({ rows: [] }),
toolbarActions: [{
id: "run",
label: "Run experiment",
icon: "play",
presentation: "primary",
command: runExperiment.ref,
params: { source: "experiments" },
input: { name: params.text({ required: true }) },
submitLabel: "Start experiment",
}],
},
});
Actions use the shared command path and current resource context. params
provides static arguments; values collected by input override matching static
arguments. An input schema opens the command dialog. It supports
command-backed choices.
when uses the workbench context expression to control visibility, and
disabled disables an action. Command visibility and enablement still apply.
Use presentation: "primary" for the main action and "secondary" for other
actions. Secondary is the default. More than one primary action produces a
warning, and an unknown command produces an error diagnostic.
Table and board row actions
Row and selection actions pass row IDs to their commands. Row activation passes the whole row. This applies to 0.43.x and main.
| Callback | What the host passes |
|---|---|
rowActions command on a dataTable or kanban view |
Command params { rowId }: the row’s id string |
selectionActions command on a dataTable with selectionMode: "multiple" |
Command params { rowIds }: an array of the selected rows’ id strings |
onRowActivate on a dataTable or kanban view |
{ row }: the row object. For a data table, this is the row your query returned, { id, values, resource? }. |
Declare the parameter on the action’s command, such as rowId: params.text({ required: true }) or rowIds: params.json<string[]>({ required: true }). Load the item by its ID in the handler. An action command does not receive row or values.
A data table runs a row action command at once and then refreshes the view. On a kanban board, a row action command that declares parameters first opens the shared parameter form with rowId filled in. A row action command with no parameters runs at once.
Use onRowActivate to open the row. Request navigation with ctx.navigation.open(target) and return nothing. A returned target does not navigate.
Appearance Contributions
Themes and file icon themes use contribution arrays. Define each theme with a
local ID and register the returned definition. Use its typed ref for a mode’s
defaultTheme.
import { defineExtension, defineTheme, packageAsset } from "@pstdio/sdk/extensions";
const monokai = defineTheme({
id: "monokai",
title: "Monokai",
format: "vscode-color-theme",
mode: "dark",
source: packageAsset("./themes/monokai.json", import.meta.url),
});
export default defineExtension({ themes: [monokai] });
The runtime qualifies the ref with the extension owner. For publisher acme and
package planner, the theme ID is acme.planner.theme.monokai.
The runtime and public UI importer share one pure theme converter.
It supplies application roles from VS Code colors, then applies pstdio.colors
overrides. Editor colors and syntax rules go to Monaco separately.
Normal control selection uses a tint of the app foreground over its background.
editor.selectionBackground remains an editor text-selection color; it does not
set pressed buttons or selected navigation rows. Primary buttons derive missing
hover and pressed colors from their own palette, with readable text in each state.
Subtle surfaces, such as user messages, prefer sideBar.background. If it is absent
or blends into the canvas, the converter derives a visible surface. Transparent
colors are compared after compositing. Hover fallbacks account for both canvas
and panel backgrounds. Explicit application overrides remain authoritative.
Mapping precedence is explicit: app text prefers foreground over
editor.foreground; panels prefer editorWidget.background, then
panel.background, then sideBar.background. Menu state colors prefer their
menu.* pair over the corresponding list.* pair. Input and badge foregrounds
do not replace global text roles. text.selection supplies readable app text
selection over bg.accent-secondary.blue-medium.
Theme assets support hexadecimal colors (including alpha), inline tokenColors,
scope arrays and comma-separated scopes. Set the contribution’s mode explicitly
when possible; otherwise the asset’s type and background luminance determine it.
External include files and file-based TextMate syntax definitions are unsupported.
Inline their content before importing. Invalid or unsupported assets produce a
diagnostic and are omitted without preventing healthy themes from registering.
Semantic token rules are not imported. Validate text contrast, interactive states,
transparent and identical surfaces, portals, terminal colors, and theme changes
while project contributions load or are removed.
Views: filter, sort, and display
Kanban and data table bodies share one view model. A view stores:
filter: a rule is{ attributeId, condition, value }. Normal rules join with"and". Optionalgroupscontain one level of advanced rules, each withconjunction: "and" | "or"andrules. Normal rules and groups combine using AND. Whole-view OR filters remain supported and appear as one Advanced filter bubble in the dashboard. Groups cannot contain other groups.sorts: zero or one field and direction pair. Display settings and table headers edit this same single sort. An empty list keeps the board’s manual order, or the query’s order for a table.settings: board display settings (view mode, grouping, sub-grouping, visible properties), or table display settings (grouping,rowNumbers,wrapRows,showStats,hiddenColumns,columnOrder).
Search is screen state. It narrows what is on screen, is never saved, and is never sent to a query.
Boolean fields hold real true or false values. Their controls read as predicates, such as “Ticket is Archived” or “Ticket is not Archived”. Set the native view body’s resourceKind to a resource-kind ref to use its singular label as the subject; otherwise the subject is “Item”. The property label supplies the predicate. is false and is-not true show the same negative predicate; is-not also includes rows with no value. In the CLI, use --filter "archived is false". Data-table columns opt in with type: "boolean"; undeclared columns keep their existing text filters.
When changing an enum field to a boolean, declare its old stored IDs in type.legacyValues, for example { kind: "boolean", legacyValues: { active: false, archived: true } }. The host normalizes saved rules before cleanup, and the renderer normalizes local view state before edits. This map never coerces row values or allows old option lists in new API writes. Keep the map while saved views may still use those IDs.
Each field kind accepts a fixed list of conditions. VIEW_FILTER_CONDITIONS in @pstdio/sdk/extensions is the only copy, and the dashboard, the views API, and pst views all read it.
| Field kind | Conditions | Sortable |
|---|---|---|
string |
contains, does-not-contain, is, is-not, is-empty, is-not-empty |
yes |
boolean |
is, is-not, is-empty, is-not-empty |
yes |
number |
is, is-not, gt, gte, lt, lte, is-empty, is-not-empty |
yes |
date |
is, is-before, is-after, is-on-or-before, is-on-or-after, is-empty, is-not-empty |
yes |
enum, status, user |
is-any-of, is-none-of, is-empty, is-not-empty |
yes |
enum-multi |
has-any-of, has-all-of, has-none-of, is-empty, is-not-empty |
no |
A date value is a day (2026-10-02) or a day relative to today (today, today-7, today+7). Relative days resolve against the viewer’s date each time the view renders. Option values are compared by value ID. The board title is a built-in string field with ID title.
Declare the starting view with defaultFilter, defaultSorts, and defaultSettings, and multiple starting views with defaultViews:
defineView({
id: "tickets",
title: "Tickets",
body: {
kind: "kanban",
attributes,
query: queryTickets,
defaultFilter: {
conjunction: "and",
rules: [{ attributeId: "archived", condition: "is-any-of", value: ["active"] }],
},
defaultSorts: [{ attributeId: "created", direction: "desc" }],
defaultViews: [
{
id: "urgent",
title: "Urgent",
settings: { viewMode: "board", columnGrouping: "status", rowGrouping: "none", displayProperties: ["id"] },
filter: { conjunction: "and", rules: [{ attributeId: "priority", condition: "is-any-of", value: ["urgent"] }] },
sorts: [{ attributeId: "updated", direction: "desc" }],
},
],
},
});
Data table columns can declare type ("string", "number", or "date") and groupable: true. Without a type, a column whose values are all numbers is a number field and every other column is text. Columns are filterable by default. Declare filterable: false on a column to exclude it from Filter and reject saved rules for it. Query-returned columns use the same option and take precedence over declared columns. Disabling filtering keeps display, sorting, and grouping available. Only groupable columns appear under Grouping in the table’s Display menu. Tables group by exact value; empty values form a last “No
Inline charts and row height (on main)
Native table columns and the React DataTable support renderer: { type: "sparkline" }
and renderer: { type: "bar-chart" }. Supply a cell value as
{ values: [12, null, 8], labels: ["Run 1", "Run 2", "Run 3"] }.
Labels are optional. A null is an unmeasured gap; zero is a measurement.
Sparklines leave gaps and bar charts share a zero baseline, including signed values.
Entirely unmeasured cells show “No data”.
Both renderers accept an optional numeric domain: [minimum, maximum] to compare
cells on one scale, and a unit suffix such as "ms" or "MB". Without a domain,
each sparkline fits its data. Bar charts always expand their scale to include zero, even with an explicit domain. Chart columns sort
and filter by the last non-null measurement. Their accessible name includes the
labels and values. Hover a bar or sparkline position to see its measurement; focus
a chart with the keyboard to see all its labels and values. Tooltips also identify
unmeasured sparkline positions.
Set defaultSettings: { rowHeight: "tall" } to start with taller rows. The Display
menu offers Compact, Comfortable, and Tall; the selected height belongs to the
saved view. Bar labels and values stay in tooltips at every row height; larger rows show thicker bars.
The default stays compact for existing views. Row wrapping remains independent.
These additive declarations share the coordinated API 0.4.0 step on main.
Publish the supporting host, SDK, and UI before an independent extension uses them.
Image columns (on main)
Native table columns and the React DataTable support renderer: { type: "image" }. A cell value is an image URL, { src, alt }, or an array of either for a gallery. src is any image URL the dashboard can load, such as an https: or data:image/ URL; the host does not check the scheme. Prefer alt text: search, sorting, filtering and screen readers use it, falling back to the file name.
columns: [
{ id: "photo", label: "Photo", renderer: { type: "image" } },
{ id: "brand", label: "Brand", renderer: { type: "image", shape: "circle", fit: "contain", showLabel: true } },
],
// A row value: { photo: { src: "https://cdn.example.com/shoe.png", alt: "Trail shoe, side view" } }
Thumbnails fill the row, so Comfortable and Tall row heights show larger previews. A gallery shows three thumbnails and counts the rest. Clicking a thumbnail opens the shared image viewer without activating the row; a gallery opens as a carousel. An image that fails to load shows a placeholder, and an empty value shows a dash. fit is cover (default) or contain; shape is square (default) or circle; showLabel shows the first image’s alt text beside it. Image columns are text fields for filters. This addition shares API 0.5.0 on main; publish the host, SDK and UI before an independent extension adopts it.
The query receives filter, sorts, and the display settings. The new indexed collection query helpers infer paged providers, which apply these controls before returning a bounded page. Custom providers without an explicit query mode retain the full-result contract: the renderer applies filtering and sorting to their returned rows.
API 0.2.0 removes the fields deprecated in published package version 0.43.1. Migrate declarations and query handlers to the replacements below.
| Removed | Replacement |
|---|---|
defaultFilters: { status: ["todo"] } |
defaultFilter with an is-any-of rule (has-any-of for enum-multi) |
defaultSettings.ordering, settings.ordering in defaultViews |
defaultSorts, sorts; manual ordering is an empty list |
filters in defaultViews |
filter |
params.filters and params.settings.ordering in a kanban query |
params.filter and params.sorts |
The host sends only params.filter, params.sorts, and display settings. Historical saved-view migration still converts old stored filters and ordering; new declarations and requests must use the current fields.
Shared views
defaultViews defines the starting views for a collection with no saved views. The host saves them as ordinary project views that people and agents can edit, rename, reorder, and delete. At least one view must remain. defaultActiveViewId chooses the initial default. Saved project views and their shared default take precedence after initialization. Do not store a second copy in extension storage.
The host saves user-created views for kanban, resource list and data table views per project, extension instance and local view ID. Query-returned attributes, columns, and status options are used to validate settings, rules, and sorts. Keep field IDs stable across releases. A successful query can clean rules for removed fields and options from saved views; a failed query never removes them.
Use board view commands and APIs for agent workflows. KanbanRendererViewsSource and DataTableViewsSource supply shared views and asynchronous mutations to the UI renderers. The workbench accepts a subscribable views provider from its host. Standalone callers need a views source to persist view changes.
Resource lists
Available on main, after 0.46.0 (view.resourceList.v1). A resourceList body renders the native kanban detailed list with the shared view bar, filters, ordering and properties. It has one display, a grouping with any number of sub-groupings, and no row dragging. Extensions supply data through the public SDK; no webview is needed.
import { defineView } from "@pstdio/sdk/extensions";
const resources = defineView({
id: "resources",
title: "Resources",
body: {
kind: "resourceList",
attributes: [{
id: "device", label: "Device", groupable: true, filterable: true,
type: { kind: "enum", options: [
{ value: "local", label: "This device", color: "green", note: "Online", canCreate: true },
] },
}],
defaultSettings: { columnGrouping: "device", showChildren: true },
query: async () => ({ rows: [{
id: "workspace", title: "Improve search", icon: "folder",
attributes: { id: "WS-12", device: "local" },
children: [{ id: "session", title: "Check results", icon: "message-square", attributes: {} }],
}] }),
},
});
Enum options define group labels, dot colors and optional short note text. canCreate: true shows an Add action when the body also declares createRow. Its columnParam receives the group value, using the same creation form as kanban. Groups count parent resources and collapse independently. Children can have their own children; each level nests one indent further and collapses independently. Row IDs must be unique across parents and all levels of children.
Set subGroupings to further groupable attributes, outermost first, to split each group again, such as rules grouped by region, then channel, then severity. Each level uses a different attribute. Sub-groups count the loaded resources they contain and collapse independently; sub-groups without resources are absent. Add actions stay on the top-level groups. Without a grouping there are no sub-groupings. rowGrouping stays "none" for resource lists. Sub-groupings and deeper children share API 0.5.0 on main.
Groups without source resources are absent, so their Add actions are also absent. Supply a creation toolbar action for a new empty collection or to create the first resource in an unused group.
Rows reuse kanban shorthand (attributes.id), property chips, badges, dates and resource menus. Each row can declare an optional icon and navigation target. The Display menu offers Grouping, then Sub-grouping, Sub-grouping 2 and so on (added with Add sub-grouping), Child rows (Show or Hide), ordering and visible properties. defaultViews uses ResourceListRendererSettings: columnGrouping, displayProperties and optional subGroupings and showChildren. The host persists these alongside the filter and sorts using the existing collection-view store. Its wire settings also contain the fixed viewMode: "list" and rowGrouping: "none" fields.
See the example extension and the ResourceList onboarding Canvas preview. The shared list skeleton and empty state cover first load and empty queries. queryMode: "paged", refresh events, toolbar actions, row actions and activation callbacks follow the kanban contracts.
Sidenav levels
A page-owned content navigation tree starts a sidenav level. Its sections replace the mode content while that page or any child location is open. The nearest owner in the page location parent chain wins, so levels can nest. Pages with only header or footer trees do not start a level.
This extension adds a Recipes row to the project navigation. The row opens the Recipes page. That page owns the recipe-list tree, so the recipes replace the project navigation. Opening a recipe keeps the level, because the Recipe page declares Recipes as its parent.
import {
defineExtension,
defineNavigationItem,
defineNavigationTree,
definePage,
defineResourceKind,
defineView,
workbenchModes,
} from "@pstdio/sdk/extensions";
const recipe = defineResourceKind({ id: "recipe", label: "Recipe", icon: "chef-hat" });
const recipes = [
{ id: "pancakes", title: "Pancakes" },
{ id: "ramen", title: "Ramen" },
];
const recipeView = defineView({
id: "recipe",
title: "Recipe",
body: { kind: "controls", query: async () => ({ values: {} }) },
});
// Opening this page starts the Recipes level.
const recipesPage = definePage({
id: "recipes",
title: "Recipes",
path: "recipes",
mode: workbenchModes.project,
main: { kind: "panels", empty: recipeView.ref },
slots: [],
});
// A child page keeps the Recipes level open through its declared parent.
const recipePage = definePage({
id: "recipe",
title: "Recipe",
path: "recipe",
mode: workbenchModes.project,
parent: recipesPage.ref,
resource: { kinds: [recipe.ref] },
main: { kind: "view", view: recipeView.ref, cardinality: "one" },
slots: [],
});
const recipeList = defineView({
id: "recipe-list",
title: "Recipes",
body: {
kind: "tree",
body: async () => [
{
id: "recipes",
label: "Recipes",
collapsible: false,
nodes: recipes.map(({ id, title }) => {
const resource = { type: recipe.id, id, label: title };
return {
id,
label: title,
icon: "chef-hat",
resource,
target: { kind: "page", page: recipePage.ref, resource },
};
}),
},
],
},
});
export default defineExtension({
resourceKinds: [recipe],
views: [recipeView, recipeList],
pages: [recipesPage, recipePage],
navigationItems: [
// The main level shows one row that opens the level.
defineNavigationItem({
id: "recipes",
owner: workbenchModes.project,
slot: "content",
label: "Recipes",
icon: "chef-hat",
group: "",
action: { kind: "page", page: recipesPage.ref },
}),
],
navigationTrees: [
// A page owner starts a level instead of adding rows to the project navigation.
defineNavigationTree({
id: "recipe-list",
owner: recipesPage.ref,
slot: "content",
view: recipeList.ref,
resourceScope: "project",
}),
],
});
The header and footer keep the mode’s sections, followed by the sections of every open level from the outermost inward. Header rows therefore stay visible in nested levels. Rows that users drag into the header or footer also stay there inside levels.
Inside a level, the shared Sidenav adds a fixed left-arrow button labeled Back to followed by the current mode name, such as Back to project. It is the first entry in the main navigation content, with the same padding and row spacing as other entries. It cannot be moved or hidden. Selecting it opens the last root-level page, or the configured default when no root-level page has been used. The breadcrumb and browser history also remain available.
The same action is available with Alt+Shift+Up, both outside and inside shortcut mode. Its shortcut hint appears on the return row in keyboard mode, and it is listed under the current mode’s name in shortcut discovery and the command palette.
Users can hide and reorder a level’s labeled sections, but its rows keep the order their owner gives them.
A level page without a declared parent, such as Notes, has nothing outside the level in its breadcrumb. The host then leads that breadcrumb with a project crumb. It opens the last location the user visited outside every level, or the start page when there is none. A page whose mode sets chrome.sidenav also hides the project rows, so it counts as a level here. Extensions need no code for this: declare a parent when the level belongs under another page, and leave it out when the level is a top-level page.
For example, Notes contributes one mode-owned navigation item opening its Notes page. Its note-list tree is owned by that page. Notes are top-level rows in a section with a New note action. A compound target opens the Notes page and pins the chosen note panel; the location remains in the Notes level. To add sections at the main level, own them with the mode instead of a page.
Session commands contributed through sessionSlots.headerPrimary or sessionSlots.headerOverflow also appear in shared session resource menus. Session tree rows must set resource explicitly, even when target.resource already names the session. Visibility and execution use the clicked session; opening a different resource first is not required. Open session panel remains a host command for other callers; it is not contributed to session item menus. Session tab and current-page breadcrumb menus add the Sessions group with New session, Switch session, and View all sessions. Switch session opens a scoped resource search modal.
Queued conversation requests
The host provides these project-scoped ctx.sessions methods:
getQueuedFollowUps(sessionId)returns full saved requests, their revisions, and the active run precondition.updateQueuedFollowUp(sessionId, queuePosition, input)saves the full request and returns its new revision. SendexpectedRevision; omitted fields retain saved values.model: nullselects the provider default,params: nullresets supported defaults, andattachments: []clears references.combineQueuedFollowUps(sessionId, targetPosition, { sourcePosition, sourceRevision, targetRevision })atomically combines compatible requests.steerQueuedFollowUp(sessionId, queuePosition, { expectedRevision, expectedRunStartedAt })returns an accepted, rejected, or uncertain outcome.
An active HarnessSession may provide steer({ deliveryId, prompt, attachments, signal }). It must use native input without cancelling or starting a turn. Before returning accepted, emit exactly one normalized user message whose ID is deliveryId. Native history must preserve that correlation for recovery. A successful pipe write alone is insufficient. A transport failure after input may have been sent is uncertain. Only return rejected when native input was definitely refused. Older harnesses remain supported without this optional method.
Publish the additive SDK before harness extensions adopt it. Codex native acceptance and persisted clientUserMessageId were verified on 0.160.0. Claude Code 2.1.294 validation is blocked by a weekly usage limit; OpenCode is unverified. This host change enables neither adapter by itself.
Paged tables and boards
On unreleased API 0.5.0, defineView defaults queries created by
collectionViewQuery or collectionTableQuery to queryMode: "paged". Existing
custom callbacks retain their full-result contract when rebuilt with the new SDK;
custom bounded providers explicitly set queryMode: "paged". For a genuinely small fixed list,
declare queryMode: "static" and maxRows between 1 and 500. The host checks
the bound, including nested rows. Both modes reject complete collection reads
through storage or workspace APIs, including nested command calls. Query only
the required projections and use database aggregates for counts. Providers without an explicit bounded mode retain their existing full-result contract.
Kanban and resource-list views can set supportsFieldsOnly: true when their
filter options can be read independently of their rows. For saved-view validation
the host then invokes query with fieldsOnly: true. Return all current
attributes, including dynamic enum options. The result may use rows: [].
Paged providers still return their usual page metadata. The host preserves saved
filters when field discovery fails or the attributes are missing. Older hosts
continue to request rows.
For a new resource, use collectionViewQuery({ index, attributes, resourceKind })
from @pstdio/sdk/extensions, or collectionTableQuery({ index, columns, resourceKind }). defineExtension installs their collection-scoped index before
queries run. These helpers translate filters, search, the first supported sort,
grouping and collapsed groups before selection. Table helpers also return
requested statistics for scalar projections. Date controls use the viewer’s
calendar; option search uses resolved display labels and text sorting uses the
viewer locale with numeric, case-insensitive ordering. Custom display values
need explicit query projections and matching search predicates through fields.
Dynamic computed or related date values must supply date.dayField,
date.textField, and orderField projections for the controls they expose.
Declared local dates and literal or conditional computed dates are formatted by
the helper using the viewer’s locale and time zone.
Publish the supporting host and SDK before releasing independent consumers.
The host passes params.page with a limit of at most 500, a zero-based offset,
optional cursor and expected revision, search text, selected field IDs, and
collapsed table group keys. page.presentation supplies resolved option labels
and empty-group keys so query search and collapse match the native controls.
Set initialPageSize on a paged table or board to
request a larger page; tables can also offer pageSizeOptions. Fields include
visible columns/properties and active grouping fields. page.searchFields
separately names the displayed searchable fields. Badge-list displays also
request their companion item field. Apply params.filter, params.sorts, and
search to the complete indexed collection before selecting a page. Return the
requested fields and only the bounded rows.
Do not load every record to calculate a page, group count, badge, or total.
Preserve the controls’ filter semantics. Scalar string is and is-not use
locale-independent JavaScript lowercase matching, as do contains and
does-not-contain. Map them to the public equalsIgnoreCase, contains, and
not storage predicates. An empty text rule is incomplete and does not filter
rows; use empty and notEmpty for the explicit empty-value controls.
Search trims surrounding whitespace and uses the same locale-independent
lowercase rule. It matches displayed text: visible table columns, or the board’s
title and displayed properties. A selected grouping field can still be hidden
and must not become searchable only because it occurs in page.fields.
textContains supports ordinary string, number, and boolean display text.
Providers with date labels, custom display labels, diff summaries, or other
formatted cells must translate searches to those display semantics before
paging; matching their raw stored value is not equivalent.
Return { rows, page }, where page contains:
revision: the committed owner/query revision shared by rows and aggregates.cursor: the next opaque cursor, ornullat the end.total: rows matching the view filter before search.filteredTotal: rows matching filter and search, excluding collapsed table groups.groups: complete grouping counts, each withfield,value, andcount. Subgroups also identify their parent field/value. Missing values usenull. At most 500 grouped combinations produce at most 1,000 parent/subgroup summaries.statistics: requested table column summaries, keyed by field ID, when a visible statistics control requests them. Never calculate these from one page.
Use declared storageIndexes, ctx.storage.records.query, and aggregate to
serve these requests. Select the index matching the requested ordering, including
a stable tie order. Check that every aggregate revision matches the selected page.
When page.cursor is present, pass it to storage and omit offset; otherwise
pass offset. Pass page.revision in either case. Direct page navigation therefore
uses one indexed query, without visiting earlier cursors. See
direct page navigation.
Resolve related records only for returned rows, using readMany or
ctx.resources.identityMany batches of at most 100. Keep full bodies out of row
responses unless those bodies are the explicitly selected content. Row and
selection actions receive the selected row IDs and can read their details when
the action runs. Selection retains explicitly chosen rows across table pages;
Select all selects loaded rows, not unseen records.
Table page controls and board scrolling request new pages. Board columns and lists also provide a keyboard-accessible Load more action. A column can have a positive complete count before any of its cards occur in the loaded page; the load action requests the next bounded page rather than fetching the whole group. During table navigation, the visible page label and row numbers stay with the accepted rows, while a loading status names the requested page. Changing search, filters, ordering, display fields, or grouping starts from the first page. An obsolete request is cancelled and cannot replace a newer page. Refresh events remain scoped to the renderer; after an edit they reset its page sequence while keeping the previous rows visible until the replacement arrives. A stale revision keeps those rows and shows Retry, which reloads from the first page.
Project setup views (API 0.3.1 on main)
An optional projectSetup: { view, hiddenSetting? } on defineExtension offers an owned,
declared view after a newly created project opens. The host waits for authoritative enabled
setup contributions before opening anything; absent, disabled or hidden setup shows no setup UI.
Multiple contributions run in declaration order;
closing one advances to the next. Ordinary project navigation does not replay setup.
hiddenSetting names a declared boolean extension setting. When true it suppresses automatic
setup; a device-scoped setting shares this preference across projects. Unknown or nonboolean
keys fail extension validation. Disabling/removing an active setup contribution closes its view.
The host owns the dialog and focus trap: webviews render standalone content with their own
providers, without nested dialogs. Declare placement.close to let Skip/Finish close the calling
overlay; that capability cannot close another placement.
Reopening a folder that already has a project does not offer setup. Disabled or removed
extensions contribute no setup. These additions require a published SDK and host containing
API 0.3.1 and project-setup.v1.
Dashboard commands and session ordering (API 0.3.1 on main)
Dashboard webviews with commands.execute can use public workbenchCommands refs: newConversation, openToolSearch, retryProjectSetup, and recentResources. Pass the ref’s id to the host capability. Commands run in the webview’s selected project; stale project invocations are rejected. Setup retry uses the existing project setup service and returns only after it finishes. recentResources returns the five most recently opened resources in the selected project with their explicit navigation targets. It uses this device’s saved navigation activity, preserves resource ownership, and uses live built-in metadata and last-seen extension presentation refreshed by the normal view lifecycle. Removed or unavailable resources are omitted. Subscribe to viewDataEvents.recentResourcesChanged to refresh while a view remains open. These are dashboard commands, not server-side extension commands or CLI actions. Publish the SDK and host before extensions adopt these additions.
ctx.sessions.query({ orderBy: "updated", limit: 5 }) returns the most recently updated conversations. Unlike lastActivity, this order uses only updatedAt, with descending IDs to break ties. Its cursor preserves that order across local and synced personal history.
Sessions provider navigation
sessionBrowser and sessionBrowserId are implementation-free public refs for pstdio.session-browser. Use sessionBrowser.pages.sessions for browsing, pages.session with a canonical pstdio session resource for a full conversation, and panels.conversation for shared Side chat. pages.compose is the landing composer; pages.draft accepts a canonical pstdio session-draft resource. views.conversation and views.list let compatibility definitions use the same installed renderer without another chat or persistence owner. Missing or disabled providers use ordinary unavailable-target feedback.
sessionBrowser.commands.create accepts optional workspaceId, harnessId, deviceId, side, and replace. commands.open accepts a required sessionId plus optional side and replace. Use command refs through public command/navigation APIs; replace switches the invoking viewer and preserves its placement. These refs declare the provider contract; the SDK/host prerequisite does not install that provider. Publish supporting SDK packages before production adoption.
The old workbenchPages.sessions, session, newSession, sessionComposer, workbenchPanels.projectSession, and workbenchCommands.newConversation refs remain at their original identities and are deprecated in favor of these provider refs. The adoption stage supplies thin legacy definitions; remove deprecated public refs only together in a breaking release.
Resource mutation commands can act on another provider’s canonical resource. When the invoking resource matches the declared mutation type and resolved ID in the selected project, native optimistic previews and write serialization preserve that resource’s identity. Without a matching subject, the command’s own extension identity remains the default. This changes presentation ownership only; the command service still enforces its normal permissions and scope.
Updated at: 2026-11-17