@geminixiang/mikan 1.0.0-beta.2 → 1.0.0-beta.21

package/dist/sandbox/host.js.map

@@ -1 +1 @@
-{"version":3,"file":"host.js","sourceRoot":"","sources":["../../src/sandbox/host.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from \"child_process\";\nimport type {\n  ExecOptions,\n  ExecResult,\n  Executor,\n  HostSandboxConfig,\n  RuntimePathContext,\n  SandboxAdapter,\n} from \"./types.js\";\nimport { killProcessTree } from \"./utils.js\";\nimport { createMountedRuntimePathContext } from \"./path-context.js\";\n\nfunction parseHostSandboxArg(value: string): HostSandboxConfig | undefined {\n  if (value === \"host\") {\n    return { type: \"host\" };\n  }\n  return undefined;\n}\n\nexport class HostExecutor implements Executor {\n  async exec(command: string, options?: ExecOptions): Promise<ExecResult> {\n    return new Promise((resolve, reject) => {\n      const shell = process.platform === \"win32\" ? \"cmd\" : \"sh\";\n      const shellArgs = process.platform === \"win32\" ? [\"/c\"] : [\"-c\"];\n\n      const child = spawn(shell, [...shellArgs, command], {\n        detached: true,\n        stdio: [\"ignore\", \"pipe\", \"pipe\"],\n      });\n\n      let stdout = \"\";\n      let stderr = \"\";\n      let timedOut = false;\n\n      const timeoutHandle =\n        options?.timeout && options.timeout > 0\n          ? setTimeout(() => {\n              timedOut = true;\n              killProcessTree(child.pid!);\n            }, options.timeout * 1000)\n          : undefined;\n\n      const onAbort = () => {\n        if (child.pid) killProcessTree(child.pid);\n      };\n\n      if (options?.signal) {\n        if (options.signal.aborted) {\n          onAbort();\n        } else {\n          options.signal.addEventListener(\"abort\", onAbort, { once: true });\n        }\n      }\n\n      child.stdout?.on(\"data\", (data) => {\n        stdout += data.toString();\n        if (stdout.length > 10 * 1024 * 1024) {\n          stdout = stdout.slice(0, 10 * 1024 * 1024);\n        }\n      });\n\n      child.stderr?.on(\"data\", (data) => {\n        stderr += data.toString();\n        if (stderr.length > 10 * 1024 * 1024) {\n          stderr = stderr.slice(0, 10 * 1024 * 1024);\n        }\n      });\n\n      child.on(\"close\", (code) => {\n        if (timeoutHandle) clearTimeout(timeoutHandle);\n        if (options?.signal) {\n          options.signal.removeEventListener(\"abort\", onAbort);\n        }\n\n        if (options?.signal?.aborted) {\n          reject(new Error(`${stdout}\\n${stderr}\\nCommand aborted`.trim()));\n          return;\n        }\n\n        if (timedOut) {\n          reject(\n            new Error(\n              `${stdout}\\n${stderr}\\nCommand timed out after ${options?.timeout} seconds`.trim(),\n            ),\n          );\n          return;\n        }\n\n        resolve({ stdout, stderr, code: code ?? 0 });\n      });\n    });\n  }\n\n  getWorkspacePath(hostPath: string): string {\n    return hostPath;\n  }\n\n  getPathContext(hostWorkspaceRoot: string): RuntimePathContext {\n    return createMountedRuntimePathContext(hostWorkspaceRoot, hostWorkspaceRoot);\n  }\n\n  getSandboxConfig(): HostSandboxConfig {\n    return { type: \"host\" };\n  }\n}\n\nexport const hostSandboxAdapter: SandboxAdapter<HostSandboxConfig> = {\n  type: \"host\",\n  parse: parseHostSandboxArg,\n  createExecutor: () => new HostExecutor(),\n};\n"]}
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../../src/sandbox/host.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from \"child_process\";\nimport { mkdir, readFile, rename, writeFile } from \"fs/promises\";\nimport { dirname } from \"path\";\nimport type {\n  ExecOptions,\n  ExecResult,\n  Executor,\n  HostSandboxConfig,\n  RuntimePathContext,\n  SandboxAdapter,\n} from \"./types.js\";\nimport { killProcessTree } from \"./utils.js\";\nimport { createMountedRuntimePathContext } from \"./path-context.js\";\n\nfunction parseHostSandboxArg(value: string): HostSandboxConfig | undefined {\n  if (value === \"host\") {\n    return { type: \"host\" };\n  }\n  return undefined;\n}\n\nexport class HostExecutor implements Executor {\n  async exec(command: string, options?: ExecOptions): Promise<ExecResult> {\n    return new Promise((resolve, reject) => {\n      const shell = process.platform === \"win32\" ? \"cmd\" : \"sh\";\n      const shellArgs = process.platform === \"win32\" ? [\"/c\"] : [\"-c\"];\n\n      const child = spawn(shell, [...shellArgs, command], {\n        detached: true,\n        stdio: [\"ignore\", \"pipe\", \"pipe\"],\n      });\n\n      let stdout = \"\";\n      let stderr = \"\";\n      let timedOut = false;\n\n      const timeoutHandle =\n        options?.timeout && options.timeout > 0\n          ? setTimeout(() => {\n              timedOut = true;\n              killProcessTree(child.pid!);\n            }, options.timeout * 1000)\n          : undefined;\n\n      const onAbort = () => {\n        if (child.pid) killProcessTree(child.pid);\n      };\n\n      if (options?.signal) {\n        if (options.signal.aborted) {\n          onAbort();\n        } else {\n          options.signal.addEventListener(\"abort\", onAbort, { once: true });\n        }\n      }\n\n      child.stdout?.on(\"data\", (data) => {\n        stdout += data.toString();\n        if (stdout.length > 10 * 1024 * 1024) {\n          stdout = stdout.slice(0, 10 * 1024 * 1024);\n        }\n      });\n\n      child.stderr?.on(\"data\", (data) => {\n        stderr += data.toString();\n        if (stderr.length > 10 * 1024 * 1024) {\n          stderr = stderr.slice(0, 10 * 1024 * 1024);\n        }\n      });\n\n      child.on(\"close\", (code) => {\n        if (timeoutHandle) clearTimeout(timeoutHandle);\n        if (options?.signal) {\n          options.signal.removeEventListener(\"abort\", onAbort);\n        }\n\n        if (options?.signal?.aborted) {\n          reject(new Error(`${stdout}\\n${stderr}\\nCommand aborted`.trim()));\n          return;\n        }\n\n        if (timedOut) {\n          reject(\n            new Error(\n              `${stdout}\\n${stderr}\\nCommand timed out after ${options?.timeout} seconds`.trim(),\n            ),\n          );\n          return;\n        }\n\n        resolve({ stdout, stderr, code: code ?? 0 });\n      });\n    });\n  }\n\n  async readFile(path: string): Promise<string> {\n    return readFile(path, \"utf-8\");\n  }\n\n  async readFileBase64(path: string): Promise<string> {\n    return (await readFile(path)).toString(\"base64\");\n  }\n\n  async writeFile(path: string, content: string): Promise<void> {\n    await mkdir(dirname(path), { recursive: true });\n    const stage = `${path}.mikan-stage`;\n    await writeFile(stage, content, \"utf-8\");\n    await rename(stage, path);\n  }\n\n  getWorkspacePath(hostPath: string): string {\n    return hostPath;\n  }\n\n  getPathContext(hostWorkspaceRoot: string): RuntimePathContext {\n    return createMountedRuntimePathContext(hostWorkspaceRoot, hostWorkspaceRoot);\n  }\n\n  getSandboxConfig(): HostSandboxConfig {\n    return { type: \"host\" };\n  }\n}\n\nexport const hostSandboxAdapter: SandboxAdapter<HostSandboxConfig> = {\n  type: \"host\",\n  parse: parseHostSandboxArg,\n  createExecutor: () => new HostExecutor(),\n};\n"]}

