@hachej/boring-agent 0.1.12 → 0.1.13

package/dist/server/index.d.ts

@@ -215,9 +215,16 @@ interface VercelSandboxWorkspaceOptions {
 }
 declare function createVercelSandboxWorkspace(sandbox: Sandbox$1, workspaceOpts?: VercelSandboxWorkspaceOptions): VercelSandboxWorkspace;
 
-type RuntimeModeId = 'direct' | 'local' | 'vercel-sandbox';
+type BuiltinRuntimeModeId = 'direct' | 'local' | 'vercel-sandbox';
+type RuntimeModeId = BuiltinRuntimeModeId | (string & {});
 interface RuntimeModeAdapter {
     readonly id: RuntimeModeId;
+    /**
+     * Declares whether the workspace files are strongly available on the host
+     * path before create() runs. Composition layers use this to decide whether
+     * host-side fs checks/prompts are safe without hard-coding sandbox IDs.
+     */
+    readonly workspaceFsCapability?: Workspace['fsCapability'];
     create(ctx: ModeContext): Promise<RuntimeBundle>;
     dispose?(): Promise<void>;
 }
@@ -260,6 +267,8 @@ interface CreateAgentAppOptions {
     sessionId?: string;
     templatePath?: string;
     mode?: RuntimeModeId;
+    /** Supply a custom runtime adapter to plug in non-built-in sandbox/workspace modes. */
+    runtimeModeAdapter?: RuntimeModeAdapter;
     authToken?: string;
     version?: string;
     logger?: boolean;
@@ -295,12 +304,15 @@ interface RegisterAgentRoutesOptions {
         request?: FastifyRequest;
     }) => string | undefined | Promise<string | undefined>;
     mode?: RuntimeModeId;
+    /** Supply a custom runtime adapter to plug in non-built-in sandbox/workspace modes. */
+    runtimeModeAdapter?: RuntimeModeAdapter;
     version?: string;
     extraTools?: AgentTool[];
     getExtraTools?: (ctx: {
         workspaceId: string;
         workspaceRoot: string;
         runtimeMode: RuntimeModeId;
+        workspaceFsCapability?: Workspace['fsCapability'];
     }) => AgentTool[] | Promise<AgentTool[]>;
     systemPromptAppend?: string;
     resourceLoaderOptions?: PiResourceLoaderOptions;
@@ -329,4 +341,4 @@ interface Logger {
 }
 declare function createLogger(prefix: string): Logger;
 
-export { type CreateAgentAppOptions, type DeploymentSnapshotProvider, type DeploymentSnapshotRecipe, type DeploymentSnapshotResult, type DeploymentSnapshotStatus, FileHandleStore, type LogFields, type Logger, type ModeContext, PI_PACKAGE_RESOURCE_FILTERS, type PiPackageSource, type PiResourceLoaderOptions, type ProvisionRuntimeWorkspaceOptions, type RegisterAgentRoutesOptions, type RuntimeBundle, type RuntimeModeAdapter, type RuntimeModeId, 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, createVercelDeploymentSnapshotProvider, createVercelSandboxWorkspace, hasBwrap, mergePiPackageSources, piPackageSourceKey, prepareDeploymentSnapshot, prepareVercelDeploymentSnapshot, provisionRuntimeWorkspace, registerAgentRoutes, resolveMode, resolveSandboxHandle };
+export { type BuiltinRuntimeModeId, type CreateAgentAppOptions, type DeploymentSnapshotProvider, type DeploymentSnapshotRecipe, type DeploymentSnapshotResult, type DeploymentSnapshotStatus, FileHandleStore, type LogFields, type Logger, type ModeContext, PI_PACKAGE_RESOURCE_FILTERS, type PiPackageSource, type PiResourceLoaderOptions, type ProvisionRuntimeWorkspaceOptions, type RegisterAgentRoutesOptions, type RuntimeBundle, type RuntimeModeAdapter, type RuntimeModeId, 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, createVercelDeploymentSnapshotProvider, createVercelSandboxWorkspace, hasBwrap, mergePiPackageSources, piPackageSourceKey, prepareDeploymentSnapshot, prepareVercelDeploymentSnapshot, provisionRuntimeWorkspace, registerAgentRoutes, resolveMode, resolveSandboxHandle };

package/dist/server/index.js

