@telorun/runner-core 0.5.2

package/LICENSE

@@ -0,0 +1,17 @@
+# SUSTAINABLE USE LICENSE (Fair-code)
+
+Copyright (c) 2026 CodeNet Sp. z o.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to use, copy, modify, and distribute the Software for any purpose—including commercial purposes—subject to the following conditions:
+
+1. ANTI-COMPETITION RESTRICTION: The Software may not be provided to third parties as a managed service, commercial SaaS (Software-as-a-Service), PaaS (Platform-as-a-Service), BaaS (Backend-as-a-Service), or similar offering where the primary value provided to the user is the functionality of the Software itself, without a separate commercial license from the copyright holder.
+
+2. PERMITTED COMMERCIAL USE: You are free to use the Software to build, host, and monetize your own commercial applications, products, and services, provided such use does not violate Clause 1.
+
+3. ATTRIBUTION: This copyright notice and license must be included in all copies or substantial portions of the Software.
+
+4. CONTRIBUTIONS: Contributions to the Software are welcome and encouraged. By contributing, you agree that your contributions may be incorporated into the Software and distributed under this license.
+
+5. DISCLAIMER: The Software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the Software or the use or other dealings in the Software.
+
+For commercial licensing, managed hosting exemptions, or enterprise inquiries, please contact <contact@codenet.pl>.

package/README.md

@@ -0,0 +1,38 @@
+# @telorun/runner-core
+
+Backend-neutral core shared by the Telo runners ([`docker-runner`](../../apps/docker-runner)
+and [`k8s-runner`](../../apps/k8s-runner)). It owns everything about a run
+*except* how the workload is actually spawned:
+
+- the `/v1` HTTP+SSE **session contract** and Fastify routes (`/v1/health`,
+  `/v1/probe`, `/v1/sessions`, `/v1/sessions/:id/events` SSE,
+  `/v1/sessions/:id/io` WebSocket PTY);
+- the in-memory **session registry**, event/byte **ring buffers** (SSE + PTY
+  replay with gap detection), and bundle-path traversal guards;
+- graceful-shutdown helpers and base config parsing.
+
+## The seam: `RunnerBackend`
+
+Concrete runners implement a small abstract interface — a byte-stream out
+(`onOutput`), a stdin writer, a resize signal, and a wait/exit (`done`) — *not*
+any docker- or k8s-specific stream shape:
+
+```ts
+interface RunnerBackend {
+  probe(config): Promise<AvailabilityReport>;
+  start(spec): Promise<BackendSession>; // writeStdin / resize / done / stop
+  reapOrphans?(): Promise<void>;
+}
+```
+
+Bundle delivery is the backend's responsibility (docker writes a shared-volume
+workdir; k8s stages a tarball for an initContainer fetch), so `start` receives
+the raw `bundle` rather than a pre-resolved path. `buildServer({ backend, config,
+version })` wires a backend into the full `/v1` app.
+
+## Development
+
+```bash
+pnpm --filter @telorun/runner-core build
+pnpm --filter @telorun/runner-core test
+```

package/dist/backend.d.ts