package/dist/sandbox/identity.d.ts

@@ -0,0 +1,21 @@
+import type { SandboxConfig } from "./types.js";
+/**
+ * Runtime actor identity: the one key that names a conversation's vault dir,
+ * docker container and network, and cloudflare sandbox suffix. Everything
+ * that needs such a name consumes actorKey(); nothing may re-derive or
+ * re-sanitize it — two sanitizers with divergent outputs used to make a
+ * container/vault mismatch a silent wrong-identity bug rather than an error.
+ */
+export declare function sanitizeIdentitySegment(value: string): string;
+/**
+ * The actor key for a sandbox config: per-conversation for managed sandboxes
+ * (image/gondolin/cloudflare/firecracker), the fixed container name for a shared
+ * container, and the platform user id on the host.
+ */
+export declare function actorKey(baseConfig: SandboxConfig, ids: {
+    userId: string;
+    conversationId: string;
+}): string;
+/** Scope a base cloudflare sandbox id to one actor key. */
+export declare function scopeCloudflareSandboxId(baseId: string, actorVaultKey: string): string;
+//# sourceMappingURL=identity.d.ts.map

package/dist/sandbox/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/sandbox/identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM7D;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,UAAU,EAAE,aAAa,EACzB,GAAG,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GAC9C,MAAM,CAaR;AAED,2DAA2D;AAC3D,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CAEtF"}

package/dist/sandbox/identity.js

@@ -0,0 +1,36 @@
+/**
+ * Runtime actor identity: the one key that names a conversation's vault dir,
+ * docker container and network, and cloudflare sandbox suffix. Everything
+ * that needs such a name consumes actorKey(); nothing may re-derive or
+ * re-sanitize it — two sanitizers with divergent outputs used to make a
+ * container/vault mismatch a silent wrong-identity bug rather than an error.
+ */
+export function sanitizeIdentitySegment(value) {
+    const sanitized = value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return sanitized || "unknown";
+}
+/**
+ * The actor key for a sandbox config: per-conversation for managed sandboxes
+ * (image/gondolin/cloudflare/firecracker), the fixed container name for a shared
+ * container, and the platform user id on the host.
+ */
+export function actorKey(baseConfig, ids) {
+    if (baseConfig.type === "container") {
+        return `container-${baseConfig.container}`;
+    }
+    if (baseConfig.type === "image" ||
+        baseConfig.type === "gondolin" ||
+        baseConfig.type === "cloudflare" ||
+        baseConfig.type === "firecracker") {
+        return sanitizeIdentitySegment(ids.conversationId);
+    }
+    return ids.userId;
+}
+/** Scope a base cloudflare sandbox id to one actor key. */
+export function scopeCloudflareSandboxId(baseId, actorVaultKey) {
+    return `${baseId}-${sanitizeIdentitySegment(actorVaultKey)}`;
+}
+//# sourceMappingURL=identity.js.map

package/dist/sandbox/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/sandbox/identity.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa;IACnD,MAAM,SAAS,GAAG,KAAK;SACpB,WAAW,EAAE;SACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC3B,OAAO,SAAS,IAAI,SAAS,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CACtB,UAAyB,EACzB,GAA+C;IAE/C,IAAI,UAAU,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QACpC,OAAO,aAAa,UAAU,CAAC,SAAS,EAAE,CAAC;IAC7C,CAAC;IACD,IACE,UAAU,CAAC,IAAI,KAAK,OAAO;QAC3B,UAAU,CAAC,IAAI,KAAK,UAAU;QAC9B,UAAU,CAAC,IAAI,KAAK,YAAY;QAChC,UAAU,CAAC,IAAI,KAAK,aAAa,EACjC,CAAC;QACD,OAAO,uBAAuB,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,GAAG,CAAC,MAAM,CAAC;AACpB,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,wBAAwB,CAAC,MAAc,EAAE,aAAqB;IAC5E,OAAO,GAAG,MAAM,IAAI,uBAAuB,CAAC,aAAa,CAAC,EAAE,CAAC;AAC/D,CAAC","sourcesContent":["import type { SandboxConfig } from \"./types.js\";\n\n/**\n * Runtime actor identity: the one key that names a conversation's vault dir,\n * docker container and network, and cloudflare sandbox suffix. Everything\n * that needs such a name consumes actorKey(); nothing may re-derive or\n * re-sanitize it — two sanitizers with divergent outputs used to make a\n * container/vault mismatch a silent wrong-identity bug rather than an error.\n */\nexport function sanitizeIdentitySegment(value: string): string {\n  const sanitized = value\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, \"-\")\n    .replace(/^-+|-+$/g, \"\");\n  return sanitized || \"unknown\";\n}\n\n/**\n * The actor key for a sandbox config: per-conversation for managed sandboxes\n * (image/gondolin/cloudflare/firecracker), the fixed container name for a shared\n * container, and the platform user id on the host.\n */\nexport function actorKey(\n  baseConfig: SandboxConfig,\n  ids: { userId: string; conversationId: string },\n): string {\n  if (baseConfig.type === \"container\") {\n    return `container-${baseConfig.container}`;\n  }\n  if (\n    baseConfig.type === \"image\" ||\n    baseConfig.type === \"gondolin\" ||\n    baseConfig.type === \"cloudflare\" ||\n    baseConfig.type === \"firecracker\"\n  ) {\n    return sanitizeIdentitySegment(ids.conversationId);\n  }\n  return ids.userId;\n}\n\n/** Scope a base cloudflare sandbox id to one actor key. */\nexport function scopeCloudflareSandboxId(baseId: string, actorVaultKey: string): string {\n  return `${baseId}-${sanitizeIdentitySegment(actorVaultKey)}`;\n}\n"]}

package/dist/sandbox/index.d.ts

