@telorun/runner-core 0.8.1 → 0.9.0

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,
         );

package/src/routes/io.ts

@@ -1,7 +1,7 @@
 import type { FastifyInstance, FastifyPluginAsync, FastifyRequest } from "fastify";
 import type { WebSocket } from "@fastify/websocket";
 
-import { isTerminal } from "../contract.js";
+import { isTerminal, type ByteStreamTag } from "../contract.js";
 import type { BufferedBytes } from "../session/byte-ring-buffer.js";
 import type { SessionRegistry } from "../session/registry.js";
 
@@ -12,6 +12,11 @@ export interface IoRouteDeps {
 
 const RESIZE_THROTTLE_MS = 50;
 const SEQ_PREFIX_BYTES = 4;
+const STREAM_TAG_BYTES = 1;
+/** Wire codes for the per-frame stream tag. A tag rather than a labelled merged
+ *  stream: under `io: "streams"` the transport really did separate stdout from
+ *  stderr, and under `tty` it really did not. */
+const STREAM_CODES: Record<ByteStreamTag, number> = { tty: 0, stdout: 1, stderr: 2 };
 /** Upper bound on cols/rows accepted from the client. xterm + a fit addon
  *  produce values in the low thousands at extreme zoom; anything past this
  *  is either nonsense or a malicious client trying to feed
@@ -28,7 +33,7 @@ interface ControlFrame {
 
 export function ioRoute(deps: IoRouteDeps): FastifyPluginAsync {
   return async (app: FastifyInstance) => {
-    app.get<{ Params: { id: string }; Querystring: { lastSeq?: string } }>(
+    app.get<{ Params: { id: string }; Querystring: IoQuery }>(
       "/v1/sessions/:id/io",
       { websocket: true },
       (socket, req) => handleIo(socket, req, deps),
@@ -36,9 +41,16 @@ export function ioRoute(deps: IoRouteDeps): FastifyPluginAsync {
   };
 }
 
+interface IoQuery {
+  lastSeq?: string;
+  /** Which application's terminal to attach to. Required whenever the session
+   *  runs more than one app — there is no defensible default among several. */
+  app?: string;
+}
+
 function handleIo(
   socket: WebSocket,
-  req: FastifyRequest<{ Params: { id: string }; Querystring: { lastSeq?: string } }>,
+  req: FastifyRequest<{ Params: { id: string }; Querystring: IoQuery }>,
   deps: IoRouteDeps,
 ): void {
   // Origin allowlist runs INSIDE the handler (post-handshake) rather than
@@ -61,6 +73,24 @@ function handleIo(
     return;
   }
 
+  // Resolve which app's terminal this attachment is for. An explicit name must
+  // exist; an omitted one is only defensible on a single-app session.
+  const requestedApp = req.query.app?.trim() || undefined;
+  const channel = requestedApp
+    ? entry.apps.get(requestedApp)
+    : deps.registry.soleApp(entry);
+  if (!channel) {
+    closeWith(
+      socket,
+      4404,
+      requestedApp
+        ? `session runs no app named '${requestedApp}'`
+        : `session runs ${entry.apps.size} apps — ?app= is required`,
+    );
+    return;
+  }
+  const appName = channel.name;
+
   const lastSeq = parseLastSeq(req.query.lastSeq);
 
   // Subscribe BEFORE snapshotting the replay buffer. This is load-bearing:
@@ -71,7 +101,7 @@ function handleIo(
   // the handler switches to direct-send mode.
   let mode: "deferred" | "direct" = "deferred";
   const liveQueue: BufferedBytes[] = [];
-  const unsubscribe = deps.registry.subscribeBytes(sessionId, (buffered) => {
+  const unsubscribe = deps.registry.subscribeBytes(sessionId, appName, (buffered) => {
     if (socket.readyState !== socket.OPEN) return;
     if (mode === "deferred") {
       liveQueue.push(buffered);
@@ -80,7 +110,7 @@ function handleIo(
     }
   });
 
-  const { entries, hasGap } = entry.byteBuffer.replay(lastSeq);
+  const { entries, hasGap } = channel.byteBuffer.replay(lastSeq);
 
   // If the session is already terminal AND the byte buffer holds nothing
   // newer than what the client already saw, there's no live channel to
@@ -91,8 +121,9 @@ function handleIo(
     return;
   }
 
-  // Confirm the resume point so the client can validate its own bookkeeping.
-  sendJson(socket, { type: "seq", seq: lastSeq });
+  // Confirm the resume point and which attachment this is, so a client knows
+  // whether to offer resize before it sends one.
+  sendJson(socket, { type: "seq", seq: lastSeq, app: appName, io: channel.io });
   if (hasGap) {
     sendJson(socket, { type: "gap", reason: "buffer_evicted" });
   }
@@ -125,7 +156,7 @@ function handleIo(
     if (!next) return;
     // Session may have exited between schedule and flush; backends treat
     // resize on a gone workload as a no-op.
-    entry.session?.resize(next.cols, next.rows);
+    entry.session?.resize(appName, next.cols, next.rows);
   };
 
   socket.on("message", (raw, isBinary) => {
@@ -133,7 +164,7 @@ function handleIo(
       const session = entry.session;
       if (!session) return;
       const buf = raw instanceof Buffer ? raw : Buffer.from(raw as ArrayBuffer);
-      session.writeStdin(buf);
+      session.writeStdin(appName, buf);
       return;
     }
     const text = raw.toString();
@@ -144,6 +175,13 @@ function handleIo(
       return;
     }
     if (parsed.type === "resize") {
+      // A resize is meaningless with no PTY — rejected rather than silently
+      // dropped, so a client attached to a `streams` app learns it must not
+      // wire its terminal's resize through.
+      if (channel.io !== "tty") {
+        sendJson(socket, { type: "error", error: "resize_unsupported", io: channel.io });
+        return;
+      }
       const cols = clampDimension(parsed.cols);
       const rows = clampDimension(parsed.rows);
       if (cols === null || rows === null) return;
@@ -190,7 +228,12 @@ function handleIo(
     drainAndClose(Date.now() + TERMINAL_DRAIN_MAX_MS);
   }
 
+  // A byte-channel attachment counts as a live client: a session whose terminal
+  // someone is watching is not idle, even with no SSE stream open.
+  const releaseSubscriber = deps.registry.addSubscriber(sessionId);
+
   const cleanup = (): void => {
+    releaseSubscriber();
     unsubscribe();
     unsubscribeStatus();
     if (resizeTimer) clearTimeout(resizeTimer);
@@ -200,14 +243,17 @@ function handleIo(
   socket.on("error", cleanup);
 }
 
-/** Wire format for a binary frame: `[seq:4 BE][payload:N]`. The 4-byte
+/** Wire format for a binary frame: `[seq:4 BE][stream:1][payload:N]`. The 4-byte
  *  prefix lets the client de-sync detect — it knows the authoritative seq
  *  for every byte received, instead of inferring from frame count. Replay
- *  duplicates and reconnect resumes both lean on this. */
+ *  duplicates and reconnect resumes both lean on this. The stream byte says
+ *  which source produced the payload; it is `tty` under a terminal attach and
+ *  never asserts a split the transport did not make. */
 function sendBytesFrame(socket: WebSocket, buffered: BufferedBytes): void {
   if (socket.readyState !== socket.OPEN) return;
-  const prefix = Buffer.alloc(SEQ_PREFIX_BYTES);
+  const prefix = Buffer.alloc(SEQ_PREFIX_BYTES + STREAM_TAG_BYTES);
   prefix.writeUInt32BE(buffered.seq, 0);
+  prefix.writeUInt8(STREAM_CODES[buffered.stream] ?? 0, SEQ_PREFIX_BYTES);
   try {
     socket.send(Buffer.concat([prefix, buffered.bytes]));
   } catch {

package/src/routes/session-start.ts

@@ -1,17 +1,19 @@
 import type { FastifyInstance, FastifyReply, FastifyRequest } from "fastify";
 
 import { isEventFrame } from "@telorun/debug-wire";
-import type { RunnerBackend } from "../backend.js";
+import type { RunnerBackend, WorkloadLaunch } from "../backend.js";
+import { RunProjection } from "../debug/run-projection.js";
 import {
   ACCEPTED_TERMS_HEADER,
   SessionStartError,
-  type PortMapping,
-  type RunBundle,
   type RunnerTerms,
-  type SessionConfig,
 } from "../contract.js";
 import { generateSessionId } from "../session/session-id.js";
-import { SessionLimitError, type SessionRegistry } from "../session/registry.js";
+import {
+  SessionLimitError,
+  type SessionEntry,
+  type SessionRegistry,
+} from "../session/registry.js";
 
 /** JSON Schema for the `ports` body field, shared by every session-creating
  *  route so bundle and app sessions validate port mappings identically. */
@@ -58,15 +60,7 @@ export interface WorkloadStartDeps {
   defaultRegistryUrl?: string;
 }
 
-export interface WorkloadStartArgs {
-  bundle: RunBundle;
-  entryRelativePath: string;
-  env: Record<string, string>;
-  ports: PortMapping[];
-  config: SessionConfig;
-  selfContained: boolean;
-  inspect: boolean;
-}
+export type WorkloadStartArgs = WorkloadLaunch;
 
 /**
  * The session-creation leaf shared by `POST /v1/sessions` (bundle sessions) and
@@ -86,7 +80,12 @@ export async function startWorkloadSession(
 
   let entry: ReturnType<SessionRegistry["register"]>;
   try {
-    entry = deps.registry.register({ sessionId });
+    entry = deps.registry.register({
+      sessionId,
+      mode: args.mode,
+      agent: args.agent?.name,
+      apps: args.apps.map((a) => ({ name: a.name, io: a.io, ports: a.ports })),
+    });
   } catch (err) {
     if (err instanceof SessionLimitError) {
       reply.code(409).send({ error: "too_many_sessions", message: err.message });
@@ -101,10 +100,11 @@ export async function startWorkloadSession(
   // whitespace from an editor input doesn't flow into the workload.
   const configRegistryUrl = args.config.registryUrl?.trim() || undefined;
   const registryUrl = configRegistryUrl ?? deps.defaultRegistryUrl;
-  const sessionEnv =
+  const sessionEnv = withoutCacheOverride(
     registryUrl && !("TELO_REGISTRY_URL" in args.env)
       ? { ...args.env, TELO_REGISTRY_URL: registryUrl }
-      : args.env;
+      : args.env,
+  );
 
   // Respond as soon as the session is registered — BEFORE the backend starts.
   // `backend.start()` now spans the on-cluster image build and pod bring-up,
@@ -119,29 +119,92 @@ export async function startWorkloadSession(
     createdAt: entry.createdAt.toISOString(),
   });
 
+  // Every app's first generation is attributed to the session coming up; a
+  // reload after that is a watch reload unless a route says otherwise.
+  const projection = new RunProjection(deps.registry, sessionId);
+  projection.expectAll("initial");
+  // Parked on the entry so the reload / resume routes can attribute the
+  // generation they are about to cause.
+  entry.attribution = projection;
+
+  const launch: WorkloadLaunch = { ...args, env: sessionEnv };
+  entry.launch = launch;
+  launchWorkload(app, deps, launch, entry);
+}
+
+/**
+ * Wire a backend workload to an EXISTING registry entry and start it in the
+ * background. Shared by session creation and by `resume`, which builds a fresh
+ * pod from the checkpoint under the same session id — the callback wiring is the
+ * contract's, so a second copy of it would be a second place run outcomes,
+ * output routing and the credential boundary could drift.
+ */
+export function launchWorkload(
+  app: FastifyInstance,
+  deps: WorkloadStartDeps,
+  args: WorkloadStartArgs,
+  entry: SessionEntry,
+): void {
+  const sessionId = entry.sessionId;
+  const projection = entry.attribution;
+
   deps.backend
     .start({
       sessionId,
       bundle: args.bundle,
-      entryRelativePath: args.entryRelativePath,
-      env: sessionEnv,
-      ports: args.ports,
+      env: args.env,
       config: args.config,
       selfContained: args.selfContained,
       inspect: args.inspect,
+      mode: args.mode,
+      apps: args.apps,
+      agent: args.agent,
       onStatus: (status) => deps.registry.emit(sessionId, { type: "status", status }),
-      onProgress: (phase, message, done) =>
-        deps.registry.emit(sessionId, { type: "progress", phase, message, done }),
-      onOutput: (chunk) => deps.registry.pushBytes(sessionId, chunk),
+      onProgress: (phase, message, done, app) =>
+        deps.registry.emit(sessionId, { type: "progress", app, phase, message, done }),
+      onOutput: (app, chunk, stream) => deps.registry.pushBytes(sessionId, app, chunk, stream),
       // Relay only kernel *event* frames to the client. stdout/stderr already
       // arrive over the byte channel (onOutput), so forwarding log frames would
       // double the traffic and let log spam evict lifecycle events from the
       // byte-capped replay buffer. The editor discards relayed logs anyway.
-      onDebug: (frame) => {
-        if (isEventFrame(frame)) deps.registry.emit(sessionId, { type: "debug", frame });
+      //
+      // The projection sees EVERY frame, including the ones not relayed — run
+      // outcomes are derived from lifecycle events, not from what a client
+      // happens to be shown.
+      onDebug: (appName, frame) => {
+        projection?.frame(appName, frame);
+        if (isEventFrame(frame)) {
+          deps.registry.emit(sessionId, { type: "debug", app: appName, frame });
+        }
+      },
+      // A watch session's app dying is a RUN outcome, not a session status: the
+      // rest of the session is still up, and the next edit starts the next
+      // generation. The projection owns generation identity, so the ending goes
+      // through it rather than being emitted directly.
+      onRunEnded: (appName, outcome) =>
+        projection?.endGeneration(appName, outcome) ??
+        deps.registry.finishGeneration(sessionId, appName, {
+          phase: "failed",
+          reason: outcome.reason ?? "workload ended",
+        }),
+      onReachability: (app, port, state) =>
+        deps.registry.emit(sessionId, { type: "reachability", app, port, state }),
+      onEndpoints: (appName, change) => {
+        // The registry's own channel is what `GET /v1/sessions/:id` reports, so
+        // the delta has to land there too — otherwise the session document keeps
+        // describing the port set the session STARTED with, forever.
+        const channel = entry.apps.get(appName);
+        if (channel) {
+          const removed = new Set(
+            (change.removed ?? []).map((e) => `${e.protocol}/${e.port}`),
+          );
+          channel.ports = [
+            ...channel.ports.filter((p) => !removed.has(`${p.protocol}/${p.port}`)),
+            ...(change.added ?? []).map((e) => ({ port: e.port, protocol: e.protocol })),
+          ];
+        }
+        deps.registry.emit(sessionId, { type: "endpoints", app: appName, ...change });
       },
-      onReachability: (port, state) =>
-        deps.registry.emit(sessionId, { type: "reachability", port, state }),
       isUserStopped: () => entry.userStopped,
     })
     .then(async (session) => {
@@ -172,3 +235,19 @@ export async function startWorkloadSession(
       deps.registry.emit(sessionId, { type: "status", status: { kind: "failed", message } });
     });
 }
+
+/**
+ * Drop a client-supplied `TELO_CACHE_DIR`.
+ *
+ * It OUTRANKS the `telo-workspace.yaml` marker the session seeds at its
+ * workspace root, so a client that sets it silently gives every app its own
+ * module cache — the exact thing the marker exists to prevent. Where a cache
+ * root is genuinely needed (the workspace container, whose manifest lives
+ * outside the workspace) the backend sets it itself.
+ */
+function withoutCacheOverride(env: Record<string, string>): Record<string, string> {
+  if (!("TELO_CACHE_DIR" in env)) return env;
+  const rest = { ...env };
+  delete rest.TELO_CACHE_DIR;
+  return rest;
+}