@@ -0,0 +1,71 @@
+import type { DebugFrame } from "@telorun/debug-wire";
+import type { AvailabilityReport, PortMapping, ProbeConfig, RunBundle, RunPhase, RunStatus, SessionConfig } from "./contract.js";
+/**
+ * The seam between backend-neutral session machinery (routes, registry, SSE)
+ * and a concrete workload runtime (docker container, kubernetes pod).
+ *
+ * Deliberately abstract: a byte-stream out (`onOutput`), a stdin writer
+ * (`BackendSession.writeStdin`), a resize signal, and a wait/exit (`done`) —
+ * NOT docker's `ReadWriteStream` duplex. The k8s backend serves the same shape
+ * over the Pod `attach` subresource; the docker backend adapts its hijacked
+ * attach duplex onto it. Bundle delivery is the backend's responsibility too
+ * (docker writes a shared-volume workdir; k8s stages the bundle for an
+ * initContainer fetch), so the spec carries the raw `bundle` rather than a
+ * pre-resolved on-disk path.
+ */
+export interface RunnerBackend {
+    /** Report readiness without starting a session (daemon/cluster reachable,
+     *  image pullable, scaffolding present). Backs `POST /v1/probe`. */
+    probe(config: ProbeConfig): Promise<AvailabilityReport>;
+    /** Spawn the workload and wire it to the supplied callbacks. Resolves once
+     *  the workload has started (after a `running` status is emitted); rejects
+     *  with `SessionStartError` for any pre-start failure. */
+    start(spec: BackendStartSpec): Promise<BackendSession>;
+    /** Reap workloads orphaned by a prior runner process, matched by the
+     *  backend's own labelling. Run once at boot — the session registry is
+     *  in-memory, so a restart otherwise leaks running workloads. */
+    reapOrphans?(): Promise<void>;
+}
+export interface BackendStartSpec {
+    sessionId: string;
+    bundle: RunBundle;
+    /** Bundle-relative entry path, already traversal-normalized by core. */
+    entryRelativePath: string;
+    env: Record<string, string>;
+    ports: PortMapping[];
+    config: SessionConfig;
+    /** When true, launch the workload with `--inspect` and relay its kernel debug
+     *  stream via `onDebug`. The inspect endpoint stays reachable only by the
+     *  runner — never published outward. */
+    inspect: boolean;
+    /** Emit a lifecycle status. The backend drives `starting` → `running` →
+     *  terminal (`exited`/`failed`/`stopped`). */
+    onStatus(status: RunStatus): void;
+    /** Emit a progress message for a coming-up phase (build / provision / boot).
+     *  Additive to status — surfaces what's happening while the session is still
+     *  `starting`, driving the editor's spinner + step feed. */
+    onProgress(phase: RunPhase, message: string, done?: boolean): void;
+    /** Raw merged stdout/stderr (PTY) bytes from the workload. */
+    onOutput(chunk: Buffer): void;
+    /** A frame relayed from the workload's kernel debug stream. Only called when
+     *  `inspect` is true and the backend has connected to the inspect endpoint. */
+    onDebug(frame: DebugFrame): void;
+    /** True once a user stop / shutdown has been requested — lets the backend
+     *  classify a kill as `stopped` rather than `failed`. */
+    isUserStopped(): boolean;
+}
+export interface BackendSession {
+    /** Write bytes to the workload's stdin (PTY). A no-op once the workload has
+     *  terminated, so callers need not track liveness. */
+    writeStdin(bytes: Uint8Array): void;
+    /** Resize the workload's PTY. */
+    resize(cols: number, rows: number): void;
+    /** Resolves after the workload terminates and its terminal status has been
+     *  emitted via `onStatus`. Never rejects — terminal failures surface as a
+     *  `failed` status. */
+    readonly done: Promise<void>;
+    /** Force-stop the workload. Idempotent and safe to call after natural exit
+     *  (a backend should treat an already-gone workload as a no-op). */
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EACX,WAAW,EACX,SAAS,EACT,QAAQ,EACR,SAAS,EACT,aAAa,EACd,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B;wEACoE;IACpE,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAExD;;8DAE0D;IAC1D,KAAK,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAEvD;;qEAEiE;IACjE,WAAW,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,CAAC;IAClB,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB;;4CAEwC;IACxC,OAAO,EAAE,OAAO,CAAC;IAEjB;kDAC8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAClC;;gEAE4D;IAC5D,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACnE,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;mFAC+E;IAC/E,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC;6DACyD;IACzD,aAAa,IAAI,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B;0DACsD;IACtD,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAEpC,iCAAiC;IACjC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzC;;2BAEuB;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;wEACoE;IACpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB"}

package/dist/backend.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=backend.js.map

package/dist/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":""}

package/dist/base-image-catalog.d.ts

@@ -0,0 +1,110 @@
+/**
+ * A base-image catalog backed by the Docker Hub repository-tags API. A runner
+ * advertises the resolved tag list as an `enum` on its session `image` field so
+ * the editor renders a base-image picker, and validates a chosen image against
+ * the same list server-side — the runner is the source of truth, so a non-editor
+ * client can't widen the allowed set.
+ *
+ * The list is fetched at startup and on a refresh interval, cached in memory,
+ * and degrades gracefully: when Docker Hub is unreachable the catalog still
+ * serves the configured default (always present), so the runner boots and a
+ * session can still start on the default image.
+ *
+ * Free of runner specifics — it takes only a repository, a default ref, and a
+ * tag filter — but the tag source is specifically Docker Hub's registry API
+ * (`hub.docker.com/v2`); a base on another registry (GHCR, a private registry)
+ * can't be enumerated or digest-resolved here. The Docker registry the kubelet
+ * pulls from is a separate concern; this resolves the *menu* of base images, not
+ * pull auth.
+ */
+/** A composable predicate set narrowing a repository's tag list to the offered
+ *  menu. Named flags cover the common cases; `include`/`exclude` are the regex
+ *  escape hatch for everything else. */
+export interface TagFilter {
+    /** Keep only `MAJOR.MINOR.PATCH[-variant]` tags — drops moving tags (`latest`,
+     *  `0`, `0.30`) and their variants (`latest-slim`, `0-slim`). */
+    pinnedOnly?: boolean;
+    /** Drop commit-hash tags (`sha-<hex>` or a bare hex string). */
+    excludeSha?: boolean;
+    /** Drop semver prereleases (`0.30.1-rc.1`, `…-alpha`). Variant suffixes like
+     *  `-slim` / `-rust-1.95.0` are NOT prereleases and are kept. */
+    excludePrerelease?: boolean;
+    /** A tag must match at least one of these to be kept. */
+    include?: RegExp[];
+    /** A tag matching any of these is dropped. */
+    exclude?: RegExp[];
+}
+export interface BaseImageCatalogOptions {
+    /** `namespace/repository`, e.g. `telorun/node`. */
+    repository: string;
+    /** Always-present default ref — the pre-selected option and the
+     *  Docker-Hub-unreachable fallback, e.g. `telorun/node:latest-slim`. */
+    defaultRef: string;
+    filter?: TagFilter;
+    /** Cap the advertised list to this many tags (newest first). Default 20. */
+    limit?: number;
+    /** Background refresh cadence in ms. Default 1h. */
+    refreshIntervalMs?: number;
+    /** Upper bound on tags pulled from Docker Hub before filtering. Default 200. */
+    maxTagsScanned?: number;
+    /** Per-request timeout for a Docker Hub call, in ms. Default 10s. */
+    requestTimeoutMs?: number;
+    /** Injectable fetch for tests; defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/** Apply a {@link TagFilter} to a tag list, preserving input order. Pure — the
+ *  unit-testable core of the catalog. */
+export declare function filterTags(tags: string[], filter?: TagFilter): string[];
+/**
+ * Parse a Docker image reference into the Docker Hub coordinates needed to look
+ * up its digest, or `null` when the ref points at a non-Docker-Hub registry.
+ * Handles the `library/` shorthand, optional `docker.io` host, and an already
+ * `@sha256:`-pinned digest (carried through verbatim).
+ */
+export declare function parseDockerHubRef(ref: string): {
+    namespace: string;
+    repo: string;
+    tag: string;
+    digest?: string;
+} | null;
+/**
+ * Resolve a Docker Hub image ref's CURRENT manifest digest. A moving tag
+ * (`latest-slim`) maps to a new digest once a new version is published, so a
+ * build that folds this into its cache key detects that the base moved and
+ * rebuilds. An already `@sha256:`-pinned ref returns its digest without a
+ * network call. Returns `undefined` for a non-Docker-Hub ref (not an error —
+ * resolution simply doesn't apply) or when a Hub request fails. A genuine
+ * request failure is reported to `onError` rather than swallowed, so an operator
+ * whose Hub calls persistently fail (auth / network / rate-limit) gets a signal
+ * instead of an unexplained "always reuses the cached image".
+ */
+export declare function resolveTagDigest(ref: string, opts?: {
+    fetchImpl?: typeof fetch;
+    requestTimeoutMs?: number;
+    onError?: (err: unknown) => void;
+}): Promise<string | undefined>;
+export declare class BaseImageCatalog {
+    private readonly repository;
+    private readonly defaultRef;
+    private readonly filter;
+    private readonly limit;
+    private readonly refreshIntervalMs;
+    private readonly maxTagsScanned;
+    private readonly requestTimeoutMs;
+    private readonly fetchImpl;
+    /** Filtered tags (bare, newest first); empty until the first refresh. */
+    private tags;
+    private timer?;
+    constructor(opts: BaseImageCatalogOptions);
+    /** The advertised image refs: the default first, then the filtered tags. */
+    current(): string[];
+    /** Whether `ref` is offered by this catalog (server-side allowlist check). */
+    isAllowed(ref: string): boolean;
+    /** Refetch and re-filter the tag list. Throws on a fetch/HTTP failure. */
+    refresh(): Promise<void>;
+    /** Begin periodic background refresh. Refresh failures are surfaced to
+     *  `onError` rather than swallowed; the last good list keeps serving. */
+    start(onError?: (err: unknown) => void): void;
+    stop(): void;
+}
+//# sourceMappingURL=base-image-catalog.d.ts.map

package/dist/base-image-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-image-catalog.d.ts","sourceRoot":"","sources":["../src/base-image-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;wCAEwC;AACxC,MAAM,WAAW,SAAS;IACxB;qEACiE;IACjE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gEAAgE;IAChE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;qEACiE;IACjE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB;4EACwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AA+BD;yCACyC;AACzC,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,GAAE,SAAc,GAAG,MAAM,EAAE,CAW3E;AAoED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,GACV;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAoC1E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE;IACJ,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7B,GACL,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAwB7B;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,yEAAyE;IACzE,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,KAAK,CAAC,CAAiC;gBAEnC,IAAI,EAAE,uBAAuB;IAWzC,4EAA4E;IAC5E,OAAO,IAAI,MAAM,EAAE;IAKnB,8EAA8E;IAC9E,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI/B,0EAA0E;IACpE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B;6EACyE;IACzE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI;IAQ7C,IAAI,IAAI,IAAI;CAMb"}

package/dist/base-image-catalog.js

@@ -0,0 +1,245 @@
+/**
+ * A base-image catalog backed by the Docker Hub repository-tags API. A runner
+ * advertises the resolved tag list as an `enum` on its session `image` field so
+ * the editor renders a base-image picker, and validates a chosen image against
+ * the same list server-side — the runner is the source of truth, so a non-editor
+ * client can't widen the allowed set.
+ *
+ * The list is fetched at startup and on a refresh interval, cached in memory,
+ * and degrades gracefully: when Docker Hub is unreachable the catalog still
+ * serves the configured default (always present), so the runner boots and a
+ * session can still start on the default image.
+ *
+ * Free of runner specifics — it takes only a repository, a default ref, and a
+ * tag filter — but the tag source is specifically Docker Hub's registry API
+ * (`hub.docker.com/v2`); a base on another registry (GHCR, a private registry)
+ * can't be enumerated or digest-resolved here. The Docker registry the kubelet
+ * pulls from is a separate concern; this resolves the *menu* of base images, not
+ * pull auth.
+ */
+const SHA_TAG = /^(?:sha-)?[0-9a-f]{7,}$/i;
+const PINNED_TAG = /^\d+\.\d+\.\d+(?:[-.].*)?$/;
+const PRERELEASE_CORE = /^\d+\.\d+\.\d+-(.+)$/;
+/** First `-` identifier on a pinned tag that marks it a prerelease rather than a
+ *  build variant (`-slim`, `-rust-*`). */
+const PRERELEASE_TOKENS = new Set([
+    "rc",
+    "alpha",
+    "beta",
+    "pre",
+    "preview",
+    "next",
+    "canary",
+    "dev",
+    "nightly",
+    "snapshot",
+]);
+function isShaTag(tag) {
+    return SHA_TAG.test(tag);
+}
+function isPrerelease(tag) {
+    const m = PRERELEASE_CORE.exec(tag);
+    if (!m)
+        return false;
+    const firstId = m[1].split(/[-.]/, 1)[0].toLowerCase();
+    return PRERELEASE_TOKENS.has(firstId);
+}
+/** Apply a {@link TagFilter} to a tag list, preserving input order. Pure — the
+ *  unit-testable core of the catalog. */
+export function filterTags(tags, filter = {}) {
+    return tags.filter((tag) => {
+        if (filter.excludeSha && isShaTag(tag))
+            return false;
+        if (filter.pinnedOnly && !PINNED_TAG.test(tag))
+            return false;
+        if (filter.excludePrerelease && isPrerelease(tag))
+            return false;
+        if (filter.include && filter.include.length > 0 && !filter.include.some((re) => re.test(tag))) {
+            return false;
+        }
+        if (filter.exclude && filter.exclude.some((re) => re.test(tag)))
+            return false;
+        return true;
+    });
+}
+function splitRepository(repository) {
+    const slash = repository.indexOf("/");
+    // A bare name (no slash) is a Docker official image under `library/`.
+    if (slash < 0)
+        return ["library", repository];
+    return [repository.slice(0, slash), repository.slice(slash + 1)];
+}
+function unique(refs) {
+    const seen = new Set();
+    const out = [];
+    for (const ref of refs) {
+        if (!seen.has(ref)) {
+            seen.add(ref);
+            out.push(ref);
+        }
+    }
+    return out;
+}
+/**
+ * Fetch a repository's tags from Docker Hub, newest first, bounded by
+ * `maxTagsScanned`. Paginates the `/v2/repositories/{ns}/{repo}/tags` endpoint
+ * and sorts by `last_updated` descending so the cap keeps the most recent tags
+ * regardless of the API's page ordering. Throws on a network/HTTP error — the
+ * caller decides whether a failure degrades to default-only.
+ */
+async function fetchRepoTags(repository, maxTagsScanned, requestTimeoutMs, fetchImpl) {
+    const [namespace, repo] = splitRepository(repository);
+    const collected = [];
+    let url = `https://hub.docker.com/v2/repositories/${encodeURIComponent(namespace)}/` +
+        `${encodeURIComponent(repo)}/tags?page_size=100`;
+    while (url && collected.length < maxTagsScanned) {
+        const res = await fetchImpl(url, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(requestTimeoutMs),
+        });
+        if (!res.ok) {
+            throw new Error(`Docker Hub tags request for '${repository}' failed: ${res.status} ${res.statusText}`);
+        }
+        const body = (await res.json());
+        for (const r of body.results ?? []) {
+            if (typeof r.name === "string") {
+                collected.push({ name: r.name, lastUpdated: r.last_updated ?? "" });
+            }
+        }
+        url = body.next ?? null;
+    }
+    collected.sort((a, b) => a.lastUpdated < b.lastUpdated ? 1 : a.lastUpdated > b.lastUpdated ? -1 : 0);
+    return collected.map((c) => c.name);
+}
+/**
+ * Parse a Docker image reference into the Docker Hub coordinates needed to look
+ * up its digest, or `null` when the ref points at a non-Docker-Hub registry.
+ * Handles the `library/` shorthand, optional `docker.io` host, and an already
+ * `@sha256:`-pinned digest (carried through verbatim).
+ */
+export function parseDockerHubRef(ref) {
+    let rest = ref;
+    let digest;
+    const at = ref.indexOf("@");
+    if (at >= 0) {
+        digest = ref.slice(at + 1);
+        rest = ref.slice(0, at);
+    }
+    // A first path segment with a `.`/`:` (or `localhost`) is a registry host.
+    const firstSlash = rest.indexOf("/");
+    const firstPart = firstSlash >= 0 ? rest.slice(0, firstSlash) : "";
+    if (firstPart.includes(".") || firstPart.includes(":") || firstPart === "localhost") {
+        const hubHosts = new Set(["docker.io", "index.docker.io", "registry-1.docker.io"]);
+        if (!hubHosts.has(firstPart))
+            return null;
+        rest = rest.slice(firstSlash + 1);
+    }
+    // `rest` is now `name[:tag]`; the tag is the segment after a colon that isn't
+    // inside the path (i.e. after the last `/`).
+    const lastColon = rest.lastIndexOf(":");
+    const lastSlash = rest.lastIndexOf("/");
+    let name = rest;
+    let tag = "latest";
+    if (lastColon > lastSlash) {
+        name = rest.slice(0, lastColon);
+        tag = rest.slice(lastColon + 1);
+    }
+    const slash = name.indexOf("/");
+    return {
+        namespace: slash >= 0 ? name.slice(0, slash) : "library",
+        repo: slash >= 0 ? name.slice(slash + 1) : name,
+        tag,
+        digest,
+    };
+}
+/**
+ * Resolve a Docker Hub image ref's CURRENT manifest digest. A moving tag
+ * (`latest-slim`) maps to a new digest once a new version is published, so a
+ * build that folds this into its cache key detects that the base moved and
+ * rebuilds. An already `@sha256:`-pinned ref returns its digest without a
+ * network call. Returns `undefined` for a non-Docker-Hub ref (not an error —
+ * resolution simply doesn't apply) or when a Hub request fails. A genuine
+ * request failure is reported to `onError` rather than swallowed, so an operator
+ * whose Hub calls persistently fail (auth / network / rate-limit) gets a signal
+ * instead of an unexplained "always reuses the cached image".
+ */
+export async function resolveTagDigest(ref, opts = {}) {
+    const parsed = parseDockerHubRef(ref);
+    if (!parsed)
+        return undefined;
+    if (parsed.digest)
+        return parsed.digest;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const url = `https://hub.docker.com/v2/repositories/${encodeURIComponent(parsed.namespace)}/` +
+        `${encodeURIComponent(parsed.repo)}/tags/${encodeURIComponent(parsed.tag)}`;
+    try {
+        const res = await fetchImpl(url, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(opts.requestTimeoutMs ?? 10_000),
+        });
+        if (!res.ok) {
+            opts.onError?.(new Error(`Docker Hub tag request for '${ref}' failed: ${res.status} ${res.statusText}`));
+            return undefined;
+        }
+        const body = (await res.json());
+        return body.digest ?? body.images?.find((i) => i.digest)?.digest ?? undefined;
+    }
+    catch (err) {
+        opts.onError?.(err);
+        return undefined;
+    }
+}
+export class BaseImageCatalog {
+    repository;
+    defaultRef;
+    filter;
+    limit;
+    refreshIntervalMs;
+    maxTagsScanned;
+    requestTimeoutMs;
+    fetchImpl;
+    /** Filtered tags (bare, newest first); empty until the first refresh. */
+    tags = [];
+    timer;
+    constructor(opts) {
+        this.repository = opts.repository;
+        this.defaultRef = opts.defaultRef;
+        this.filter = opts.filter ?? {};
+        this.limit = opts.limit ?? 20;
+        this.refreshIntervalMs = opts.refreshIntervalMs ?? 60 * 60 * 1000;
+        this.maxTagsScanned = opts.maxTagsScanned ?? 200;
+        this.requestTimeoutMs = opts.requestTimeoutMs ?? 10_000;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    /** The advertised image refs: the default first, then the filtered tags. */
+    current() {
+        const refs = this.tags.map((tag) => `${this.repository}:${tag}`);
+        return unique([this.defaultRef, ...refs]);
+    }
+    /** Whether `ref` is offered by this catalog (server-side allowlist check). */
+    isAllowed(ref) {
+        return this.current().includes(ref);
+    }
+    /** Refetch and re-filter the tag list. Throws on a fetch/HTTP failure. */
+    async refresh() {
+        const tags = await fetchRepoTags(this.repository, this.maxTagsScanned, this.requestTimeoutMs, this.fetchImpl);
+        this.tags = filterTags(tags, this.filter).slice(0, this.limit);
+    }
+    /** Begin periodic background refresh. Refresh failures are surfaced to
+     *  `onError` rather than swallowed; the last good list keeps serving. */
+    start(onError) {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            this.refresh().catch((err) => onError?.(err));
+        }, this.refreshIntervalMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+    }
+}
+//# sourceMappingURL=base-image-catalog.js.map