@@ -2,16 +2,25 @@ import { ContainerExecutor } from "./container.js";
 import { FirecrackerExecutor } from "./firecracker.js";
 import { CloudflareSandboxExecutor } from "./cloudflare.js";
 import { HostExecutor } from "./host.js";
-import type { Executor, SandboxAdapter, SandboxConfig } from "./types.js";
+import { GondolinExecutor } from "./gondolin.js";
+export { configureGondolinRuntime, type GondolinBootstrapOptions } from "./gondolin-bootstrap.js";
+import type { Executor, RuntimePathContext, SandboxAdapter, SandboxConfig } from "./types.js";
 export type { CloudflareSandboxConfig, ExecOptions, ExecResult, Executor, RuntimePathContext, SandboxAdapter, SandboxConfig, } from "./types.js";
-export { CloudflareSandboxExecutor, ContainerExecutor, FirecrackerExecutor, HostExecutor };
+export { CloudflareSandboxExecutor, ContainerExecutor, FirecrackerExecutor, HostExecutor, GondolinExecutor, };
 export { SandboxError } from "./errors.js";
-declare const sandboxAdapters: readonly [SandboxAdapter<import("./types.js").HostSandboxConfig>, SandboxAdapter<import("./types.js").ContainerSandboxConfig>, SandboxAdapter<import("./types.js").ImageSandboxConfig>, SandboxAdapter<import("./types.js").FirecrackerSandboxConfig>, SandboxAdapter<import("./types.js").CloudflareSandboxConfig>];
+declare const sandboxAdapters: readonly [SandboxAdapter<import("./types.js").HostSandboxConfig>, SandboxAdapter<import("./types.js").ContainerSandboxConfig>, SandboxAdapter<import("./types.js").ImageSandboxConfig>, SandboxAdapter<import("./types.js").GondolinSandboxConfig>, SandboxAdapter<import("./types.js").FirecrackerSandboxConfig>, SandboxAdapter<import("./types.js").CloudflareSandboxConfig>];
 export declare function getSandboxAdapters(): readonly [...typeof sandboxAdapters];
 export declare function parseSandboxArg(value: string): SandboxConfig;
 export declare function validateSandbox(config: SandboxConfig): Promise<void>;
 /**
- * Create an executor that runs commands on host, in Docker, in a Firecracker VM, or through a Cloudflare sandbox bridge.
+ * Create an executor that runs commands on host, in Docker, in a microVM, in a Firecracker VM, or through a Cloudflare sandbox bridge.
  */
 export declare function createExecutor(config: SandboxConfig, env?: Record<string, string>, ensureReady?: () => Promise<void>): Executor;
+/**
+ * The runtime path context for a sandbox config before an actor-specific
+ * executor is resolved. `image` configs are unresolved by nature (the actor
+ * decides the concrete container), but their mount layout is fixed, so path
+ * mapping is known without resolving.
+ */
+export declare function getUnresolvedSandboxPathContext(sandboxConfig: SandboxConfig, hostWorkspaceRoot: string): RuntimePathContext;
 //# sourceMappingURL=index.d.ts.map

package/dist/sandbox/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAA2B,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAA6B,MAAM,kBAAkB,CAAC;AAClF,OAAO,EAAE,yBAAyB,EAA4B,MAAM,iBAAiB,CAAC;AACtF,OAAO,EAAE,YAAY,EAAsB,MAAM,WAAW,CAAC;AAG7D,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE1E,YAAY,EACV,uBAAuB,EACvB,WAAW,EACX,UAAU,EACV,QAAQ,EACR,kBAAkB,EAClB,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,YAAY,EAAE,CAAC;AAC3F,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,QAAA,MAAM,eAAe,sTAMX,CAAC;AAKX,wBAAgB,kBAAkB,IAAI,SAAS,CAAC,GAAG,OAAO,eAAe,CAAC,CAEzE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAiB5D;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAO1E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAChC,QAAQ,CASV"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAA2B,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAA6B,MAAM,kBAAkB,CAAC;AAClF,OAAO,EAAE,yBAAyB,EAA4B,MAAM,iBAAiB,CAAC;AACtF,OAAO,EAAE,YAAY,EAAsB,MAAM,WAAW,CAAC;AAE7D,OAAO,EAAE,gBAAgB,EAA0B,MAAM,eAAe,CAAC;AAGzE,OAAO,EAAE,wBAAwB,EAAE,KAAK,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAClG,OAAO,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE9F,YAAY,EACV,uBAAuB,EACvB,WAAW,EACX,UAAU,EACV,QAAQ,EACR,kBAAkB,EAClB,cAAc,EACd,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,GACjB,CAAC;AACF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,QAAA,MAAM,eAAe,kXAOX,CAAC;AAKX,wBAAgB,kBAAkB,IAAI,SAAS,CAAC,GAAG,OAAO,eAAe,CAAC,CAEzE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAiB5D;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAO1E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,aAAa,EACrB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAChC,QAAQ,CASV;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,aAAa,EAAE,aAAa,EAC5B,iBAAiB,EAAE,MAAM,GACxB,kBAAkB,CAMpB"}

package/dist/sandbox/index.js

@@ -3,13 +3,17 @@ import { FirecrackerExecutor, firecrackerSandboxAdapter } from "./firecracker.js
 import { CloudflareSandboxExecutor, cloudflareSandboxAdapter } from "./cloudflare.js";
 import { HostExecutor, hostSandboxAdapter } from "./host.js";
 import { imageSandboxAdapter } from "./image.js";
+import { GondolinExecutor, gondolinSandboxAdapter } from "./gondolin.js";
 import { SandboxError } from "./errors.js";
-export { CloudflareSandboxExecutor, ContainerExecutor, FirecrackerExecutor, HostExecutor };
+import { createMountedRuntimePathContext } from "./path-context.js";
+export { configureGondolinRuntime } from "./gondolin-bootstrap.js";
+export { CloudflareSandboxExecutor, ContainerExecutor, FirecrackerExecutor, HostExecutor, GondolinExecutor, };
 export { SandboxError } from "./errors.js";
 const sandboxAdapters = [
     hostSandboxAdapter,
     containerSandboxAdapter,
     imageSandboxAdapter,
+    gondolinSandboxAdapter,
     firecrackerSandboxAdapter,
     cloudflareSandboxAdapter,
 ];
