Interface: WorkspaceService
Defined in: packages/sdk/src/workspace-service.ts:232
Consumer API for workspace state, exposed as ExtensionContext.workspaces. Read via getState / subscribe; drive via the create/rename/ close methods. Opening editor tabs lives on ExtensionContext.editors, not here.
Methods
getState()
getState(): WorkspaceState;Defined in: packages/sdk/src/workspace-service.ts:234
Current frozen view of workspace state.
Returns
subscribe()
subscribe(listener): Disposable;Defined in: packages/sdk/src/workspace-service.ts:235
Parameters
listener
(s) => void
Returns
get()
get(id): Workspace | undefined;Defined in: packages/sdk/src/workspace-service.ts:240
The workspace with this id, or undefined. A one-shot lookup for event handlers; for reactive reads use useServiceState over the state.
Parameters
id
string
Returns
Workspace | undefined
createFromFolderPicker()
createFromFolderPicker(): Promise<Workspace | null>;Defined in: packages/sdk/src/workspace-service.ts:242
Show a folder picker and create a workspace from the chosen folder.
Returns
Promise<Workspace | null>
create()
create(input): Workspace;Defined in: packages/sdk/src/workspace-service.ts:243
Parameters
input
Returns
rename()
rename(id, name): void;Defined in: packages/sdk/src/workspace-service.ts:244
Parameters
id
string
name
string
Returns
void
reorder()
reorder(
from,
to,
position): void;Defined in: packages/sdk/src/workspace-service.ts:251
Move a workspace to a new position relative to a reference workspace.
Parameters
from
string
Id of the workspace being dragged / moved.
to
string
Id of the reference workspace (the insertion anchor).
position
"before" | "after"
Whether to place from before or after to.
Returns
void
activate()
activate(id): void;Defined in: packages/sdk/src/workspace-service.ts:253
Activate (and reopen if closed).
Parameters
id
string
Returns
void
close()
close(id): void;Defined in: packages/sdk/src/workspace-service.ts:255
Soft close — workspace stays saved but is hidden from the active list.
Parameters
id
string
Returns
void
reopen()
reopen(id): void;Defined in: packages/sdk/src/workspace-service.ts:257
Reverse of close.
Parameters
id
string
Returns
void
addFolder()
addFolder(id, folder): void;Defined in: packages/sdk/src/workspace-service.ts:259
Add an extra folder to a workspace (no-op if already present or is the primary).
Parameters
id
string
folder
string
Returns
void
removeFolder()
removeFolder(id, folder): void;Defined in: packages/sdk/src/workspace-service.ts:261
Remove an extra folder from a workspace.
Parameters
id
string
folder
string
Returns
void
delete()
delete(id): Promise<void>;Defined in: packages/sdk/src/workspace-service.ts:270
Hard delete — permanent removal. Also reaps every terminal in the workspace (removes records and kills live PTY sessions); callers do not need a separate TerminalService.closeWorkspace step. The entry is removed from state synchronously (before this returns); the returned promise resolves once the reaped PTYs have actually been killed, for callers (e.g. tests) that need that guarantee. Most callers can ignore it.
Parameters
id
string
Returns
Promise<void>
setStatus()
setStatus(workspaceId, row): void;Defined in: packages/sdk/src/workspace-service.ts:276
Imperatively adorn a workspace row with a status line. row.id is the adornment key for WorkspaceService.clearStatus.
Parameters
workspaceId
string
row
Returns
void
clearStatus()
clearStatus(workspaceId, rowId): void;Defined in: packages/sdk/src/workspace-service.ts:279
Remove an imperative status row previously set via WorkspaceService.setStatus.
Parameters
workspaceId
string
rowId
string
Returns
void
bindStatus()
bindStatus(binder): Disposable;Defined in: packages/sdk/src/workspace-service.ts:299
Keep a status projection in sync for every workspace. provide returns an array of rows (may be empty). Prefer this over repeatedly calling WorkspaceService.setStatus.
Parameters
binder
Returns
Example
ctx.subscriptions.push(
ctx.workspaces.bindStatus({
id: "my-ext.status",
provide(workspaceId) {
const running = getRunningTasks(workspaceId);
return running.map(t => ({ id: t.id, activity: "working", label: t.name, startedAt: t.startedAt }));
},
}),
);registerStatus()
registerStatus(provider): Disposable;Defined in: packages/sdk/src/workspace-service.ts:304
Parameters
provider
Returns
Deprecated
Prefer WorkspaceService.bindStatus.
getStatus()
getStatus(workspaceId): WorkspaceStatusRow[];Defined in: packages/sdk/src/workspace-service.ts:311
Concatenate imperative rows and all binders' rows for one workspace (in binder registration order). Called synchronously during panel render — binders must be fast and side-effect-free.
Parameters
workspaceId
string
Returns
invalidateStatus()
invalidateStatus(): void;Defined in: packages/sdk/src/workspace-service.ts:322
Signal that binder data has changed. Fires all listeners registered via WorkspaceService.subscribeStatus, causing the Workspaces panel to re-query binders and re-render the status rows.
Call this after any mutation to the state your provide function reads. Imperative WorkspaceService.setStatus / WorkspaceService.clearStatus already notify listeners.
Returns
void
subscribeStatus()
subscribeStatus(listener): Disposable;Defined in: packages/sdk/src/workspace-service.ts:330
Subscribe to status invalidations. The listener is called whenever WorkspaceService.invalidateStatus is invoked (or imperative set/clear runs). Returns a Disposable that cancels the subscription.
Parameters
listener
() => void
Returns
registerSection()
registerSection(provider): Disposable;Defined in: packages/sdk/src/workspace-service.ts:354
Register a section provider that mounts a React component inside workspace rows in the Workspaces side panel. Returns a Disposable that unregisters the provider and unmounts the component from all rows.
Return null from your component for workspaces where the section should not appear — this produces no DOM node and no visual gap.
Parameters
provider
Returns
Example
ctx.subscriptions.push(
ctx.workspaces.registerSection({
id: "my-ext.section",
component: ({ workspaceId }) => {
const ws = ctx.workspaces.get(workspaceId);
if (!ws?.terminals.length) return null;
return <MyCard terminals={ws.terminals} />;
},
}),
);subscribeSection()
subscribeSection(listener): Disposable;Defined in: packages/sdk/src/workspace-service.ts:371
Subscribe to section registration changes. The listener is called whenever a WorkspaceSectionProvider is registered or unregistered. Returns a Disposable that cancels the subscription.
The Workspaces panel subscribes internally to re-render when providers are added or removed.
No invalidateSection by design. Unlike status rows and badges, a section is a live React component that re-renders on its own internal or context-driven state changes — it is not a snapshot returned from a provide() call, so there is nothing for the host to re-query. If a section needs to trigger a full workspace-panel refresh (rare), it should update its own state directly.
Parameters
listener
() => void
Returns
registerPropertyPage()
registerPropertyPage(page): Disposable;Defined in: packages/sdk/src/workspace-service.ts:396
Register a property page that adds a tab to the workspace properties modal. The host composes all registered pages into the modal's tab bar, after the built-in General tab. The extension is responsible for persisting its settings via ctx.storage.workspace, immediately on change — the modal has no Save button.
Returns a Disposable that unregisters the page and unmounts the component from any open properties modal.
Parameters
page
Returns
Example
ctx.subscriptions.push(
ctx.workspaces.registerPropertyPage({
id: "silo.github-actions.properties",
title: "GitHub Actions",
icon: <IconGitHub size={14} />,
component: GhActionsWorkspaceSettings,
visible: (ws) => hasDetectedRepo(ws.id),
}),
);getOpenWorkspaceMenuItems()
getOpenWorkspaceMenuItems(): Promise<MenuEntry[]>;Defined in: packages/sdk/src/workspace-service.ts:422
The rows of the Open Workspace menu — the same menu the Navigator's + button opens: any saved groups, then closed workspaces to reopen (a missing folder is flagged), a separator, then "New workspace…" and "New Group…".
Use it to offer workspace switching from your own UI without rebuilding the list — the returned entries drop straight into UiService.showMenu, including as a submenu of one of your own rows. Async because the closed-workspace rows check whether each folder still exists on disk.
Returns
Promise<MenuEntry[]>
Example
ctx.ui.showMenu({
items: [
{ label: "Refresh", run: refresh },
{ type: "separator" },
{ label: "Workspace", submenu: await ctx.workspaces.getOpenWorkspaceMenuItems() },
],
anchor,
});getWorkspaceMenuItems()
getWorkspaceMenuItems(workspaceId): MenuEntry[];Defined in: packages/sdk/src/workspace-service.ts:450
The rows of one workspace's context menu — Properties…, Close, then whatever extensions contributed on the "workspace"surface.
Use it when your own UI names a workspace without being the workspace list — an agent row showing which workspace its terminal lives in, a search result grouped by workspace — so the same actions are one right-click away there too. Returns an empty array for an unknown id.
Group membership actions (Move to Group, Remove from Group) are not included: group state is host-internal (ADR 0023), so the Workspaces view appends those itself.
Parameters
workspaceId
string
Returns
Example
ctx.ui.showMenu({
items: [
{ label: "Mark as seen", run: acknowledge },
{ type: "separator" },
{ label: ws.name, submenu: ctx.workspaces.getWorkspaceMenuItems(ws.id) },
],
at: { x: e.clientX, y: e.clientY },
});setBadge()
setBadge(workspaceId, badge): void;Defined in: packages/sdk/src/workspace-service.ts:456
Imperatively adorn a workspace name with a badge. badge.id is the adornment key for WorkspaceService.clearBadge.
Parameters
workspaceId
string
badge
Returns
void
clearBadge()
clearBadge(workspaceId, badgeId): void;Defined in: packages/sdk/src/workspace-service.ts:459
Remove an imperative badge previously set via WorkspaceService.setBadge.
Parameters
workspaceId
string
badgeId
string
Returns
void
bindBadge()
bindBadge(binder): Disposable;Defined in: packages/sdk/src/workspace-service.ts:479
Keep a badge projection in sync for every workspace. provide returns an array of badges (may be empty).
Parameters
binder
Returns
Example
ctx.subscriptions.push(
ctx.workspaces.bindBadge({
id: "my-ext.badges",
provide(workspaceId) {
const status = getStatus(workspaceId);
if (!status) return [];
return [{ id: "status", text: status.label, color: status.color }];
},
}),
);registerBadge()
registerBadge(provider): Disposable;Defined in: packages/sdk/src/workspace-service.ts:484
Parameters
provider
Returns
Deprecated
Prefer WorkspaceService.bindBadge.
getBadges()
getBadges(workspaceId): WorkspaceBadge[];Defined in: packages/sdk/src/workspace-service.ts:490
Concatenate imperative badges and all binders' badges for one workspace (in binder registration order).
Parameters
workspaceId
string
Returns
invalidateBadges()
invalidateBadges(): void;Defined in: packages/sdk/src/workspace-service.ts:496
Signal that badge binder data has changed. Imperative set/clear already notify listeners.
Returns
void
subscribeBadges()
subscribeBadges(listener): Disposable;Defined in: packages/sdk/src/workspace-service.ts:501
Subscribe to badge invalidations.
Parameters
listener
() => void