bb.workspace and bb.workspace-ui

The headless bb.workspace plugin owns workspace data and routing. The bb.workspace-ui plugin presents projects and environments.

Purpose

bb.workspace gives app and server plugins one stable workspace model. It owns projects, environments, routing, and environment providers.

bb.workspace-ui supplies the default project switcher and environment pages. It requires the bb.workspace service.

The data plugin has consumers beyond its own UI. It therefore ships headless and carries no presentation assumptions.

The bb.workspace plugin (data)

bb.workspace declares no surfaces. A service replacement does not need to implement React components, pages, or shell controls.

Surfaces

bb.workspace-ui owns workspace presentation. The data service returns no React nodes, icons, colors, or renderer choices.

Services

bb.workspace

The service token matches by ID and semver. A required consumer restarts after a winner change. The first-party implementation uses kernel storage, realtime, host RPC, and HTTP ports.

import { defineService } from "@get-bb/plugin/server";

export const workspaceService = defineService<WorkspaceService>(
  "bb.workspace",
  "1.0",
);

export interface WorkspaceService {
  readonly projects: WorkspaceProjects;
  readonly environments: WorkspaceEnvironments;
  readonly hosts: WorkspaceHosts;
  readonly terminals: WorkspaceTerminals;
  readonly routing: WorkspaceRouting;
  watch(listener: (event: WorkspaceSystemChangeEvent) => void): Dispose;
}

export interface WorkspaceProjects {
  list(query?: ProjectListQuery): Promise<ProjectPage>;
  get(projectId: ProjectId): Promise<Project>;
  create(input: ProjectCreateInput): Promise<Project>;
  update(projectId: ProjectId, patch: ProjectPatch): Promise<Project>;
  delete(projectId: ProjectId): Promise<{ deleted: true }>;
  reorder(projectIds: readonly ProjectId[]): Promise<readonly ProjectId[]>;

  branches(input: ProjectBranchesInput): Promise<readonly BranchInfo[]>;
  commands(projectId: ProjectId): Promise<readonly ProjectCommand[]>;
  defaultExecutionOptions(projectId: ProjectId): Promise<ExecutionDefaults>;
  files(input: ProjectFilesInput): Promise<ProjectFilePage>;
  fileContent(input: ProjectFileContentInput): Promise<ProjectFileContent>;
  paths(projectId: ProjectId): Promise<readonly WorkspacePath[]>;
  promptHistory(input: ProjectPromptHistoryInput): Promise<PromptHistoryPage>;
  catalogSnapshot(query?: ProjectListQuery): Promise<ProjectCatalogSnapshot>;

  readonly attachments: WorkspaceProjectAttachments;
  readonly sources: WorkspaceProjectSources;

  watch(
    selector: { projectId?: ProjectId },
    listener: (event: ProjectChangeEvent) => void,
  ): Dispose;
}

export interface WorkspaceProjectAttachments {
  copy(input: ProjectAttachmentCopyInput): Promise<void>;
  read(input: ProjectAttachmentReadInput): Promise<ProjectAttachmentContent>;
  upload(input: ProjectAttachmentUploadInput): Promise<ProjectAttachment>;
}

export interface WorkspaceProjectSources {
  add(projectId: ProjectId, input: ProjectSourceCreateInput): Promise<ProjectSource>;
  update(sourceId: SourceId, patch: ProjectSourcePatch): Promise<ProjectSource>;
  delete(sourceId: SourceId): Promise<{ deleted: true }>;
}

export interface WorkspaceEnvironments {
  list(query?: EnvironmentListQuery): Promise<EnvironmentPage>;
  get(environmentId: EnvironmentId): Promise<Environment>;
  update(environmentId: EnvironmentId, patch: EnvironmentPatch): Promise<Environment>;
  archiveThreads(environmentId: EnvironmentId): Promise<{ archivedThreadIds: ThreadId[] }>;