@@ -27,7 +31,7 @@ export function parseSandboxArg(value) {
     if (value.startsWith("docker:")) {
         throw new SandboxError(`Error: '${value}' is not supported. Use 'container:<container-name>' for the shared-container mode or 'image:<image-name>' for mikan-managed per-user containers.`);
     }
-    throw new SandboxError(`Error: Invalid sandbox type '${value}'. Use 'host', 'container:<container-name>', 'image:<image-name>', 'firecracker:<vm-id>:<host-path>', or 'cloudflare:<sandbox-id>'`);
+    throw new SandboxError(`Error: Invalid sandbox type '${value}'. Use 'host', 'container:<container-name>', 'image:<image-name>', 'gondolin:default', 'firecracker:<vm-id>:<host-path>', or 'cloudflare:<sandbox-id>'`);
 }
 export async function validateSandbox(config) {
     const adapter = sandboxAdapterByType.get(config.type);
@@ -37,7 +41,7 @@ export async function validateSandbox(config) {
     await adapter.validate?.(config);
 }
 /**
- * Create an executor that runs commands on host, in Docker, in a Firecracker VM, or through a Cloudflare sandbox bridge.
+ * Create an executor that runs commands on host, in Docker, in a microVM, in a Firecracker VM, or through a Cloudflare sandbox bridge.
  */
 export function createExecutor(config, env, ensureReady) {
     const adapter = sandboxAdapterByType.get(config.type);
@@ -49,4 +53,16 @@ export function createExecutor(config, env, ensureReady) {
     }
     return adapter.createExecutor(config, env, ensureReady);
 }
+/**
+ * The runtime path context for a sandbox config before an actor-specific
+ * executor is resolved. `image` configs are unresolved by nature (the actor
+ * decides the concrete container), but their mount layout is fixed, so path
+ * mapping is known without resolving.
+ */
+export function getUnresolvedSandboxPathContext(sandboxConfig, hostWorkspaceRoot) {
+    if (sandboxConfig.type === "image") {
+        return createMountedRuntimePathContext(hostWorkspaceRoot, "/workspace");
+    }
+    return createExecutor(sandboxConfig).getPathContext(hostWorkspaceRoot);
+}
 //# sourceMappingURL=index.js.map

package/dist/sandbox/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAC5E,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAClF,OAAO,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AACtF,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAY3C,OAAO,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,YAAY,EAAE,CAAC;AAC3F,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,eAAe,GAAG;IACtB,kBAAkB;IAClB,uBAAuB;IACvB,mBAAmB;IACnB,yBAAyB;IACzB,wBAAwB;CAChB,CAAC;AACX,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAClC,eAAe,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CACZ,CAAC;AAEhD,MAAM,UAAU,kBAAkB;IAChC,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,KAAK,MAAM,OAAO,IAAI,eAAe,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,IAAI,KAAK,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,YAAY,CACpB,WAAW,KAAK,mJAAmJ,CACpK,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,YAAY,CACpB,gCAAgC,KAAK,oIAAoI,CAC1K,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,MAAqB;IACzD,MAAM,OAAO,GAAG,oBAAoB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,YAAY,CAAC,oCAAoC,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC;IAC7E,CAAC;IAED,MAAM,OAAO,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAqB,EACrB,GAA4B,EAC5B,WAAiC;IAEjC,MAAM,OAAO,GAAG,oBAAoB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACtD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,YAAY,CAAC,oCAAoC,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC;QAC5B,MAAM,IAAI,YAAY,CAAC,oEAAoE,CAAC,CAAC;IAC/F,CAAC;IACD,OAAO,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;AAC1D,CAAC","sourcesContent":["import { ContainerExecutor, containerSandboxAdapter } from \"./container.js\";\nimport { FirecrackerExecutor, firecrackerSandboxAdapter } from \"./firecracker.js\";\nimport { CloudflareSandboxExecutor, cloudflareSandboxAdapter } from \"./cloudflare.js\";\nimport { HostExecutor, hostSandboxAdapter } from \"./host.js\";\nimport { imageSandboxAdapter } from \"./image.js\";\nimport { SandboxError } from \"./errors.js\";\nimport type { Executor, SandboxAdapter, SandboxConfig } from \"./types.js\";\n\nexport type {\n  CloudflareSandboxConfig,\n  ExecOptions,\n  ExecResult,\n  Executor,\n  RuntimePathContext,\n  SandboxAdapter,\n  SandboxConfig,\n} from \"./types.js\";\nexport { CloudflareSandboxExecutor, ContainerExecutor, FirecrackerExecutor, HostExecutor };\nexport { SandboxError } from \"./errors.js\";\n\nconst sandboxAdapters = [\n  hostSandboxAdapter,\n  containerSandboxAdapter,\n  imageSandboxAdapter,\n  firecrackerSandboxAdapter,\n  cloudflareSandboxAdapter,\n] as const;\nconst sandboxAdapterByType = new Map(\n  sandboxAdapters.map((adapter) => [adapter.type, adapter]),\n) as Map<SandboxConfig[\"type\"], SandboxAdapter>;\n\nexport function getSandboxAdapters(): readonly [...typeof sandboxAdapters] {\n  return sandboxAdapters;\n}\n\nexport function parseSandboxArg(value: string): SandboxConfig {\n  for (const adapter of sandboxAdapters) {\n    const config = adapter.parse(value);\n    if (config) {\n      return config;\n    }\n  }\n\n  if (value.startsWith(\"docker:\")) {\n    throw new SandboxError(\n      `Error: '${value}' is not supported. Use 'container:<container-name>' for the shared-container mode or 'image:<image-name>' for mikan-managed per-user containers.`,\n    );\n  }\n\n  throw new SandboxError(\n    `Error: Invalid sandbox type '${value}'. Use 'host', 'container:<container-name>', 'image:<image-name>', 'firecracker:<vm-id>:<host-path>', or 'cloudflare:<sandbox-id>'`,\n  );\n}\n\nexport async function validateSandbox(config: SandboxConfig): Promise<void> {\n  const adapter = sandboxAdapterByType.get(config.type);\n  if (!adapter) {\n    throw new SandboxError(`Error: Unsupported sandbox type '${config.type}'`);\n  }\n\n  await adapter.validate?.(config);\n}\n\n/**\n * Create an executor that runs commands on host, in Docker, in a Firecracker VM, or through a Cloudflare sandbox bridge.\n */\nexport function createExecutor(\n  config: SandboxConfig,\n  env?: Record<string, string>,\n  ensureReady?: () => Promise<void>,\n): Executor {\n  const adapter = sandboxAdapterByType.get(config.type);\n  if (!adapter) {\n    throw new SandboxError(`Error: Unsupported sandbox type '${config.type}'`);\n  }\n  if (!adapter.createExecutor) {\n    throw new SandboxError(\"Error: image sandbox must resolve to a concrete container executor\");\n  }\n  return adapter.createExecutor(config, env, ensureReady);\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { ContainerExecutor, containerSandboxAdapter } from \"./container.js\";\nimport { FirecrackerExecutor, firecrackerSandboxAdapter } from \"./firecracker.js\";\nimport { CloudflareSandboxExecutor, cloudflareSandboxAdapter } from \"./cloudflare.js\";\nimport { HostExecutor, hostSandboxAdapter } from \"./host.js\";\nimport { imageSandboxAdapter } from \"./image.js\";\nimport { GondolinExecutor, gondolinSandboxAdapter } from \"./gondolin.js\";\nimport { SandboxError } from \"./errors.js\";\nimport { createMountedRuntimePathContext } from \"./path-context.js\";\nexport { configureGondolinRuntime, type GondolinBootstrapOptions } from \"./gondolin-bootstrap.js\";\nimport type { Executor, RuntimePathContext, SandboxAdapter, SandboxConfig } from \"./types.js\";\n\nexport type {\n  CloudflareSandboxConfig,\n  ExecOptions,\n  ExecResult,\n  Executor,\n  RuntimePathContext,\n  SandboxAdapter,\n  SandboxConfig,\n} from \"./types.js\";\nexport {\n  CloudflareSandboxExecutor,\n  ContainerExecutor,\n  FirecrackerExecutor,\n  HostExecutor,\n  GondolinExecutor,\n};\nexport { SandboxError } from \"./errors.js\";\n\nconst sandboxAdapters = [\n  hostSandboxAdapter,\n  containerSandboxAdapter,\n  imageSandboxAdapter,\n  gondolinSandboxAdapter,\n  firecrackerSandboxAdapter,\n  cloudflareSandboxAdapter,\n] as const;\nconst sandboxAdapterByType = new Map(\n  sandboxAdapters.map((adapter) => [adapter.type, adapter]),\n) as Map<SandboxConfig[\"type\"], SandboxAdapter>;\n\nexport function getSandboxAdapters(): readonly [...typeof sandboxAdapters] {\n  return sandboxAdapters;\n}\n\nexport function parseSandboxArg(value: string): SandboxConfig {\n  for (const adapter of sandboxAdapters) {\n    const config = adapter.parse(value);\n    if (config) {\n      return config;\n    }\n  }\n\n  if (value.startsWith(\"docker:\")) {\n    throw new SandboxError(\n      `Error: '${value}' is not supported. Use 'container:<container-name>' for the shared-container mode or 'image:<image-name>' for mikan-managed per-user containers.`,\n    );\n  }\n\n  throw new SandboxError(\n    `Error: Invalid sandbox type '${value}'. Use 'host', 'container:<container-name>', 'image:<image-name>', 'gondolin:default', 'firecracker:<vm-id>:<host-path>', or 'cloudflare:<sandbox-id>'`,\n  );\n}\n\nexport async function validateSandbox(config: SandboxConfig): Promise<void> {\n  const adapter = sandboxAdapterByType.get(config.type);\n  if (!adapter) {\n    throw new SandboxError(`Error: Unsupported sandbox type '${config.type}'`);\n  }\n\n  await adapter.validate?.(config);\n}\n\n/**\n * Create an executor that runs commands on host, in Docker, in a microVM, in a Firecracker VM, or through a Cloudflare sandbox bridge.\n */\nexport function createExecutor(\n  config: SandboxConfig,\n  env?: Record<string, string>,\n  ensureReady?: () => Promise<void>,\n): Executor {\n  const adapter = sandboxAdapterByType.get(config.type);\n  if (!adapter) {\n    throw new SandboxError(`Error: Unsupported sandbox type '${config.type}'`);\n  }\n  if (!adapter.createExecutor) {\n    throw new SandboxError(\"Error: image sandbox must resolve to a concrete container executor\");\n  }\n  return adapter.createExecutor(config, env, ensureReady);\n}\n\n/**\n * The runtime path context for a sandbox config before an actor-specific\n * executor is resolved. `image` configs are unresolved by nature (the actor\n * decides the concrete container), but their mount layout is fixed, so path\n * mapping is known without resolving.\n */\nexport function getUnresolvedSandboxPathContext(\n  sandboxConfig: SandboxConfig,\n  hostWorkspaceRoot: string,\n): RuntimePathContext {\n  if (sandboxConfig.type === \"image\") {\n    return createMountedRuntimePathContext(hostWorkspaceRoot, \"/workspace\");\n  }\n\n  return createExecutor(sandboxConfig).getPathContext(hostWorkspaceRoot);\n}\n"]}

