@telorun/runner-core 0.8.2 → 0.10.0

package/src/debug/ports-resolved.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+
+import type { DebugFrame } from "@telorun/debug-wire";
+import { portKey, portsResolvedFrom, PORTS_RESOLVED_EVENT } from "./ports-resolved.js";
+
+const frame = (event: string, payload?: unknown): DebugFrame => ({
+  kind: "event",
+  timestamp: "2026-01-01T00:00:00.000Z",
+  event,
+  payload,
+});
+
+describe("portsResolvedFrom", () => {
+  it("reads the declared port set the kernel resolved", () => {
+    expect(
+      portsResolvedFrom(
+        frame(PORTS_RESOLVED_EVENT, {
+          ports: [
+            { name: "http", port: 3000, protocol: "tcp" },
+            { name: "metrics", port: 9100, protocol: "udp" },
+          ],
+        }),
+      ),
+    ).toEqual([
+      { port: 3000, protocol: "tcp" },
+      { port: 9100, protocol: "udp" },
+    ]);
+  });
+
+  it("reads an empty set as an empty set, not as 'no information'", () => {
+    // An app that dropped its last `ports:` entry has to un-route it, so the
+    // difference between [] and undefined is load-bearing.
+    expect(portsResolvedFrom(frame(PORTS_RESOLVED_EVENT, { ports: [] }))).toEqual([]);
+  });
+
+  it("ignores every other frame", () => {
+    expect(portsResolvedFrom(frame("Kernel.Started"))).toBeUndefined();
+    expect(
+      portsResolvedFrom({ kind: "log", timestamp: "", stream: "stdout", line: "x" }),
+    ).toBeUndefined();
+  });
+
+  it("ignores a payload it cannot make sense of", () => {
+    // The runner reads a stream from a kernel it is not versioned with, so an
+    // unrecognizable frame is one to skip, never one to fail the session on.
+    expect(portsResolvedFrom(frame(PORTS_RESOLVED_EVENT))).toBeUndefined();
+    expect(portsResolvedFrom(frame(PORTS_RESOLVED_EVENT, { ports: "3000" }))).toBeUndefined();
+    expect(
+      portsResolvedFrom(frame(PORTS_RESOLVED_EVENT, { ports: [{ port: "3000" }, { port: 80 }] })),
+    ).toEqual([{ port: 80, protocol: "tcp" }]);
+  });
+
+  it("defaults an unstated protocol to tcp", () => {
+    expect(portsResolvedFrom(frame(PORTS_RESOLVED_EVENT, { ports: [{ port: 80 }] }))).toEqual([
+      { port: 80, protocol: "tcp" },
+    ]);
+  });
+});
+
+describe("portKey", () => {
+  it("separates the two protocols on one number", () => {
+    expect(portKey({ port: 3000, protocol: "tcp" })).not.toBe(
+      portKey({ port: 3000, protocol: "udp" }),
+    );
+  });
+});

package/src/debug/ports-resolved.ts

@@ -0,0 +1,43 @@
+import { isEventFrame, type DebugFrame } from "@telorun/debug-wire";
+
+import type { PortMapping, PortProtocol } from "../contract.js";
+
+/** The kernel says this once per load: the Application's `ports:` block has
+ *  resolved to these integers. It re-fires on every watch reload, which is what
+ *  lets a host re-route without parsing a manifest. */
+export const PORTS_RESOLVED_EVENT = "Kernel.PortsResolved";
+
+/**
+ * The declared port set carried by a `Kernel.PortsResolved` frame, or undefined
+ * for any other frame.
+ *
+ * DECLARED, not bound. A runner routes what the manifest asked for; whether
+ * anything actually bound it is the reachability watcher's question, and it
+ * already answers it per port. Routing what happened to be bound instead would
+ * expose a port the manifest never declared, and would rest on a per-module
+ * convention — a transport whose kind does not emit a listening event would
+ * silently get no routing at all.
+ *
+ * Tolerant of a payload that is not the expected shape: a runner reads this off
+ * a stream produced by a kernel it does not version together with, so a frame it
+ * cannot make sense of is one to ignore, not to fail on.
+ */
+export function portsResolvedFrom(frame: DebugFrame): PortMapping[] | undefined {
+  if (!isEventFrame(frame) || frame.event !== PORTS_RESOLVED_EVENT) return undefined;
+  const raw = (frame.payload as { ports?: unknown } | undefined)?.ports;
+  if (!Array.isArray(raw)) return undefined;
+  const ports: PortMapping[] = [];
+  for (const entry of raw) {
+    const port = (entry as { port?: unknown })?.port;
+    const protocol = (entry as { protocol?: unknown })?.protocol;
+    if (typeof port !== "number" || !Number.isInteger(port)) continue;
+    ports.push({ port, protocol: protocol === "udp" ? "udp" : ("tcp" as PortProtocol) });
+  }
+  return ports;
+}
+
+/** Identity of a port within a session: the pair, since tcp/3000 and udp/3000
+ *  are different endpoints. */
+export function portKey(mapping: PortMapping): string {
+  return `${mapping.protocol}/${mapping.port}`;
+}