  providers(hostId: HostId): Promise<readonly EnvironmentProviderDescriptor[]>;
  provision(
    input: EnvironmentProvisionInput,
    options?: { signal?: AbortSignal },
  ): AsyncIterable<EnvironmentProvisionEvent>;
  reconnect(environmentId: EnvironmentId): Promise<Environment>;
  destroy(
    environmentId: EnvironmentId,
    options?: { signal?: AbortSignal },
  ): Promise<void>;

  status(input: EnvironmentStatusInput): Promise<EnvironmentStatus>;
  paths(environmentId: EnvironmentId): Promise<readonly WorkspacePath[]>;
  commit(input: EnvironmentCommitInput): Promise<CommitResult>;
  squashMerge(input: EnvironmentSquashMergeInput): Promise<SquashMergeResult>;
  diff(input: EnvironmentDiffInput): Promise<EnvironmentDiff>;
  diffBranches(environmentId: EnvironmentId): Promise<readonly BranchInfo[]>;
  diffFiles(input: EnvironmentDiffInput): Promise<EnvironmentDiffFilePage>;
  diffFile(input: EnvironmentDiffFileInput): Promise<EnvironmentDiffFile>;
  diffPatch(input: EnvironmentDiffPatchInput): Promise<EnvironmentPatchResult>;

  pullRequest(environmentId: EnvironmentId): Promise<EnvironmentPullRequest | null>;
  markPullRequestDraft(environmentId: EnvironmentId): Promise<EnvironmentPullRequest>;
  markPullRequestReady(environmentId: EnvironmentId): Promise<EnvironmentPullRequest>;
  mergePullRequest(input: EnvironmentPullRequestMergeInput): Promise<MergeResult>;

  watch(
    selector: { environmentId?: EnvironmentId },
    listener: (event: EnvironmentChangeEvent) => void,
  ): Dispose;
}

export interface WorkspaceHosts {
  list(): Promise<readonly HostRecord[]>;
  get(hostId: HostId): Promise<HostRecord>;
  update(hostId: HostId, patch: HostPatch): Promise<HostRecord>;
  delete(hostId: HostId): Promise<{ deleted: true }>;
  directory(input: HostDirectoryInput): Promise<HostDirectoryPage>;
  pathsExist(hostId: HostId, paths: readonly string[]): Promise<readonly boolean[]>;
  pickFolder(hostId: HostId, options?: FolderPickerOptions): Promise<string | null>;
  cloneDefaultPath(hostId: HostId, projectId: ProjectId): Promise<string>;
  createJoinCode(): Promise<HostJoinCode>;
  retryUpdate(hostId: HostId): Promise<HostRecord>;
  providerCliStatus(hostId: HostId, providerId: string): Promise<ProviderCliStatus>;
  installProviderCli(hostId: HostId, providerId: string): Promise<ProviderCliInstallResult>;
  watch(listener: (event: HostChangeEvent) => void): Dispose;
}

export interface WorkspaceTerminals {
  list(scope: TerminalScope): Promise<readonly TerminalRecord[]>;
  create(input: TerminalCreateInput): Promise<TerminalRecord>;
  get(terminalId: string): Promise<TerminalRecord>;
  input(terminalId: string, data: string): Promise<void>;
  output(terminalId: string, cursor?: string): Promise<TerminalOutput>;
  resize(terminalId: string, columns: number, rows: number): Promise<void>;
  rename(terminalId: string, title: string): Promise<TerminalRecord>;
  restart(terminalId: string): Promise<TerminalRecord>;
  close(terminalId: string): Promise<void>;
}

export type WorkspaceSystemChangeEvent =
  | { kind: "host"; hostId: HostId | null }
  | { kind: "environment"; environmentId: EnvironmentId | null }
  | { kind: "project"; projectId: ProjectId | null };

export interface WorkspaceRouting {
  parse(url: URL): WorkspaceRoute | null;
  href(target: WorkspaceTarget): string;
  context(route: WorkspaceRoute): WorkspaceContext;
}