package/dist/sandbox/types.d.ts

@@ -1,4 +1,4 @@
-export type SandboxConfig = HostSandboxConfig | ContainerSandboxConfig | ImageSandboxConfig | FirecrackerSandboxConfig | CloudflareSandboxConfig;
+export type SandboxConfig = HostSandboxConfig | ContainerSandboxConfig | ImageSandboxConfig | GondolinSandboxConfig | FirecrackerSandboxConfig | CloudflareSandboxConfig;
 export interface HostSandboxConfig {
     type: "host";
 }
@@ -10,6 +10,19 @@ export interface ImageSandboxConfig {
     type: "image";
     image: string;
 }
+export interface GondolinSandboxConfig {
+    type: "gondolin";
+    profile: "default" | "remote";
+    /** Local-only runtime details supplied after actor/workspace resolution. */
+    image?: string;
+    workspacePath?: string;
+    mounts?: Array<{
+        source: string;
+        target: string;
+    }>;
+    instanceId?: string;
+    resourceKey?: string;
+}
 export interface FirecrackerSandboxConfig {
     type: "firecracker";
     vmId: string;
@@ -26,6 +39,23 @@ export interface Executor {
      * Execute a bash command.
      */
     exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    /**
+     * Read a runtime file as UTF-8 text. The executor owns the transport, so
+     * file contents never pass through shell argv or extra shell parse layers.
+     */
+    readFile(path: string, options?: ExecOptions): Promise<string>;
+    /**
+     * Read a runtime file as base64 (for binary content, e.g. images). Same
+     * transport ownership as readFile.
+     */
+    readFileBase64(path: string, options?: ExecOptions): Promise<string>;
+    /**
+     * Write a runtime file, creating parent directories and replacing via a
+     * staging file so an aborted write never truncates the target. Like
+     * readFile, transport is the executor's concern — content must survive
+     * arbitrary quoting and ARG_MAX limits.
+     */
+    writeFile(path: string, content: string, options?: ExecOptions): Promise<void>;
     /**
      * Get the workspace path prefix for this executor.
      * Host: returns the actual path.

package/dist/sandbox/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sandbox/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GACrB,iBAAiB,GACjB,sBAAsB,GACtB,kBAAkB,GAClB,wBAAwB,GACxB,uBAAuB,CAAC;AAE5B,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,aAAa,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAElE;;;;OAIG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;IAE3C;;OAEG;IACH,cAAc,CAAC,iBAAiB,EAAE,MAAM,GAAG,kBAAkB,CAAC;IAE9D;;OAEG;IACH,gBAAgB,IAAI,aAAa,CAAC;CACnC;AAED,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,yEAAyE;IACzE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,oFAAoF;IACpF,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC;CACrD;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc,CAAC,OAAO,SAAS,aAAa,GAAG,aAAa;IAC3E,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,cAAc,CAAC,CACb,MAAM,EAAE,OAAO,EACf,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAChC,QAAQ,CAAC;CACb"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/sandbox/types.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sandbox/types.ts"],"names":[],"mappings":"","sourcesContent":["export type SandboxConfig =\n  | HostSandboxConfig\n  | ContainerSandboxConfig\n  | ImageSandboxConfig\n  | FirecrackerSandboxConfig\n  | CloudflareSandboxConfig;\n\nexport interface HostSandboxConfig {\n  type: \"host\";\n}\n\nexport interface ContainerSandboxConfig {\n  type: \"container\";\n  container: string;\n}\n\nexport interface ImageSandboxConfig {\n  type: \"image\";\n  image: string;\n}\n\nexport interface FirecrackerSandboxConfig {\n  type: \"firecracker\";\n  vmId: string;\n  hostPath: string;\n  sshUser?: string;\n  sshPort?: number;\n}\n\nexport interface CloudflareSandboxConfig {\n  type: \"cloudflare\";\n  sandboxId: string;\n}\n\nexport interface Executor {\n  /**\n   * Execute a bash command.\n   */\n  exec(command: string, options?: ExecOptions): Promise<ExecResult>;\n\n  /**\n   * Get the workspace path prefix for this executor.\n   * Host: returns the actual path.\n   * Container/Firecracker: returns /workspace.\n   */\n  getWorkspacePath(hostPath: string): string;\n\n  /**\n   * Return explicit host/control-plane/runtime path semantics for this executor.\n   */\n  getPathContext(hostWorkspaceRoot: string): RuntimePathContext;\n\n  /**\n   * Get the current sandbox config used by this executor.\n   */\n  getSandboxConfig(): SandboxConfig;\n}\n\nexport interface RuntimePathContext {\n  /** Host-side workspace root used by mikan's control plane. */\n  hostWorkspaceRoot: string;\n  /** Workspace root as seen by bash/read/write/edit inside the runtime. */\n  runtimeWorkspaceRoot: string;\n  /** Translate a runtime path back to a host path when the runtime is host-backed. */\n  runtimeToHostPath?: (runtimePath: string) => string;\n}\n\nexport interface ExecOptions {\n  timeout?: number;\n  signal?: AbortSignal;\n}\n\nexport interface ExecResult {\n  stdout: string;\n  stderr: string;\n  code: number;\n}\n\nexport interface SandboxAdapter<TConfig extends SandboxConfig = SandboxConfig> {\n  type: TConfig[\"type\"];\n  parse(value: string): TConfig | undefined;\n  validate?(config: TConfig): Promise<void>;\n  createExecutor?(\n    config: TConfig,\n    env?: Record<string, string>,\n    ensureReady?: () => Promise<void>,\n  ): Executor;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sandbox/types.ts"],"names":[],"mappings":"","sourcesContent":["export type SandboxConfig =\n  | HostSandboxConfig\n  | ContainerSandboxConfig\n  | ImageSandboxConfig\n  | GondolinSandboxConfig\n  | FirecrackerSandboxConfig\n  | CloudflareSandboxConfig;\n\nexport interface HostSandboxConfig {\n  type: \"host\";\n}\n\nexport interface ContainerSandboxConfig {\n  type: \"container\";\n  container: string;\n}\n\nexport interface ImageSandboxConfig {\n  type: \"image\";\n  image: string;\n}\n\nexport interface GondolinSandboxConfig {\n  type: \"gondolin\";\n  profile: \"default\" | \"remote\";\n  /** Local-only runtime details supplied after actor/workspace resolution. */\n  image?: string;\n  workspacePath?: string;\n  mounts?: Array<{ source: string; target: string }>;\n  instanceId?: string;\n  resourceKey?: string;\n}\n\nexport interface FirecrackerSandboxConfig {\n  type: \"firecracker\";\n  vmId: string;\n  hostPath: string;\n  sshUser?: string;\n  sshPort?: number;\n}\n\nexport interface CloudflareSandboxConfig {\n  type: \"cloudflare\";\n  sandboxId: string;\n}\n\nexport interface Executor {\n  /**\n   * Execute a bash command.\n   */\n  exec(command: string, options?: ExecOptions): Promise<ExecResult>;\n\n  /**\n   * Read a runtime file as UTF-8 text. The executor owns the transport, so\n   * file contents never pass through shell argv or extra shell parse layers.\n   */\n  readFile(path: string, options?: ExecOptions): Promise<string>;\n\n  /**\n   * Read a runtime file as base64 (for binary content, e.g. images). Same\n   * transport ownership as readFile.\n   */\n  readFileBase64(path: string, options?: ExecOptions): Promise<string>;\n\n  /**\n   * Write a runtime file, creating parent directories and replacing via a\n   * staging file so an aborted write never truncates the target. Like\n   * readFile, transport is the executor's concern — content must survive\n   * arbitrary quoting and ARG_MAX limits.\n   */\n  writeFile(path: string, content: string, options?: ExecOptions): Promise<void>;\n\n  /**\n   * Get the workspace path prefix for this executor.\n   * Host: returns the actual path.\n   * Container/Firecracker: returns /workspace.\n   */\n  getWorkspacePath(hostPath: string): string;\n\n  /**\n   * Return explicit host/control-plane/runtime path semantics for this executor.\n   */\n  getPathContext(hostWorkspaceRoot: string): RuntimePathContext;\n\n  /**\n   * Get the current sandbox config used by this executor.\n   */\n  getSandboxConfig(): SandboxConfig;\n}\n\nexport interface RuntimePathContext {\n  /** Host-side workspace root used by mikan's control plane. */\n  hostWorkspaceRoot: string;\n  /** Workspace root as seen by bash/read/write/edit inside the runtime. */\n  runtimeWorkspaceRoot: string;\n  /** Translate a runtime path back to a host path when the runtime is host-backed. */\n  runtimeToHostPath?: (runtimePath: string) => string;\n}\n\nexport interface ExecOptions {\n  timeout?: number;\n  signal?: AbortSignal;\n}\n\nexport interface ExecResult {\n  stdout: string;\n  stderr: string;\n  code: number;\n}\n\nexport interface SandboxAdapter<TConfig extends SandboxConfig = SandboxConfig> {\n  type: TConfig[\"type\"];\n  parse(value: string): TConfig | undefined;\n  validate?(config: TConfig): Promise<void>;\n  createExecutor?(\n    config: TConfig,\n    env?: Record<string, string>,\n    ensureReady?: () => Promise<void>,\n  ): Executor;\n}\n"]}

package/dist/sandbox/utils.d.ts

@@ -1,4 +1,16 @@
 export declare function execSimple(cmd: string, args: string[]): Promise<string>;
 export declare function killProcessTree(pid: number): void;
 export declare function shellEscape(s: string): string;
+interface ExecLikeResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+interface ExecLike<TOptions> {
+    exec(command: string, options?: TOptions): Promise<ExecLikeResult>;
+}
+export declare function execReadFileBase64<TOptions>(executor: ExecLike<TOptions>, path: string, options?: TOptions): Promise<string>;
+export declare function execReadFile<TOptions>(executor: ExecLike<TOptions>, path: string, options?: TOptions): Promise<string>;
+export declare function execWriteFile<TOptions>(executor: ExecLike<TOptions>, path: string, content: string, options?: TOptions): Promise<void>;
+export {};
 //# sourceMappingURL=utils.d.ts.map

package/dist/sandbox/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/sandbox/utils.ts"],"names":[],"mappings":"AAEA,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBvE;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAqBjD;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7C"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/sandbox/utils.ts"],"names":[],"mappings":"AAEA,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBvE;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAqBjD;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7C;AAWD,UAAU,cAAc;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,QAAQ,CAAC,QAAQ;IACzB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACpE;AAED,wBAAsB,kBAAkB,CAAC,QAAQ,EAC/C,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,MAAM,CAAC,CAMjB;AAED,wBAAsB,YAAY,CAAC,QAAQ,EACzC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED,wBAAsB,aAAa,CAAC,QAAQ,EAC1C,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,IAAI,CAAC,CAuBf"}

