@telorun/runner-core 0.5.2

package/src/contract.ts

@@ -0,0 +1,170 @@
+/**
+ * The backend-neutral `/v1` session contract. Every field here is shared by
+ * the docker and kubernetes backends and travels over the HTTP+SSE wire to the
+ * editor adapter. Backend-specific concerns (how a container/pod is spawned,
+ * how the bundle is delivered) live behind the `RunnerBackend` interface.
+ */
+
+import type { DebugFrame } from "@telorun/debug-wire";
+
+export type PullPolicy = "missing" | "always" | "never";
+
+/**
+ * What a runner advertises about itself on `GET /v1/capabilities`. The editor
+ * fetches this to render a generic runner config form — instead of hardcoding
+ * per-backend fields — so the runner is the authority on its own config surface.
+ * `config.schema` is a JSON Schema describing the editable `SessionConfig` fields
+ * (each property carries its own `default`); server-enforced fields are marked
+ * `readOnly` with the enforced value as their `default`. `baseUrl` is never in
+ * this schema — the client owns it (you need it to reach the runner).
+ */
+export interface RunnerCapabilities {
+  displayName: string;
+  description: string;
+  config: { schema: JsonSchema };
+  features: RunnerFeatures;
+  /** A usage agreement the operator requires before a session may start.
+   *  Omitted (or undefined) when this runner has no terms — e.g. a local
+   *  development runner. The runner ENFORCES it: `POST /v1/sessions` is rejected
+   *  with `428 terms_required` unless the client sends `x-telo-accepted-terms`
+   *  matching `terms.version`. The editor surfaces it and records acceptance. */
+  terms?: RunnerTerms;
+}
+
+/** An operator-defined agreement. `version` is opaque and operator-controlled;
+ *  bumping it re-prompts every client. `body` is plain text / markdown. */
+export interface RunnerTerms {
+  version: string;
+  title: string;
+  body: string;
+}
+
+/** HTTP header carrying the accepted terms version on `POST /v1/sessions`. */
+export const ACCEPTED_TERMS_HEADER = "x-telo-accepted-terms";
+
+export interface RunnerFeatures {
+  /** Runner exposes a live PTY byte channel (`/v1/sessions/:id/io`). */
+  io: boolean;
+  /** Runner can publish workload ports back to the client. */
+  ports: boolean;
+}
+
+/** A JSON Schema document, kept structurally open so runner-core need not depend
+ *  on a JSON-Schema type package. The editor treats it as `JSONSchema7`. */
+export type JsonSchema = Record<string, unknown>;
+
+export interface ProbeConfig {
+  image: string;
+  pullPolicy: PullPolicy;
+}
+
+export interface SessionConfig {
+  image: string;
+  pullPolicy: PullPolicy;
+  registryUrl?: string;
+}
+
+export interface ConfigIssue {
+  path: string;
+  message: string;
+}
+
+export type AvailabilityReport =
+  | { status: "ready" }
+  | { status: "needs-setup"; issues: ConfigIssue[] }
+  | { status: "unavailable"; message: string; remediation?: string };
+
+export interface RunBundle {
+  entryRelativePath: string;
+  files: Array<{ relativePath: string; contents: string }>;
+}
+
+export type PortProtocol = "tcp" | "udp";
+
+export interface PortMapping {
+  port: number;
+  protocol: PortProtocol;
+}
+
+/**
+ * Announced on `RunStatus.running`. `host`/`port` describe a directly-dialable
+ * endpoint (docker host-port publish); `url` carries a fully-qualified address
+ * for backends that front the workload with a proxy/ingress (k8s per-session
+ * ingress), where a bare host:port is not reachable. The client adapter fills an
+ * empty `host` from its own baseUrl — the runner does not know the hostname the
+ * client used to reach it.
+ */
+export interface RunnerEndpoint {
+  host: string;
+  port: number;
+  protocol: PortProtocol;
+  /** Fully-qualified URL when the endpoint is fronted by a proxy/ingress. */
+  url?: string;
+}
+
+export interface StartSessionRequest {
+  bundle: RunBundle;
+  env: Record<string, string>;
+  ports?: PortMapping[];
+  config: SessionConfig;
+  /** Request the kernel debug stream. When true the runner launches the
+   *  workload with `--inspect`, subscribes to the in-workload inspect endpoint
+   *  (reachable only by the runner — never published outward), and relays each
+   *  frame to the client as a `debug` {@link RunEvent}. */
+  inspect?: boolean;
+}
+
+export type RunStatus =
+  | { kind: "starting" }
+  /** `inspectUrl` is the kernel debug/inspection UI fronted by a proxy (set only
+   *  when the session ran with `inspect` and the runner has a public base URL);
+   *  absent when the inspect endpoint isn't externally reachable. */
+  | { kind: "running"; endpoints?: RunnerEndpoint[]; inspectUrl?: string }
+  | { kind: "exited"; code: number }
+  | { kind: "failed"; message: string }
+  | { kind: "stopped" };
+
+/**
+ * Coarse phase a session passes through while coming up, carried on `progress`
+ * events. Additive to the status enum: `RunStatus` stays `starting` until the
+ * workload is actually up; these messages drive the editor's spinner + step feed.
+ */
+export type RunPhase = "build" | "provision" | "boot";
+
+export type RunEvent =
+  | { type: "stdout"; chunk: string }
+  | { type: "stderr"; chunk: string }
+  | { type: "status"; status: RunStatus }
+  | { type: "progress"; phase: RunPhase; message: string; done?: boolean }
+  /** A frame relayed from the workload's kernel debug stream (kernel event or
+   *  log line). Only emitted when the session was started with `inspect`. */
+  | { type: "debug"; frame: DebugFrame };
+
+export function isTerminal(status: RunStatus): boolean {
+  return status.kind === "exited" || status.kind === "failed" || status.kind === "stopped";
+}
+
+/**
+ * Stages a session start can fail at. The docker/k8s backends share the
+ * vocabulary; not every stage applies to every backend (`pull`/`inspect` are
+ * image-availability stages, `create`/`attach`/`start` are workload stages).
+ */
+export type StartFailureStage =
+  | "pull"
+  | "inspect"
+  | "daemon"
+  | "create"
+  | "attach"
+  | "start";
+
+export class SessionStartError extends Error {
+  constructor(
+    public readonly kind: "pull_failed" | "start_failed",
+    public readonly stage: StartFailureStage,
+    message: string,
+    public readonly daemonMessage?: string,
+  ) {
+    super(message);
+    this.name = "SessionStartError";
+  }
+}