The watch methods replace entity filters on the broad old realtime subscription. A watched service edge receives provider availability changes without a plugin restart.

The service uses the following record shapes.

export type ProjectId = string & { readonly __projectId: unique symbol };
export type EnvironmentId = string & { readonly __environmentId: unique symbol };
export type HostId = string & { readonly __hostId: unique symbol };
export type SourceId = string & { readonly __sourceId: unique symbol };
export type ThreadId = string & { readonly __threadId: unique symbol };

export interface Project {
  id: ProjectId;
  name: string;
  description: string | null;
  personal: boolean;
  order: number;
  sources: readonly ProjectSource[];
  createdAt: string;
  updatedAt: string;
}

export interface ProjectSource {
  id: SourceId;
  projectId: ProjectId;
  hostId: HostId;
  path: string;
  gitRemoteUrl: string | null;
  default: boolean;
}

export interface Environment {
  id: EnvironmentId;
  projectId: ProjectId;
  hostId: HostId;
  providerId: EnvironmentProviderId;
  state: "provisioning" | "ready" | "retiring" | "destroying" | "destroyed" | "failed";
  managed: boolean;
  handle: JsonObject | null;
  summary: EnvironmentSummary | null;
  createdAt: string;
  updatedAt: string;
}

export interface EnvironmentSummary {
  label: string;
  path: string | null;
  isRepo: boolean;
  isWorktree: boolean;
  branch: string | null;
  baseBranch: string | null;
  defaultBranch: string | null;
}

export type EnvironmentProvisionEvent =
  | { kind: "progress"; step: string; text: string; status: "started" | "completed" | "failed" }
  | { kind: "output"; line: string }
  | { kind: "ready"; environment: Environment };

export type WorkspaceTarget =
  | { kind: "compose"; projectId?: ProjectId; initialPrompt?: string; focusPrompt?: boolean }
  | { kind: "project"; projectId: ProjectId }
  | { kind: "environment"; environmentId: EnvironmentId; subPath?: string }
  | { kind: "thread"; threadId: ThreadId }
  | { kind: "plugin-panel"; pluginId: string; path: string; subPath?: string }
  | { kind: "thread-panel"; threadId: ThreadId; panelId: string; params?: JsonValue }
  | { kind: "file-preview"; source: WorkspaceFileSource; path: string }
  | { kind: "file-external"; source: WorkspaceFileSource; path: string }
  | { kind: "url"; url: string };

export type WorkspaceRoute = Exclude<
  WorkspaceTarget,
  { kind: "file-external" | "url" }
>;

export interface WorkspaceContext {
  projectId: ProjectId | null;
  environmentId: EnvironmentId | null;
  threadId: ThreadId | null;
  route: WorkspaceRoute;
}

Methods use explicit input records for operations with more than one value. All list methods return bounded pages and a continuation token. The generated contract.json contains the complete schemas and limits.

bb.workspace.envProvider

This keyed contract uses EnvironmentProviderId as its key. The key has the form <pluginId>/<name>. One winner serves each key.

export type EnvironmentProviderId = `${string}/${string}`;

export const environmentProvider = defineKeyedService<
  EnvironmentProviderId,
  EnvironmentProviderService
>("bb.workspace.envProvider", "1.0");

export interface EnvironmentProviderService {
  describe(): Promise<EnvironmentProviderDescriptor>;
  provision(
    request: ProviderProvisionRequest,
    options?: { signal?: AbortSignal },
  ): AsyncIterable<ProviderProvisionEvent>;
  reconnect(request: ProviderReconnectRequest): Promise<EnvironmentHandle>;
  destroy(
    request: ProviderDestroyRequest,
    options?: { signal?: AbortSignal },
  ): Promise<void>;
  summarize(handle: EnvironmentHandle): Promise<EnvironmentSummary>;
}