package/dist/sandbox/utils.js

@@ -48,4 +48,42 @@ export function shellEscape(s) {
     // Escape for passing to sh -c
     return `'${s.replace(/'/g, "'\\''")}'`;
 }
+/**
+ * Shared exec-backed file transport for executors whose only channel into the
+ * runtime is `exec` (docker exec, ssh, HTTP). Contents travel base64-encoded —
+ * the base64 alphabet is inert under every shell parse layer — and writes are
+ * chunked so no single command approaches the per-argument ARG_MAX limit,
+ * staged, then moved into place so an aborted write never truncates the file.
+ */
+const WRITE_CHUNK_CHARS = 65536;
+export async function execReadFileBase64(executor, path, options) {
+    const result = await executor.exec(`base64 < ${shellEscape(path)}`, options);
+    if (result.code !== 0) {
+        throw new Error(result.stderr.trim() || `Failed to read file: ${path}`);
+    }
+    return result.stdout.replace(/\s+/g, "");
+}
+export async function execReadFile(executor, path, options) {
+    return Buffer.from(await execReadFileBase64(executor, path, options), "base64").toString("utf-8");
+}
+export async function execWriteFile(executor, path, content, options) {
+    const encoded = Buffer.from(content, "utf-8").toString("base64");
+    const escapedPath = shellEscape(path);
+    const stage = shellEscape(`${path}.mikan-stage`);
+    const stageB64 = shellEscape(`${path}.mikan-stage.b64`);
+    const run = async (command) => {
+        const result = await executor.exec(command, options);
+        if (result.code !== 0) {
+            await executor.exec(`rm -f ${stage} ${stageB64}`, options).catch(() => { });
+            throw new Error(result.stderr.trim() || `Failed to write file: ${path}`);
+        }
+    };
+    const dir = path.includes("/") ? path.slice(0, path.lastIndexOf("/")) || "/" : ".";
+    await run(`mkdir -p ${shellEscape(dir)} && : > ${stageB64}`);
+    for (let offset = 0; offset === 0 || offset < encoded.length; offset += WRITE_CHUNK_CHARS) {
+        const chunk = encoded.slice(offset, offset + WRITE_CHUNK_CHARS);
+        await run(`printf '%s' ${shellEscape(chunk)} >> ${stageB64}`);
+    }
+    await run(`base64 -d < ${stageB64} > ${stage} && mv ${stage} ${escapedPath} && rm -f ${stageB64}`);
+}
 //# sourceMappingURL=utils.js.map

