@crouton-kit/crouter 0.3.32 → 0.3.33

package/dist/core/frontmatter.js

@@ -1,18 +1,6 @@
 import { parse as parseYaml } from 'yaml';
-import { isSkillType } from '../types.js';
 const FRONTMATTER_RE = /^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n?/;
-export function parseFrontmatter(source) {
-    const match = source.match(FRONTMATTER_RE);
-    if (!match) {
-        return { data: null, body: source, raw: '' };
-    }
-    const raw = match[1];
-    const body = source.slice(match[0].length);
-    return { data: toSkillFrontmatter(parseYamlBlock(raw)), body, raw };
-}
-/** Like parseFrontmatter but returns the raw key/value record instead of
- *  coercing to SkillFrontmatter. Used by consumers (e.g. subagents) that read
- *  fields skills don't declare, such as `tools` and `model`. */
+/** Parse a frontmatter block as a raw key/value record. */
 export function parseFrontmatterGeneric(source) {
     const match = source.match(FRONTMATTER_RE);
     if (!match) {
@@ -22,26 +10,6 @@ export function parseFrontmatterGeneric(source) {
     const body = source.slice(match[0].length);
     return { data: parseYamlBlock(raw), body, raw };
 }
-function toSkillFrontmatter(out) {
-    const fm = {
-        name: scalarToString(out.name) ?? '',
-        description: scalarToString(out.description),
-        keywords: Array.isArray(out.keywords) ? out.keywords.map((k) => String(k)) : undefined,
-        type: isSkillType(out.type) ? out.type : undefined,
-    };
-    return fm;
-}
-/** Coerce a YAML scalar (string/number/boolean) to its string form. A skill's
- *  `name`/`description` are always strings to consumers; native non-string
- *  scalars (a numeric/boolean value) render as their string form, and
- *  non-scalars (null/undefined/array/object) yield undefined. */
-function scalarToString(v) {
-    if (typeof v === 'string')
-        return v;
-    if (typeof v === 'number' || typeof v === 'boolean')
-        return String(v);
-    return undefined;
-}
 /** Parse the inner YAML of a frontmatter block into a key/value record.
  *
  *  ONE strict parser, no fallback. The frontmatter contract IS "valid YAML":
@@ -65,25 +33,3 @@ function normalizeToRecord(parsed) {
     }
     return {};
 }
-export function serializeFrontmatter(data) {
-    const lines = ['---'];
-    lines.push(`name: ${quoteIfNeeded(data.name)}`);
-    if (data.description !== undefined) {
-        lines.push(`description: ${quoteIfNeeded(data.description)}`);
-    }
-    if (data.type !== undefined) {
-        lines.push(`type: ${data.type}`);
-    }
-    if (data.keywords && data.keywords.length) {
-        const inline = `[${data.keywords.map(quoteIfNeeded).join(', ')}]`;
-        lines.push(`keywords: ${inline}`);
-    }
-    lines.push('---');
-    return lines.join('\n') + '\n';
-}
-function quoteIfNeeded(s) {
-    if (/[:#\-\[\]{},&*?|<>=!%@`]/.test(s) || /^\s/.test(s) || /\s$/.test(s)) {
-        return `"${s.replace(/"/g, '\\"')}"`;
-    }
-    return s;
-}

package/dist/core/hearth/config.d.ts

@@ -0,0 +1,2 @@
+import type { M0Config } from './types.js';
+export declare function loadM0Config(env?: NodeJS.ProcessEnv): M0Config;

package/dist/core/hearth/config.js

@@ -0,0 +1,75 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { general } from '../errors.js';
+const ENV = {
+    provider: 'CRTR_HEARTH_PROVIDER',
+    registry: 'CRTR_HEARTH_M0_REGISTRY',
+    guestUser: 'CRTR_HEARTH_M0_GUEST_USER',
+    guestHome: 'CRTR_HEARTH_M0_GUEST_HOME',
+    guestCode: 'CRTR_HEARTH_M0_GUEST_CODE',
+    webPort: 'CRTR_HEARTH_M0_WEB_PORT',
+    nodeKind: 'CRTR_HEARTH_M0_NODE_KIND',
+    piPackages: 'CRTR_HEARTH_M0_PI_PACKAGES',
+    piAuthJson: 'CRTR_HEARTH_M0_PI_AUTH_JSON',
+    relayToken: 'CRTR_HEARTH_M0_RELAY_TOKEN',
+};
+function expandHomePath(input) {
+    if (input.startsWith('~'))
+        return join(homedir(), input.slice(1));
+    return resolve(input);
+}
+function parsePort(value, fallback, name) {
+    if (value === undefined || value === '')
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+        throw general(`invalid ${name}: ${value}`, { env: name });
+    }
+    return parsed;
+}
+const SAFE_PI_PACKAGE_SPEC = /^[A-Za-z0-9@/_:.-]+$/;
+const DEFAULT_PI_PACKAGES = ['npm:pi-claude-oauth-adapter@0.1.2'];
+function parsePiPackages(env) {
+    const raw = env[ENV.piPackages]?.trim();
+    if (raw === undefined || raw === '')
+        return [...DEFAULT_PI_PACKAGES];
+    const tokens = raw.split(/[,\s]+/).map((token) => token.trim()).filter((token) => token !== '');
+    if (tokens.length === 0) {
+        throw general(`invalid ${ENV.piPackages}: ${raw}`, { env: ENV.piPackages });
+    }
+    if (tokens.length === 1 && tokens[0]?.toLowerCase() === 'none')
+        return [];
+    if (tokens.some((token) => token.toLowerCase() === 'none')) {
+        throw general(`invalid ${ENV.piPackages}: none must be the only value`, { env: ENV.piPackages });
+    }
+    for (const spec of tokens) {
+        if (!SAFE_PI_PACKAGE_SPEC.test(spec)) {
+            throw general(`invalid ${ENV.piPackages}: ${spec}`, { env: ENV.piPackages, packageSpec: spec });
+        }
+    }
+    return tokens;
+}
+export function loadM0Config(env = process.env) {
+    const providerName = (env[ENV.provider] ?? '').trim().toLowerCase();
+    const registryPath = expandHomePath(env[ENV.registry] ?? '~/.crouter/hearth/m0/homes.json');
+    const guestUser = (env[ENV.guestUser] ?? 'agent').trim();
+    const guestHome = expandHomePath(env[ENV.guestHome] ?? '/home/agent');
+    const guestCodePath = expandHomePath(env[ENV.guestCode] ?? '/opt/crouter');
+    const piPackages = parsePiPackages(env);
+    const webPort = parsePort(env[ENV.webPort], 7878, ENV.webPort);
+    const nodeKind = (env[ENV.nodeKind] ?? 'general').trim();
+    const piAuthJson = env[ENV.piAuthJson]?.trim() || null;
+    const relayToken = env[ENV.relayToken]?.trim() || null;
+    return {
+        providerName,
+        registryPath,
+        guestUser,
+        guestHome,
+        guestCodePath,
+        piPackages,
+        webPort,
+        nodeKind,
+        piAuthJson,
+        relayToken,
+    };
+}

package/dist/core/hearth/guest-env.d.ts

@@ -0,0 +1,2 @@
+import type { M0Config } from './types.js';
+export declare function guestEnv(config: M0Config): Record<string, string>;

package/dist/core/hearth/guest-env.js

@@ -0,0 +1,11 @@
+import { join } from 'node:path';
+export function guestEnv(config) {
+    const home = config.guestHome;
+    return {
+        HOME: home,
+        CRTR_HOME: join(home, '.crouter'),
+        PI_CODING_AGENT_DIR: join(home, '.pi', 'agent'),
+        PATH: `${join(home, '.crtr-runtime', 'bin')}:/usr/local/bin:/usr/bin:/bin`,
+        SANDBOX_DISABLE_PROCESS_LOGGING: 'true',
+    };
+}

package/dist/core/hearth/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export { loadM0Config } from './config.js';
+export { getHomeBackend, type HomeBackend } from './provider.js';
+export { readRegistry, writeRegistry, getHome, putHome, updateHome, listHomes, acquireRegistryLock } from './registry.js';
+export { guestEnv } from './guest-env.js';

package/dist/core/hearth/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export { loadM0Config } from './config.js';
+export { getHomeBackend } from './provider.js';
+export { readRegistry, writeRegistry, getHome, putHome, updateHome, listHomes, acquireRegistryLock } from './registry.js';
+export { guestEnv } from './guest-env.js';

package/dist/core/hearth/provider.d.ts

@@ -0,0 +1,21 @@
+import type { MachineId, MachineRef, M0Config, TenantId } from './types.js';
+/**
+ * The Hearth home backend seam. The wake-proxy front door (token auth, origin checks,
+ * SSE/WS forwarding, the source gate) is vendor-neutral and drives a home purely through
+ * this interface — never a concrete sandbox SDK.
+ */
+export interface HomeBackend {
+    /**
+     * Bring the tenant's home up and serving — warm-resume or recreate as the backend decides —
+     * refresh its public route, and persist `webRoute` + `relayToken` to the registry.
+     */
+    wake(tenantId: TenantId): Promise<void>;
+    /** Pause the tenant's home. */
+    suspend(tenantId: TenantId): Promise<void>;
+    /** Machine resources (cpu/mem) for status, or null when unavailable. */
+    getMachine(machineId: MachineId): Promise<MachineRef | null>;
+}
+/**
+ * Resolve the configured home backend.
+ */
+export declare function getHomeBackend(config: M0Config): HomeBackend;

package/dist/core/hearth/provider.js

@@ -0,0 +1,10 @@
+import { general } from '../errors.js';
+import { BlaxelHomeBackend } from './providers/blaxel-home.js';
+/**
+ * Resolve the configured home backend.
+ */
+export function getHomeBackend(config) {
+    if (config.providerName === 'blaxel')
+        return new BlaxelHomeBackend(config);
+    throw general('no Hearth home provider configured — Blaxel backend pending', { status: 503 });
+}

package/dist/core/hearth/providers/blaxel-bootstrap.d.ts

@@ -0,0 +1,10 @@
+export interface BuildBootstrapScriptOpts {
+    guestHome: string;
+    crtrVersion: string;
+    relayToken: string;
+    webPort: number;
+    nodeId?: string | null;
+    piAuthJson?: string | null;
+    isFirstProvision: boolean;
+}
+export declare function buildBootstrapScript(opts: BuildBootstrapScriptOpts): string;

package/dist/core/hearth/providers/blaxel-bootstrap.js

@@ -0,0 +1,39 @@
+import { join } from 'node:path';
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+export function buildBootstrapScript(opts) {
+    const runtimeDir = join(opts.guestHome, '.crtr-runtime');
+    const versionMarker = join(runtimeDir, '.crtr-version');
+    const lines = [
+        'set -e',
+        `export HOME=${shellQuote(opts.guestHome)}`,
+        'export CRTR_HOME="$HOME/.crouter"',
+        'export PI_CODING_AGENT_DIR="$HOME/.pi/agent"',
+        'export PATH="$HOME/.crtr-runtime/bin:/usr/local/bin:/usr/bin:/bin"',
+        'export SANDBOX_DISABLE_PROCESS_LOGGING=true',
+        'mkdir -p "$HOME/.crouter" "$HOME/.pi/agent" "$HOME/.crtr-runtime/bin"',
+        // The provisioner launches this script as a detached (background) exec, so its stdout is not
+        // captured. Redirect everything to a log on the durable volume so install/seed/node-new
+        // failures are inspectable, and so the first-provision node id can be read from a file (below).
+        'exec >>"$HOME/.crtr-runtime/bootstrap.log" 2>&1',
+        `if [ ! -x "$HOME/.crtr-runtime/bin/crtr" ] || [ "$(cat ${shellQuote(versionMarker)} 2>/dev/null || true)" != ${shellQuote(opts.crtrVersion)} ]; then`,
+        `  npm install -g --prefix ${shellQuote(runtimeDir)} @crouton-kit/crouter@${shellQuote(opts.crtrVersion)}`,
+        `  printf '%s\n' ${shellQuote(opts.crtrVersion)} > ${shellQuote(versionMarker)}`,
+        'fi',
+    ];
+    if (opts.isFirstProvision && (opts.piAuthJson?.trim() ?? '') !== '') {
+        lines.push('if [ ! -f "$PI_CODING_AGENT_DIR/auth.json" ]; then', '  cat > "$PI_CODING_AGENT_DIR/auth.json" <<\'PI_AUTH_JSON\'', opts.piAuthJson.trim(), 'PI_AUTH_JSON', 'fi');
+    }
+    lines.push('setsid --fork crtr canvas daemon start </dev/null >>"$HOME/.crtr-runtime/daemon.log" 2>&1');
+    if (opts.isFirstProvision) {
+        lines.push('home_node_output="$(', "crtr node new --root --kind general --name home <<'SEED'", 'Hearth home seed for the Blaxel home backend.', 'SEED', ')"', 'home_node_id="$(printf %s\\n "$home_node_output" | grep -Eo \'__HEARTH_NODE_ID__=[^[:space:]]+|node_id[:=][[:space:]]*[^[:space:]]+|node_id[[:space:]]+[A-Za-z0-9-]+\' | tail -n 1 | sed -E \'s/^(__HEARTH_NODE_ID__=|node_id[:=][[:space:]]*|node_id[[:space:]]+)//\')"', 'if [ -z "$home_node_id" ]; then', '  printf "failed to parse home node id from crtr node new output\n%s\n" "$home_node_output" >&2', '  exit 1', 'fi', 'printf "__HEARTH_NODE_ID__=%s\n" "$home_node_id"', 
+        // The provisioner polls this file (background exec stdout is not captured).
+        'printf "%s\n" "$home_node_id" > "$HOME/.crtr-runtime/home-node-id"');
+    }
+    else {
+        lines.push('if [ -z ' + shellQuote((opts.nodeId ?? '').trim()) + ' ]; then', '  printf "missing nodeId for bootstrap revive\n" >&2', '  exit 1', 'fi', `crtr canvas revive ${shellQuote((opts.nodeId ?? '').trim())}`);
+    }
+    lines.push(`setsid --fork crtr web serve --host 0.0.0.0 --port ${opts.webPort} --token ${shellQuote(opts.relayToken)} </dev/null >>"$HOME/.crtr-runtime/web.log" 2>&1`);
+    return lines.join('\n');
+}

package/dist/core/hearth/providers/blaxel-home.d.ts

@@ -0,0 +1,11 @@
+import type { M0Config, MachineRef, TenantId } from '../types.js';
+import { BlaxelMachineProvider } from './blaxel.js';
+export declare class BlaxelHomeBackend {
+    private readonly config;
+    private readonly provider;
+    private readonly crtrVersion;
+    constructor(config: M0Config, provider?: BlaxelMachineProvider);
+    wake(tenantId: TenantId): Promise<void>;
+    suspend(tenantId: TenantId): Promise<void>;
+    getMachine(machineId: string): Promise<MachineRef | null>;
+}

package/dist/core/hearth/providers/blaxel-home.js

@@ -0,0 +1,126 @@
+import { readFileSync } from 'node:fs';
+import { general } from '../../errors.js';
+import { nowIso } from '../../fs-utils.js';
+import { getHome, updateHome } from '../registry.js';
+import { guestEnv } from '../guest-env.js';
+import { buildBootstrapScript } from './blaxel-bootstrap.js';
+import { BlaxelMachineProvider } from './blaxel.js';
+function readCrtrVersion() {
+    const file = new URL('../../../../package.json', import.meta.url);
+    const pkg = JSON.parse(readFileSync(file, 'utf8'));
+    if (typeof pkg.version !== 'string' || pkg.version.trim() === '') {
+        throw general('missing crtr package version', { packageJson: file.pathname });
+    }
+    return pkg.version;
+}
+function stableRouteName(home) {
+    return home.webRoute?.routeId ?? `${home.machineId}-web`;
+}
+function homeStorage(home, config) {
+    return {
+        kind: 'volume',
+        durability: 'durable-volume',
+        longTermContract: true,
+        ownerMachineId: home.machineId,
+        guestHome: config.guestHome,
+        volumeId: home.homeStorage.volumeId,
+        mountPath: config.guestHome,
+    };
+}
+function buildHomeRecord(home, config, route, timestamps) {
+    return {
+        ...home,
+        providerName: 'blaxel',
+        homeStorage: homeStorage(home, config),
+        webRoute: route,
+        state: 'running',
+        createdAt: timestamps.createdAt ?? home.createdAt,
+        updatedAt: timestamps.updatedAt,
+    };
+}
+function ensureReadyHome(home, tenantId) {
+    if (home === null) {
+        throw general(`no home for tenant ${tenantId} — run the existing provision/bootstrap flow`, { tenantId });
+    }
+    if (typeof home.machineId !== 'string' || home.machineId === '') {
+        throw general(`home ${tenantId} is missing machineId — run the existing provision/bootstrap flow`, { tenantId });
+    }
+    if (typeof home.homeStorage?.volumeId !== 'string' || home.homeStorage.volumeId === '') {
+        throw general(`home ${tenantId} is missing homeStorage.volumeId — run the existing provision/bootstrap flow`, { tenantId });
+    }
+    if (typeof home.nodeId !== 'string' || home.nodeId === '') {
+        throw general(`home ${tenantId} is missing nodeId — run the existing provision/bootstrap flow`, { tenantId });
+    }
+    if (typeof home.relayToken !== 'string' || home.relayToken === '') {
+        throw general(`home ${tenantId} is missing relayToken — run the existing provision/bootstrap flow`, { tenantId });
+    }
+    return home;
+}
+function isRunningMachine(machine) {
+    return machine !== null && machine.state !== 'terminated';
+}
+export class BlaxelHomeBackend {
+    config;
+    provider;
+    crtrVersion;
+    constructor(config, provider) {
+        this.config = config;
+        this.provider = provider ?? new BlaxelMachineProvider();
+        this.crtrVersion = readCrtrVersion();
+    }
+    async wake(tenantId) {
+        const current = ensureReadyHome(getHome(this.config.registryPath, tenantId), tenantId);
+        const machine = await this.getMachine(current.machineId);
+        const relayToken = current.relayToken ?? '';
+        if (relayToken === '') {
+            throw general(`home ${tenantId} is missing relayToken — run the existing provision/bootstrap flow`, { tenantId });
+        }
+        const bootstrapScript = buildBootstrapScript({
+            guestHome: this.config.guestHome,
+            crtrVersion: this.crtrVersion,
+            relayToken,
+            webPort: this.config.webPort,
+            nodeId: current.nodeId ?? undefined,
+            piAuthJson: this.config.piAuthJson,
+            isFirstProvision: false,
+        });
+        if (isRunningMachine(machine)) {
+            try {
+                await this.provider.waitForPort(current.machineId, this.config.webPort, { maxWaitMs: 30_000 });
+            }
+            catch {
+                await this.provider.exec(current.machineId, { command: bootstrapScript, background: true, cwd: this.config.guestHome });
+                await this.provider.waitForPort(current.machineId, this.config.webPort, { maxWaitMs: 30_000 });
+            }
+        }
+        else {
+            await this.provider.createMachine({
+                tenantId,
+                name: current.machineId,
+                envs: guestEnv(this.config),
+                volumeMount: { volumeName: current.homeStorage.volumeId, path: this.config.guestHome },
+                ports: [{ target: this.config.webPort, protocol: 'HTTP' }],
+            });
+            await this.provider.exec(current.machineId, { command: bootstrapScript, background: true, cwd: this.config.guestHome });
+            await this.provider.waitForPort(current.machineId, this.config.webPort, { maxWaitMs: 60_000 });
+        }
+        const route = await this.provider.publishHttpPort(current.machineId, {
+            machineId: current.machineId,
+            targetPort: this.config.webPort,
+            routeName: stableRouteName(current),
+            routeId: stableRouteName(current),
+        });
+        const updatedAt = nowIso();
+        updateHome(this.config.registryPath, tenantId, () => buildHomeRecord({ ...current, webRoute: route, relayToken }, this.config, route, { createdAt: current.createdAt, updatedAt }));
+    }
+    async suspend(tenantId) {
+        updateHome(this.config.registryPath, tenantId, (draft) => {
+            draft.updatedAt = nowIso();
+            return draft;
+        });
+    }
+    async getMachine(machineId) {
+        const machine = await this.provider.getMachine(machineId);
+        return machine.state === 'terminated' ? null : machine;
+    }
+}

package/dist/core/hearth/providers/blaxel.d.ts

@@ -0,0 +1,26 @@
+import type { MachineRef, RouteRef } from '../types.js';
+import type { CreateMachineInput, DestroyOutcome, ExecInput, ExecResult, HealthResult, MachineProvider, PublishHttpPortInput, VolumeRef } from './types.js';
+interface BlaxelMachineProviderOptions {
+    region?: string;
+    memory?: number;
+    image?: string;
+}
+export declare class BlaxelMachineProvider implements MachineProvider {
+    readonly providerName: "blaxel";
+    private readonly config;
+    constructor(options?: BlaxelMachineProviderOptions);
+    createVolume(input: {
+        name: string;
+    }): Promise<VolumeRef>;
+    createMachine(input: CreateMachineInput): Promise<MachineRef>;
+    getMachine(machineId: string): Promise<MachineRef>;
+    exec(machineId: string, input: ExecInput): Promise<ExecResult>;
+    waitForPort(machineId: string, port: number, opts?: {
+        maxWaitMs?: number;
+    }): Promise<void>;
+    publishHttpPort(machineId: string, input: PublishHttpPortInput): Promise<RouteRef>;
+    health(): Promise<HealthResult>;
+    destroy(machineId: string): Promise<DestroyOutcome>;
+    destroyVolume(volumeId: string): Promise<DestroyOutcome>;
+}
+export {};

package/dist/core/hearth/providers/blaxel.js

@@ -0,0 +1,208 @@
+import { SandboxInstance, VolumeInstance } from '@blaxel/core';
+import { general } from '../../errors.js';
+const TERMINATED_STATES = new Set(['TERMINATED', 'DELETING', 'DEACTIVATED', 'DEACTIVATING', 'FAILED']);
+const PROVISIONING_STATES = new Set(['UPLOADING', 'BUILDING', 'DEPLOYING', 'BUILT']);
+function shStatus(status) {
+    if (status === undefined || status === null || status === '')
+        return 'unknown';
+    const normalized = status.toUpperCase();
+    if (normalized === 'DEPLOYED')
+        return 'running';
+    if (normalized === 'RUNNING' || normalized === 'STANDBY')
+        return 'running';
+    if (TERMINATED_STATES.has(normalized))
+        return 'terminated';
+    if (PROVISIONING_STATES.has(normalized))
+        return 'provisioning';
+    if (normalized === 'PAUSED' || normalized === 'SUSPENDED')
+        return 'paused';
+    return status;
+}
+function record(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    return value;
+}
+function rawFromSandbox(sandbox) {
+    return {
+        metadata: sandbox.metadata,
+        status: sandbox.status ?? null,
+        spec: sandbox.spec,
+    };
+}
+function rawFromVolume(volume) {
+    return {
+        metadata: volume.metadata,
+        status: volume.status ?? null,
+        spec: volume.spec,
+    };
+}
+function toEnvVars(envs) {
+    if (envs === undefined)
+        return undefined;
+    return Object.entries(envs)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, value]) => ({ name, value }));
+}
+function isMissingResourceError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /\b(not found|404|does not exist|missing)\b/i.test(message);
+}
+function toMachineRef(sandbox) {
+    const metadata = sandbox.metadata;
+    const status = sandbox.status ?? undefined;
+    return {
+        providerName: 'blaxel',
+        machineId: metadata.name,
+        state: shStatus(status),
+        updatedAt: metadata.updatedAt ?? null,
+        raw: rawFromSandbox(sandbox),
+    };
+}
+function toRouteRef(machineId, targetPort, preview, raw) {
+    const url = preview.spec.url ?? null;
+    return {
+        routeId: preview.name,
+        machineId,
+        targetPort,
+        url,
+        concreteUrl: url,
+        concreteUrlSource: 'provider',
+        raw: raw ?? null,
+    };
+}
+export class BlaxelMachineProvider {
+    providerName = 'blaxel';
+    config;
+    constructor(options = {}) {
+        this.config = {
+            region: options.region ?? 'us-west-2',
+            memory: options.memory ?? 2048,
+            // blaxel/prod-base:latest is NOT a supported Blaxel sandbox image (400 INVALID_IMAGE,
+            // confirmed live 2026-06-29). blaxel/node:latest ships node+npm on Alpine/musl, which the
+            // in-guest `npm i -g @crouton-kit/crouter` needs.
+            image: options.image ?? 'blaxel/node:latest',
+        };
+    }
+    async createVolume(input) {
+        const volume = await VolumeInstance.createIfNotExists({ name: input.name, size: 1024, region: this.config.region });
+        return {
+            volumeId: volume.metadata.name ?? input.name,
+            name: input.name,
+            raw: rawFromVolume(volume),
+        };
+    }
+    async createMachine(input) {
+        const sandbox = await SandboxInstance.createIfNotExists({
+            name: input.name ?? input.tenantId,
+            image: this.config.image,
+            memory: this.config.memory,
+            region: this.config.region,
+            volumes: input.volumeMount === undefined || input.volumeMount === null ? undefined : [{ name: input.volumeMount.volumeName, mountPath: input.volumeMount.path, readOnly: false }],
+            envs: toEnvVars(input.envs),
+            ports: input.ports?.map((port) => ({ target: port.target, protocol: port.protocol })),
+        });
+        await sandbox.wait({ maxWait: 90_000, interval: 500 }).catch(() => sandbox);
+        return toMachineRef(sandbox);
+    }
+    async getMachine(machineId) {
+        try {
+            const sandbox = await SandboxInstance.get(machineId);
+            return toMachineRef(sandbox);
+        }
+        catch (error) {
+            if (!isMissingResourceError(error))
+                throw error;
+            return {
+                providerName: 'blaxel',
+                machineId,
+                state: 'terminated',
+                raw: { error: error instanceof Error ? error.message : String(error) },
+            };
+        }
+    }
+    async exec(machineId, input) {
+        const sandbox = await SandboxInstance.get(machineId);
+        const response = await sandbox.process.exec({
+            command: input.command,
+            env: input.env,
+            timeout: Math.ceil((input.timeoutMs ?? 55_000) / 1000),
+            workingDir: input.cwd,
+            ...(input.background === true ? { waitForCompletion: false } : { waitForCompletion: true }),
+        });
+        const result = record(response) ?? {};
+        return {
+            exitCode: typeof result.exitCode === 'number' ? result.exitCode : null,
+            timedOut: false,
+            stdout: typeof result.stdout === 'string' ? result.stdout : typeof result.logs === 'string' ? result.logs : '',
+            stderr: typeof result.stderr === 'string' ? result.stderr : '',
+            raw: result,
+        };
+    }
+    async waitForPort(machineId, port, opts) {
+        const sandbox = await SandboxInstance.get(machineId);
+        try {
+            await sandbox.process.exec({
+                command: 'true',
+                waitForPorts: [port],
+                waitForCompletion: true,
+                timeout: Math.ceil((opts?.maxWaitMs ?? 60_000) / 1000),
+            });
+        }
+        catch (error) {
+            throw general(`blaxel sandbox ${machineId} never opened port ${port}`, {
+                machineId,
+                port,
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    async publishHttpPort(machineId, input) {
+        const sandbox = await SandboxInstance.get(machineId);
+        const previewName = input.routeName ?? input.routeId ?? `${machineId}-http`;
+        const preview = await sandbox.previews.createIfNotExists({
+            metadata: { name: previewName },
+            spec: { port: input.targetPort, public: true },
+        });
+        return toRouteRef(machineId, input.targetPort, { name: preview.name, spec: preview.spec }, {
+            preview: { metadata: preview.metadata, spec: preview.spec },
+            input,
+        });
+    }
+    async health() {
+        try {
+            await VolumeInstance.list();
+            return { ok: true, providerName: 'blaxel' };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                providerName: 'blaxel',
+                status: error instanceof Error ? error.message : String(error),
+                raw: { error: error instanceof Error ? error.message : String(error) },
+            };
+        }
+    }
+    async destroy(machineId) {
+        try {
+            await SandboxInstance.delete(machineId);
+            return { kind: 'destroyed' };
+        }
+        catch (error) {
+            if (isMissingResourceError(error))
+                return { kind: 'not_found' };
+            throw error;
+        }
+    }
+    async destroyVolume(volumeId) {
+        try {
+            await VolumeInstance.delete(volumeId);
+            return { kind: 'destroyed' };
+        }
+        catch (error) {
+            if (isMissingResourceError(error))
+                return { kind: 'not_found' };
+            throw error;
+        }
+    }
+}