export interface EnvironmentProviderDescriptor {
  id: EnvironmentProviderId;
  label: string;
  ownsRoot: boolean;
  optionsSchema: JsonSchema;
}

export type EnvironmentHandle =
  | {
      kind: "local-path";
      root: string;
      writeRoots: readonly string[];
      persisted: JsonObject;
    }
  | {
      kind: "custom";
      writeRoots: readonly string[];
      persisted: JsonObject;
    };

export interface ProviderProvisionRequest<Options extends JsonObject = JsonObject> {
  environmentId: EnvironmentId;
  projectId: ProjectId;
  hostId: HostId;
  source: ProjectSource | null;
  options: Options;
}

export interface ProviderReconnectRequest {
  environmentId: EnvironmentId;
  hostId: HostId;
  handle: EnvironmentHandle;
}

export interface ProviderDestroyRequest extends ProviderReconnectRequest {}

export type ProviderProvisionEvent =
  | { kind: "progress"; step: string; text: string; status: "started" | "completed" | "failed" }
  | { kind: "output"; line: string }
  | { kind: "done"; handle: EnvironmentHandle };

The public provider service stays on the server. Its server half calls a private typed host role for all host work. The provider must reject a handle that does not match its environment and owned root.

Exports

Module imports select exact first-party code. Service calls follow the current winner.

The app contracts replace the broad old BbContext and BbNavigate names.

export interface WorkspaceNavigation {
  toThread(threadId: ThreadId): void;
  toProject(projectId: ProjectId): void;
  toEnvironment(environmentId: EnvironmentId, subPath?: string): void;
  toPluginPanel(path: string, options?: { subPath?: string; replace?: boolean }): void;
  toCompose(options?: { projectId?: ProjectId; initialPrompt?: string; focusPrompt?: boolean }): void;
  openThreadPanel(options: ThreadPanelTarget): boolean;
  openUrl(url: string): boolean;
  openFilePreview(options: WorkspaceFileOpenOptions): boolean;
  openFileExternally(options: WorkspaceFileOpenOptions): boolean;
}

export function useWorkspaceContext(): WorkspaceContext;
export function useWorkspaceNavigate(): WorkspaceNavigation;

export interface WorkspaceAppClient {
  readonly projects: WorkspaceProjectClient;
  readonly environments: WorkspaceEnvironmentClient;
  readonly navigation: WorkspaceNavigation;
}

export function useWorkspace(): WorkspaceAppClient;

The app client follows the current bb.workspace service winner. It keeps request state and cache details outside the public contract.

Host roles

Each bb.workspace.envProvider claimant declares one private role. The role ID is bb.workspace.envProvider.host, and its name supplies the public key suffix.

export interface EnvironmentProvider<Options extends JsonObject> {
  name: string;
  label: string;
  ownsRoot: boolean;
  options: StandardSchemaV1<Options>;
  provision(request: HostProvisionRequest<Options>, context: EnvironmentProviderContext): Promise<EnvironmentHandle>;
  reconnect(request: HostReconnectRequest, context: EnvironmentProviderContext): Promise<EnvironmentHandle>;
  destroy(request: HostDestroyRequest, context: EnvironmentProviderContext): Promise<void>;
  summarize(handle: EnvironmentHandle, context: EnvironmentProviderContext): Promise<EnvironmentSummary>;
}

export interface EnvironmentProviderContext {
  signal: AbortSignal;
  lifecycle: { signal: AbortSignal };
  paths: { dataDir: string; tempDir: string };
  progress: EnvironmentProgressSink;
  workspace: EnvironmentWorkspaceFactory;
}

export interface EnvironmentProgressSink {
  step(key: string, text: string, status: "started" | "completed" | "failed"): void;
  output(line: string): void;
}

The host package supplies a contained workspace helper. It absorbs the old host workspace object and keeps filesystem paths private to the host.