package/dist/sandbox/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/sandbox/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAEtC,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,IAAc;IACpD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACtE,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE;YAC7B,MAAM,IAAI,CAAC,CAAC;QACd,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE;YAC7B,MAAM,IAAI,CAAC,CAAC;QACd,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACzB,IAAI,IAAI,KAAK,CAAC;gBAAE,OAAO,CAAC,MAAM,CAAC,CAAC;;gBAC3B,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,IAAI,aAAa,IAAI,EAAE,CAAC,CAAC,CAAC;QACxD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,KAAK,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE;gBACnD,KAAK,EAAE,QAAQ;gBACf,QAAQ,EAAE,IAAI;aACf,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,gBAAgB;QAClB,CAAC;IACH,CAAC;SAAM,CAAC;QACN,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAChC,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC;gBACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;YAC/B,CAAC;YAAC,MAAM,CAAC;gBACP,uBAAuB;YACzB,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAS;IACnC,8BAA8B;IAC9B,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AACzC,CAAC","sourcesContent":["import { spawn } from \"child_process\";\n\nexport function execSimple(cmd: string, args: string[]): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const child = spawn(cmd, args, { stdio: [\"ignore\", \"pipe\", \"pipe\"] });\n    let stdout = \"\";\n    let stderr = \"\";\n    child.stdout?.on(\"data\", (d) => {\n      stdout += d;\n    });\n    child.stderr?.on(\"data\", (d) => {\n      stderr += d;\n    });\n    child.on(\"close\", (code) => {\n      if (code === 0) resolve(stdout);\n      else reject(new Error(stderr || `Exit code ${code}`));\n    });\n  });\n}\n\nexport function killProcessTree(pid: number): void {\n  if (process.platform === \"win32\") {\n    try {\n      spawn(\"taskkill\", [\"/F\", \"/T\", \"/PID\", String(pid)], {\n        stdio: \"ignore\",\n        detached: true,\n      });\n    } catch {\n      // Ignore errors\n    }\n  } else {\n    try {\n      process.kill(-pid, \"SIGKILL\");\n    } catch {\n      try {\n        process.kill(pid, \"SIGKILL\");\n      } catch {\n        // Process already dead\n      }\n    }\n  }\n}\n\nexport function shellEscape(s: string): string {\n  // Escape for passing to sh -c\n  return `'${s.replace(/'/g, \"'\\\\''\")}'`;\n}\n"]}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/sandbox/utils.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from \"child_process\";\n\nexport function execSimple(cmd: string, args: string[]): Promise<string> {\n  return new Promise((resolve, reject) => {\n    const child = spawn(cmd, args, { stdio: [\"ignore\", \"pipe\", \"pipe\"] });\n    let stdout = \"\";\n    let stderr = \"\";\n    child.stdout?.on(\"data\", (d) => {\n      stdout += d;\n    });\n    child.stderr?.on(\"data\", (d) => {\n      stderr += d;\n    });\n    child.on(\"close\", (code) => {\n      if (code === 0) resolve(stdout);\n      else reject(new Error(stderr || `Exit code ${code}`));\n    });\n  });\n}\n\nexport function killProcessTree(pid: number): void {\n  if (process.platform === \"win32\") {\n    try {\n      spawn(\"taskkill\", [\"/F\", \"/T\", \"/PID\", String(pid)], {\n        stdio: \"ignore\",\n        detached: true,\n      });\n    } catch {\n      // Ignore errors\n    }\n  } else {\n    try {\n      process.kill(-pid, \"SIGKILL\");\n    } catch {\n      try {\n        process.kill(pid, \"SIGKILL\");\n      } catch {\n        // Process already dead\n      }\n    }\n  }\n}\n\nexport function shellEscape(s: string): string {\n  // Escape for passing to sh -c\n  return `'${s.replace(/'/g, \"'\\\\''\")}'`;\n}\n\n/**\n * Shared exec-backed file transport for executors whose only channel into the\n * runtime is `exec` (docker exec, ssh, HTTP). Contents travel base64-encoded —\n * the base64 alphabet is inert under every shell parse layer — and writes are\n * chunked so no single command approaches the per-argument ARG_MAX limit,\n * staged, then moved into place so an aborted write never truncates the file.\n */\nconst WRITE_CHUNK_CHARS = 65536;\n\ninterface ExecLikeResult {\n  stdout: string;\n  stderr: string;\n  code: number;\n}\n\ninterface ExecLike<TOptions> {\n  exec(command: string, options?: TOptions): Promise<ExecLikeResult>;\n}\n\nexport async function execReadFileBase64<TOptions>(\n  executor: ExecLike<TOptions>,\n  path: string,\n  options?: TOptions,\n): Promise<string> {\n  const result = await executor.exec(`base64 < ${shellEscape(path)}`, options);\n  if (result.code !== 0) {\n    throw new Error(result.stderr.trim() || `Failed to read file: ${path}`);\n  }\n  return result.stdout.replace(/\\s+/g, \"\");\n}\n\nexport async function execReadFile<TOptions>(\n  executor: ExecLike<TOptions>,\n  path: string,\n  options?: TOptions,\n): Promise<string> {\n  return Buffer.from(await execReadFileBase64(executor, path, options), \"base64\").toString(\"utf-8\");\n}\n\nexport async function execWriteFile<TOptions>(\n  executor: ExecLike<TOptions>,\n  path: string,\n  content: string,\n  options?: TOptions,\n): Promise<void> {\n  const encoded = Buffer.from(content, \"utf-8\").toString(\"base64\");\n  const escapedPath = shellEscape(path);\n  const stage = shellEscape(`${path}.mikan-stage`);\n  const stageB64 = shellEscape(`${path}.mikan-stage.b64`);\n\n  const run = async (command: string) => {\n    const result = await executor.exec(command, options);\n    if (result.code !== 0) {\n      await executor.exec(`rm -f ${stage} ${stageB64}`, options).catch(() => {});\n      throw new Error(result.stderr.trim() || `Failed to write file: ${path}`);\n    }\n  };\n\n  const dir = path.includes(\"/\") ? path.slice(0, path.lastIndexOf(\"/\")) || \"/\" : \".\";\n  await run(`mkdir -p ${shellEscape(dir)} && : > ${stageB64}`);\n  for (let offset = 0; offset === 0 || offset < encoded.length; offset += WRITE_CHUNK_CHARS) {\n    const chunk = encoded.slice(offset, offset + WRITE_CHUNK_CHARS);\n    await run(`printf '%s' ${shellEscape(chunk)} >> ${stageB64}`);\n  }\n  await run(\n    `base64 -d < ${stageB64} > ${stage} && mv ${stage} ${escapedPath} && rm -f ${stageB64}`,\n  );\n}\n"]}

