@north-light/api 0.3.579 → 0.3.587

package/dist/core/runtime/roadmap.d.ts

@@ -0,0 +1,24 @@
+import { type CanvasDb } from '../canvas/db.js';
+export declare const ROADMAP_NAME = "roadmap";
+/** Fallback preview when the roadmap is seeded without a goal. */
+export declare const ROADMAP_PREVIEW = "To understand this node's long-term task and current plan, read this.";
+/** A roadmap's preview is its goal's first line; the fallback covers a goal-less seed. */
+export declare function roadmapPreview(goal?: string): string;
+/** How a node addresses its own roadmap in `crtr canvas read` / `crtr doc edit`. */
+export declare function roadmapRef(nodeId: string): string;
+export declare function hasRoadmap(nodeId: string): Promise<boolean>;
+/** The roadmap's newest head body, or null when the node has none. */
+export declare function readRoadmap(nodeId: string): Promise<string | null>;
+/** Seed a fresh, EXTREMELY BAREBONES roadmap document — the section skeleton
+ *  with one-line prompts — authored by the node. The owner fleshes it out as
+ *  its next act with `crtr doc edit roadmap`. Leaves an existing roadmap
+ *  untouched and returns null; otherwise returns the seeded body. */
+export declare function seedRoadmap(db: CanvasDb, nodeId: string, opts?: {
+    goal?: string;
+    exitCriteria?: string;
+}): Promise<string | null>;
+/** `seedRoadmap` in its own canvas write; true when it wrote one. */
+export declare function ensureRoadmap(nodeId: string, opts?: {
+    goal?: string;
+    exitCriteria?: string;
+}): Promise<boolean>;

package/dist/core/runtime/roadmap.js

@@ -0,0 +1,86 @@
+// The roadmap — a node's task at its own level of abstraction, in four
+// sections: Goal, Exit criteria, Where things stand (present state, rewritten in
+// place), and Working set ([[links]] whose previews attach when the roadmap is
+// delivered). Detail below the node's level lives with whichever node or
+// document holds it; it never lists child ids or status (bearings do). It is
+// what lets a node survive a refresh-yield:
+// revive with no memory, the roadmap loads at boot, continue. Its preview is
+// the goal's first line — all that someone linking to the roadmap sees.
+//
+// The roadmap is the node's own document `roadmap` (kind knowledge) with the
+// rule `on: boot`, `deliver: content`. The rule is node-owned, so only that node
+// sees it, and boot delivery hands it to every new session of the node.
+// Seeded at promotion (or an orchestrator birth); a base node may write its own.
+import { openDb, withCanvasWrite } from '../canvas/db.js';
+import { findMany as findBodies } from '../graph/bodies.js';
+import { heads, writeDocument } from '../graph/documents.js';
+import { asRuntimeWriter } from '../permissions/ceiling.js';
+import { getById, liveDocumentNamed, nodeObject } from '../graph/objects.js';
+import { readerForNode } from '../graph/reader.js';
+export const ROADMAP_NAME = 'roadmap';
+/** Fallback preview when the roadmap is seeded without a goal. */
+export const ROADMAP_PREVIEW = "To understand this node's long-term task and current plan, read this.";
+/** A roadmap's preview is its goal's first line; the fallback covers a goal-less seed. */
+export function roadmapPreview(goal) {
+    const first = goal?.split('\n').map((line) => line.trim()).find((line) => line !== '');
+    return first ?? ROADMAP_PREVIEW;
+}
+/** How a node addresses its own roadmap in `crtr canvas read` / `crtr doc edit`. */
+export function roadmapRef(nodeId) {
+    return `${nodeId}/${ROADMAP_NAME}`;
+}
+async function roadmapObject(db, nodeId) {
+    const node = await getById(db, nodeId);
+    if (node === null || node.type !== 'node')
+        return null;
+    return await liveDocumentNamed(db, node.id, ROADMAP_NAME);
+}
+export async function hasRoadmap(nodeId) {
+    return await roadmapObject(await openDb(), nodeId) !== null;
+}
+/** The roadmap's newest head body, or null when the node has none. */
+export async function readRoadmap(nodeId) {
+    const db = await openDb();
+    const doc = await roadmapObject(db, nodeId);
+    if (doc === null)
+        return null;
+    const head = (await heads(db, doc))[0];
+    if (head === undefined)
+        return null;
+    // No stored text (a revision from before the text moved into the database) reads as no roadmap; a database error still propagates.
+    return (await findBodies(db, [head.body_hash])).get(head.body_hash) ?? null;
+}
+function scaffold(opts) {
+    return `# Roadmap
+
+## Goal
+${opts.goal?.trim() || '(the goal you now own)'}
+
+## Exit criteria
+${opts.exitCriteria?.trim() || '(what "done" looks like)'}
+
+## Where things stand
+(present state at your level: settled, in flight, remaining)
+
+## Working set
+(links to the documents the work depends on now, one per line)
+`;
+}
+/** Seed a fresh, EXTREMELY BAREBONES roadmap document — the section skeleton
+ *  with one-line prompts — authored by the node. The owner fleshes it out as
+ *  its next act with `crtr doc edit roadmap`. Leaves an existing roadmap
+ *  untouched and returns null; otherwise returns the seeded body. */
+export async function seedRoadmap(db, nodeId, opts = {}) {
+    if (await roadmapObject(db, nodeId) !== null)
+        return null;
+    const body = scaffold(opts);
+    await writeDocument(db, asRuntimeWriter(await readerForNode(db, nodeId, async () => [])), {
+        owner: await nodeObject(db, nodeId), name: ROADMAP_NAME, kind: 'knowledge', preview: roadmapPreview(opts.goal), privacy: 'public',
+        rules: [{ on: 'boot', deliver: 'content' }],
+    }, body);
+    return body;
+}
+/** `seedRoadmap` in its own canvas write; true when it wrote one. */
+export async function ensureRoadmap(nodeId, opts = {}) {
+    return await withCanvasWrite(async (db) => await seedRoadmap(db, nodeId, opts) !== null);
+}