export interface EnvironmentWorkspaceFactory {
  provision(options: ProvisionWorkspaceInput): Promise<EnvironmentWorkspace>;
  personalRoot(dataDir: string): string;
  validatePersonalPath(input: PersonalPathInput): string;
}

export interface EnvironmentWorkspace {
  readonly path: string;
  readonly managed: boolean;
  readonly isGitRepo: boolean;
  readonly isWorktree: boolean;

  getDefaultBranch(): Promise<string | null>;
  getCurrentBranch(): Promise<string | null>;
  getHeadSha(): Promise<string | null>;
  getLocalStateFingerprint(): Promise<string>;
  getSharedGitRefsFingerprint(): Promise<string>;
  getAdditionalWorkspaceWriteRoots(): Promise<readonly string[]>;
  getStatus(options?: WorkspaceStatusOptions): Promise<EnvironmentStatus>;
  getDiff(options?: WorkspaceDiffOptions): Promise<EnvironmentDiff>;
  diffFiles(options: WorkspaceDiffFilesInput): Promise<EnvironmentDiffFilePage>;
  diffPatch(options: WorkspaceDiffPatchInput): Promise<EnvironmentPatchResult>;
  getPullRequest(): Promise<EnvironmentPullRequest | null>;
  listFiles(): Promise<readonly WorkspacePath[]>;

  commit(options: WorkspaceCommitOptions): Promise<CommitResult>;
  reset(): Promise<void>;
  squashMerge(options: WorkspaceSquashMergeOptions): Promise<SquashMergeResult>;
  runPullRequestAction(action: PullRequestAction): Promise<EnvironmentPullRequest>;
  destroy(): Promise<void>;
}

export type ProvisionWorkspaceInput =
  | { mode: "unmanaged"; path: string }
  | { mode: "managed-worktree"; sourcePath: string; environmentId: EnvironmentId; branch?: string }
  | { mode: "personal"; environmentId: EnvironmentId; targetPath?: string }
  | { mode: "reconnect-managed-worktree"; environmentId: EnvironmentId; path: string };

export interface WorkspaceStatusOptions {
  mergeBaseBranch?: string;
  maxUntrackedLineStatFiles?: number;
  maxUntrackedLineStatBytes?: number;
}

export interface WorkspaceDiffOptions {
  target?: WorkspaceDiffTarget;
  maxDiffBytes?: number;
  maxFileListBytes?: number;
  maxUntrackedFiles?: number;
}

export interface WorkspaceDiffFilesInput {
  target: WorkspaceDiffTarget;
  maxFiles: number;
}

export interface WorkspaceDiffPatchInput {
  target: WorkspaceDiffTarget;
  paths: readonly string[];
  maxBytesPerFile: number;
}

export interface WorkspaceCommitOptions {
  message: string;
  noVerify: boolean;
}

export interface WorkspaceSquashMergeOptions {
  targetBranch: string;
  commitMessage: string;
}

export type PullRequestAction = "mark-draft" | "mark-ready" | "merge";

The server half owns the public provider token. Consumers never call the private host role. The kernel inspector joins both records under one provider key.

Example

This plugin adds a scratch environment provider. It consumes the workspace service and adds no UI claim.

{
  "id": "acme.scratch-workspace",
  "version": "2.0.0",
  "claims": [
    {
      "service": "bb.workspace.envProvider",
      "key": "acme.scratch-workspace/scratch",
      "version": "1.0.0"
    }
  ],
  "requires": [{ "service": "bb.workspace", "range": "^1" }],
  "artifacts": {
    "server": "./dist/server.js",
    "host": "./dist/host.js"
  }
}

// server.ts
import { defineServerPlugin } from "@get-bb/plugin/server";
import { environmentProvider, workspaceService } from "@bb/workspace/contracts";