package/dist/sessions/chat-history-sync.d.ts

@@ -0,0 +1,32 @@
+import { type ResolvedSessionScope } from "./store.js";
+export type { ChatHistorySyncOptions, HasMaterializedSessionOptions, RegisterThreadSessionOptions, ResetChatSessionOptions, ResolveChatSessionScopeOptions, SyncChatSessionOptions, ThreadBootstrapWaitOptions, } from "./types.js";
+import type { ChatHistorySyncOptions, HasMaterializedSessionOptions, RegisterThreadSessionOptions, ResetChatSessionOptions, ResolveChatSessionScopeOptions, SyncChatSessionOptions, ThreadBootstrapWaitOptions } from "./types.js";
+/** What one sync pass actually did — the inspectable result of a sync. */
+export interface ChatSyncReport {
+    /** Log messages appended to the session in this pass. */
+    appended: number;
+    /** The log message id recorded as the new sync watermark. */
+    lastMessageId?: string;
+}
+export declare function hasMaterializedChatSession(options: HasMaterializedSessionOptions): boolean;
+export declare function registerThreadSession(options: RegisterThreadSessionOptions): string | null;
+export declare function waitForThreadSessionBootstrap(options: ThreadBootstrapWaitOptions): Promise<boolean>;
+/**
+ * Syncs the platform chat transcript (log.jsonl) into managed session files:
+ * resolves which session file a message belongs to (top-level vs thread,
+ * with biweekly rotation), bootstraps new sessions from recent history, and
+ * incrementally appends log messages the session does not yet represent.
+ */
+export declare class ChatHistorySync {
+    private readonly recentDays;
+    private readonly maxTopLevelMessages;
+    private readonly now;
+    constructor(options?: ChatHistorySyncOptions);
+    resolveSessionScope(options: ResolveChatSessionScopeOptions): Promise<ResolvedSessionScope>;
+    syncSessionManager(options: SyncChatSessionOptions): ChatSyncReport;
+    resetSession(options: ResetChatSessionOptions): string;
+    private resolveTopLevelSessionFile;
+    private historyWindow;
+    private resolveThreadSessionScope;
+}
+//# sourceMappingURL=chat-history-sync.d.ts.map

package/dist/sessions/chat-history-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-history-sync.d.ts","sourceRoot":"","sources":["../../src/sessions/chat-history-sync.ts"],"names":[],"mappings":"AASA,OAAO,EAUL,KAAK,oBAAoB,EAE1B,MAAM,YAAY,CAAC;AAQpB,YAAY,EACV,sBAAsB,EACtB,6BAA6B,EAC7B,4BAA4B,EAC5B,uBAAuB,EACvB,8BAA8B,EAC9B,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EACV,sBAAsB,EACtB,6BAA6B,EAC7B,4BAA4B,EAC5B,uBAAuB,EACvB,8BAA8B,EAC9B,sBAAsB,EACtB,0BAA0B,EAC3B,MAAM,YAAY,CAAC;AAEpB,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,6BAA6B,GAAG,OAAO,CAQ1F;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,GAAG,IAAI,CAQ1F;AAED,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,OAAO,CAAC,CAqBlB;AAED;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IAEjC,YAAY,OAAO,GAAE,sBAA2B,EAI/C;IAEK,mBAAmB,CACvB,OAAO,EAAE,8BAA8B,GACtC,OAAO,CAAC,oBAAoB,CAAC,CAsB/B;IAED,kBAAkB,CAAC,OAAO,EAAE,sBAAsB,GAAG,cAAc,CAUlE;IAED,YAAY,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAUrD;IAED,OAAO,CAAC,0BAA0B;IA2ClC,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,yBAAyB;CA4ClC"}