@hachej/boring-workspace 0.1.54 → 0.1.56

package/docs/PLUGIN_SYSTEM.md

@@ -282,6 +282,63 @@ parses `/name args` only.
   `package.json#pi` block — Pi-sourced commands appear automatically. No
   harness changes required.
 
+### 4.8 Generic session attention badges
+
+`WorkspaceAttention` is the generic way for plugins to say “this chat session
+needs attention”. The workspace owns only the display and routing mechanics;
+plugins own the domain semantics, surface UI, and bridge/API operations.
+
+A plugin should use its own `reason` namespace and may attach a `sessionBadge`
+for the session list:
+
+```ts
+const { addBlocker, removeBlocker } = useWorkspaceAttention()
+
+addBlocker({
+  id: `pr-review:${sessionId}:123`,
+  reason: "pr-review.review",
+  sessionId,
+  surfaceKind: "pr-review",
+  target: "review-123",
+  label: "Review PR #123 to continue",
+  sessionBadge: {
+    kind: "review",
+    label: "review",
+    tone: "warning",
+    priority: 20,
+  },
+  actions: [{ id: "open", label: "Open review" }],
+})
+```
+
+`sessionBadge.kind` is stable metadata for tests/styling
+(`data-boring-badge="review"`). `label` is the short text rendered in the row.
+`tone` is visual only; plugin code should not infer behavior from it. If several
+plugins mark one session, the highest `priority` badge wins.
+
+Composer blocker actions are plugin-defined. Workspace provides a convenience
+for `id: "open"` when `surfaceKind` is present, and emits
+`WORKSPACE_ATTENTION_ACTION_EVENT` for every action with `{ blockerId, actionId,
+sessionId, blocker }`. The owning plugin should listen for its domain-specific
+actions such as `approve`, `request-changes`, or `cancel`; workspace does not
+assign semantics to those action ids.
+
+Ask-user consumes this as an ask-user-specific attention type:
+
+```ts
+reason: "ask-user.question"
+sessionBadge: { kind: "question", label: "question", tone: "attention" }
+```
+
+Other plugins should not reuse ask-user’s reason or badge kind unless they are
+actually delegating to ask-user. For example, a PR review plugin should use
+`reason: "pr-review.review"` and `kind: "review"` even if both are ultimately
+“human input”.
+
+Compatibility: old blockers with `reason: "waiting_for_user_input"` still render
+a legacy `needs input` badge, but new plugins should provide `sessionBadge`
+explicitly.
+
 ---
 
 ## 5. Key algorithms

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-workspace",
-  "version": "0.1.54",
+  "version": "0.1.56",
   "type": "module",
   "license": "MIT",
   "description": "Workspace UI, plugin, and bridge package for composing chat, files, catalogs, editors, and app-specific panes.",
@@ -34,6 +34,10 @@
       "types": "./dist/shared.d.ts",
       "import": "./dist/shared.js"
     },