package/src/debug/relay.ts

@@ -0,0 +1,104 @@
+import type { DebugFrame } from "@telorun/debug-wire";
+
+export interface DebugRelayOptions {
+  /** The workload's inspect SSE endpoint, e.g. `http://telo-run-<id>:9230/events`.
+   *  Reachable only by the runner over the backend's private network. */
+  url: string;
+  /** Delivered each parsed frame off the stream. */
+  onFrame: (frame: DebugFrame) => void;
+  /** Aborts the relay (session ended). */
+  signal: AbortSignal;
+  /** Optional connect-retry budget. The workload's inspect server isn't up the
+   *  instant the container starts; we retry until it answers or `signal` aborts.
+   *  Default: retry indefinitely (until abort). */
+  onError?: (err: Error) => void;
+}
+
+const RECONNECT_DELAY_MS = 500;
+
+/**
+ * Subscribe to a workload's inspect SSE endpoint and deliver each frame to
+ * `onFrame`. Retries the connection until the endpoint answers or `signal`
+ * aborts, and reconnects if the stream drops while the session is still live.
+ * The runner relays these frames onward; the workload's inspect port is never
+ * exposed outside the runner.
+ *
+ * Backend-neutral (uses global `fetch`); the docker and k8s backends share it.
+ */
+export async function relayDebugStream(opts: DebugRelayOptions): Promise<void> {
+  const { url, onFrame, signal } = opts;
+  while (!signal.aborted) {
+    try {
+      const res = await fetch(url, {
+        signal,
+        headers: { accept: "text/event-stream" },
+      });
+      if (!res.ok || !res.body) {
+        await delay(RECONNECT_DELAY_MS, signal);
+        continue;
+      }
+      await pump(res.body, onFrame, signal);
+    } catch (err) {
+      if (signal.aborted) return;
+      opts.onError?.(err instanceof Error ? err : new Error(String(err)));
+    }
+    await delay(RECONNECT_DELAY_MS, signal);
+  }
+}
+
+async function pump(
+  body: ReadableStream<Uint8Array>,
+  onFrame: (frame: DebugFrame) => void,
+  signal: AbortSignal,
+): Promise<void> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  try {
+    while (!signal.aborted) {
+      const { value, done } = await reader.read();
+      if (done) return;
+      buf += decoder.decode(value, { stream: true });
+      let sep: number;
+      // SSE frames are separated by a blank line.
+      while ((sep = buf.indexOf("\n\n")) >= 0) {
+        const frame = parseSseData(buf.slice(0, sep));
+        buf = buf.slice(sep + 2);
+        if (frame) onFrame(frame);
+      }
+    }
+  } finally {
+    reader.cancel().catch(() => undefined);
+  }
+}
+
+/** Extract and parse the `data:` payload of one SSE frame. Ignores comment
+ *  lines (`: heartbeat`) and unparseable frames. */
+function parseSseData(block: string): DebugFrame | null {
+  const data = block
+    .split("\n")
+    .filter((line) => line.startsWith("data:"))
+    .map((line) => line.slice(5).trimStart())
+    .join("\n");
+  if (!data) return null;
+  try {
+    return JSON.parse(data) as DebugFrame;
+  } catch {
+    return null;
+  }
+}
+
+function delay(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal.aborted) return resolve();
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      resolve();
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/dependency-key.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+
+import type { RunBundle } from "./contract.js";
+import { extractDependencyKey } from "./dependency-key.js";
+
+function bundle(manifest: string, extra: RunBundle["files"] = []): RunBundle {
+  return {
+    entryRelativePath: "manifest.yaml",
+    files: [{ relativePath: "manifest.yaml", contents: manifest }, ...extra],
+  };
+}
+
+const APP = [
+  "kind: Telo.Application",
+  "metadata:",
+  "  name: app",
+  "imports:",
+  "  Console: std/console@0.9.0",
+  "  Http: std/http-server@1.2.0",
+  "---",
+  "kind: Telo.Definition",
+  "metadata:",
+  "  name: Thing",
+  "controllers:",
+  "  - pkg:npm/@acme/thing@1.0.0",
+  "",
+].join("\n");
+
+describe("extractDependencyKey", () => {
+  it("collects imports and body-declared controllers, sorted", () => {
+    const key = extractDependencyKey(bundle(APP));
+    expect(key.importSources).toEqual(["std/console@0.9.0", "std/http-server@1.2.0"]);
+    expect(key.controllerLocators).toEqual(["pkg:npm/@acme/thing@1.0.0"]);
+    expect(key.fullContentFallback).toBe(false);
+  });
+
+  it("reads the object form of an import entry", () => {
+    const m = APP.replace(
+      "  Console: std/console@0.9.0",
+      "  Console:\n    source: std/console@0.9.0\n    variables: { level: info }",
+    );
+    expect(extractDependencyKey(bundle(m)).importSources).toContain("std/console@0.9.0");
+  });
+
+  it("flags local_path controllers for full-content fallback", () => {
+    const m = APP.replace(
+      "  - pkg:npm/@acme/thing@1.0.0",
+      "  - pkg:npm/@acme/thing@1.0.0\nlocal_path: ./thing",
+    );
+    expect(extractDependencyKey(bundle(m)).fullContentFallback).toBe(true);
+  });
+
+  it("flags an unparseable file for full-content fallback", () => {
+    const key = extractDependencyKey(bundle(APP, [{ relativePath: "broken.yaml", contents: "a: b: c: :\n  - [" }]));
+    expect(key.fullContentFallback).toBe(true);
+  });
+
+  it("returns empty sets for a manifest with no imports or controllers", () => {
+    const key = extractDependencyKey(bundle("kind: Telo.Application\nmetadata:\n  name: bare\n"));
+    expect(key.importSources).toEqual([]);
+    expect(key.controllerLocators).toEqual([]);
+    expect(key.fullContentFallback).toBe(false);
+  });
+});