package/src/debug/relay.ts

@@ -29,17 +29,27 @@ const RECONNECT_DELAY_MS = 500;
  */
 export async function relayDebugStream(opts: DebugRelayOptions): Promise<void> {
   const { url, onFrame, signal } = opts;
+  // The last id delivered, carried across reconnects. Without it a drop replays
+  // the producer's whole buffer, and a consumer that DERIVES state from the
+  // stream — the run projection counting generations — re-counts every reload
+  // still in that buffer. In a watch session that is one pair per save.
+  let lastEventId = 0;
   while (!signal.aborted) {
     try {
       const res = await fetch(url, {
         signal,
-        headers: { accept: "text/event-stream" },
+        headers: {
+          accept: "text/event-stream",
+          ...(lastEventId > 0 ? { "last-event-id": String(lastEventId) } : {}),
+        },
       });
       if (!res.ok || !res.body) {
         await abortableDelay(RECONNECT_DELAY_MS, signal);
         continue;
       }
-      await pump(res.body, onFrame, signal);
+      await pump(res.body, onFrame, signal, (id) => {
+        lastEventId = id;
+      });
     } catch (err) {
       if (signal.aborted) return;
       opts.onError?.(err instanceof Error ? err : new Error(String(err)));
@@ -52,6 +62,7 @@ async function pump(
   body: ReadableStream<Uint8Array>,
   onFrame: (frame: DebugFrame) => void,
   signal: AbortSignal,
+  onId: (id: number) => void,
 ): Promise<void> {
   const reader = body.getReader();
   const decoder = new TextDecoder();
@@ -64,9 +75,15 @@ async function pump(
       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));
+        const block = buf.slice(0, sep);
         buf = buf.slice(sep + 2);
-        if (frame) onFrame(frame);
+        const frame = parseSseData(block);
+        if (!frame) continue;
+        onFrame(frame);
+        // Checkpoint AFTER delivery, so a frame the consumer never saw is not
+        // skipped on the next reconnect.
+        const id = parseSseId(block);
+        if (id !== null) onId(id);
       }
     }
   } finally {
@@ -74,6 +91,17 @@ async function pump(
   }
 }
 