package/dist/base-image-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-image-catalog.js","sourceRoot":"","sources":["../src/base-image-catalog.ts"],"names":[],"mappings":"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"}

package/dist/capabilities-schema.d.ts

@@ -0,0 +1,33 @@
+import type { JsonSchema, PullPolicy } from "./contract.js";
+export interface SessionConfigSchemaOptions {
+    /** Default container image; becomes the field's advertised `default`. */
+    imageDefault: string;
+    /** When set (and non-empty), constrains `image` to this allowlist — advertised
+     *  as a JSON Schema `enum` so the editor renders a base-image picker. The
+     *  picker is editable within the list, so an `imageEnum` overrides `enforced`
+     *  for the `image` field (a one-entry enum is effectively locked anyway). */
+    imageEnum?: string[];
+    /** Default pull policy (defaults to `missing`). */
+    pullPolicyDefault?: PullPolicy;
+    /** Override the `pullPolicy` field description. `pullPolicy` semantics differ
+     *  per backend (docker: container pull policy; k8s: base-image build
+     *  freshness), so each runner can supply wording that matches its behaviour. */
+    pullPolicyDescription?: string;
+    /** When true, `image` is server-enforced — advertised `readOnly` (locked to
+     *  `imageDefault`) so the editor renders it disabled but still sends it. No
+     *  effect once `imageEnum` is set (the picker is the constraint). `pullPolicy`
+     *  is always client-editable. */
+    enforced?: boolean;
+    /** Include the optional `registryUrl` field (a runner that forwards a module
+     *  registry URL to its workloads). */
+    registryUrl?: boolean;
+}
+/**
+ * Builds the JSON Schema a runner advertises on `/v1/capabilities` for the
+ * editable `SessionConfig` surface. `baseUrl` is deliberately absent — the
+ * client owns it. Server-enforced runners pass `enforced: true` to lock `image`
+ * as `readOnly` (the value still travels on the wire); `pullPolicy` is always
+ * client-editable.
+ */
+export declare function sessionConfigSchema(opts: SessionConfigSchemaOptions): JsonSchema;
+//# sourceMappingURL=capabilities-schema.d.ts.map

