@hachej/boring-workspace 0.1.17 → 0.1.18

package/dist/server.d.ts

@@ -1,7 +1,8 @@
-export { C as ComposeServerPluginsOptions, S as ServerBootstrapOptions, f as ServerBootstrapResult, g as ServerPluginError, a as WorkspaceProvisioningContribution, b as WorkspaceRouteContribution, W as WorkspaceServerPlugin, h as bootstrapServer, d as composeServerPlugins, c as createInMemoryBridge, e as defineServerPlugin, v as validateServerPlugin } from './bootstrapServer-BreQ9QBc.js';
+export { S as ServerBootstrapOptions, d as ServerBootstrapResult, a as WorkspaceProvisioningContribution, b as WorkspaceRouteContribution, W as WorkspaceServerPlugin, e as bootstrapServer, c as createInMemoryBridge, f as defineServerPlugin, v as validateServerPlugin } from './createInMemoryBridge-BDxDzihm.js';
 import { FastifyRequest, FastifyInstance } from 'fastify';
-import { U as UiBridge, A as AgentTool } from './agent-tool-DEtfQPVB.js';
-export { C as CommandResult, a as UiCommand, b as UiState } from './agent-tool-DEtfQPVB.js';
+import { U as UiBridge, A as AgentTool } from './ui-bridge-Gfh1MMgl.js';
+export { C as CommandResult, b as UiCommand, c as UiState } from './ui-bridge-Gfh1MMgl.js';
+import { B as BoringPackageBoringField, a as BoringPackagePiField } from './manifest-CyNNdfYz.js';
 export { PiPackageSource as WorkspacePiPackageSource } from '@hachej/boring-agent/server';
 
 interface UiRoutesOptions {
@@ -59,4 +60,238 @@ declare function createExecUiTool(uiBridge: UiBridge, opts?: ExecUiToolOptions):
  */
 declare function createWorkspaceUiTools(uiBridge: UiBridge, opts?: ExecUiToolOptions): AgentTool[];
 
-export { UiBridge, type UiRoutesOptions, createExecUiTool, createGetUiStateTool, createWorkspaceUiTools, uiRoutes };
+/**
+ * boring-ui system prompt — workflow steps + a Pi-style docs pointer
+ * block (per DECISIONS.md #17). The block lists absolute paths into the
+ * installed `@hachej/boring-pi` package so the agent's `read` tool can
+ * fetch the SKILL.md + reference docs on demand, without inlining their
+ * ~12-30 KB of markdown into every system prompt.
+ *
+ * `@hachej/boring-pi` is a runtime dep of `@hachej/boring-workspace`;
+ * a missing install means the host shipped without it (degraded mode),
+ * in which case we still emit the workflow + skill-by-name reference
+ * for `<available_skills>` consumers but skip the absolute paths.
+ */
+interface BuildBoringSystemPromptOptions {
+    /**
+     * CLI invocation that writes the canonical files (e.g.
+     * `boring-ui scaffold-plugin`). When unset, step 1 falls back to
+     * "read the skill" — the agent then has no canonical anchor and
+     * reliability suffers on smaller models, so always provide this in
+     * production.
+     */
+    scaffoldCommand?: string;
+    /** CLI invocation that validates `.pi/extensions/*` manifests. Omit when unavailable. */
+    verifyCommand?: string;
+    /**
+     * Test escape hatch. Overrides the runtime `require.resolve` of
+     * `@hachej/boring-pi/package.json`:
+     *   - `undefined` (default): resolve via require.resolve
+     *   - `string`: use as the boring-pi root verbatim
+     *   - `null`: force the degraded path (no resolution attempt)
+     * Production should leave unset.
+     */
+    boringPiRootOverride?: string | null;
+}
+declare function buildBoringSystemPrompt(opts: BuildBoringSystemPromptOptions): string;
+
+interface BoringServerPluginManifest {
+    id: string;
+    rootDir: string;
+    version: string;
+    boring: BoringPackageBoringField;
+    pi?: BoringPackagePiField;
+    frontPath?: string;
+    frontUrl?: string;
+    serverPath?: string;
+    extensionPaths?: string[];
+    skillPaths?: string[];
+}
+/**
+ * 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 = {
+    type: "boring.plugin.load";
+    id: string;
+    boring: BoringPackageBoringField;
+    version: string;
+    revision: number;
+    frontUrl?: string;
+    /**
+     * 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[];
+} | {
+    type: "boring.plugin.unload";
+    id: string;
+    revision: number;
+} | {
+    type: "boring.plugin.error";
+    id: string;
+    revision: number;
+    message: string;
+};
+interface BoringPluginListEntry {
+    id: string;
+    boring: BoringPackageBoringField;
+    pi?: BoringPackagePiField;
+    version: string;
+    revision: number;
+    frontUrl?: string;
+}
+
+interface BoringPluginPreflightIssue {
+    pluginDir: string;
+    pluginId?: string;
+    code: "MISSING_PACKAGE_JSON" | "INVALID_PACKAGE_JSON" | "INVALID_PLUGIN_METADATA";
+    message: string;
+}
+interface BoringPluginPreflightResult {
+    ok: boolean;
+    errors: BoringPluginPreflightIssue[];
+}
+interface BoringPluginScanResult {
+    preflight: BoringPluginPreflightResult;
+    plugins: BoringServerPluginManifest[];
+}
+declare function scanBoringPlugins(pluginDirs: string[]): BoringPluginScanResult;
+declare function preflightBoringPlugins(pluginDirs: string[]): BoringPluginPreflightResult;
+declare function readBoringPlugins(pluginDirs: string[]): BoringServerPluginManifest[];
+
+interface BoringPluginAssetManagerOptions {
+    pluginDirs: string[];
+    /**
+     * Root directory for per-plugin `.error` sidecar files written by the
+     * asset manager and read by verify-plugin. Defaults to `<cwd>/.pi/extensions`.
+     * Multi-tenant / non-standard layouts MUST provide an explicit path —
+     * the default assumes workspace root equals `process.cwd()`.
+     */
+    errorRoot?: string;
+}
+interface LoadBoringAssetsError {
+    id: string;
+    revision: number;
+    message: string;
+}
+interface LoadBoringAssetsResult {
+    loaded: BoringPluginListEntry[];
+    events: BoringPluginEvent[];
+    errors: LoadBoringAssetsError[];
+}
+type Listener = (event: BoringPluginEvent) => void;
+declare class BoringPluginAssetManager {
+    private readonly pluginDirs;
+    private readonly errorRoot;
+    private readonly loaded;
+    private readonly revisions;
+    private readonly listeners;
+    private loading;
+    private reloadQueued;
+    constructor(options: BoringPluginAssetManagerOptions);
+    preflight(): BoringPluginPreflightResult;
+    list(): BoringPluginListEntry[];
+    getError(pluginId: string): string | null;
+    subscribe(listener: Listener): () => void;
+    load(): Promise<LoadBoringAssetsResult>;
+    private drainLoads;
+    private doLoadOnce;
+    private collectPreflightErrors;
+    private bumpRevision;
+    private emit;
+    private errorPath;
+    private writeError;
+    private clearError;
+}
+
+interface PluginReloadRebuild {
+    ok: boolean;
+    diagnostics: {
+        source: string;
+        message: string;
+        pluginId?: string;
+    }[];
+}
+/**
+ * One per plugin whose load event carried a non-empty
+ * `requiresRestart` field. Surfaced alongside the /reload response so
+ * the agent (and chat UI) can warn the user without subscribing to
+ * the SSE event stream.
+ */
+interface PluginRestartWarning {
+    id: string;
+    surfaces: PluginRestartSurface[];
+    message: string;
+}
+/**
+ * Walk a load result's events for boring.plugin.load events that
+ * carried `requiresRestart`. Each becomes a human-readable warning
+ * with a one-line message — small, surface-aware, formatted for both
+ * humans and agents.
+ */
+declare function collectRestartWarnings(events: BoringPluginEvent[]): PluginRestartWarning[];
+interface BoringPluginRoutesOptions {
+    manager: BoringPluginAssetManager;
+    /**
+     * Server-side plugin rebuild closure (jiti re-import of dir-source
+     * entries). Called AFTER the asset manager scan. Per-plugin failures
+     * surface as diagnostics; combined with asset-manager errors into the
+     * 422 response body so the agent's /reload UI can show them. Optional —
+     * tests that exercise the route in isolation can omit it.
+     */
+    rebuildPlugins?: () => Promise<PluginReloadRebuild>;
+    /** Register the developer reload endpoint. Static discovery/listing remains available when false. */
+    enableReloadRoute?: boolean;
+}
+declare function boringPluginRoutes(app: FastifyInstance, opts: BoringPluginRoutesOptions): Promise<void>;
+
+/**
+ * Concatenates the `pi.systemPrompt` from every currently loaded boring
+ * plugin into a single block, prefixed by a stable header. Returns
+ * `undefined` when no plugin contributes a prompt so the harness can skip
+ * the append entirely.
+ *
+ * The harness calls this on every prompt rebuild — Pi calls it from
+ * `before_agent_start`, which `piSession.reload()` re-fires. Live plugin
+ * additions/removals therefore land on the next agent turn without any
+ * workspace-injected harness extension.
+ */
+declare function aggregatePluginPrompts(manager: BoringPluginAssetManager): string | undefined;
+
+interface PluginSignatureCachePayload {
+    version: 1;
+    /**
+     * `fileSignature(serverPath)` at load time, or null when the plugin
+     * has no server entry.
+     */
+    serverSignature: string | null;
+    /** Unix ms when the manager wrote this cache. */
+    loadedAt: number;
+}
+/**
+ * mtimeMs+size — cheap, mirrors what the asset manager uses to decide
+ * whether to fire `requiresRestart` on /reload. Bytes are deliberately
+ * NOT hashed (perf bug on 50MB+ bundles, and we only need change
+ * detection, not content equality).
+ */
+declare function pluginFileSignature(path: string | undefined): string;
+declare function writePluginSignatureCache(pluginRootDir: string, payload: Omit<PluginSignatureCachePayload, "version" | "loadedAt"> & Partial<Pick<PluginSignatureCachePayload, "loadedAt">>): void;
+declare function readPluginSignatureCache(pluginRootDir: string): PluginSignatureCachePayload | null;
+
+export { BoringPluginAssetManager, type BoringPluginEvent, type BoringPluginListEntry, type BoringPluginScanResult, type BoringServerPluginManifest, type PluginReloadRebuild, type PluginRestartWarning, UiBridge, type UiRoutesOptions, aggregatePluginPrompts, boringPluginRoutes, buildBoringSystemPrompt, collectRestartWarnings, createExecUiTool, createGetUiStateTool, createWorkspaceUiTools, pluginFileSignature, preflightBoringPlugins, readBoringPlugins, readPluginSignatureCache, scanBoringPlugins, uiRoutes, writePluginSignatureCache };