@hachej/boring-agent 0.1.18 → 0.1.22

package/README.md

@@ -28,6 +28,7 @@ npx @hachej/boring-agent
 | **Three execution modes** | `direct` (no isolation, macOS dev) / `local` (bwrap sandbox) / `vercel-sandbox` (Firecracker microVM) |
 | **CLI + embeddable** | `npx @hachej/boring-agent` works standalone; `<ChatPanel />` composes into any layout |
 | **7 standard tools** | `bash`, `read`, `write`, `edit`, `find`, `grep`, `ls` — ported from pi-coding-agent |
+| **Workspace-local runtime provisioning** | Generates `.boring-agent` inside the selected workspace for mirrored skills, SDKs, CLIs, and templates |
 | **Workspace-agnostic FS** | `Workspace` interface — agent tools and HTTP routes share the same filesystem view |
 | **Session management** | List, create, switch, delete sessions with streamed history hydration |
 | **UI bridge** | Agent opens files, panels, and surfaces in the workbench via typed commands |
@@ -58,6 +59,21 @@ write a test for src/utils.ts
 
 ---
 
+## Workspace-local runtime provisioning
+
+Boring UI keeps generated runtime state in the selected workspace at
+`$BORING_AGENT_WORKSPACE_ROOT/.boring-agent`. Plugin skills are mirrored to
+`.boring-agent/skills`, runtime CLIs live under `.boring-agent/node` or
+`.boring-agent/venv`, and templates seed only missing workspace files. The
+folder is generated/disposable and should not be hand-edited or committed.
+
+See [docs/runtime-provisioning.md](docs/runtime-provisioning.md) for the full
+user and plugin-author contract, including package metadata shape,
+`provisionWorkspace: false`, `/api/v1/agent/reload`, and direct/local/Vercel
+mode behavior.
+
+---
+
 ## Architecture
 
 ```

package/dist/{chunk-W73RUHY3.js → chunk-6R7O6BHW.js}

@@ -1,3 +1,16 @@
+// src/shared/telemetry.ts
+var noopTelemetry = {
+  capture() {
+  }
+};
+function safeCapture(telemetry, event) {
+  try {
+    void Promise.resolve(telemetry.capture(event)).catch(() => {
+    });
+  } catch {
+  }
+}
+
 // src/shared/error-codes.ts
 import { z } from "zod";
 var ErrorCode = z.enum([
@@ -37,6 +50,15 @@ var ErrorCode = z.enum([
   // Plugin
   "PLUGIN_LOAD_FAILED",
   "PLUGIN_NAME_COLLISION",
+  // Runtime provisioning
+  "PROVISIONING_LAYOUT_FAILED",
+  "PROVISIONING_SKILLS_FAILED",
+  "PROVISIONING_TEMPLATES_FAILED",
+  "PROVISIONING_NODE_PREFLIGHT_FAILED",
+  "PROVISIONING_NPM_INSTALL_FAILED",
+  "PROVISIONING_UV_BOOTSTRAP_FAILED",
+  "PROVISIONING_UV_INSTALL_FAILED",
+  "PROVISIONING_ARTIFACT_FAILED",
   // Internal
   "INTERNAL_ERROR"
 ]);
@@ -68,6 +90,8 @@ function validateTool(tool) {
 }
 
 export {
+  noopTelemetry,
+  safeCapture,
   ErrorCode,
   ERROR_CODES,
   ApiErrorPayloadSchema,

package/dist/front/index.d.ts

@@ -5,7 +5,7 @@ import { T as ToolUiMetadata } from '../tool-ui-DIFNGwYd.js';
 import * as ai from 'ai';
 import { UIMessage, FileUIPart, ChatStatus } from 'ai';
 import * as _ai_sdk_react from '@ai-sdk/react';
-import { S as SendMessageInput, e as SessionSummary } from '../harness-DRrTn_5T.js';
+import { S as SendMessageInput, e as SessionSummary } from '../harness-BCit36Ha.js';
 import { Button, Collapsible, CollapsibleContent, CollapsibleTrigger, InputGroupAddon, InputGroupButton, InputGroupTextarea } from '@hachej/boring-ui-kit';
 import { Streamdown } from 'streamdown';
 import { StickToBottom } from 'use-stick-to-bottom';

package/dist/{harness-DRrTn_5T.d.ts → harness-BCit36Ha.d.ts}

@@ -29,6 +29,18 @@ interface SessionDetail extends SessionSummary {
     messages: UIMessage[];
 }
 
+interface TelemetrySink {
+    capture(event: TelemetryEvent): void | Promise<void>;
+    flush?(): void | Promise<void>;
+}
+interface TelemetryEvent {
+    name: string;
+    distinctId?: string;
+    properties?: Record<string, unknown>;
+}
+declare const noopTelemetry: TelemetrySink;
+declare function safeCapture(telemetry: TelemetrySink, event: TelemetryEvent): void;
+
 type JSONSchema = Record<string, unknown>;
 interface AgentTool {
     name: string;
@@ -67,6 +79,8 @@ interface AgentHarnessFactoryInput {
      * prompt context without a workspace-injected harness extension.
      */
     systemPromptDynamic?: () => string | undefined | Promise<string | undefined>;
+    /** Host-provided telemetry sink. Optional and best-effort; harnesses may ignore it. */
+    telemetry?: TelemetrySink;
 }
 type AgentHarnessFactory = (input: AgentHarnessFactoryInput) => AgentHarness | Promise<AgentHarness>;
 interface AgentHarness {
@@ -127,4 +141,4 @@ interface RunContext {
     userId?: string;
 }
 
-export type { AgentTool as A, JSONSchema as J, RunContext as R, SendMessageInput as S, ToolExecContext as T, AgentHarness as a, SessionCtx as b, SessionDetail as c, SessionStore as d, SessionSummary as e, ToolResult as f, AgentHarnessFactory as g, AgentHarnessFactoryInput as h };
+export { type AgentTool as A, type JSONSchema as J, type RunContext as R, type SendMessageInput as S, type TelemetryEvent as T, type AgentHarness as a, type SessionCtx as b, type SessionDetail as c, type SessionStore as d, type SessionSummary as e, type TelemetrySink as f, type ToolExecContext as g, type ToolResult as h, type AgentHarnessFactory as i, type AgentHarnessFactoryInput as j, noopTelemetry as n, safeCapture as s };

package/dist/server/index.d.ts

@@ -1,8 +1,8 @@
 import { S as Sandbox, f as SandboxHandleStore, e as SandboxHandleRecord, W as Workspace, F as FileSearch, P as PluginRestartWarning } from '../agentPluginEvents-zyIvVjsA.js';
 import { Sandbox as Sandbox$1 } from '@vercel/sandbox';
 import { FastifyInstance, FastifyRequest, FastifyPluginAsync } from 'fastify';
-import { A as AgentTool, g as AgentHarnessFactory } from '../harness-DRrTn_5T.js';
-export { h as AgentHarnessFactoryInput } from '../harness-DRrTn_5T.js';
+import { f as TelemetrySink, A as AgentTool, i as AgentHarnessFactory } from '../harness-BCit36Ha.js';
+export { j as AgentHarnessFactoryInput } from '../harness-BCit36Ha.js';
 import { PackageSource, ExtensionFactory, SettingsManager } from '@mariozechner/pi-coding-agent';
 import 'ai';
 
@@ -181,12 +181,12 @@ declare function fileRoutes(app: FastifyInstance, opts: {
     getWorkspace?: (request: FastifyRequest) => Workspace | Promise<Workspace>;
 }, done: (err?: Error) => void): void;
 
-interface RuntimeTemplateContribution {
+interface RuntimeTemplateContribution$1 {
     id: string;
     path: string | URL;
     target?: string;
 }
-interface RuntimePythonSpec {
+interface RuntimePythonSpec$1 {
     id: string;
     /** uv-compatible pyproject.toml. Console scripts declared here are exposed to the agent. */
     projectFile: string | URL;
@@ -195,23 +195,23 @@ interface RuntimePythonSpec {
     /** Env vars exported by command shims, e.g. plugin builtin paths. */
     env?: Record<string, string | URL>;
 }
-interface RuntimeNodePackageSpec {
+interface RuntimeNodePackageSpec$1 {
     id: string;
     /** Package name materialized under workspaceRoot/node_modules, e.g. @boring/workspace. */
     packageName: string;
     /** Source package root. The provisioner copies the built package payload into node_modules. */
     packageRoot: string | URL;
 }
-interface RuntimeProvisioningContribution {
-    templateDirs?: RuntimeTemplateContribution[];
-    python?: RuntimePythonSpec[];
-    nodePackages?: RuntimeNodePackageSpec[];
+interface RuntimeProvisioningContribution$1 {
+    templateDirs?: RuntimeTemplateContribution$1[];
+    python?: RuntimePythonSpec$1[];
+    nodePackages?: RuntimeNodePackageSpec$1[];
 }
 interface ProvisionRuntimeWorkspaceOptions {
     workspaceRoot: string;
     contributions?: Array<{
         id: string;
-        provisioning?: RuntimeProvisioningContribution;
+        provisioning?: RuntimeProvisioningContribution$1;
     }>;
     force?: boolean;
 }
@@ -223,6 +223,31 @@ interface RuntimeWorkspaceProvisioningResult {
 }
 declare function provisionRuntimeWorkspace({ workspaceRoot, contributions, force, }: ProvisionRuntimeWorkspaceOptions): Promise<RuntimeWorkspaceProvisioningResult>;
 
+interface BoringAgentRuntimePaths {
+    /** Runtime-visible workspace root. This is BORING_AGENT_WORKSPACE_ROOT. */
+    workspaceRoot: string;
+    agentDir: string;
+    node: string;
+    nodeModules: string;
+    nodeBin: string;
+    venv: string;
+    venvBin: string;
+    venvPython: string;
+    sdk: string;
+    uvHome: string;
+    uvBin: string;
+    skills: string;
+    cache: string;
+    nodeCache: string;
+    uvCache: string;
+    pipCache: string;
+    tmp: string;
+}
+declare function getBoringAgentRuntimePaths(runtimeWorkspaceRoot: string): BoringAgentRuntimePaths;
+declare function getBoringAgentPathEntries(paths: BoringAgentRuntimePaths): string[];
+declare function getBoringAgentRuntimeEnv(paths: BoringAgentRuntimePaths, adapterCacheRoot?: string): Record<string, string>;
+
+declare const VERCEL_SANDBOX_WORKSPACE_ROOT = "/workspace";
 interface VercelSandboxWorkspace extends Workspace {
     invalidateMetadataCache(): void;
 }
@@ -231,6 +256,120 @@ interface VercelSandboxWorkspaceOptions {
 }
 declare function createVercelSandboxWorkspace(sandbox: Sandbox$1, workspaceOpts?: VercelSandboxWorkspaceOptions): VercelSandboxWorkspace;
 
+interface ProvisioningLogger {
+    info?(message: string, fields?: Record<string, unknown>): void;
+    warn?(message: string, fields?: Record<string, unknown>): void;
+    error?(message: string, fields?: Record<string, unknown>): void;
+}
+
+interface PluginSkillSource {
+    name: string;
+    source: string | URL;
+}
+interface RuntimeTemplateContribution {
+    id: string;
+    path: string | URL;
+    target?: string;
+}
+interface RuntimePythonSpec {
+    id: string;
+    projectFile: string | URL;
+    packageName?: string;
+    packageRoot?: string | URL;
+    version?: string;
+    extraLibs?: string[];
+    env?: Record<string, string | URL>;
+    expectedBins?: string[];
+}
+interface RuntimeNodePackageSpec {
+    id: string;
+    packageName: string;
+    packageRoot?: string | URL;
+    version?: string;
+    expectedBins?: string[];
+}
+interface RuntimeProvisioningContribution {
+    templateDirs?: RuntimeTemplateContribution[];
+    python?: RuntimePythonSpec[];
+    nodePackages?: RuntimeNodePackageSpec[];
+}
+interface WorkspaceProvisioningResult {
+    changed: boolean;
+    env: Record<string, string>;
+    pathEntries: string[];
+    skillPaths: string[];
+}
+interface WorkspaceProvisioningExecResult {
+    stdout?: string;
+    stderr?: string;
+}
+interface WorkspaceProvisioningAdapter {
+    mode: 'direct' | 'local' | 'vercel-sandbox';
+    exec(command: string, args: string[], opts?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        timeoutMs?: number;
+    }): Promise<WorkspaceProvisioningExecResult | void>;
+    resolveInstallSource(source: string | URL, opts: {
+        kind: 'node' | 'python';
+        id: string;
+        fingerprint: string;
+    }): Promise<string>;
+    workspaceFs: {
+        exists(workspaceRelativePath: string): Promise<boolean>;
+        /** Remove a workspace-relative generated path. Missing path is success. */
+        rm(workspaceRelativePath: string): Promise<void>;
+        /** Create a workspace-relative directory recursively. */
+        mkdir(workspaceRelativePath: string): Promise<void>;
+        writeText(workspaceRelativePath: string, content: string): Promise<void>;
+        readText(workspaceRelativePath: string): Promise<string | null>;
+        /** Copy a host file or directory into the workspace; directory copies are recursive. */
+        copyFromHost(hostSourcePath: string | URL, workspaceRelativeTarget: string): Promise<void>;
+    };
+    getRuntimeCacheRoot(): string;
+}
+interface ProvisioningTelemetryContext {
+    workspaceId?: string;
+    sessionId?: string;
+    requestId?: string;
+    runtimeMode?: string;
+}
+interface ProvisionWorkspaceRuntimeOptions {
+    plugins: Array<{
+        id: string;
+        skills?: PluginSkillSource[];
+        provisioning?: RuntimeProvisioningContribution;
+    }>;
+    adapter: WorkspaceProvisioningAdapter;
+    runtimeLayout: BoringAgentRuntimePaths;
+    logger?: ProvisioningLogger;
+    telemetry?: TelemetrySink;
+    telemetryContext?: ProvisioningTelemetryContext;
+}
+
+declare function provisionWorkspaceRuntime(opts: ProvisionWorkspaceRuntimeOptions): Promise<WorkspaceProvisioningResult>;
+
+declare const VERCEL_PROVISIONING_CACHE_ROOT = "/tmp/boring-agent-cache";
+interface VercelProvisioningArtifactRequest {
+    kind: 'node' | 'python';
+    id: string;
+    fingerprint: string;
+    source: string | URL;
+    outputPath: string;
+}
+interface CreateVercelProvisioningAdapterOptions {
+    runtimeLayout: BoringAgentRuntimePaths;
+    workspaceFs: WorkspaceProvisioningAdapter['workspaceFs'];
+    exec(command: string, args: string[], opts?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        timeoutMs?: number;
+    }): Promise<WorkspaceProvisioningExecResult | void>;
+    prepareArtifact(request: VercelProvisioningArtifactRequest): Promise<void>;
+    cacheRoot?: string;
+}
+declare function createVercelProvisioningAdapter(options: CreateVercelProvisioningAdapterOptions): WorkspaceProvisioningAdapter;
+
 type BuiltinRuntimeModeId = 'direct' | 'local' | 'vercel-sandbox';
 type RuntimeModeId = BuiltinRuntimeModeId | (string & {});
 interface RuntimeModeAdapter {
@@ -242,6 +381,7 @@ interface RuntimeModeAdapter {
      */
     readonly workspaceFsCapability?: Workspace['fsCapability'];
     create(ctx: ModeContext): Promise<RuntimeBundle>;
+    createProvisioningAdapter?(runtimeLayout: BoringAgentRuntimePaths, ctx?: ModeContext): WorkspaceProvisioningAdapter;
     dispose?(): Promise<void>;
 }
 interface ModeContext {
@@ -249,6 +389,8 @@ interface ModeContext {
     sessionId: string;
     workspaceId?: string;
     templatePath?: string;
+    requestId?: string;
+    telemetry?: TelemetrySink;
 }
 interface RuntimeBundle {
     workspace: Workspace;
@@ -342,8 +484,14 @@ interface CreateAgentAppOptions {
     harnessFactory?: AgentHarnessFactory;
     /** Optional pi adapter/runtime knobs used by the default harness. */
     pi?: PiHarnessOptions;
+    /** Optional runtime provisioning result used to wire generated PATH/env/skills into tools and Pi. */
+    runtimeProvisioning?: WorkspaceProvisioningResult;
+    /** Optional dynamic runtime provisioning source used after /reload refreshes generated env/PATH. */
+    getRuntimeProvisioning?: () => WorkspaceProvisioningResult | undefined;
     /** Optional stable namespace for file-backed session storage. */
     sessionNamespace?: string;
+    /** Optional best-effort telemetry sink supplied by an embedding host. */
+    telemetry?: TelemetrySink;
     /** Optional explicit file-backed session directory. Mostly for tests/hosts. */
     sessionDir?: string;
     /**
@@ -400,6 +548,8 @@ interface RegisterAgentRoutesOptions {
         request?: FastifyRequest;
     }) => PiHarnessOptions | undefined | Promise<PiHarnessOptions | undefined>;
     sessionNamespace?: string;
+    /** Optional best-effort telemetry sink supplied by an embedding host. */
+    telemetry?: TelemetrySink;
     getSessionNamespace?: (ctx: {
         workspaceId: string;
         workspaceRoot: string;
@@ -409,6 +559,26 @@ interface RegisterAgentRoutesOptions {
     sandboxHandleStore?: SandboxHandleStore;
     getWorkspaceId?: (request: FastifyRequest) => string | Promise<string>;
     getWorkspaceRoot?: (workspaceId: string, request: FastifyRequest) => string | Promise<string>;
+    /**
+     * Optional runtime reconciliation hook. Callers own plugin discovery and may
+     * call provisionWorkspaceRuntime() with the normalized structural inputs.
+     * registerAgentRoutes only consumes the returned env/PATH/skill paths.
+     */
+    provisionRuntime?: (ctx: {
+        workspaceId: string;
+        workspaceRoot: string;
+        runtimeMode: RuntimeModeId;
+        runtimeLayout: BoringAgentRuntimePaths;
+        provisioningAdapter?: WorkspaceProvisioningAdapter;
+        request?: FastifyRequest;
+    }) => WorkspaceProvisioningResult | undefined | Promise<WorkspaceProvisioningResult | undefined>;
+    provisionWorkspace?: boolean;
+    /** Optional hook called before /api/v1/agent/reload reloads the harness. */
+    beforeReload?: (ctx: {
+        workspaceId: string;
+        workspaceRoot: string;
+        request: FastifyRequest;
+    }) => void | ReloadHookResult | undefined | Promise<void | ReloadHookResult | undefined>;
 }
 /**
  * Fastify plugin that mounts agent routes onto a host app (typically core-built).
@@ -430,4 +600,4 @@ interface Logger {
 }
 declare function createLogger(prefix: string): Logger;
 
-export { AgentHarnessFactory, type BuiltinRuntimeModeId, type CreateAgentAppOptions, type DeploymentSnapshotProvider, type DeploymentSnapshotRecipe, type DeploymentSnapshotResult, type DeploymentSnapshotStatus, FileHandleStore, type LogFields, type Logger, type ModeContext, PI_PACKAGE_RESOURCE_FILTERS, type PiExtensionFactory, type PiHarnessOptions, type PiPackageSource, type ProvisionRuntimeWorkspaceOptions, type RegisterAgentRoutesOptions, type RuntimeBundle, type RuntimeModeAdapter, type RuntimeModeId, type RuntimeNodePackageSpec, type RuntimeProvisioningContribution, type RuntimePythonSpec, type RuntimeTemplateContribution, type RuntimeWorkspaceProvisioningResult, type SnapshotBakeOptions, type SnapshotBakeResult, UV_SETUP_COMMANDS, UV_SETUP_COMMANDS as VERCEL_UV_SETUP_COMMANDS, type VercelBakeClient, type VercelBakeSandbox, type VercelDeploymentSnapshotOptions, applyCspHeaders, autoDetectMode, bakeSnapshotIfNeeded, buildDeploymentSnapshotRecipe, buildPackageHash, buildSnapshotRecipeHash, compactPiPackages, createAgentApp, createBwrapSandbox, createDirectSandbox, createLogger, createNodeWorkspace, createResourceSettingsManager, createVercelDeploymentSnapshotProvider, createVercelSandboxWorkspace, fileRoutes, hasBwrap, mergePiPackageSources, piPackageSourceKey, prepareDeploymentSnapshot, prepareVercelDeploymentSnapshot, provisionRuntimeWorkspace, registerAgentRoutes, resolveMode, resolveSandboxHandle };
+export { AgentHarnessFactory, type BoringAgentRuntimePaths, type BuiltinRuntimeModeId, type CreateAgentAppOptions, type CreateVercelProvisioningAdapterOptions, type DeploymentSnapshotProvider, type DeploymentSnapshotRecipe, type DeploymentSnapshotResult, type DeploymentSnapshotStatus, FileHandleStore, type LogFields, type Logger, type ModeContext, PI_PACKAGE_RESOURCE_FILTERS, type PiExtensionFactory, type PiHarnessOptions, type PiPackageSource, type PluginSkillSource, type ProvisionRuntimeWorkspaceOptions, type ProvisionWorkspaceRuntimeOptions, type RegisterAgentRoutesOptions, type RuntimeBundle, type RuntimeModeAdapter, type RuntimeModeId, type RuntimeNodePackageSpec, type RuntimeProvisioningContribution, type RuntimePythonSpec, type RuntimeTemplateContribution, type RuntimeWorkspaceProvisioningResult, type SnapshotBakeOptions, type SnapshotBakeResult, UV_SETUP_COMMANDS, VERCEL_PROVISIONING_CACHE_ROOT, VERCEL_SANDBOX_WORKSPACE_ROOT, UV_SETUP_COMMANDS as VERCEL_UV_SETUP_COMMANDS, type VercelBakeClient, type VercelBakeSandbox, type VercelDeploymentSnapshotOptions, type VercelProvisioningArtifactRequest, type WorkspaceProvisioningAdapter, type WorkspaceProvisioningExecResult, type WorkspaceProvisioningResult, applyCspHeaders, autoDetectMode, bakeSnapshotIfNeeded, buildDeploymentSnapshotRecipe, buildPackageHash, buildSnapshotRecipeHash, compactPiPackages, createAgentApp, createBwrapSandbox, createDirectSandbox, createLogger, createNodeWorkspace, createResourceSettingsManager, createVercelDeploymentSnapshotProvider, createVercelProvisioningAdapter, createVercelSandboxWorkspace, fileRoutes, getBoringAgentPathEntries, getBoringAgentRuntimeEnv, getBoringAgentRuntimePaths, hasBwrap, mergePiPackageSources, piPackageSourceKey, prepareDeploymentSnapshot, prepareVercelDeploymentSnapshot, provisionRuntimeWorkspace, provisionWorkspaceRuntime, registerAgentRoutes, resolveMode, resolveSandboxHandle };