+/** The `id:` of one SSE frame, or null when the producer sent none — an older
+ *  kernel, whose stream simply has no resume point. */
+function parseSseId(block: string): number | null {
+  for (const line of block.split("\n")) {
+    if (!line.startsWith("id:")) continue;
+    const parsed = Number.parseInt(line.slice(3).trim(), 10);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
 /** Extract and parse the `data:` payload of one SSE frame. Ignores comment
  *  lines (`: heartbeat`) and unparseable frames. */
 function parseSseData(block: string): DebugFrame | null {

package/src/debug/run-projection.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, it } from "vitest";
+
+import type { DebugFrame } from "@telorun/debug-wire";
+import type { RunEvent } from "../contract.js";
+import { SessionRegistry } from "../session/registry.js";
+import { RunProjection } from "./run-projection.js";
+
+function harness(apps = [{ name: "app" }]) {
+  const registry = new SessionRegistry({
+    maxSessions: 4,
+    exitTtlMs: 1000,
+    replayBufferBytes: 100_000,
+  });
+  const entry = registry.register({ sessionId: "s1", mode: "watch", apps });
+  const projection = new RunProjection(registry, "s1");
+  entry.attribution = projection;
+  const runs = (): RunEvent[] =>
+    entry.buffer.replay(0).entries.map((e) => e.event).filter((e) => e.type === "run");
+  return { registry, entry, projection, runs };
+}
+
+const event = (name: string, payload?: unknown): DebugFrame => ({
+  kind: "event",
+  timestamp: "2026-01-01T00:00:00.000Z",
+  event: name,
+  payload,
+});
+
+describe("RunProjection", () => {
+  it("brackets a generation from Kernel.Starting and Kernel.Stopped", () => {
+    const h = harness();
+    h.projection.expectAll("initial");
+    h.projection.frame("app", event("Kernel.Starting"));
+    h.projection.frame("app", event("Kernel.Started"));
+    h.projection.frame("app", event("Kernel.Stopped", { exitCode: 0 }));
+
+    expect(h.runs()).toMatchObject([
+      { type: "run", app: "app", generation: 1, phase: "started", trigger: "initial" },
+      { type: "run", app: "app", generation: 1, phase: "completed", code: 0 },
+    ]);
+  });
+
+  it("leaves the session running when a generation completes", () => {
+    const h = harness();
+    h.projection.expectAll("initial");
+    h.registry.emit("s1", { type: "status", status: { kind: "running" } });
+    h.projection.frame("app", event("Kernel.Starting"));
+    h.projection.frame("app", event("Kernel.Stopped", { exitCode: 0 }));
+
+    // The whole point of the split: a one-shot app finishing is not the session
+    // ending, so nothing is scheduled for eviction.
+    expect(h.entry.status).toEqual({ kind: "running" });
+    expect(h.entry.exitedAt).toBeNull();
+    expect(h.entry.evictionTimer).toBeNull();
+  });
+
+  it("counts a reload as the next generation and attributes it to the watcher", () => {
+    const h = harness();
+    h.projection.expectAll("initial");
+    h.projection.frame("app", event("Kernel.Starting"));
+    h.projection.frame("app", event("Kernel.Stopped", { exitCode: 0 }));
+    h.projection.frame("app", event("Kernel.Starting"));
+
+    expect(h.runs().at(-1)).toMatchObject({
+      generation: 2,
+      phase: "started",
+      trigger: "watch",
+    });
+  });
+
+  it("attributes a generation a route caused, then falls back to watch", () => {
+    const h = harness();
+    h.projection.expectAll("initial");
+    h.projection.frame("app", event("Kernel.Starting"));
+    h.projection.frame("app", event("Kernel.Stopped", { exitCode: 0 }));
+
+    h.projection.expect("app", "manual");
+    h.projection.frame("app", event("Kernel.Starting"));
+    h.projection.frame("app", event("Kernel.Stopped", { exitCode: 0 }));
+    h.projection.frame("app", event("Kernel.Starting"));
+
+    const started = h.runs().filter((e) => e.type === "run" && e.phase === "started");
+    expect(started.map((e) => (e as { trigger: string }).trigger)).toEqual([
+      "initial",
+      "manual",
+      "watch",
+    ]);
+  });
+
+  it("opens a generation for a load failure, which emits no Kernel.Starting", () => {
+    const h = harness();
+    h.projection.expectAll("initial");
+    // A manifest that fails to LOAD never reaches Kernel.Starting; reporting the
+    // failure of a generation the client never saw start would be unreadable.
+    h.projection.frame(
+      "app",
+      event("Kernel.RunFailed", {
+        phase: "load",
+        code: "ERR_MANIFEST_VALIDATION_FAILED",
+        message: "bad manifest",
+      }),
+    );
+
+    expect(h.runs()).toMatchObject([
+      { generation: 1, phase: "started", trigger: "initial" },
+      { generation: 1, phase: "failed", reason: "ERR_MANIFEST_VALIDATION_FAILED" },
+    ]);
+  });
+
+  it("does not double-count a boot failure that follows Kernel.Starting", () => {
+    const h = harness();
+    h.projection.expectAll("initial");
+    h.projection.frame("app", event("Kernel.Starting"));
+    h.projection.frame("app", event("Kernel.RunFailed", { phase: "start", message: "boom" }));
+
+    expect(h.runs()).toMatchObject([
+      { generation: 1, phase: "started" },
+      { generation: 1, phase: "failed", reason: "boom" },
+    ]);
+  });
+
+  it("closes a generation whose WORKLOAD ended, with no Kernel.Stopped", () => {
+    const h = harness();
+    h.projection.expectAll("initial");
+    h.projection.frame("app", event("Kernel.Starting"));
+    // A container that goes away emits nothing — there is nothing left to emit
+    // it — so the backend reports the ending through the contract instead.
+    h.projection.endGeneration("app", { reason: "application container exited" });
+
+    expect(h.runs()).toMatchObject([
+      { generation: 1, phase: "started" },
+      { generation: 1, phase: "failed", reason: "application container exited" },
+    ]);
+  });
+
+  it("ignores a workload ending when no generation is open", () => {
+    const h = harness();
+    h.projection.endGeneration("app", { reason: "gone" });
+    expect(h.runs()).toEqual([]);
+  });
+
+  it("counts generations per app, not per session", () => {
+    const h = harness([{ name: "web" }, { name: "worker" }]);
+    h.projection.expectAll("initial");
+    h.projection.frame("web", event("Kernel.Starting"));
+    h.projection.frame("worker", event("Kernel.Starting"));
+    h.projection.frame("worker", event("Kernel.Stopped", { exitCode: 0 }));
+    h.projection.frame("worker", event("Kernel.Starting"));
+
+    const byApp = (name: string) =>
+      h.runs().filter((e) => (e as { app: string }).app === name);
+    expect(byApp("web").at(-1)).toMatchObject({ generation: 1, phase: "started" });
+    expect(byApp("worker").at(-1)).toMatchObject({ generation: 2, phase: "started" });
+  });
+});

package/src/debug/run-projection.ts

@@ -0,0 +1,122 @@
+import { isEventFrame, type DebugFrame } from "@telorun/debug-wire";
+
+import type { RunTrigger } from "../contract.js";
+import type { SessionRegistry } from "../session/registry.js";
+
+/**
+ * Projects per-app `run` events out of the kernel lifecycle events the debug
+ * stream already carries.
+ *
+ * The runner cannot see inside the container, and parsing the merged PTY stream
+ * is not a contract — so a watch session always runs with the kernel debug
+ * stream on and this reads it. A watch reload is a stop/start pair on ONE debug
+ * connection, so `generation` is counted here and the kernel is asked for
+ * nothing.
+ *
+ * Three event names are read, and only three:
+ *  - `Kernel.Starting`  → the generation began
+ *  - `Kernel.Stopped`   → it ended, carrying `exitCode`
+ *  - `Kernel.RunFailed` → it never reached a running state, carrying why
+ *
+ * `Kernel.Started` is deliberately ignored: it and `Kernel.Starting` bracket the
+ * same transition, and one `started` per generation is the contract.
+ */
+export class RunProjection {
+  /** What to attribute the NEXT generation of each app to. A reload is a watch
+   *  reload unless something told us otherwise, so `watch` is the resting value
+   *  and `initial` / `manual` / `resume` are set by whoever caused them. */
+  private readonly triggers = new Map<string, RunTrigger>();
+
+  constructor(
+    private readonly registry: SessionRegistry,
+    private readonly sessionId: string,
+  ) {}
+
+  /** Attribute an app's next generation. Called with `initial` when the session
+   *  comes up, `manual` from the reload route, `resume` after a pod recreate. */
+  expect(app: string, trigger: RunTrigger): void {
+    this.triggers.set(app, trigger);
+  }
+
+  /** Attribute every app's next generation — the session-wide cases (initial,
+   *  resume) always move all of them together. */
+  expectAll(trigger: RunTrigger): void {
+    const entry = this.registry.get(this.sessionId);
+    for (const app of entry?.apps.keys() ?? []) this.triggers.set(app, trigger);
+  }
+
+  /** Feed one frame from `app`'s debug stream. Frames that are not one of the
+   *  three lifecycle events pass through untouched. */
+  frame(app: string, frame: DebugFrame): void {
+    if (!isEventFrame(frame)) return;
+    switch (frame.event) {
+      case "Kernel.Starting":
+        this.begin(app);
+        return;
+      case "Kernel.Stopped":
+        this.registry.finishGeneration(this.sessionId, app, {
+          phase: "completed",
+          code: exitCodeOf(frame.payload),
+        });
+        return;
+      case "Kernel.RunFailed":
+        // A LOAD failure emits no `Kernel.Starting` — the kernel never got that
+        // far — so open the generation here rather than reporting a failure of a
+        // generation the client never saw start. The pair is what a consumer
+        // reads as "this attempt happened and did not survive".
+        this.begin(app);
+        this.registry.finishGeneration(this.sessionId, app, {
+          phase: "failed",
+          reason: failureReason(frame.payload),
+        });
+        return;
+      default:
+        return;
+    }
+  }
+
+  /**
+   * Close the open generation because its WORKLOAD ended, not because the kernel
+   * said so. A container that goes away under `--watch` emits no `Kernel.Stopped`
+   * — there is nothing left to emit it — so the backend reports the ending and
+   * this turns it into the same run outcome the kernel path produces.
+   */
+  endGeneration(app: string, outcome: { code?: number; reason?: string }): void {
+    const channel = this.registry.get(this.sessionId)?.apps.get(app);
+    if (!channel || channel.startedAt === null) return;
+    this.registry.finishGeneration(
+      this.sessionId,
+      app,
+      outcome.reason === undefined && outcome.code !== undefined
+        ? { phase: "completed", code: outcome.code }
+        : { phase: "failed", reason: outcome.reason ?? "workload ended" },
+    );
+  }
+
+  /** Open a generation unless one is already open — `Kernel.Starting` followed
+   *  by a `Kernel.RunFailed` from the boot phase must not count twice. */
+  private begin(app: string): void {
+    const channel = this.registry.get(this.sessionId)?.apps.get(app);
+    if (!channel || channel.startedAt !== null) return;
+    const trigger = this.triggers.get(app) ?? "watch";
+    // Consumed: the next generation is a plain watch reload unless something
+    // says otherwise again.
+    this.triggers.delete(app);
+    this.registry.startGeneration(this.sessionId, app, trigger);
+  }
+}
+
+function exitCodeOf(payload: unknown): number {
+  const code = (payload as { exitCode?: unknown } | undefined)?.exitCode;
+  return typeof code === "number" ? code : 0;
+}
+
+/** The most actionable thing the failure carries: a diagnostic code when the
+ *  kernel had one (`CEL_UNKNOWN_FIELD`, `ERR_MANIFEST_VALIDATION_FAILED`), else
+ *  its message. A code is what a reader — an agent above all — branches on. */
+function failureReason(payload: unknown): string {
+  const p = payload as { code?: unknown; message?: unknown } | undefined;
+  if (typeof p?.code === "string" && p.code !== "") return p.code;
+  if (typeof p?.message === "string" && p.message !== "") return p.message;
+  return "run failed";
+}

package/src/index.ts

@@ -17,17 +17,36 @@ export {
   SessionRegistry,
   SessionLimitError,
   SessionEvictedError,
+  UnknownAppError,
+  type AppChannel,
+  type RunAttribution,
   type SessionEntry,
+  type RegisterArgs,
   type RegistryDeps,
+  type WorkspaceCheckpoint,
 } from "./session/registry.js";
+export { WatchSupervisor, type WatchSupervisorDeps } from "./session/watch-supervisor.js";
+export { RunProjection } from "./debug/run-projection.js";
+export {
+  portKey,
+  portsResolvedFrom,
+  PORTS_RESOLVED_EVENT,
+} from "./debug/ports-resolved.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 { WorkspaceClient } from "./session/workspace-client.js";
+export { workspaceAppManifest, WORKSPACE_APP_FILENAME } from "./session/workspace-app.js";
+export {
+  workspaceMarkerWrite,
+  WORKSPACE_MARKER_CONTENTS,
+  WORKSPACE_MARKER_FILENAME,
+} from "./session/workspace-marker.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 { sessionsRoute, type SessionsRouteDeps, type WatchConfig } from "./routes/sessions.js";
 export { appsRoute, type AppsRouteDeps } from "./routes/apps.js";
 export { ioRoute, type IoRouteDeps } from "./routes/io.js";
 export { relayDebugStream, type DebugRelayOptions } from "./debug/relay.js";

package/src/routes/apps.ts

@@ -2,7 +2,7 @@ import type { FastifyInstance, FastifyPluginAsync } from "fastify";
 
 import type { RunnerBackend } from "../backend.js";
 import type { ResolvedRunnerApp } from "../config.js";
-import type { PortMapping, RunnerTerms } from "../contract.js";
+import { DEFAULT_APP_NAME, type PortMapping, type RunnerTerms } from "../contract.js";
 import type { SessionRegistry } from "../session/registry.js";
 import { enforceTerms, portsSchema, startWorkloadSession } from "./session-start.js";
 
@@ -88,15 +88,24 @@ export function appsRoute(deps: AppsRouteDeps): FastifyPluginAsync {
           app,
           deps,
           {
-            // Self-contained image — no bundle to deliver; the entry path is an
-            // unused placeholder so the backend spec stays total.
+            // Self-contained image — no bundle to deliver, and no entry path:
+            // the image's own entrypoint runs.
             bundle: { entryRelativePath: "telo.yaml", files: [] },
-            entryRelativePath: "telo.yaml",
             env,
-            ports: req.body?.ports ?? [],
             config: { image: appEntry.image, pullPolicy: appEntry.pullPolicy },
             selfContained: true,
             inspect: req.body?.inspect ?? false,
+            // An operator-predefined app session is one run of one application.
+            // Watch is a workspace shape, and this door carries no workspace.
+            mode: "run",
+            apps: [
+              {
+                name: DEFAULT_APP_NAME,
+                entryRelativePath: "",
+                ports: req.body?.ports ?? [],
+                io: "tty",
+              },
+            ],
           },
           reply,
         );