@vendoai/vendo 0.4.0

package/dist/runtime-capture.js

@@ -0,0 +1,111 @@
+import { capturedPinBaselineSchema } from "@vendoai/actions";
+import { sha256Hex, VendoError } from "@vendoai/core";
+function nodeModules() {
+    const proc = globalThis.process;
+    if (!proc?.cwd || !proc.getBuiltinModule)
+        return null;
+    const fs = proc.getBuiltinModule("node:fs");
+    const path = proc.getBuiltinModule("node:path");
+    const url = proc.getBuiltinModule("node:url");
+    return fs && path && url ? { fs, path, url, cwd: proc.cwd } : null;
+}
+function isInside(path, root, candidate) {
+    const relative = path.relative(path.resolve(root), path.resolve(candidate));
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function sourceCandidates(path, url, root, source) {
+    if (source.startsWith("file:")) {
+        try {
+            return [url.fileURLToPath(source)];
+        }
+        catch {
+            return [];
+        }
+    }
+    let clean = source.split(/[?#]/, 1)[0] ?? source;
+    // A dev browser's import.meta.url is an http(s) module URL (Vite serves
+    // /src/... under the dev origin). Only its pathname matters: the realpath
+    // root-confinement below decides what is actually readable.
+    if (/^https?:\/\//iu.test(clean)) {
+        try {
+            clean = decodeURIComponent(new URL(clean).pathname);
+        }
+        catch {
+            return [];
+        }
+    }
+    if (clean.startsWith("/@fs/"))
+        return [path.resolve(clean.slice(4))];
+    if (path.isAbsolute(clean)) {
+        const candidates = [path.resolve(clean)];
+        // Vite-style project-root ids use `/src/...`, not an absolute filesystem path.
+        if (clean.startsWith("/src/"))
+            candidates.push(path.resolve(root, clean.slice(1)));
+        return candidates;
+    }
+    return [path.resolve(root, clean)];
+}
+async function existingBaseline(fs, file) {
+    try {
+        return capturedPinBaselineSchema.parse(JSON.parse(await fs.promises.readFile(file, "utf8")));
+    }
+    catch {
+        return null;
+    }
+}
+/** Node-only capture primitive. Returning null keeps edge/Worker bundles file-system free. */
+export function createRuntimeCapture(config) {
+    const modules = nodeModules();
+    if (!modules)
+        return null;
+    const { fs, path, url } = modules;
+    const root = path.resolve(config.root ?? modules.cwd());
+    const out = path.resolve(config.out ?? path.join(root, ".vendo"));
+    let realRootPromise;
+    return {
+        async capture(registration) {
+            const remixableDir = path.resolve(out, "remixable");
+            const baselineFile = path.resolve(remixableDir, `${registration.slot}.json`);
+            if (!isInside(path, remixableDir, baselineFile)) {
+                throw new VendoError("validation", "remixable slot is not a safe baseline filename");
+            }
+            realRootPromise ??= fs.promises.realpath(root);
+            const realRoot = await realRootPromise;
+            let realSource;
+            for (const candidate of sourceCandidates(path, url, root, registration.source)) {
+                try {
+                    const resolved = await fs.promises.realpath(candidate);
+                    if (isInside(path, realRoot, resolved)) {
+                        realSource = resolved;
+                        break;
+                    }
+                }
+                catch {
+                    // Try the next bundler-id interpretation.
+                }
+            }
+            if (realSource === undefined) {
+                throw new VendoError("validation", "runtime capture source must resolve inside the host root");
+            }
+            const source = await fs.promises.readFile(realSource, "utf8");
+            const hash = `sha256:${sha256Hex(source)}`;
+            const existing = await existingBaseline(fs, baselineFile);
+            if (existing?.hash === hash)
+                return { slot: registration.slot, hash, status: "unchanged" };
+            // Static extraction is primary. A valid baseline may have been refreshed by
+            // sync after this browser bundle loaded, so runtime capture only fills gaps.
+            if (existing !== null)
+                return { slot: registration.slot, hash: existing.hash, status: "preserved" };
+            const baseline = {
+                slot: registration.slot,
+                source,
+                hash,
+                exportable: registration.exportable,
+                capturedAt: new Date().toISOString(),
+            };
+            await fs.promises.mkdir(remixableDir, { recursive: true });
+            await fs.promises.writeFile(baselineFile, `${JSON.stringify(baseline, null, 2)}\n`, "utf8");
+            return { slot: registration.slot, hash, status: "captured" };
+        },
+    };
+}

package/dist/sandbox-wire.d.ts

@@ -0,0 +1,101 @@
+/**
+ * WIRE-CONTRACT — the Vendo Cloud hosted-sandbox HTTP surface.
+ *
+ * execution-v2 Wave 5: every Cloud-side wire fact the adapter and its mock
+ * rely on lives HERE, in one module, so a Cloud-side change lands in one
+ * place. Authoritative per the Cloud session's 2026-07-19 ship note (the
+ * ARTIFACT model — persistent snapshot artifacts, verified live in prod
+ * with a full snapshot → destroy → resume → fork cycle) plus this lane's
+ * own live probes and conformance runs against console.vendo.run.
+ *
+ * The surface (under `{base}/api/v1/sandboxes`, key-authed with a
+ * `Bearer VENDO_API_KEY` header; errors are `{error:{code,message}}`
+ * envelopes; 402 = metered quota, 401 = bad key):
+ *
+ * - create   `POST /` body `{env, files?, egress?: string[]}` →
+ *   201 `{id, url}`. No template field — the pooled base image is Cloud's
+ *   own; the adapter drops `spec.template` and documents it. `egress`
+ *   absent = unrestricted, `[]` = deny-all — mirroring the
+ *   SandboxAdapter.create seam contract verbatim; deny-by-default is
+ *   enforced ABOVE the seam (Wave 2 Lane E always passes the grant-derived
+ *   list). The filter is HTTP(S)-only: raw TCP is severed even to
+ *   allowlisted hosts (raw Postgres never works; the HTTPS store API does).
+ * - snapshot `POST /{id}/snapshot` → 200 `{ref}` with ref
+ *   `vendo:snap_<40hex>` — a persistent ARTIFACT of the machine's state.
+ *   The source machine keeps running (and billing); artifacts survive the
+ *   machine's destruction. (Cloud-side caveat, no wire impact: artifact
+ *   storage meters 0 GB for now.)
+ * - resume   `POST /resume` body `{ref, egress?: string[]}` → 200
+ *   `{id, url}` booting a NEW machine from the artifact (a live source
+ *   makes it a fork; a destroyed one a wake). BREAKING vs create-config
+ *   intuition: the new machine does NOT inherit network config — `egress`
+ *   absent = unrestricted (Free orgs coerce deny-all) — so the adapter
+ *   sends the applicable allowlist EXPLICITLY on every resume: the
+ *   ref-recorded one for a bare resume, the SandboxResumePolicy one when
+ *   the caller re-polices a wake (Lane E replace semantics, native).
+ *   Resume of a GC'd or pre-artifact ref answers 404.
+ * - destroy  `DELETE /{id}` → 200 `{ok:true}`; MACHINE ids only (a
+ *   URL-encoded ref answers 404); repeat-delete = 200. Snapshot artifacts
+ *   SURVIVE the machine — sleep is snapshot-then-destroy, wake is resume.
+ * - snapshot GC `DELETE /snapshots/{url-encoded ref}` → 200 `{ok:true}`,
+ *   404 = already gone (treat as the seam's idempotent no-op); reclaims
+ *   the artifact and its storage row.
+ * - request  `POST /{id}/request` body `{method, path, port?, headers?,
+ *   body_b64}` → `{status, headers, body_b64}`, relayed into the box.
+ *   `port` absent targets the canonical box port {@link CLOUD_BOX_PORT}
+ *   (NOT the box's $PORT — the one provider divergence the conformance
+ *   multiPort flag covers); any explicit 1-65535 routes (probed — an
+ *   out-of-range port answers a clean 400 validation error), so the
+ *   in-box agent control port (8811) works.
+ - exec/files also exist server-side (`POST /{id}/exec`,
+ *   `GET|PUT /{id}/files?path=`, `GET /{id}/files/list?dir=`) — adapter-
+ *   private, used for live-lane bootstrap and diagnostics only.
+ * - ingress  the create/resume handle `url`
+ *   (`https://<id-suffix>-m.vendo.run`, single-label scheme SHIPPED by
+ *   vendo-web #85 on 2026-07-20; the -m is a SUFFIX, not a prefix —
+ *   Cloudflare worker routes only allow leading wildcards, so the route is
+ *   `*-m.vendo.run/*`) is the canonical-port public surface;
+ *   `machine.url(port)` inserts other ports before the suffix
+ *   (`https://<id-suffix>-<port>-m.vendo.run`), matching the machine-proxy
+ *   parse `^([a-z0-9]{24})(?:-(port))?-m\.vendo\.run$`. Single-label hosts
+ *   ride the existing `*.vendo.run` Universal SSL cert — no advanced
+ *   certificate needed (live-verified 2026-07-20: TLS fails on the legacy
+ *   dot shape `test123.m.vendo.run`, succeeds single-label; unknown ids
+ *   answer a JSON 404). The console mints `url`, so the hostname shape is
+ *   console-side; this adapter echoes whatever handle it is given.
+ *
+ * Adapter mapping:
+ * - `machine.snapshot()` = the artifact mint, wrapped in the adapter's
+ *   composite ref {@link CLOUD_SNAPSHOT_REF_PREFIX} + base64url(JSON
+ *   {machineId, ref, allowedDomains?}): the machine id lets destroy-by-ref
+ *   reap a still-running source, and the allowlist is what a bare resume
+ *   re-applies (the wire inherits nothing).
+ * - `machine.stop()` = destroy: Cloud has no pause — with artifacts
+ *   surviving the machine, snapshot-then-destroy IS the sleep semantics
+ *   (exactly the machine-lifecycle flow), and previously minted refs stay
+ *   valid through it (the seam law).
+ * - `adapter.destroy(ref)` = best-effort reap of the recorded source
+ *   machine, then artifact GC.
+ *
+ * Lifecycle interaction: Vendo auto-sleeps an idle machine after 5 minutes
+ * (snapshot → destroy); Cloud independently sweeps at 10 minutes idle and
+ * 24 hours max age. Our sleep normally wins; when the Cloud sweep gets
+ * there first the next wake resumes from the last stored ref, losing at
+ * most scratch state since it — acceptable, because the data rule keeps
+ * anything durable in the Vendo store, never on the VM disk.
+ */
+/** The console mounts the managed-sandbox surface here
+ * (apps/console/app/api/v1/sandboxes/*). */
+export declare const CLOUD_SANDBOX_PATH = "/api/v1/sandboxes";
+/** Snapshot-artifact GC route (under {@link CLOUD_SANDBOX_PATH}). */
+export declare const CLOUD_SNAPSHOTS_SUBPATH = "/snapshots";
+/** Adapter-minted snapshot refs: this prefix + base64url(JSON state).
+ * These are what the seam (and app documents) carry. */
+export declare const CLOUD_SNAPSHOT_REF_PREFIX = "vendo:v2:";
+/** Console-minted artifact refs (`vendo:snap_<40hex>`) — carried INSIDE the
+ * adapter's composite ref, never handed to the seam bare. */
+export declare const CONSOLE_SNAPSHOT_REF_PREFIX = "vendo:";
+/** The canonical box port the relay targets when no port rides the wire
+ * (and the one the public ingress `https://<id-suffix>-m.vendo.run`
+ * serves). */
+export declare const CLOUD_BOX_PORT = 8080;

package/dist/sandbox-wire.js

@@ -0,0 +1,101 @@
+/**
+ * WIRE-CONTRACT — the Vendo Cloud hosted-sandbox HTTP surface.
+ *
+ * execution-v2 Wave 5: every Cloud-side wire fact the adapter and its mock
+ * rely on lives HERE, in one module, so a Cloud-side change lands in one
+ * place. Authoritative per the Cloud session's 2026-07-19 ship note (the
+ * ARTIFACT model — persistent snapshot artifacts, verified live in prod
+ * with a full snapshot → destroy → resume → fork cycle) plus this lane's
+ * own live probes and conformance runs against console.vendo.run.
+ *
+ * The surface (under `{base}/api/v1/sandboxes`, key-authed with a
+ * `Bearer VENDO_API_KEY` header; errors are `{error:{code,message}}`
+ * envelopes; 402 = metered quota, 401 = bad key):
+ *
+ * - create   `POST /` body `{env, files?, egress?: string[]}` →
+ *   201 `{id, url}`. No template field — the pooled base image is Cloud's
+ *   own; the adapter drops `spec.template` and documents it. `egress`
+ *   absent = unrestricted, `[]` = deny-all — mirroring the
+ *   SandboxAdapter.create seam contract verbatim; deny-by-default is
+ *   enforced ABOVE the seam (Wave 2 Lane E always passes the grant-derived
+ *   list). The filter is HTTP(S)-only: raw TCP is severed even to
+ *   allowlisted hosts (raw Postgres never works; the HTTPS store API does).
+ * - snapshot `POST /{id}/snapshot` → 200 `{ref}` with ref
+ *   `vendo:snap_<40hex>` — a persistent ARTIFACT of the machine's state.
+ *   The source machine keeps running (and billing); artifacts survive the
+ *   machine's destruction. (Cloud-side caveat, no wire impact: artifact
+ *   storage meters 0 GB for now.)
+ * - resume   `POST /resume` body `{ref, egress?: string[]}` → 200
+ *   `{id, url}` booting a NEW machine from the artifact (a live source
+ *   makes it a fork; a destroyed one a wake). BREAKING vs create-config
+ *   intuition: the new machine does NOT inherit network config — `egress`
+ *   absent = unrestricted (Free orgs coerce deny-all) — so the adapter
+ *   sends the applicable allowlist EXPLICITLY on every resume: the
+ *   ref-recorded one for a bare resume, the SandboxResumePolicy one when
+ *   the caller re-polices a wake (Lane E replace semantics, native).
+ *   Resume of a GC'd or pre-artifact ref answers 404.
+ * - destroy  `DELETE /{id}` → 200 `{ok:true}`; MACHINE ids only (a
+ *   URL-encoded ref answers 404); repeat-delete = 200. Snapshot artifacts
+ *   SURVIVE the machine — sleep is snapshot-then-destroy, wake is resume.
+ * - snapshot GC `DELETE /snapshots/{url-encoded ref}` → 200 `{ok:true}`,
+ *   404 = already gone (treat as the seam's idempotent no-op); reclaims
+ *   the artifact and its storage row.
+ * - request  `POST /{id}/request` body `{method, path, port?, headers?,
+ *   body_b64}` → `{status, headers, body_b64}`, relayed into the box.
+ *   `port` absent targets the canonical box port {@link CLOUD_BOX_PORT}
+ *   (NOT the box's $PORT — the one provider divergence the conformance
+ *   multiPort flag covers); any explicit 1-65535 routes (probed — an
+ *   out-of-range port answers a clean 400 validation error), so the
+ *   in-box agent control port (8811) works.
+ - exec/files also exist server-side (`POST /{id}/exec`,
+ *   `GET|PUT /{id}/files?path=`, `GET /{id}/files/list?dir=`) — adapter-
+ *   private, used for live-lane bootstrap and diagnostics only.
+ * - ingress  the create/resume handle `url`
+ *   (`https://<id-suffix>-m.vendo.run`, single-label scheme SHIPPED by
+ *   vendo-web #85 on 2026-07-20; the -m is a SUFFIX, not a prefix —
+ *   Cloudflare worker routes only allow leading wildcards, so the route is
+ *   `*-m.vendo.run/*`) is the canonical-port public surface;
+ *   `machine.url(port)` inserts other ports before the suffix
+ *   (`https://<id-suffix>-<port>-m.vendo.run`), matching the machine-proxy
+ *   parse `^([a-z0-9]{24})(?:-(port))?-m\.vendo\.run$`. Single-label hosts
+ *   ride the existing `*.vendo.run` Universal SSL cert — no advanced
+ *   certificate needed (live-verified 2026-07-20: TLS fails on the legacy
+ *   dot shape `test123.m.vendo.run`, succeeds single-label; unknown ids
+ *   answer a JSON 404). The console mints `url`, so the hostname shape is
+ *   console-side; this adapter echoes whatever handle it is given.
+ *
+ * Adapter mapping:
+ * - `machine.snapshot()` = the artifact mint, wrapped in the adapter's
+ *   composite ref {@link CLOUD_SNAPSHOT_REF_PREFIX} + base64url(JSON
+ *   {machineId, ref, allowedDomains?}): the machine id lets destroy-by-ref
+ *   reap a still-running source, and the allowlist is what a bare resume
+ *   re-applies (the wire inherits nothing).
+ * - `machine.stop()` = destroy: Cloud has no pause — with artifacts
+ *   surviving the machine, snapshot-then-destroy IS the sleep semantics
+ *   (exactly the machine-lifecycle flow), and previously minted refs stay
+ *   valid through it (the seam law).
+ * - `adapter.destroy(ref)` = best-effort reap of the recorded source
+ *   machine, then artifact GC.
+ *
+ * Lifecycle interaction: Vendo auto-sleeps an idle machine after 5 minutes
+ * (snapshot → destroy); Cloud independently sweeps at 10 minutes idle and
+ * 24 hours max age. Our sleep normally wins; when the Cloud sweep gets
+ * there first the next wake resumes from the last stored ref, losing at
+ * most scratch state since it — acceptable, because the data rule keeps
+ * anything durable in the Vendo store, never on the VM disk.
+ */
+/** The console mounts the managed-sandbox surface here
+ * (apps/console/app/api/v1/sandboxes/*). */
+export const CLOUD_SANDBOX_PATH = "/api/v1/sandboxes";
+/** Snapshot-artifact GC route (under {@link CLOUD_SANDBOX_PATH}). */
+export const CLOUD_SNAPSHOTS_SUBPATH = "/snapshots";
+/** Adapter-minted snapshot refs: this prefix + base64url(JSON state).
+ * These are what the seam (and app documents) carry. */
+export const CLOUD_SNAPSHOT_REF_PREFIX = "vendo:v2:";
+/** Console-minted artifact refs (`vendo:snap_<40hex>`) — carried INSIDE the
+ * adapter's composite ref, never handed to the seam bare. */
+export const CONSOLE_SNAPSHOT_REF_PREFIX = "vendo:";
+/** The canonical box port the relay targets when no port rides the wire
+ * (and the one the public ingress `https://<id-suffix>-m.vendo.run`
+ * serves). */
+export const CLOUD_BOX_PORT = 8080;

package/dist/sandbox.d.ts

@@ -0,0 +1,38 @@
+import type { SandboxAdapter } from "@vendoai/apps";
+export interface CloudSandboxOptions {
+    apiKey: string;
+    /** Defaults to the Vendo console; the composition seam passes VENDO_CLOUD_URL. */
+    baseUrl?: string;
+    /** Per-request abort timeout, in milliseconds. */
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}
+/** The Cloud sandbox adapter — the OSS side of the managed-sandbox seam: the
+ * execution-v2 SandboxAdapter speaking HTTP to the console's /api/v1/sandboxes
+ * routes (Vendo's pooled provider capacity, metered as sandbox_minutes). The
+ * wire contract — the ARTIFACT model, verified live — lives in
+ * sandbox-wire.ts. Cloned from cloudConnections' shape: behavior comes ONLY
+ * from constructor arguments (adapter rule — see selectSandbox in server.ts);
+ * the adapter never reads the environment.
+ *
+ * Provider particulars, versus the e2b reference port:
+ * - Snapshots are persistent artifacts that survive the machine; resume
+ *   boots a NEW machine from one (fork when the source lives, wake when it
+ *   is gone) and inherits NO network config, so every resume sends the
+ *   applicable allowlist explicitly — the ref-recorded one bare, the
+ *   caller's SandboxResumePolicy when a wake re-polices (Lane E replace
+ *   semantics, native on the wire).
+ * - stop() destroys the machine: Cloud has no pause, and with artifacts
+ *   surviving it, snapshot-then-destroy IS the sleep semantics; previously
+ *   minted refs stay valid through it (the seam law).
+ * - Composite refs: the seam sees `vendo:v2:<base64url state>` carrying the
+ *   console artifact ref, the source machine id (destroy-by-ref reaps a
+ *   still-running source best-effort before the artifact GC), and the
+ *   snapshot-time allowlist a bare resume re-applies.
+ * - `spec.template` is dropped from the wire: the create route takes none —
+ *   the pooled base image (Node + the in-box agent) is Cloud's own.
+ *
+ * The machine object also carries adapter-private exec/files/url used for
+ * live-lane bootstrap and diagnostics — NOT part of the public seam (the
+ * in-box agent owns the inside of the box). */
+export declare function cloudSandbox(options: CloudSandboxOptions): SandboxAdapter;