package/src/dependency-key.ts

@@ -0,0 +1,105 @@
+import { parseAllDocuments } from "yaml";
+
+import type { RunBundle } from "./contract.js";
+
+/**
+ * The inputs that determine a session's baked dependency layer — everything
+ * `telo install` would resolve into `.telo/{manifests,npm}`, and nothing about
+ * resource bodies or CEL. A backend that prebuilds a per-app image keys the
+ * image tag on this so a body-only edit reuses the image while an import or
+ * controller change rebuilds it.
+ *
+ * Derived by a SHALLOW static parse of the in-memory bundle — no graph load, no
+ * network, no archive. Exact import versions pin the transitive closure, so the
+ * authored `imports:` + body-declared controllers are sufficient.
+ *
+ * Assumes every file in the bundle is reachable from the entry (true for
+ * editor / control-plane-produced bundles, which carry exactly the app's
+ * files). It scans ALL `Telo.Definition` docs rather than following the entry's
+ * include/import graph — cheaper, and erring toward over-inclusion only ever
+ * busts the cache more eagerly. The one unsound case is a bundle carrying an
+ * orphan controller-bearing Definition that `telo install` would NOT bake (not
+ * reachable from this entry) yet another entry with the same closure WOULD: they
+ * could share a tag whose image lacks that controller. Not reachable via the
+ * editor; revisit (anchor to the include graph) if bundles ever carry unreachable
+ * Definition files.
+ */
+export interface DependencyKey {
+  /** Sorted `imports:` source strings from every module doc. */
+  importSources: string[];
+  /** Sorted controller PURLs declared by inline `Telo.Definition` docs. */
+  controllerLocators: string[];
+  /**
+   * True when a `Telo.Definition` resolves its controller from bundle-local
+   * source (`local_path`), or a file failed to parse. In either case the dep
+   * key alone can't capture a controller change, so the caller MUST also fold
+   * the full bundle contents into the tag (safe fallback to content-keying).
+   */
+  fullContentFallback: boolean;
+}
+
+function asModuleKind(kind: unknown): boolean {
+  return kind === "Telo.Application" || kind === "Telo.Library";
+}
+
+/** Pull `{ source }` out of an `imports:` map value (bare string or object). */
+function importSourceOf(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object") {
+    const source = (value as { source?: unknown }).source;
+    if (typeof source === "string") return source;
+  }
+  return undefined;
+}
+
+export function extractDependencyKey(bundle: RunBundle): DependencyKey {
+  const importSources = new Set<string>();
+  const controllerLocators = new Set<string>();
+  let fullContentFallback = false;
+
+  for (const file of bundle.files) {
+    let docs;
+    try {
+      docs = parseAllDocuments(file.contents);
+    } catch {
+      // Unparseable file — we can't know what it declares, so fall back to
+      // hashing the whole bundle rather than risk an under-specified key.
+      fullContentFallback = true;
+      continue;
+    }
+    for (const doc of docs) {
+      if (doc.errors.length > 0) {
+        fullContentFallback = true;
+        continue;
+      }
+      const value = doc.toJS() as Record<string, unknown> | null;
+      if (!value || typeof value !== "object") continue;
+      const kind = value.kind;
+
+      if (asModuleKind(kind) && value.imports && typeof value.imports === "object") {
+        for (const entry of Object.values(value.imports as Record<string, unknown>)) {
+          const source = importSourceOf(entry);
+          if (source) importSources.add(source);
+        }
+      }
+
+      if (kind === "Telo.Definition") {
+        const controllers = value.controllers;
+        if (Array.isArray(controllers)) {
+          for (const c of controllers) {
+            if (typeof c === "string") controllerLocators.add(c);
+          }
+        }
+        // A bundle-local controller's source lives in the body; the PURL/path
+        // can't capture an edit to it, so force full-content keying.
+        if (typeof value.local_path === "string") fullContentFallback = true;
+      }
+    }
+  }
+
+  return {
+    importSources: [...importSources].sort(),
+    controllerLocators: [...controllerLocators].sort(),
+    fullContentFallback,
+  };
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+export * from "./contract.js";
+export * from "./backend.js";
+export * from "./config.js";
+export * from "./server.js";
+export { sessionConfigSchema, type SessionConfigSchemaOptions } from "./capabilities-schema.js";
+export {
+  BaseImageCatalog,
+  filterTags,
+  parseDockerHubRef,
+  resolveTagDigest,
+  type TagFilter,
+  type BaseImageCatalogOptions,
+} from "./base-image-catalog.js";
+export { extractDependencyKey, type DependencyKey } from "./dependency-key.js";
+
+export {
+  SessionRegistry,
+  SessionLimitError,
+  SessionEvictedError,
+  type SessionEntry,
+  type RegistryDeps,
+} from "./session/registry.js";
+export { EventRingBuffer, type BufferedEvent } from "./session/ring-buffer.js";
+export { ByteRingBuffer, type BufferedBytes } from "./session/byte-ring-buffer.js";
+export { normalizeBundlePath, validateSessionId, BundlePathError } from "./session/bundle-path.js";
+export { streamSessionEvents, type SseStreamArgs } from "./sse/channel.js";
+export { healthRoute } from "./routes/health.js";
+export { capabilitiesRoute } from "./routes/capabilities.js";
+export { probeRoute, type ProbeRouteDeps } from "./routes/probe.js";
+export { sessionsRoute, type SessionsRouteDeps } from "./routes/sessions.js";
+export { ioRoute, type IoRouteDeps } from "./routes/io.js";
+export { relayDebugStream, type DebugRelayOptions } from "./debug/relay.js";
+export type { DebugFrame, DebugEvent, DebugLog } from "@telorun/debug-wire";

package/src/routes/capabilities.ts

@@ -0,0 +1,20 @@
+import type { FastifyInstance, FastifyPluginAsync } from "fastify";
+
+import type { RunnerCapabilities } from "../contract.js";
+
+/** Advertises the runner's self-description + editable config schema, so the
+ *  editor can render a generic runner config form without hardcoding per-backend
+ *  fields. The document is backend-authored — each concrete runner supplies its
+ *  own `RunnerCapabilities`; core only serves it.
+ *
+ *  Accepts a getter as well as a static document so a runner whose config
+ *  surface changes at runtime (e.g. a base-image catalog refreshed from a
+ *  registry) is re-resolved on each request rather than frozen at boot. */
+export function capabilitiesRoute(
+  capabilities: RunnerCapabilities | (() => RunnerCapabilities),
+): FastifyPluginAsync {
+  const resolve = typeof capabilities === "function" ? capabilities : () => capabilities;
+  return async (app: FastifyInstance) => {
+    app.get("/v1/capabilities", async () => resolve());
+  };
+}

package/src/routes/health.ts

@@ -0,0 +1,9 @@
+import type { FastifyInstance, FastifyPluginAsync } from "fastify";
+
+/** Liveness. Returns the runner's own version, supplied by the concrete runner
+ *  (each runner package has its own version). */
+export function healthRoute(version: string): FastifyPluginAsync {
+  return async (app: FastifyInstance) => {
+    app.get("/v1/health", async () => ({ ok: true, version }));
+  };
+}