package/dist/capabilities-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities-schema.d.ts","sourceRoot":"","sources":["../src/capabilities-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE5D,MAAM,WAAW,0BAA0B;IACzC,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB;;;iFAG6E;IAC7E,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,UAAU,CAAC;IAC/B;;oFAEgF;IAChF,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B;;;qCAGiC;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;0CACsC;IACtC,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,0BAA0B,GAAG,UAAU,CAqChF"}

package/dist/capabilities-schema.js

@@ -0,0 +1,44 @@
+/**
+ * Builds the JSON Schema a runner advertises on `/v1/capabilities` for the
+ * editable `SessionConfig` surface. `baseUrl` is deliberately absent — the
+ * client owns it. Server-enforced runners pass `enforced: true` to lock `image`
+ * as `readOnly` (the value still travels on the wire); `pullPolicy` is always
+ * client-editable.
+ */
+export function sessionConfigSchema(opts) {
+    const readOnly = opts.enforced === true;
+    const hasEnum = Array.isArray(opts.imageEnum) && opts.imageEnum.length > 0;
+    const properties = {
+        image: {
+            type: "string",
+            minLength: 1,
+            default: opts.imageDefault,
+            title: "Image",
+            description: "Container image the runner spawns for each run.",
+            // An allowlist renders as an editable picker; otherwise fall back to the
+            // enforced (readOnly) single value.
+            ...(hasEnum ? { enum: opts.imageEnum } : readOnly ? { readOnly: true } : {}),
+        },
+        pullPolicy: {
+            type: "string",
+            enum: ["missing", "always", "never"],
+            default: opts.pullPolicyDefault ?? "missing",
+            title: "Pull policy",
+            description: opts.pullPolicyDescription ??
+                "`missing` pulls on first use; `always` forces a pull every run; `never` fails if the image isn't present.",
+        },
+    };
+    if (opts.registryUrl) {
+        properties.registryUrl = {
+            type: "string",
+            title: "Registry URL",
+            description: "Optional base URL for the telo module registry, forwarded to the runner as TELO_REGISTRY_URL. Leave blank for the default registry.",
+        };
+    }
+    return {
+        type: "object",
+        required: ["image", "pullPolicy"],
+        properties,
+    };
+}
+//# sourceMappingURL=capabilities-schema.js.map