package/dist/core/runtime/runner/blaxel/client.d.ts

@@ -0,0 +1,83 @@
+export interface BlaxelConfig {
+    apiKey: string;
+    workspace: string;
+    region: string;
+    /** Defaults to `https://api.blaxel.ai/v0`. */
+    controlUrl?: string;
+    fetch?: typeof fetch;
+}
+/** `BLAXEL_API_KEY`, `BLAXEL_WORKSPACE`, `BLAXEL_REGION` (H-1 names). Throws when one is missing. */
+export declare function blaxelConfigFromEnv(env?: NodeJS.ProcessEnv): BlaxelConfig;
+export declare class BlaxelApiError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    constructor(status: number, code: string | null, message: string);
+}
+/** The sandbox gateway answers 404 `WORKLOAD_UNAVAILABLE` for a sandbox URL whose workload no longer exists (deleted, or never existed). */
+export declare const isWorkloadUnavailable: (error: unknown) => error is BlaxelApiError;
+export interface SandboxSpec {
+    name: string;
+    image: string;
+    memoryMb: number;
+    /** Extra ports beyond the sandbox API (8080), e.g. the broker's view port. */
+    ports?: Array<{
+        name: string;
+        target: number;
+    }>;
+}
+export interface SandboxInfo {
+    name: string;
+    /** Base URL of the sandbox API. */
+    url: string;
+    /** `RUNNING`, `STANDBY` (frozen), ...; reading it does not wake the sandbox. */
+    state: string | null;
+    status: string | null;
+}
+export type ProcessStatus = 'running' | 'completed' | 'failed' | 'killed' | 'stopped';
+export interface SandboxProcess {
+    name: string;
+    pid: string;
+    status: ProcessStatus;
+    exitCode: number;
+    command: string;
+    stdout: string;
+    stderr: string;
+    logs: string;
+}
+export interface StartProcessInput {
+    name: string;
+    command: string;
+    env?: Record<string, string>;
+    workingDir?: string;
+    waitForCompletion?: boolean;
+    /** Seconds, with `waitForCompletion`. */
+    timeout?: number;
+}
+export interface PreviewToken {
+    token: string;
+    expiresAt: string;
+}
+export interface BlaxelClient {
+    readonly config: BlaxelConfig;
+    /** Creates the sandbox; an existing one with that name is adopted (`created: false`). */
+    createSandbox(spec: SandboxSpec): Promise<SandboxInfo & {
+        created: boolean;
+    }>;
+    /** Null when the sandbox does not exist or is being deleted. */
+    getSandbox(name: string): Promise<SandboxInfo | null>;
+    /** Deleting an absent sandbox is not an error. */
+    deleteSandbox(name: string): Promise<void>;
+    startProcess(sandbox: SandboxInfo, input: StartProcessInput): Promise<SandboxProcess>;
+    /** Null when the sandbox API answers 404 for that process. */
+    getProcess(sandbox: SandboxInfo, name: string): Promise<SandboxProcess | null>;
+    /** SIGTERM. Stopping a stopped process is not an error. */
+    stopProcess(sandbox: SandboxInfo, name: string): Promise<void>;
+    killProcess(sandbox: SandboxInfo, name: string): Promise<void>;
+    /** Run a command to completion in the sandbox. */
+    exec(sandbox: SandboxInfo, name: string, command: string, timeoutS: number, env?: Record<string, string>): Promise<SandboxProcess>;
+    putFile(sandbox: SandboxInfo, path: string, content: string, permissions?: string): Promise<void>;
+    /** Creates (or adopts) a private preview on `port` and returns its URL. */
+    ensurePreview(sandboxName: string, previewName: string, port: number): Promise<string>;
+    createPreviewToken(sandboxName: string, previewName: string, expiresAt: Date): Promise<PreviewToken>;
+}
+export declare function createBlaxelClient(config: BlaxelConfig): BlaxelClient;