export default defineServerPlugin(async (api) => {
  const workspace = await api.services.use(workspaceService);
  const host = api.hostRoles.client(scratchHostRole);

  api.services.provide(environmentProvider.key("acme.scratch-workspace/scratch"), {
    describe: () => host.call("describe", {}),
    provision: (request, options) => host.stream("provision", request, options),
    reconnect: (request) => host.call("reconnect", request),
    destroy: (request, options) => host.call("destroy", request, options),
    summarize: (handle) => host.call("summarize", { handle }),
  });

  return workspace.environments.watch({}, (event) => {
    api.log.debug(`environment ${event.environmentId} changed`);
  });
});

The host artifact uses defineEnvironmentProvider. It returns a contained local-path handle.

The bb.workspace-ui plugin

bb.workspace-ui is the default presentation for the workspace domain. It requires the bb.workspace service through a required edge.

The plugin renders project and environment data. It does not own, copy, or wrap the data service.

Surfaces

These surfaces exist only while bb.workspace-ui declares them. A different presentation can omit either surface.

bb.workspace-ui.projectSwitcher

The shell supplies route state and callbacks. The surface does not own project data.

export interface ProjectSwitcherProps {
  activeProjectId: ProjectId | null;
  presentation: "compact" | "full";
  disabled?: boolean;
  onSelect(projectId: ProjectId): void;
  onCreate(): void;
}

export type ProjectSwitcherSurface = SingleSurface<ProjectSwitcherProps>;

api.surfaces.provide(
  "bb.workspace-ui.projectSwitcher",
  ({ Original, props }) => <Original {...props} presentation="compact" />,
);

A winner calls onSelect after a user choice. The router then changes the route.

bb.workspace-ui.environmentPage

The page key selects one environment view. Each key has one global winner.

export type EnvironmentPageId = "overview" | "changes" | "pull-request";

export interface EnvironmentPageProps {
  page: EnvironmentPageId;
  environmentId: EnvironmentId;
  projectId: ProjectId;
  threadId: ThreadId | null;
  compact: boolean;
  navigate: WorkspaceNavigation;
}

export type EnvironmentPageSurface = KeyedSurface<
  EnvironmentPageId,
  EnvironmentPageProps
>;

api.surfaces.provide("bb.workspace-ui.environmentPage", {
  key: "changes",
  component: ChangesPage,
});

A keyed winner does not receive Original. A failed winner returns to the default claimant for that key.

Required service edge

The manifest declares a required edge on bb.workspace. The loader activates bb.workspace-ui only after the data service becomes ready.

{
  "id": "bb.workspace-ui",
  "requires": [{ "service": "bb.workspace", "range": "^1" }]
}

A workspace service winner change restarts bb.workspace-ui with a fresh service handle.

Services

Exports

Surface claims follow the current winner. These module imports always select the first-party implementation.

Host roles

bb.workspace-ui declares no host role. It gets all workspace data through its required service edge.

Example

This app plugin replaces only the project switcher. It requires bb.workspace for project data and route actions.

{
  "id": "acme.compact-workspace-ui",
  "version": "2.0.0",
  "claims": [{ "surface": "bb.workspace-ui.projectSwitcher" }],
  "requires": [{ "service": "bb.workspace", "range": "^1" }],
  "artifacts": { "app": "./dist/app.js" }
}

// app.tsx
import { definePlugin } from "@get-bb/plugin/app";
import { useWorkspace, useWorkspaceNavigate } from "@bb/workspace/app";

function CompactSwitcher() {
  const workspace = useWorkspace();
  const navigate = useWorkspaceNavigate();
  const projects = workspace.projects.useList();

  return (
    <select
      value={workspace.projects.activeId ?? ""}
      onChange={(event) => navigate.toProject(event.target.value as ProjectId)}
    >
      {projects.data.map((project) => (
        <option key={project.id} value={project.id}>{project.name}</option>
      ))}
    </select>
  );
}

export default definePlugin((api) => {
  api.surfaces.provide("bb.workspace-ui.projectSwitcher", () => (
    <CompactSwitcher />
  ));
});

Covers