+    "./bridge-client": {
+      "types": "./dist/bridge-client.d.ts",
+      "import": "./dist/bridge-client.js"
+    },
     "./app/front": {
       "types": "./dist/app-front.d.ts",
       "import": "./dist/app-front.js",
@@ -135,9 +139,9 @@
     "tailwind-merge": "^2.0.0",
     "zod": "^3.23.0",
     "zustand": "^5.0.0",
-    "@hachej/boring-ui-kit": "0.1.54",
-    "@hachej/boring-ui-plugin-cli": "0.1.54",
-    "@hachej/boring-agent": "0.1.54"
+    "@hachej/boring-agent": "0.1.56",
+    "@hachej/boring-ui-kit": "0.1.56",
+    "@hachej/boring-ui-plugin-cli": "0.1.56"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.0.0",

package/dist/createInMemoryBridge-siFWq_R_.d.ts

@@ -1,198 +0,0 @@
-import { B as BoringPackageBoringField, a as BoringPackagePiField } from './manifest-C2vVgH_e.js';
-import { PiPackageSource, PluginSkillSource, ProvisionWorkspaceRuntimeOptions } from '@hachej/boring-agent/server';
-import { FastifyPluginAsync } from 'fastify';
-import { A as AgentTool } from './agent-tool-CB0RQyx9.js';
-import { U as UiBridge } from './ui-bridge-LeBuZqfA.js';
-
-type BoringPluginNativeFrontTargetTrust$1 = "local-trusted-native";
-/**
- * Host-owned runtime import target for a plugin front entry.
- *
- * Only the trusted native/browser-module case exists today. Future
- * target kinds (iframe/artifact/...) can extend the union without
- * rewriting list/event payload shapes.
- */
-interface BoringPluginNativeFrontTarget$1 {
-    kind: "native";
-    entryUrl: string;
-    revision: number;
-    trust: BoringPluginNativeFrontTargetTrust$1;
-}
-/**
- * Plugin front served as a plain browser module URL — the Vite-dev transport
- * (`/@fs/...`). Hosts running a Vite dev server let Vite transform the entry;
- * the CLI's runtime host mints `native` targets instead.
- */
-interface BoringPluginModuleUrlFrontTarget {
-    kind: "module-url";
-    entryUrl: string;
-    revision: number;
-}
-type BoringPluginFrontTarget$1 = BoringPluginNativeFrontTarget$1 | BoringPluginModuleUrlFrontTarget;
-type BoringPluginEvent$1 = {
-    type: "boring.plugin.load";
-    id: string;
-    boring: BoringPackageBoringField;
-    version: string;
-    revision: number;
-    frontTarget?: BoringPluginFrontTarget$1;
-} | {
-    type: "boring.plugin.unload";
-    id: string;
-    revision: number;
-} | {
-    type: "boring.plugin.error";
-    id: string;
-    revision: number;
-    message: string;
-};
-interface BoringPluginListEntry$1 {
-    id: string;
-    boring: BoringPackageBoringField;
-    pi?: BoringPackagePiField;
-    version: string;
-    revision: number;
-    frontTarget?: BoringPluginFrontTarget$1;
-}
-
-type BoringPluginSourceKind = "internal" | "external";
-interface BoringPluginSource {
-    rootDir: string;
-    kind: BoringPluginSourceKind;
-    workspaceId?: string;
-    /**
-     * True when the user explicitly registered this directory as a plugin
-     * source (e.g. a `packages` entry in Pi settings.json). Registered
-     * sources that are missing, lack a package.json, or carry no plugin
-     * metadata surface as preflight errors instead of being silently
-     * skipped the way speculative scan roots are.
-     */
-    registered?: boolean;
-}
-type BoringPluginSourceInput = string | BoringPluginSource;
-interface BoringServerPluginManifest {
-    id: string;
-    rootDir: string;
-    version: string;
-    boring: BoringPackageBoringField;
-    /** True when package.json explicitly declares a boring manifest. Pi-only packages remain valid Pi resources but are not listed as Boring plugins. */
-    hasBoring: boolean;
-    pi?: BoringPackagePiField;
-    frontPath?: string;
-    /** Legacy Vite-dev browser import fallback (`/@fs/...`). */
-    frontUrl?: string;
-    serverPath?: string;
-    extensionPaths?: string[];
-    skillPaths?: string[];
-    source: BoringPluginSource;
-}
-type BoringPluginNativeFrontTargetTrust = BoringPluginNativeFrontTargetTrust$1;
-type BoringPluginNativeFrontTarget = BoringPluginNativeFrontTarget$1;
-type BoringPluginFrontTarget = BoringPluginFrontTarget$1;
-type BoringPluginListEntry = BoringPluginListEntry$1;
-interface BoringPluginFrontTargetResolverContext {
-    revision: number;
-    /** Plugin-root-relative front entry path normalized for URL-like consumers. */
-    frontEntrySubpath: string;
-}
-type BoringPluginFrontTargetResolver = (plugin: BoringServerPluginManifest, context: BoringPluginFrontTargetResolverContext) => BoringPluginFrontTarget | undefined;
-/**
- * Surfaces whose changes the hot-reload pipeline can't re-load mid-
- * session — set when a plugin's load DID succeed but a sub-surface
- * (the agent-tools registry, Fastify routes) carries stale code from
- * the previous revision. The /reload caller (chat UI, verify-plugin,
- * etc.) should surface a "restart needed for X" warning.
- *
- * - `'routes'`: a `WorkspaceServerPlugin.routes` function changed. The
- *   workspace's Fastify instance can't unregister + re-register routes
- *   mid-flight; the previous routes stay live until next boot.
- * - `'agentTools'`: a `WorkspaceServerPlugin.agentTools` array changed.
- *   The current Pi session still has the old tool list; new sessions
- *   get the new list.
- * - Multiple surfaces: order is deterministic (`routes` before
- *   `agentTools`) so subscribers can format consistently.
- */
-type PluginRestartSurface = "routes" | "agentTools";
-type BoringPluginEvent = (Extract<BoringPluginEvent$1, {
-    type: "boring.plugin.load";
-}> & {
-    /**
-     * Non-empty when the plugin loaded but one or more server-side
-     * surfaces still hold pre-load code. UI consumers should render
-     * a "restart needed: <surfaces>" hint. Empty/omitted = fully
-     * live.
-     */
-    requiresRestart?: PluginRestartSurface[];
-}) | Extract<BoringPluginEvent$1, {
-    type: "boring.plugin.unload";
-}> | Extract<BoringPluginEvent$1, {
-    type: "boring.plugin.error";
-}>;
-
-type WorkspaceRuntimeProvisioning = NonNullable<ProvisionWorkspaceRuntimeOptions["plugins"][number]["provisioning"]>;
-interface WorkspaceServerPluginAsset {
-    /** Stable asset name within this plugin, e.g. "sdk" or "workspace-template". */
-    name: string;
-    /** Source directory or file owned by the plugin. Relative strings are resolved by the app integration. */
-    source: string | URL;
-    /** Optional runtime target path within this plugin's asset namespace. Defaults to name. */
-    target?: string;
-}
-interface WorkspaceServerPlugin {
-    id: string;
-    label?: string;
-    /**
-     * Native Pi package sources required by this workspace integration.
-     * Workspace declares them; @hachej/boring-agent applies them through Pi's native
-     * resource loader without asking Pi packages to export Boring adapters.
-     */
-    piPackages?: PiPackageSource[];
-    /**
-     * Native pi extension entrypoints contributed by this plugin.
-     * Passed to DefaultResourceLoader.additionalExtensionPaths so pi owns jiti
-     * loading and ctx.reload() re-imports fresh source.
-     */
-    extensionPaths?: string[];
-    systemPrompt?: string;
-    skills?: PluginSkillSource[];
-    agentTools?: AgentTool[];
-    provisioning?: WorkspaceRuntimeProvisioning;
-    /** Static filesystem assets this plugin needs in production/serverless bundles. */
-    assets?: WorkspaceServerPluginAsset[];
-    routes?: FastifyPluginAsync;
-    /** UI state keys owned by this plugin that browser state PUTs must not overwrite. */
-    preservedUiStateKeys?: string[];
-}
-declare function validateServerPlugin(plugin: WorkspaceServerPlugin): void;
-declare function defineServerPlugin<T extends WorkspaceServerPlugin>(plugin: T): T;
-
-interface ServerBootstrapOptions {
-    plugins?: WorkspaceServerPlugin[];
-    defaults?: WorkspaceServerPlugin[];
-    excludeDefaults?: string[];
-}
-type WorkspaceRuntimeProvisioningInput = ProvisionWorkspaceRuntimeOptions["plugins"][number];
-type WorkspaceProvisioningContribution = {
-    id: string;
-    provisioning: NonNullable<WorkspaceRuntimeProvisioningInput["provisioning"]>;
-};
-type WorkspaceRouteContribution = {
-    id: string;
-    routes: FastifyPluginAsync;
-};
-interface ServerBootstrapResult {
-    registered: string[];
-    systemPromptAppend: string;
-    piPackages: PiPackageSource[];
-    extensionPaths: string[];
-    agentTools: AgentTool[];
-    runtimePlugins: WorkspaceRuntimeProvisioningInput[];
-    provisioningContributions: WorkspaceProvisioningContribution[];
-    routeContributions: WorkspaceRouteContribution[];
-    preservedUiStateKeys: string[];
-}
-declare function bootstrapServer(options: ServerBootstrapOptions): ServerBootstrapResult;
-
-declare function createInMemoryBridge(): UiBridge;
-
-export { type BoringPluginSourceInput as B, type PluginRestartSurface as P, type ServerBootstrapOptions as S, type WorkspaceServerPlugin as W, type BoringPluginFrontTargetResolver as a, type WorkspaceProvisioningContribution as b, type WorkspaceRouteContribution as c, createInMemoryBridge as d, type WorkspaceRuntimeProvisioningInput as e, type WorkspaceServerPluginAsset as f, type BoringServerPluginManifest as g, type BoringPluginListEntry as h, type BoringPluginFrontTarget as i, type BoringPluginSource as j, type BoringPluginEvent as k, type BoringPluginFrontTargetResolverContext as l, type BoringPluginNativeFrontTarget as m, type BoringPluginNativeFrontTargetTrust as n, type BoringPluginSourceKind as o, type ServerBootstrapResult as p, bootstrapServer as q, defineServerPlugin as r, validateServerPlugin as v };