package/dist/core/runtime/runner/blaxel/client.js

@@ -0,0 +1,140 @@
+// src/core/runtime/runner/blaxel/client.ts — Blaxel control-plane and sandbox-API client (C-A2).
+//
+// Two surfaces: the control plane (`https://api.blaxel.ai/v0`: create/get/delete a sandbox, previews, preview
+// tokens) and the sandbox's own API (`https://sbx-<name>-<workspace id>.<region>.bl.run`: processes, files).
+// Both take `Authorization: Bearer <BLAXEL_API_KEY>`; the control plane also takes `X-Blaxel-Workspace`.
+// The sandbox URL is read from the create/get answer (`metadata.url`), never computed.
+// `fetch` is injectable so the unit lane runs the runner contract against a fake API.
+/** `BLAXEL_API_KEY`, `BLAXEL_WORKSPACE`, `BLAXEL_REGION` (H-1 names). Throws when one is missing. */
+export function blaxelConfigFromEnv(env = process.env) {
+    const need = (name) => {
+        const value = env[name];
+        if (!value)
+            throw new Error(`${name} is required for the Blaxel runner`);
+        return value;
+    };
+    return { apiKey: need('BLAXEL_API_KEY'), workspace: need('BLAXEL_WORKSPACE'), region: need('BLAXEL_REGION') };
+}
+export class BlaxelApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'BlaxelApiError';
+    }
+}
+/** The sandbox gateway answers 404 `WORKLOAD_UNAVAILABLE` for a sandbox URL whose workload no longer exists (deleted, or never existed). */
+export const isWorkloadUnavailable = (error) => error instanceof BlaxelApiError && error.status === 404 && error.code === 'WORKLOAD_UNAVAILABLE';
+function toInfo(raw) {
+    const url = raw.metadata.url;
+    if (!url)
+        throw new Error(`Blaxel sandbox ${raw.metadata.name} has no url`);
+    return { name: raw.metadata.name, url, state: raw.state ?? null, status: raw.status ?? null };
+}
+/**
+ * The code and message of an error body. The sandbox gateway nests them (`{"error":{"code":"WORKLOAD_UNAVAILABLE","message":...}}`);
+ * the control plane answers `{"code":404,"error":"Sandbox not found"}`, whose numeric `code` is not a Blaxel error code.
+ */
+function errorFields(json, text) {
+    const record = (json ?? {});
+    const nested = typeof record.error === 'object' && record.error !== null ? record.error : {};
+    const code = typeof nested.code === 'string' ? nested.code : typeof record.code === 'string' ? record.code : null;
+    const message = [nested.message, record.message, record.error].find((m) => typeof m === 'string') ?? text.slice(0, 300);
+    return { code, message };
+}
+export function createBlaxelClient(config) {
+    const doFetch = config.fetch ?? fetch;
+    const control = config.controlUrl ?? 'https://api.blaxel.ai/v0';
+    const headers = () => ({
+        authorization: `Bearer ${config.apiKey}`,
+        'x-blaxel-workspace': config.workspace,
+        'content-type': 'application/json',
+    });
+    async function call(url, method, body, okStatuses = []) {
+        const response = await doFetch(url, { method, headers: headers(), ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+        const text = await response.text();
+        let json = null;
+        if (text !== '') {
+            try {
+                json = JSON.parse(text);
+            }
+            catch {
+                json = { raw: text };
+            }
+        }
+        if (!response.ok) {
+            const { code, message } = errorFields(json, text);
+            // A deleted workload is never an ordinary 404: no caller may read it as "that process is absent" or "stopped".
+            const workloadGone = response.status === 404 && code === 'WORKLOAD_UNAVAILABLE';
+            if (workloadGone || !okStatuses.includes(response.status)) {
+                throw new BlaxelApiError(response.status, code, `Blaxel ${method} ${url} failed (${response.status}): ${message}`);
+            }
+        }
+        return { status: response.status, json };
+    }
+    const encodeName = encodeURIComponent;
+    return {
+        config,
+        async createSandbox(spec) {
+            const ports = [...(spec.ports ?? [])].map((p) => ({ name: p.name, target: p.target, protocol: 'HTTP' }));
+            const body = { metadata: { name: spec.name }, spec: { runtime: { image: spec.image, memory: spec.memoryMb, ...(ports.length > 0 ? { ports } : {}) }, region: config.region } };
+            const { status, json } = await call(`${control}/sandboxes`, 'POST', body, [409]);
+            if (status === 409) {
+                const existing = await this.getSandbox(spec.name);
+                if (existing === null)
+                    throw new Error(`Blaxel sandbox ${spec.name} reported as existing but cannot be read`);
+                return { ...existing, created: false };
+            }
+            return { ...toInfo(json), created: true };
+        },
+        async getSandbox(name) {
+            const { status, json } = await call(`${control}/sandboxes/${encodeName(name)}`, 'GET', undefined, [404]);
+            if (status === 404)
+                return null;
+            const raw = json;
+            // The control plane keeps answering for a deleted sandbox while it is torn down; it is not a sandbox a process can be started in.
+            return raw.status === 'DELETING' || raw.status === 'TERMINATED' ? null : toInfo(raw);
+        },
+        async deleteSandbox(name) {
+            await call(`${control}/sandboxes/${encodeName(name)}`, 'DELETE', undefined, [404]);
+        },
+        async startProcess(sandbox, input) {
+            const { json } = await call(`${sandbox.url}/process`, 'POST', input);
+            return json;
+        },
+        async getProcess(sandbox, name) {
+            const { status, json } = await call(`${sandbox.url}/process/${encodeName(name)}`, 'GET', undefined, [404]);
+            return status === 404 ? null : json;
+        },
+        async stopProcess(sandbox, name) {
+            await call(`${sandbox.url}/process/${encodeName(name)}`, 'DELETE', undefined, [404]);
+        },
+        async killProcess(sandbox, name) {
+            await call(`${sandbox.url}/process/${encodeName(name)}/kill`, 'DELETE', undefined, [404]);
+        },
+        async exec(sandbox, name, command, timeoutS, env) {
+            return await this.startProcess(sandbox, { name, command, waitForCompletion: true, timeout: timeoutS, ...(env ? { env } : {}) });
+        },
+        async putFile(sandbox, path, content, permissions = '0644') {
+            await call(`${sandbox.url}/filesystem/${path.replace(/^\/+/, '').split('/').map(encodeName).join('/')}`, 'PUT', { content, permissions });
+        },
+        async ensurePreview(sandboxName, previewName, port) {
+            const { json } = await call(`${control}/sandboxes/${encodeName(sandboxName)}/previews`, 'POST', { metadata: { name: previewName }, spec: { port, public: false } }, [409]);
+            const created = json?.spec?.url;
+            if (created)
+                return created;
+            const listed = (await call(`${control}/sandboxes/${encodeName(sandboxName)}/previews`, 'GET')).json;
+            const found = listed.find((p) => p.metadata.name === previewName);
+            if (!found)
+                throw new Error(`Blaxel preview ${previewName} of ${sandboxName} not found`);
+            return found.spec.url;
+        },
+        async createPreviewToken(sandboxName, previewName, expiresAt) {
+            const { json } = await call(`${control}/sandboxes/${encodeName(sandboxName)}/previews/${encodeName(previewName)}/tokens`, 'POST', { spec: { expiresAt: expiresAt.toISOString() } });
+            const spec = json.spec;
+            return { token: spec.token, expiresAt: spec.expiresAt };
+        },
+    };
+}

package/dist/core/runtime/runner/blaxel/image-build.d.ts

@@ -0,0 +1,74 @@
+import { type BlaxelConfig } from './client.js';
+export interface RecipeRepository {
+    name: string;
+    github_full_name: string;
+    default_branch: string;
+}
+export interface Recipe {
+    repositories: RecipeRepository[];
+    setup_script: string | null;
+    /** pi package sources, one per line (the `environments.pi_packages` text). */
+    pi_packages: string | null;
+}
+export declare const NODE_BASE_IMAGE = "public.ecr.aws/docker/library/node:24-alpine";
+/** Where the image installs the recipe's pi packages: one pi agent dir of its own, not any app's. The start script (`sandbox-start.mjs`) links its
+ *  `npm`/`git` trees into, and merges its `packages` setting with, the agent dir of whichever app the node runs in. Keep the two in step. */
+export declare const RECIPE_PI_AGENT_DIR = "/var/lib/crtr/recipe-pi-agent";
+export declare const SETUP_SCRIPT_FILE = "recipe-setup.sh";
+export declare const REPOS_DIR = "repos";
+/** The Dockerfile for a recipe revision. Pure. It clones and fetches nothing: the repositories arrive by `COPY`, so a token cannot appear here. */
+export declare function recipeDockerfile(recipe: Recipe, revision: number): string;
+export type GitRunner = (args: string[], env: Record<string, string>, cwd: string) => Promise<void>;
+export interface PrepareBuildDirInput {
+    recipe: Recipe;
+    revision: number;
+    /** A GitHub installation token limited to the recipe's repositories, or null for a source that needs none. */
+    token: string | null;
+    /** An empty directory. */
+    dir: string;
+    git?: GitRunner;
+    /** The clone URL of a repository; the default is `https://github.com/<full name>.git`. */
+    cloneUrl?: (githubFullName: string) => string;
+}
+/** Clones each repository into `<dir>/repos/<name>` and writes the Dockerfile and the setup script beside it. */
+export declare function prepareBuildDir(input: PrepareBuildDirInput): Promise<void>;
+/** A zip of every file under `dir` (deflate, unix modes kept so scripts stay executable). Empty directories are not carried. */
+export declare function zipDirectory(dir: string): Buffer;
+export interface BuiltImage {
+    /** `sandbox/<name>:<tag>`, the value of `environments.image_ref` and of a sandbox's `runtime.image`. */
+    ref: string;
+    /** Milliseconds from the upload request to `BUILT`. */
+    buildMs: number;
+}
+export interface BuildImageOptions {
+    pollMs?: number;
+    /** Give up after this long in a non-terminal state. Default 20 minutes. */
+    timeoutMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+interface ImageDoc {
+    metadata?: {
+        status?: string;
+        events?: Array<{
+            message?: string;
+            status?: string;
+        }>;
+    };
+    spec?: {
+        tags?: Array<{
+            name?: string;
+            createdAt?: string;
+            updatedAt?: string;
+        }>;
+    };
+}
+export declare function getImage(config: BlaxelConfig, name: string): Promise<ImageDoc | null>;
+/** Deleting an absent image is not an error; an image a sandbox still uses is refused by Blaxel. */
+export declare function deleteImage(config: BlaxelConfig, name: string): Promise<void>;
+/** Uploads `dir` (Dockerfile and context) as a build of sandbox image `name` and waits for it. A failed build throws with Blaxel's last event message. */
+export declare function buildImage(config: BlaxelConfig, name: string, dir: string, options?: BuildImageOptions): Promise<BuiltImage>;
+/** The image name of an environment: every revision is a new tag of it. */
+export declare const environmentImageName: (environmentId: string) => string;
+/** Removes a build directory. */
+export declare function removeBuildDir(dir: string): void;
+export {};

package/dist/core/runtime/runner/blaxel/image-build.js

@@ -0,0 +1,209 @@
+// src/core/runtime/runner/blaxel/image-build.ts — the recipe image: Dockerfile writer, build-directory clone, Blaxel image build (C-A5, D25/D93/D94).
+//
+// An environment recipe (repositories, pi packages, setup script) becomes one Blaxel sandbox image per recipe revision. The control plane
+// clones each repository into a build directory with a short-lived GitHub token, writes a Dockerfile that only COPYs the clones, zips the
+// directory and uploads it to Blaxel's build API. The token is handed to `git` through the environment of the clone process: it is in no
+// file, no Dockerfile line, no build argument and no `.git/config`, so it is in no image layer. Nothing of the person's secrets reaches the build.
+// `fetch` and `git` are injectable so the unit lane runs the whole flow against fakes.
+import { spawn } from 'node:child_process';
+import { constants as fsConstants, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, rmSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { crc32, deflateRawSync } from 'node:zlib';
+import { BlaxelApiError } from './client.js';
+export const NODE_BASE_IMAGE = 'public.ecr.aws/docker/library/node:24-alpine';
+const SANDBOX_API_IMAGE = 'ghcr.io/blaxel-ai/sandbox:latest';
+/** The user the sandbox bootstrap runs the node as. */
+const RUN_USER = 'crtr';
+/** Where the image installs the recipe's pi packages: one pi agent dir of its own, not any app's. The start script (`sandbox-start.mjs`) links its
+ *  `npm`/`git` trees into, and merges its `packages` setting with, the agent dir of whichever app the node runs in. Keep the two in step. */
+export const RECIPE_PI_AGENT_DIR = '/var/lib/crtr/recipe-pi-agent';
+const PI_VERSION = '1.1.0';
+export const SETUP_SCRIPT_FILE = 'recipe-setup.sh';
+export const REPOS_DIR = 'repos';
+const shellQuote = (value) => `'${value.replace(/'/g, `'\\''`)}'`;
+const lines = (text) => (text ?? '').split('\n').map((l) => l.trim()).filter((l) => l !== '');
+/** The Dockerfile for a recipe revision. Pure. It clones and fetches nothing: the repositories arrive by `COPY`, so a token cannot appear here. */
+export function recipeDockerfile(recipe, revision) {
+    const packages = lines(recipe.pi_packages);
+    const out = [
+        `FROM ${NODE_BASE_IMAGE}`,
+        'RUN apk add --no-cache bash git curl ripgrep',
+        `COPY --from=${SANDBOX_API_IMAGE} /sandbox-api /usr/local/bin/sandbox-api`,
+        `RUN adduser -D -h /home/${RUN_USER} -s /bin/sh ${RUN_USER} && mkdir -p /work/.crtr ${RECIPE_PI_AGENT_DIR} && chown -R ${RUN_USER} /work /var/lib/crtr`,
+    ];
+    // An empty `repos/` is not in the zip, and a COPY of a missing directory fails the build.
+    if (recipe.repositories.length > 0)
+        out.push(`COPY --chown=${RUN_USER} ${REPOS_DIR}/ /work/`);
+    if (packages.length > 0)
+        out.push(`RUN npm install -g @earendil-works/pi-coding-agent@${PI_VERSION}`);
+    if (recipe.setup_script !== null && recipe.setup_script.trim() !== '')
+        out.push(`COPY ${SETUP_SCRIPT_FILE} /tmp/${SETUP_SCRIPT_FILE}`);
+    out.push(`USER ${RUN_USER}`, 'WORKDIR /work');
+    for (const source of packages)
+        out.push(`RUN HOME=/var/lib/crtr PI_CODING_AGENT_DIR=${RECIPE_PI_AGENT_DIR} pi install ${shellQuote(source)}`);
+    if (recipe.setup_script !== null && recipe.setup_script.trim() !== '')
+        out.push(`RUN bash /tmp/${SETUP_SCRIPT_FILE}`);
+    out.push(`RUN echo ${Math.trunc(revision)} > /work/.crtr/recipe-revision`, 'USER root', 'ENTRYPOINT ["/usr/local/bin/sandbox-api"]', '');
+    return out.join('\n');
+}
+const runGit = (args, env, cwd) => new Promise((resolve, reject) => {
+    const child = spawn('git', args, { cwd, env: { ...process.env, ...env, GIT_TERMINAL_PROMPT: '0' }, stdio: ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+    child.on('error', reject);
+    child.on('close', (code) => { if (code === 0)
+        resolve();
+    else
+        reject(new Error(`git ${args[0]} failed (${code}): ${stderr.slice(0, 300)}`)); });
+});
+/** Clones each repository into `<dir>/repos/<name>` and writes the Dockerfile and the setup script beside it. */
+export async function prepareBuildDir(input) {
+    const git = input.git ?? runGit;
+    const cloneUrl = input.cloneUrl ?? ((full) => `https://github.com/${full}.git`);
+    mkdirSync(join(input.dir, REPOS_DIR), { recursive: true });
+    // The token travels as a git config entry in the clone process's environment: not in argv, not written to `.git/config`.
+    const auth = input.token === null ? {} : {
+        GIT_CONFIG_COUNT: '1',
+        GIT_CONFIG_KEY_0: 'http.https://github.com/.extraheader',
+        GIT_CONFIG_VALUE_0: `AUTHORIZATION: basic ${Buffer.from(`x-access-token:${input.token}`).toString('base64')}`,
+    };
+    for (const repo of input.recipe.repositories) {
+        if (!/^[A-Za-z0-9._-]+$/.test(repo.name) || repo.name === '.' || repo.name === '..')
+            throw new Error(`repository name ${JSON.stringify(repo.name)} is not a plain directory name`);
+        await git(['clone', '--quiet', '--branch', repo.default_branch, cloneUrl(repo.github_full_name), join(REPOS_DIR, repo.name)], auth, input.dir);
+    }
+    writeFileSync(join(input.dir, 'Dockerfile'), recipeDockerfile(input.recipe, input.revision));
+    if (input.recipe.setup_script !== null && input.recipe.setup_script.trim() !== '')
+        writeFileSync(join(input.dir, SETUP_SCRIPT_FILE), input.recipe.setup_script.endsWith('\n') ? input.recipe.setup_script : `${input.recipe.setup_script}\n`);
+}
+function walk(root, dir, out) {
+    for (const name of readdirSync(dir).sort()) {
+        const path = join(dir, name);
+        const stat = lstatSync(path);
+        const rel = relative(root, path).split('\\').join('/');
+        if (stat.isDirectory())
+            walk(root, path, out);
+        else if (stat.isSymbolicLink())
+            out.push({ name: rel, data: Buffer.from(readlinkSync(path)), mode: fsConstants.S_IFLNK | 0o777 });
+        else if (stat.isFile())
+            out.push({ name: rel, data: readFileSync(path), mode: fsConstants.S_IFREG | (stat.mode & 0o777) });
+    }
+}
+/** A zip of every file under `dir` (deflate, unix modes kept so scripts stay executable). Empty directories are not carried. */
+export function zipDirectory(dir) {
+    const entries = [];
+    walk(dir, dir, entries);
+    const parts = [];
+    const central = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const name = Buffer.from(entry.name);
+        const compressed = deflateRawSync(entry.data);
+        const crc = crc32(entry.data);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4);
+        local.writeUInt16LE(0x0800, 6);
+        local.writeUInt16LE(8, 8);
+        local.writeUInt32LE(0x21, 12); // 1980-01-01 in DOS time/date
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(compressed.length, 18);
+        local.writeUInt32LE(entry.data.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        parts.push(local, name, compressed);
+        const head = Buffer.alloc(46);
+        head.writeUInt32LE(0x02014b50, 0);
+        head.writeUInt16LE((3 << 8) | 20, 4);
+        head.writeUInt16LE(20, 6);
+        head.writeUInt16LE(0x0800, 8);
+        head.writeUInt16LE(8, 10);
+        head.writeUInt32LE(0x21, 14);
+        head.writeUInt32LE(crc, 16);
+        head.writeUInt32LE(compressed.length, 20);
+        head.writeUInt32LE(entry.data.length, 24);
+        head.writeUInt16LE(name.length, 28);
+        head.writeUInt32LE((entry.mode << 16) >>> 0, 38);
+        head.writeUInt32LE(offset, 42);
+        central.push(head, name);
+        offset += local.length + name.length + compressed.length;
+    }
+    const centralBytes = Buffer.concat(central);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(centralBytes.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...parts, centralBytes, end]);
+}
+async function api(config, method, path, body, okStatuses = []) {
+    const url = `${config.controlUrl ?? 'https://api.blaxel.ai/v0'}${path}`;
+    const response = await (config.fetch ?? fetch)(url, {
+        method,
+        headers: { authorization: `Bearer ${config.apiKey}`, 'x-blaxel-workspace': config.workspace, 'content-type': 'application/json' },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    const text = await response.text();
+    let json = null;
+    if (text !== '') {
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            json = { raw: text };
+        }
+    }
+    if (!response.ok && !okStatuses.includes(response.status))
+        throw new BlaxelApiError(response.status, null, `Blaxel ${method} ${url} failed (${response.status}): ${text.slice(0, 300)}`);
+    return { status: response.status, headers: response.headers, json };
+}
+export async function getImage(config, name) {
+    const { status, json } = await api(config, 'GET', `/images/sandbox/${encodeURIComponent(name)}`, undefined, [404]);
+    return status === 404 ? null : json;
+}
+/** Deleting an absent image is not an error; an image a sandbox still uses is refused by Blaxel. */
+export async function deleteImage(config, name) {
+    await api(config, 'DELETE', `/images/sandbox/${encodeURIComponent(name)}`, undefined, [404]);
+}
+/** Uploads `dir` (Dockerfile and context) as a build of sandbox image `name` and waits for it. A failed build throws with Blaxel's last event message. */
+export async function buildImage(config, name, dir, options = {}) {
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const started = Date.now();
+    const existing = await getImage(config, name);
+    const before = new Set((existing?.spec?.tags ?? []).map((t) => t.name));
+    const eventsBefore = existing?.metadata?.events?.length ?? 0;
+    const created = await api(config, 'POST', '/images', { resourceType: 'sandbox', name });
+    const uploadUrl = created.headers.get('x-blaxel-upload-url');
+    if (uploadUrl === null)
+        throw new Error(`Blaxel gave no upload URL for image ${name}`);
+    const put = await (config.fetch ?? fetch)(uploadUrl, { method: 'PUT', headers: { 'content-type': 'application/zip' }, body: new Uint8Array(zipDirectory(dir)) });
+    if (!put.ok)
+        throw new Error(`uploading the build context of image ${name} failed (${put.status}): ${(await put.text()).slice(0, 300)}`);
+    const deadline = started + (options.timeoutMs ?? 20 * 60_000);
+    for (;;) {
+        const image = await getImage(config, name);
+        const status = image?.metadata?.status;
+        // A rebuild of an existing image still reads BUILT until Blaxel records the new build: it adds an "initiated" and then a "succeeded" event.
+        if (status === 'BUILT' && (image?.metadata?.events?.length ?? 0) >= eventsBefore + 2) {
+            // A tag is derived from the build inputs and is immutable; the revision in the Dockerfile makes every revision's tag new. Identical inputs reuse the existing tag.
+            const all = (image?.spec?.tags ?? []).filter((t) => t.name !== undefined);
+            const fresh = all.filter((t) => !before.has(t.name));
+            const tags = fresh.length > 0 ? fresh : all;
+            const tag = tags.sort((a, b) => (b.updatedAt ?? '').localeCompare(a.updatedAt ?? ''))[0]?.name;
+            if (tag === undefined)
+                throw new Error(`Blaxel built image ${name} but no new tag appeared`);
+            return { ref: `sandbox/${name}:${tag}`, buildMs: Date.now() - started };
+        }
+        if (status === 'FAILED' || status === 'TERMINATED') {
+            const events = image?.metadata?.events ?? [];
+            throw new Error(`building image ${name} ${status.toLowerCase()}: ${events[events.length - 1]?.message ?? 'no message'}`);
+        }
+        if (Date.now() > deadline)
+            throw new Error(`building image ${name} did not finish within ${options.timeoutMs ?? 20 * 60_000} ms (last status ${status ?? 'none'})`);
+        await sleep(options.pollMs ?? 3000);
+    }
+}
+/** The image name of an environment: every revision is a new tag of it. */
+export const environmentImageName = (environmentId) => `env-${environmentId}`;
+/** Removes a build directory. */
+export function removeBuildDir(dir) { rmSync(dir, { recursive: true, force: true }); }

package/dist/core/runtime/runner/index.d.ts

@@ -0,0 +1,9 @@
+import type { Runner, RunnerKind } from './types.js';
+/** The Blaxel implementation is installed by the cloud runner module. */
+export declare function registerBlaxelRunner(runner: Runner): void;
+/** A machine environment is this process's own host for a Mac's crtrd (process runner) and another machine for a cloud role (the remote machine runner, design-import I13). */
+export declare function runnerKindForEnvironment(kind: 'machine' | 'blaxel'): RunnerKind;
+export declare function runnerForEnvironment(kind: 'machine' | 'blaxel'): Runner;
+export declare function runnerForEnvironmentId(environmentId: string): Promise<Runner>;
+/** The runner that holds an execution row, by the row's `runner` column. */
+export declare function runnerForExecution(runner: RunnerKind): Runner;