package/dist/capabilities-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities-schema.js","sourceRoot":"","sources":["../src/capabilities-schema.ts"],"names":[],"mappings":"AA0BA;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAgC;IAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC;IACxC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IAC3E,MAAM,UAAU,GAA+B;QAC7C,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,SAAS,EAAE,CAAC;YACZ,OAAO,EAAE,IAAI,CAAC,YAAY;YAC1B,KAAK,EAAE,OAAO;YACd,WAAW,EAAE,iDAAiD;YAC9D,yEAAyE;YACzE,oCAAoC;YACpC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7E;QACD,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC;YACpC,OAAO,EAAE,IAAI,CAAC,iBAAiB,IAAI,SAAS;YAC5C,KAAK,EAAE,aAAa;YACpB,WAAW,EACT,IAAI,CAAC,qBAAqB;gBAC1B,2GAA2G;SAC9G;KACF,CAAC;IACF,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,UAAU,CAAC,WAAW,GAAG;YACvB,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,cAAc;YACrB,WAAW,EACT,qIAAqI;SACxI,CAAC;IACJ,CAAC;IACD,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC;QACjC,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,37 @@
+import type { RunnerTerms } from "./contract.js";
+/**
+ * Backend-neutral runner configuration. Concrete runners (docker, k8s) extend
+ * `RunnerCoreConfig` with their own fields and reuse these parse helpers so
+ * config validation and error reporting stay identical across backends.
+ */
+export interface RunnerCoreConfig {
+    port: number;
+    logLevel: string;
+    maxSessions: number;
+    exitTtlMs: number;
+    replayBufferBytes: number;
+    corsOrigins: string[] | "*";
+}
+export declare class RunnerConfigError extends Error {
+}
+export declare function parsePositiveInt(raw: string | undefined, fallback: number, field: string): number;
+export declare function parseBool(raw: string | undefined, fallback: boolean, field: string): boolean;
+export declare function parsePort(raw: string | undefined, fallback: number): number;
+/**
+ * Build the runner's usage terms from the environment. Terms are opt-in: returns
+ * `undefined` (no gate) unless a non-empty body is provided.
+ *
+ * The body comes from `RUNNER_TERMS_FILE` (a path read at startup — the natural
+ * fit for a k8s ConfigMap mount or a bind-mounted file) or, for short notes,
+ * inline `RUNNER_TERMS_BODY`. `RUNNER_TERMS_VERSION` is optional and defaults to
+ * a short hash of the body, so editing the agreement automatically re-prompts
+ * every client; set it explicitly only to control "material change vs. typo".
+ * A configured-but-unreadable `RUNNER_TERMS_FILE` is a hard error rather than a
+ * silent "no terms", so a misconfiguration can't quietly drop the gate.
+ */
+export declare function loadTermsFromEnv(env: NodeJS.ProcessEnv): RunnerTerms | undefined;
+export declare function parseCorsOrigins(raw: string | undefined): string[] | "*";
+export declare function loadCoreConfig(env: NodeJS.ProcessEnv, defaults?: {
+    port?: number;
+}): RunnerCoreConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;CAC7B;AAED,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAE/C,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,MAAM,CAOR;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAM5F;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,WAAW,GAAG,SAAS,CAQhF;AAsBD,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,GAAG,CAMxE;AAED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,QAAQ,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,gBAAgB,CAiBlB"}