@@ -2164,6 +2164,7 @@ async function copyTemplate(templatePath, workspaceRoot) {
 // src/server/runtime/modes/direct.ts
 var directModeAdapter = {
   id: "direct",
+  workspaceFsCapability: "strong",
   async create(ctx) {
     await mkdir6(ctx.workspaceRoot, { recursive: true });
     await copyTemplate(ctx.templatePath, ctx.workspaceRoot);
@@ -2182,6 +2183,7 @@ var directModeAdapter = {
 import { mkdir as mkdir7 } from "fs/promises";
 var localModeAdapter = {
   id: "local",
+  workspaceFsCapability: "strong",
   async create(ctx) {
     if (process.platform !== "linux") {
       throw new Error("local mode requires Linux with bubblewrap");
@@ -2249,17 +2251,32 @@ function toRemotePath(value) {
   }
   return value;
 }
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var WORKSPACE_ALIAS_PREFIX_BOUNDARY = String.raw`(^|[\s"'=:;,\[({<>&|])`;
+var WORKSPACE_ALIAS_SUFFIX_BOUNDARY = String.raw`(?=/|$|[\s"'=:;,)\]}> &|])`;
+var WORKSPACE_ALIAS_PATTERN = new RegExp(
+  `${WORKSPACE_ALIAS_PREFIX_BOUNDARY}${escapeRegExp(VERCEL_SANDBOX_WORKSPACE_ROOT)}${WORKSPACE_ALIAS_SUFFIX_BOUNDARY}`,
+  "g"
+);
+function replaceWorkspaceAliases(value) {
+  return value.replace(
+    WORKSPACE_ALIAS_PATTERN,
+    (_match, prefix) => `${prefix}${VERCEL_SANDBOX_REMOTE_ROOT}`
+  );
+}
 function toRemoteCwd(cwd) {
   if (!cwd) return cwd;
   return toRemotePath(cwd);
 }
 function toRemoteCommand(command) {
-  return command.replaceAll(VERCEL_SANDBOX_WORKSPACE_ROOT, VERCEL_SANDBOX_REMOTE_ROOT);
+  return replaceWorkspaceAliases(command);
 }
 function toRemoteEnv(env) {
   if (!env) return void 0;
   return Object.fromEntries(
-    Object.entries(env).map(([key, value]) => [key, toRemotePath(value)])
+    Object.entries(env).map(([key, value]) => [key, replaceWorkspaceAliases(toRemotePath(value))])
   );
 }
 function createVercelSandboxExec(sandbox, execOpts = {}) {
@@ -2590,6 +2607,7 @@ function createVercelSandboxModeAdapter(opts = {}) {
   const snapshotScheduler = opts.snapshotScheduler ?? null;
   return {
     id: "vercel-sandbox",
+    workspaceFsCapability: "best-effort",
     async dispose() {
       await snapshotScheduler?.shutdown();
     },
@@ -2686,7 +2704,7 @@ var MODE_ADAPTERS = {
   local: localModeAdapter,
   "vercel-sandbox": vercelSandboxModeAdapter
 };
-function isRuntimeModeId(value) {
+function isBuiltinRuntimeModeId(value) {
   return value === "direct" || value === "local" || value === "vercel-sandbox";
 }
 function hasBwrap() {
@@ -2696,7 +2714,7 @@ function hasBwrap() {
 function autoDetectMode() {
   const explicitMode = getEnv("BORING_AGENT_MODE");
   if (explicitMode) {
-    if (!isRuntimeModeId(explicitMode)) {
+    if (!isBuiltinRuntimeModeId(explicitMode)) {
       throw new Error(
         `Invalid BORING_AGENT_MODE "${explicitMode}". Expected direct, local, or vercel-sandbox.`
       );
@@ -2709,7 +2727,8 @@ function autoDetectMode() {
   return "direct";
 }
 function resolveMode(mode = autoDetectMode()) {
-  return MODE_ADAPTERS[mode];
+  if (isBuiltinRuntimeModeId(mode)) return MODE_ADAPTERS[mode];
+  throw new Error(`Runtime mode "${mode}" has no built-in adapter. Pass runtimeModeAdapter to use a custom sandbox mode.`);
 }
 
 // src/server/createAgentApp.ts
@@ -4554,22 +4573,29 @@ function boundFs(workspaceRoot) {
 }
 
 // src/server/tools/operations/vercel.ts
-import { relative as relative5 } from "path";
+import { isAbsolute as isAbsolute5, relative as relative5 } from "path";
 function rootAliases(workspace) {
   const aliases = [workspace.root];
   if (workspace.root === VERCEL_SANDBOX_WORKSPACE_ROOT) aliases.push(VERCEL_SANDBOX_REMOTE_ROOT);
   if (workspace.root === VERCEL_SANDBOX_REMOTE_ROOT) aliases.push(VERCEL_SANDBOX_WORKSPACE_ROOT);
   return aliases;
 }
+function isOutsideWorkspaceRel(rel) {
+  return rel === ".." || rel.startsWith("../") || rel.startsWith("..\\") || isAbsolute5(rel);
+}
 function toRelPath(workspace, absolutePath) {
   for (const root of rootAliases(workspace)) {
     const rel = relative5(root, absolutePath);
-    if (!rel.startsWith("..") && !rel.startsWith("/")) return rel;
+    if (!isOutsideWorkspaceRel(rel)) return rel;
   }
   const skillMarker = "/.agents/skills/";
   const skillIndex = absolutePath.indexOf(skillMarker);
   if (skillIndex >= 0) {
-    return `.agents/skills/${absolutePath.slice(skillIndex + skillMarker.length)}`;
+    const skillPath = absolutePath.slice(skillIndex + skillMarker.length);
+    if (skillPath.includes("\0") || skillPath.split(/[\\/]+/).includes("..")) {
+      throw new Error(`path "${absolutePath}" escapes the workspace skills directory`);
+    }
+    return `.agents/skills/${skillPath}`;
   }
   throw new Error(
     `path "${absolutePath}" is outside workspace; use a path relative to the workspace root or under ${rootAliases(workspace).join(" / ")}`
@@ -4663,7 +4689,7 @@ function fallbackFindCommand(pattern, cwd, options) {
 function isFdMissing(result) {
   if (result.exitCode !== 127) return false;
   const stderr = Buffer.from(result.stderr).toString("utf-8");
-  return /fd: not found|fd: command not found|not found/i.test(stderr);
+  return /\bfd: (?:not found|command not found)\b/i.test(stderr);
 }
 function vercelFindOps(sandbox, workspace) {
   return {
@@ -6998,14 +7024,15 @@ async function createAgentApp(opts = {}) {
   const sessionId = opts.sessionId ?? DEFAULT_SESSION_ID;
   const templatePath = opts.templatePath ?? getEnv("BORING_AGENT_TEMPLATE_PATH");
   const app = Fastify({ logger: opts.logger ?? true, bodyLimit: 16 * 1024 * 1024 });
-  const resolvedMode = opts.mode ?? autoDetectMode();
-  const runtimeBundle = await resolveMode(resolvedMode).create({
+  const resolvedMode = opts.runtimeModeAdapter?.id ?? opts.mode ?? autoDetectMode();
+  const modeAdapter = opts.runtimeModeAdapter ?? resolveMode(resolvedMode);
+  const runtimeBundle = await modeAdapter.create({
     workspaceRoot,
     sessionId,
     templatePath
   });
   const pluginTools = [];
-  if (resolvedMode !== "vercel-sandbox") {
+  if (modeAdapter.workspaceFsCapability === "strong") {
     const pluginResult = await loadPlugins({ cwd: workspaceRoot });
     if (pluginResult.errors.length > 0) {
       for (const e of pluginResult.errors) {
@@ -7293,8 +7320,8 @@ var registerAgentRoutes = async (app, opts) => {
   const workspaceRoot = opts.workspaceRoot ?? process.cwd();
   const sessionId = opts.sessionId ?? DEFAULT_WORKSPACE_ID3;
   const templatePath = opts.templatePath ?? getEnv("BORING_AGENT_TEMPLATE_PATH");
-  const resolvedMode = opts.mode ?? autoDetectMode();
-  const modeAdapter = selectRuntimeModeAdapter(resolvedMode, opts.sandboxHandleStore);
+  const resolvedMode = opts.runtimeModeAdapter?.id ?? opts.mode ?? autoDetectMode();
+  const modeAdapter = opts.runtimeModeAdapter ?? selectRuntimeModeAdapter(resolvedMode, opts.sandboxHandleStore);
   app.addHook("onClose", async () => {
     await modeAdapter.dispose?.();
   });
@@ -7322,7 +7349,7 @@ var registerAgentRoutes = async (app, opts) => {
       ...buildUploadAgentTools(runtimeBundle)
     ];
     const pluginTools = [];
-    if (resolvedMode !== "vercel-sandbox") {
+    if (modeAdapter.workspaceFsCapability === "strong") {
       const pluginResult = await loadPlugins({ cwd: root });
       if (pluginResult.errors.length > 0) {
         for (const e of pluginResult.errors) {
@@ -7339,7 +7366,8 @@ var registerAgentRoutes = async (app, opts) => {
     const scopedExtraTools = opts.getExtraTools ? await opts.getExtraTools({
       workspaceId,
       workspaceRoot: root,
-      runtimeMode: resolvedMode
+      runtimeMode: resolvedMode,
+      workspaceFsCapability: runtimeBundle.workspace.fsCapability
     }) : [];
     const tools = mergeTools({
       standardTools,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hachej/boring-agent",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "type": "module",
   "license": "MIT",
   "description": "Pane-embeddable coding agent. Ships direct/local/vercel-sandbox execution modes behind one interface.",
@@ -74,7 +74,7 @@
     "use-stick-to-bottom": "^1.1.3",
     "yaml": "^2.8.3",
     "zod": "^3.25.76",
-    "@hachej/boring-ui-kit": "0.1.12"
+    "@hachej/boring-ui-kit": "0.1.13"
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.1",