@telorun/runner-core 0.8.2 → 0.10.0

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
@@ -81,12 +75,22 @@ export async function startWorkloadSession(
   deps: WorkloadStartDeps,
   args: WorkloadStartArgs,
   reply: FastifyReply,
+  /** Things the route decided about this session that the client would
+   *  otherwise have to infer from an absence — an agent dropped because its
+   *  port collided with an application's. Emitted on the stream, because the
+   *  201 is sent before the workload starts and has nowhere to carry them. */
+  notices?: string[],
 ): Promise<void> {
   const sessionId = generateSessionId();
 
   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 +105,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 +124,96 @@ export async function startWorkloadSession(
     createdAt: entry.createdAt.toISOString(),
   });
 
+  for (const message of notices ?? []) {
+    deps.registry.emit(sessionId, { type: "progress", phase: "provision", message });
+  }
+
+  // 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 +244,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;
+}