@telorun/k8s-runner 0.10.2 → 0.12.0

package/README.md

@@ -66,6 +66,220 @@ service-account token, seccomp `RuntimeDefault`); a sandbox RuntimeClass
 image is single-tenant, so install scripts run normally inside the trusted build
 (native/postinstall controllers work) with no cross-tenant cache to poison.
 
+## Watch sessions
+
+Everything above describes a **run** session: one pod per Run click, terminal when
+the workload exits. `POST /v1/sessions` with `mode: "watch"` asks for something
+different — a **workspace that runs continuously**. One pod holds a shared
+`/workspace` volume, a `workspace` container serving the editor's file routes, one
+`app-<name>` container per application running `telo run --watch`, and optionally
+a co-resident `agent` drawn from the `RUNNER_APPS` catalog. An edit then costs a
+kernel reload instead of a pod: no schedule, no pull, no build.
+
+Off unless `RUNNER_WATCH_SESSIONS` is set. Run sessions are entirely unaffected.
+
+### The pod
+
+| Container | Image | Present | Writes | Credential |
+| --- | --- | --- | --- | --- |
+| `workspace` | The kernel image, over a runner-supplied manifest | Always | `/workspace` | None |
+| `agent` | Operator catalog image | When `agent` is requested | `/workspace` | Operator env |
+| `app-<name>` | The kernel image | One per app | `/workspace`, `/telo-cache/<name>`, scratch | Session-declared env only |
+
+**The env split is the credential boundary.** It used to be structural (two pods)
+and is now a code invariant: the operator env goes on `agent` alone, every
+`app-<name>` gets the session's declared env and nothing else, and `workspace`
+gets neither — it serves files and holds no secrets.
+
+**A shared `fsGroup` is required**, and its absence is the kind of thing that
+fails as a confusing "file not found" one reload after a write: every container
+reads and writes `/workspace`, so they must share a GID or the agent writes files
+the app cannot read.
+
+**The agent is routed like an app port, and reported like one.** Its catalog
+entry declares the `port` its image listens on, and the session refuses an agent
+without one (`400 agent_port_undeclared`) rather than starting a container
+nothing can reach. The pod's containers share one network namespace, so two of
+them cannot bind the same port at all — but where an application declares the
+agent's port the **manifest wins**: the session starts without the agent and says
+so on its stream, rather than refusing to run the user's app over a container
+they never asked for and cannot decline. Nothing else is arranged: the pod's containers
+share one network namespace, so the port simply joins the session's own Service
+and Ingress and answers at `<agentPort>-<sessionId>.<base-domain>`. The `running`
+status carries it as an `agent` endpoint beside `endpoints` — separate, because
+`endpoints` are the ports the user's applications declared, and an
+operator-launched container is not one of them. It is reachable without auth for
+as long as the session lives, which is the exposure an app session of the same
+image already has.
+
+**Nothing verifies that the agent listens where `port` says.** `port` tells the
+runner where to route; what the image actually binds is configured separately
+(the authoring agent reads `PORT`, defaulting to 8080). If the two disagree the
+runner publishes a port and routes a host with nothing behind it, and the agent
+appears to start while every request to it fails — neither backend watches the
+agent's port the way both watch an application's. Keep `port` and any `PORT` in
+the entry's `env` in agreement.
+
+**The workspace surface is runner infrastructure, not agent functionality.** It is
+part of the `/v1` session contract, so the runner owns its manifest and its
+routes; the agent is one more writer on the volume beside the app containers,
+using its own filesystem tools. It runs the plain kernel image over a manifest the
+runner reconciles into a content-addressed ConfigMap — there is no third image to
+build, and a runner upgrade that changes the manifest leaves running sessions
+mounting the one they booted with.
+
+**Watch sessions never build an image.** The build path exists to put a dependency
+closure on disk before boot; a watch session resolves its own into the workspace
+volume, which lives as long as the pod, so the download happens once per session
+and every later reload resolves from local disk.
+
+**One cache for the whole session.** The runner seeds `telo-workspace.yaml` at
+the workspace root when the session starts, and the kernel anchors its `.telo`
+cache at the directory holding that marker — so two apps importing the same
+module resolve it once between them, and an app in a subdirectory does not get a
+cache of its own. The application containers therefore carry no `TELO_CACHE_DIR`:
+that variable OUTRANKS the marker, so setting it per app is exactly what would
+undo this. Only the `workspace` container keeps an explicit root, because its own
+manifest lives outside the workspace and the walk-up would never reach the
+marker. A workspace that brings its own marker keeps it — overwriting one with a
+real `modules:` list would change what `telo release` discovers.
+
+**Egress moves into the session namespace.** Module fetches used to be scoped to
+the build namespace; a watch session resolves them itself, so the session
+namespace's NetworkPolicy has to reach module registries as well as the model
+provider. Core NetworkPolicy is CIDR-only and registries sit behind rotating-IP
+CDNs, so a locked-down operator needs a CNI with FQDN policy or an egress proxy
+here — the same stated dependency the build namespace already carries, one
+namespace over.
+
+### Two nouns on one stream
+
+*Session status* (`status` events) is `starting` / `running` / `suspended` /
+`stopped` / `failed`. *Run outcome* (`run` events) is one per app per reload
+generation:
+
+```json
+{ "type": "run", "app": "web", "generation": 3, "phase": "started",   "trigger": "watch" }
+{ "type": "run", "app": "web", "generation": 3, "phase": "completed", "code": 0, "durationMs": 412 }
+{ "type": "run", "app": "worker", "generation": 4, "phase": "failed", "reason": "ERR_MANIFEST_VALIDATION_FAILED" }
+```
+
+A one-shot Runnable finishing emits `run` with `phase: "completed"` and leaves
+`status: running` — the session is alive and the next edit starts that app's next
+generation. `generation` is monotonic per app and starts at 1.
+
+Those events are **projected** from the kernel debug stream, not parsed out of the
+terminal: a watch session always runs with `--inspect` on, and `Kernel.Starting` /
+`Kernel.Stopped` bracket each generation on one debug connection that survives
+reloads. The one thing that stream did not carry is a manifest that fails to load
+at all, so the CLI now emits `Kernel.RunFailed` (`{ phase: "load" | "start", code?,
+message }`) — a dotted event name inside an existing frame kind, so it obliges no
+other runtime.
+
+### Routes
+
+| Route | Purpose |
+| --- | --- |
+| `GET /v1/sessions/:id/workspace` | Content-hash tree the editor diffs against its own files |
+| `POST /v1/sessions/:id/workspace` | Apply a `{ write: [{path, content, encoding?}], delete: [path] }` change set |
+| `GET /v1/sessions/:id/workspace/file?path=` | One file's contents |
+| `POST /v1/sessions/:id/reload?app=<name>` | Re-run one app with no file change (omit `app` for all) |
+| `PUT /v1/sessions/:id/apps` | Change the running app set (checkpoint + pod recreate) |
+| `POST /v1/sessions/:id/resume` | Bring a suspended session back under the same id |
+
+### A port set that changes on reload
+
+Adding a `ports:` entry is as ordinary an edit as adding an import, and a
+container may bind any port regardless of what the pod spec declares — so without
+handling, the app listens and is simply unreachable: no ingress, no error, no
+event.
+
+The kernel re-resolves its `ports:` block on every load and says so on the stream
+the runner is already reading (`Kernel.PortsResolved`), so nothing re-parses a
+manifest on the reload path. The runner patches the Service and the Ingress live
+and emits an `endpoints` event; a pod's `containerPort` list is documentation, so
+this costs no pod recreate. A port another app in the session already declares
+cannot be routed — session hosts carry no app name — and comes back on that same
+event as `rejected` rather than being dropped.
+
+It routes the DECLARED set, not what happened to bind. A port the manifest never
+declared is not exposed, and "did anything actually bind it" is already answered
+per port by the reachability watcher (`checking` → `reachable` / `unreachable`).
+Keying on a listening event instead would rest on a per-module convention: a
+transport whose kind does not emit one would silently get no routing.
+
+### Reload and the app set
+
+`reload` exists because `--watch` reloads on change, and pressing Run again after a
+one-shot app completed is not a change. It touches the named app's entry manifest
+through the same path everything else uses, so it needs no signalling into the
+container, no shared PID namespace and no `exec` — **RBAC gains only `configmaps:
+get, create` and `update` on services/ingresses**, the latter so a reload that
+changes an app's declared port set can re-patch its routing. Without that, adding a
+`ports:` entry leaves the app bound to a port with no ingress, no error and no
+event.
+
+Changing the app set costs a pod recreate because a pod's container list is fixed
+at creation. That is the only editing action in the design that costs a pod, and
+it reuses suspend/resume rather than adding a second path.
+
+### Suspend and resume
+
+A session is no longer a pod. With no SSE/WS subscriber for
+`RUNNER_WATCH_IDLE_SECONDS`, the runner snapshots the workspace, deletes the pod
+and keeps the session record — `status: suspended`, which is deliberately **not**
+terminal. `POST /v1/sessions/:id/resume` creates a fresh pod seeded from that
+checkpoint under the same session id. Aggressive reaping is what makes per-visitor
+watch sessions affordable, and the checkpoint is what makes aggressive reaping
+safe; they only work as a pair.
+
+**The editor holds the authoritative workspace; the checkpoint is a cache.** The
+runner is a single replica with an in-memory registry, so a redeploy, crash or
+node move drops every suspended session and `resume` answers `404`. That is by
+design and it buys less than it looks: a durable suspended workspace is only
+meaningful when there is an identity to reattach it to, and accounts are an
+explicit non-goal. A watch session exists because an editor is driving it, that
+editor already holds every file and already diffs its own copy against
+`GET /workspace`, so a `404` costs one change set. Two consequences, stated rather
+than discovered: a suspended session is best-effort, and a watch session with no
+editor attached and unsaved agent writes is the one place work can be lost —
+bounded by `RUNNER_WORKSPACE_CHECKPOINT_SECONDS`.
+
+**Capacity changes shape.** Concurrency becomes bounded by simultaneous *editors*
+rather than simultaneous *runs*; the run-session ceilings were sized for the
+opposite assumption, which is why watch has its own.
+
+### `io` — terminal or separated streams
+
+Each app declares `io: "tty"` (default) or `io: "streams"`. The difference is
+observable **to the application**, not just to the client: `isatty()` drives
+colour, line-versus-block buffering, progress bars and prompts, so a loop that is
+always a PTY systematically hides how the app behaves in production.
+
+| | `tty` | `streams` |
+| --- | --- | --- |
+| Output | One merged stream, as a terminal produces | Separated at the source |
+| `/io` resize | Yes | Rejected — meaningless without a PTY |
+| `CLICOLOR_FORCE` | Injected | **Not** injected |
+
+Nothing is invented at the transport layer: the Pod `attach` subresource without a
+TTY already gives separate stdout and stderr channels. The TTY is what collapses
+it. `streams` forces nothing *off* either — with no terminal the colour precedence
+already resolves to no colour, and an explicit `NO_COLOR` would sit above an app's
+own `color: always` and suppress a decision worth observing.
+
+`GET /v1/sessions/:id/io?app=<name>` attaches to one app's terminal; `?app=` is
+required whenever the session runs more than one, since there is no defensible
+default among several. Every binary frame is `[seq:4 BE][stream:1][payload]`.
+
+### Ports are unique across the whole session
+
+Session hosts are `<port>-<sessionId>.<base-domain>`, a single label, so two apps
+both listening on 3000 would collide with nothing to distinguish them. That is a
+`400 port_conflict` at session create rather than an app name added to the host
+scheme: the user controls both manifests, and a rejected request is a better
+outcome than a URL that silently reaches the wrong app.
+
 ## Configuration (env)
 
 | Env | Default | Purpose |
@@ -74,7 +288,7 @@ image is single-tenant, so install scripts run normally inside the trusted build
 | `PORT` | `8062` | HTTP listen port |
 | `RUNNER_DISPLAY_NAME` | `Telo Runner` | Display name advertised on `/v1/capabilities` (the editor's runner label) |
 | `RUNNER_DESCRIPTION` | `Runs the Telo application in a cloud environment` | Description advertised on `/v1/capabilities` |
-| `RUNNER_APPS` | _(unset → no apps)_ | JSON map of operator-predefined apps launchable by name (chart: inline `apps.catalog`, or `apps.catalogSecret` referencing a Secret holding the JSON — use the Secret whenever entries embed secrets in `env`); see the docker-runner README for the entry shape. App sessions run the catalog image directly as a pod — no on-cluster build |
+| `RUNNER_APPS` | _(unset → no apps)_ | JSON map of operator-predefined apps launchable by name (chart: inline `apps.catalog`, or `apps.catalogSecret` referencing a Secret holding the JSON — use the Secret whenever entries embed secrets in `env`); see the docker-runner README for the entry shape, including the `port` an entry must declare to be usable as a session's co-resident `agent`. App sessions run the catalog image directly as a pod — no on-cluster build |
 | `RUNNER_APP_MAX_CPU` | `500m` | CPU ceiling for predefined-app pods (separate from the anonymous-session ceiling) |
 | `RUNNER_APP_MAX_MEMORY` | `512Mi` | Memory ceiling for predefined-app pods |
 | `RUNNER_APP_MAX_TTL_SECONDS` | `21600` | Wall-clock TTL for predefined-app pods (agent sessions are long-lived) |
@@ -90,6 +304,13 @@ image is single-tenant, so install scripts run normally inside the trusted build
 | `RUNNER_MAX_TTL_SECONDS` | `3600` | Wall-clock TTL (Pod `activeDeadlineSeconds`) |
 | `RUNNER_MAX_EPHEMERAL_STORAGE` | `512Mi` | Per-Pod ephemeral-storage ceiling |
 | `RUNNER_MAX_SESSIONS` | `32` | Global session backstop; at capacity the oldest exited session is evicted before a new run is rejected |
+| `RUNNER_WATCH_SESSIONS` | `false` | Server-side gate. Watch sessions are never client-requestable when off |
+| `RUNNER_WATCH_IDLE_SECONDS` | `300` | No SSE/WS subscriber for this long → suspend |
+| `RUNNER_WATCH_MAX_TTL_SECONDS` | `21600` | Pod deadline for a watch session. One deadline covers the agent and the app containers, so it takes the longer ceiling and lets idleness do the real work |
+| `RUNNER_WATCH_MAX_SESSIONS` | `8` | Concurrency ceiling for watch sessions, separate from `RUNNER_MAX_SESSIONS` |
+| `RUNNER_WATCH_RELOAD_LIMIT` | `30` | Per-session reloads per minute |
+| `RUNNER_WATCH_SUSPENDED_TTL_SECONDS` | `86400` | How long a suspended session record is retained before eviction. Deliberately not the pod deadline: that bounds a pod, so on its own nothing would ever evict a suspended record |
+| `RUNNER_WORKSPACE_CHECKPOINT_SECONDS` | `30` | How often the runner pulls a whole-tree workspace snapshot |
 | `RUNNER_EXIT_TTL_MS` | `14400000` | How long exited sessions stay in the registry (so the editor can re-attach and replay their history after a reload) before eviction |
 | `RUNNER_TERMS_FILE` | _(unset)_ | Path to the agreement file (plain text / markdown), read at startup — mount it from a `ConfigMap` (e.g. `/etc/telo/terms.md`). Setting this (or `RUNNER_TERMS_BODY`) enables terms: the runner advertises them on `/v1/capabilities` and rejects `POST /v1/sessions` with `428` unless the client sends `x-telo-accepted-terms` matching the version. An unreadable path fails startup. The public cloud should set this |
 | `RUNNER_TERMS_BODY` | _(unset)_ | Inline agreement text, for short notes; ignored when `RUNNER_TERMS_FILE` is set |

package/dist/capabilities.d.ts

@@ -7,6 +7,11 @@ export interface KubernetesRunnerCapabilitiesOptions {
     defaultImage: string;
     terms?: RunnerTerms;
     imageEnum?: string[];
+    /** Whether the operator enabled watch sessions. Advertised so a client knows
+     *  before it asks — a runner with watch off rejects the field. */
+    watch: boolean;
+    /** Catalog names admissible as a session's co-resident `agent`. */
+    agents?: string[];
 }
 /** What k8s-runner advertises on `/v1/capabilities`. The runner serves
  *  untrusted/anonymous code under a hard-ceiling policy. `image` is a base-image

package/dist/capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,mCAAmC;IAClD;wDACoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;;;6EAW6E;AAC7E,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,mCAAmC,GACxC,kBAAkB,CAiBpB"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,WAAW,EACjB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,mCAAmC;IAClD;wDACoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB;sEACkE;IAClE,KAAK,EAAE,OAAO,CAAC;IACf,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;6EAW6E;AAC7E,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,mCAAmC,GACxC,kBAAkB,CAyBpB"}

package/dist/capabilities.js

@@ -16,7 +16,15 @@ export function kubernetesRunnerCapabilities(opts) {
     return {
         displayName,
         description,
-        features: { io: true, ports: true },
+        features: {
+            // Both attach modes: the kubernetes attach subresource without a TTY
+            // already gives separate stdout and stderr channels, so `streams` invents
+            // nothing at the transport layer.
+            io: ["tty", "streams"],
+            ports: true,
+            watch: opts.watch,
+            ...(opts.agents && opts.agents.length > 0 ? { agents: opts.agents } : {}),
+        },
         config: {
             schema: sessionConfigSchema({
                 imageDefault: defaultImage,

package/dist/capabilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,GAGpB,MAAM,sBAAsB,CAAC;AAY9B;;;;;;;;;;;6EAW6E;AAC7E,MAAM,UAAU,4BAA4B,CAC1C,IAAyC;IAEzC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC1E,OAAO;QACL,WAAW;QACX,WAAW;QACX,QAAQ,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE;QACnC,MAAM,EAAE;YACN,MAAM,EAAE,mBAAmB,CAAC;gBAC1B,YAAY,EAAE,YAAY;gBAC1B,QAAQ,EAAE,IAAI;gBACd,SAAS;gBACT,qBAAqB,EACnB,iKAAiK;aACpK,CAAC;SACH;QACD,KAAK;KACN,CAAC;AACJ,CAAC"}
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,GAGpB,MAAM,sBAAsB,CAAC;AAiB9B;;;;;;;;;;;6EAW6E;AAC7E,MAAM,UAAU,4BAA4B,CAC1C,IAAyC;IAEzC,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IAC1E,OAAO;QACL,WAAW;QACX,WAAW;QACX,QAAQ,EAAE;YACR,qEAAqE;YACrE,0EAA0E;YAC1E,kCAAkC;YAClC,EAAE,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC;YACtB,KAAK,EAAE,IAAI;YACX,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1E;QACD,MAAM,EAAE;YACN,MAAM,EAAE,mBAAmB,CAAC;gBAC1B,YAAY,EAAE,YAAY;gBAC1B,QAAQ,EAAE,IAAI;gBACd,SAAS;gBACT,qBAAqB,EACnB,iKAAiK;aACpK,CAAC;SACH;QACD,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/k8s/backend.d.ts

@@ -2,18 +2,11 @@ import type { RunnerBackend } from "@telorun/runner-core";
 import type { BundleStore } from "../bundle-store.js";
 import type { K8sRunnerConfig } from "../config.js";
 import type { KubeClient } from "./client.js";
+export { podFailureMessage } from "./pod-status.js";
 export interface K8sBackendDeps {
     kube: KubeClient;
     config: K8sRunnerConfig;
     bundleStore: BundleStore;
 }
 export declare function createKubernetesBackend(deps: K8sBackendDeps): RunnerBackend;
-/**
- * Builds an actionable failure message from a terminal Pod status. Init
- * containers are inspected first: a failed init container leaves the main
- * container unstarted, so reading only `containerStatuses` would fall through
- * to the bare "pod failed". For prebuilt session pods the common failure is the
- * main container itself (image pull, OOM, a non-zero exit).
- */
-export declare function podFailureMessage(obj: unknown): string;
 //# sourceMappingURL=backend.d.ts.map

package/dist/k8s/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/k8s/backend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAMV,aAAa,EACd,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAkB9C,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CA0X3E;AAiGD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAOtD"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/k8s/backend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAOV,aAAa,EACd,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAgB9C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAepD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;CAC1B;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CA0Y3E"}

package/dist/k8s/backend.js

@@ -4,6 +4,9 @@ import { clampLimits } from "../limits.js";
 import { ensureSessionImage } from "./image-build.js";
 import { buildSessionIngress, buildSessionService, endpointsFor } from "./ingress.js";
 import { buildAppPod, buildSessionPod, INSPECT_PORT } from "./pod-spec.js";
+import { deletePod, is404, msg, podFailureMessage, podStatus, podPhase, provisionMessage, terminalStatus, } from "./pod-status.js";
+import { startWatchSession } from "./watch-session.js";
+export { podFailureMessage } from "./pod-status.js";
 const RESIZE_CHANNEL = 4;
 /** How long a Pod may take to reach Running before the start is abandoned.
  *  activeDeadlineSeconds only bounds an already-running Pod, so a stuck
@@ -13,7 +16,7 @@ const WATCH_REARM_DELAY_MS = 2_000;
 export function createKubernetesBackend(deps) {
     const { kube, config, bundleStore } = deps;
     const ns = config.sessionNamespace;
-    async function probe(_probe) {
+    async function probe(probeConfig) {
         try {
             await kube.core.readNamespace({ name: ns });
         }
@@ -35,7 +38,22 @@ export function createKubernetesBackend(deps) {
         return { status: "ready" };
     }
     async function start(spec) {
+        // A watch session is a different pod shape and a different lifetime — it
+        // outlives its runs — so it takes its own path rather than accreting
+        // branches through this one. It also never builds an image: the build path
+        // exists to put a dependency closure on disk before boot, and a watch
+        // session fetches its own and keeps it for the pod's life.
+        if (spec.mode === "watch") {
+            return startWatchSession({ kube, config }, spec);
+        }
+        return startRunSession(spec);
+    }
+    async function startRunSession(spec) {
         const podName = `telo-run-${spec.sessionId}`;
+        // A run session is one application by construction — `apps` carries exactly
+        // one entry, defaulted by core when the request declared none.
+        const app = spec.apps[0];
+        const appName = app.name;
         // The /v1 contract carries no per-request limits yet, so `requested` is
         // undefined and the configured ceiling is always the effective limit. When
         // a control plane begins passing limits, plumb them here — the clamp is
@@ -52,7 +70,7 @@ export function createKubernetesBackend(deps) {
                 sessionId: spec.sessionId,
                 podName,
                 env: spec.env,
-                ports: spec.ports,
+                ports: app.ports,
                 limits,
                 image: spec.config.image,
                 pullPolicy: spec.config.pullPolicy,
@@ -72,10 +90,10 @@ export function createKubernetesBackend(deps) {
                 managedByLabel: config.managedByLabel,
             }, {
                 bundle: spec.bundle,
-                entryRelativePath: spec.entryRelativePath,
+                entryRelativePath: app.entryRelativePath,
                 baseImage: spec.config.image || config.defaultImage,
                 pullPolicy: spec.config.pullPolicy,
-                onProgress: (message, done) => spec.onProgress("build", message, done),
+                onProgress: (message, done) => spec.onProgress("build", message, done, appName),
             });
             // The image is keyed on the dependency closure only, so deliver the
             // per-session body to the Pod's /app at boot via a tokenized, single-use URL.
@@ -84,9 +102,9 @@ export function createKubernetesBackend(deps) {
                 config,
                 sessionId: spec.sessionId,
                 podName,
-                entryRelativePath: spec.entryRelativePath,
+                entryRelativePath: app.entryRelativePath,
                 env: spec.env,
-                ports: spec.ports,
+                ports: app.ports,
                 limits,
                 image,
                 bundleUrl,
@@ -115,9 +133,9 @@ export function createKubernetesBackend(deps) {
         const reachAbort = new AbortController();
         const stdin = new PassThrough();
         const stdout = new Writable({
-            write(chunk, _enc, cb) {
+            write(chunk, encoding, cb) {
                 if (chunk?.byteLength)
-                    spec.onOutput(Buffer.from(chunk));
+                    spec.onOutput(appName, Buffer.from(chunk), "tty");
                 cb();
             },
         });
@@ -154,7 +172,7 @@ export function createKubernetesBackend(deps) {
             if (readyFlipped || finished)
                 return;
             readyFlipped = true;
-            spec.onStatus({ kind: "running", endpoints: endpointsFor(config, spec.sessionId, spec.ports) });
+            spec.onStatus({ kind: "running", endpoints: endpointsFor(config, spec.sessionId, app.ports) });
         };
         let resolveRunning;
         let rejectRunning;
@@ -171,7 +189,7 @@ export function createKubernetesBackend(deps) {
                 const provision = provisionMessage(obj);
                 if (provision && provision !== lastProvision) {
                     lastProvision = provision;
-                    spec.onProgress("provision", provision);
+                    spec.onProgress("provision", provision, undefined, appName);
                 }
             }
             if (phase === "Running" && !runningSeen) {
@@ -219,7 +237,7 @@ export function createKubernetesBackend(deps) {
             if (finished)
                 return;
             try {
-                const req = await kube.watch.watch(`/api/v1/namespaces/${ns}/pods`, { fieldSelector: `metadata.name=${podName}` }, (_type, obj) => handlePhase(obj), () => {
+                const req = await kube.watch.watch(`/api/v1/namespaces/${ns}/pods`, { fieldSelector: `metadata.name=${podName}` }, (type, obj) => handlePhase(obj), () => {
                     if (finished)
                         return;
                     void reconcileOnce().then(() => {
@@ -270,11 +288,11 @@ export function createKubernetesBackend(deps) {
         }
         catch (err) {
             // Attach failure isn't fatal — status still flows; surface the degraded PTY.
-            spec.onOutput(Buffer.from(`\r\n[runner] failed to attach PTY: ${msg(err)}\r\n`));
+            spec.onOutput(appName, Buffer.from(`\r\n[runner] failed to attach PTY: ${msg(err)}\r\n`), "tty");
         }
-        if (config.sessionIngressBaseDomain && spec.ports.length > 0) {
-            await createIngress(deps, spec.sessionId, podName, podUid, spec.ports).catch((err) => {
-                spec.onOutput(Buffer.from(`\r\n[runner] failed to create ingress: ${msg(err)}\r\n`));
+        if (config.sessionIngressBaseDomain && app.ports.length > 0) {
+            await createIngress(deps, spec.sessionId, podName, podUid, app.ports).catch((err) => {
+                spec.onOutput(appName, Buffer.from(`\r\n[runner] failed to create ingress: ${msg(err)}\r\n`), "tty");
             });
         }
         // The Running watch event usually carries `podIP`; if it lagged, read the
@@ -296,19 +314,19 @@ export function createKubernetesBackend(deps) {
             if (ip) {
                 void relayDebugStream({
                     url: `http://${ip}:${INSPECT_PORT}/events`,
-                    onFrame: spec.onDebug,
+                    onFrame: (frame) => spec.onDebug(appName, frame),
                     signal: debugAbort.signal,
                 });
             }
             else {
-                spec.onOutput(Buffer.from("\r\n[runner] debug stream unavailable: pod IP unknown\r\n"));
+                spec.onOutput(appName, Buffer.from("\r\n[runner] debug stream unavailable: pod IP unknown\r\n"), "tty");
             }
         }
         // Reachability check: a workload bound to 127.0.0.1 (or listening on the
         // wrong port) is unreachable on the pod network and surfaces only as a
         // downstream 502. Watch each advertised tcp port from the runner and report
         // per-port state to studio's endpoint badge. Background; finish() aborts it.
-        const tcpPorts = spec.ports.filter((p) => p.protocol === "tcp").map((p) => p.port);
+        const tcpPorts = app.ports.filter((p) => p.protocol === "tcp").map((p) => p.port);
         if (tcpPorts.length > 0) {
             void (async () => {
                 const ip = await resolvePodIP();
@@ -318,13 +336,13 @@ export function createKubernetesBackend(deps) {
                     // Couldn't resolve the pod IP to probe — report unverified rather than
                     // leaving the badge spinning forever.
                     for (const port of tcpPorts)
-                        spec.onReachability(port, "unreachable");
+                        spec.onReachability(appName, port, "unreachable");
                     return;
                 }
                 await watchReachability({
                     host: ip,
                     ports: tcpPorts,
-                    onState: (port, state) => spec.onReachability(port, state),
+                    onState: (port, state) => spec.onReachability(appName, port, state),
                     signal: reachAbort.signal,
                 });
             })();
@@ -332,7 +350,7 @@ export function createKubernetesBackend(deps) {
         // `flipRunning` already announced `running` from the watch's Running
         // transition (which `await running` above waited on).
         return {
-            writeStdin(bytes) {
+            writeStdin(app, bytes) {
                 try {
                     stdin.write(Buffer.from(bytes));
                 }
@@ -340,7 +358,7 @@ export function createKubernetesBackend(deps) {
                     /* stream ended */
                 }
             },
-            resize(cols, rows) {
+            resize(app, cols, rows) {
                 if (!socket)
                     return;
                 try {
@@ -397,16 +415,6 @@ async function createIngress(deps, sessionId, podName, podUid, ports) {
         return;
     await kube.networking.createNamespacedIngress({ namespace: ns, body: ingress });
 }
-async function deletePod(kube, ns, name) {
-    try {
-        await kube.core.deleteNamespacedPod({ name, namespace: ns, gracePeriodSeconds: 0 });
-    }
-    catch (err) {
-        // 404 = already gone (natural exit + GC). Anything else is a real failure.
-        if (!is404(err))
-            throw err;
-    }
-}
 async function clusterReachable(kube) {
     try {
         await kube.core.listNamespace();
@@ -416,124 +424,4 @@ async function clusterReachable(kube) {
         return false;
     }
 }
-function podStatus(obj) {
-    return obj?.status;
-}
-function podPhase(obj) {
-    return podStatus(obj)?.phase;
-}
-/** A coming-up message for the studio feed while the Pod is still scheduling /
- *  pulling / delivering the body / creating the container; undefined once running. */
-function provisionMessage(obj) {
-    const status = podStatus(obj);
-    if (status?.phase !== "Pending")
-        return undefined;
-    const containers = [
-        ...(status.initContainerStatuses ?? []),
-        ...(status.containerStatuses ?? []),
-    ];
-    for (const cs of containers) {
-        const reason = cs.state?.waiting?.reason;
-        if (reason)
-            return humanizeWaitReason(reason);
-    }
-    return "Scheduling";
-}
-function humanizeWaitReason(reason) {
-    switch (reason) {
-        case "ContainerCreating":
-            return "Creating container";
-        case "PodInitializing":
-            return "Delivering application";
-        case "ErrImagePull":
-        case "ImagePullBackOff":
-            return "Pulling image";
-        default:
-            return reason;
-    }
-}
-function terminalStatus(obj, userStopped) {
-    if (userStopped)
-        return { kind: "stopped" };
-    const phase = podPhase(obj);
-    if (phase === "Succeeded")
-        return { kind: "exited", code: containerExitCode(obj) ?? 0 };
-    return { kind: "failed", message: podFailureMessage(obj) };
-}
-// Exit code of the main session container — used to report a clean exit.
-function containerExitCode(obj) {
-    const term = podStatus(obj)?.containerStatuses?.[0]?.state?.terminated;
-    return typeof term?.exitCode === "number" ? term.exitCode : null;
-}
-const MAX_FAILURE_DETAIL = 500;
-/**
- * Builds an actionable failure message from a terminal Pod status. Init
- * containers are inspected first: a failed init container leaves the main
- * container unstarted, so reading only `containerStatuses` would fall through
- * to the bare "pod failed". For prebuilt session pods the common failure is the
- * main container itself (image pull, OOM, a non-zero exit).
- */
-export function podFailureMessage(obj) {
-    const status = podStatus(obj);
-    const fromContainer = firstContainerProblem(status);
-    if (fromContainer)
-        return fromContainer;
-    if (status?.message)
-        return truncateDetail(status.message);
-    if (status?.reason)
-        return status.reason;
-    return "pod failed";
-}
-function firstContainerProblem(status) {
-    const groups = [
-        ["init container", status?.initContainerStatuses],
-        ["container", status?.containerStatuses],
-    ];
-    for (const [label, statuses] of groups) {
-        for (const cs of statuses ?? []) {
-            const problem = containerStateProblem(cs.state) ?? containerStateProblem(cs.lastState);
-            if (problem)
-                return `${label} "${cs.name}" ${problem}`;
-        }
-    }
-    return undefined;
-}
-function containerStateProblem(state) {
-    const term = state?.terminated;
-    if (term && term.exitCode !== 0) {
-        const reason = term.reason ? `${term.reason} ` : "";
-        const detail = term.message ? `: ${truncateDetail(term.message)}` : "";
-        return `failed: ${reason}(exit code ${term.exitCode ?? "unknown"})${detail}`;
-    }
-    const waiting = state?.waiting;
-    if (waiting?.reason && isBlockingWaitReason(waiting.reason)) {
-        const detail = waiting.message ? `: ${truncateDetail(waiting.message)}` : "";
-        return `waiting: ${waiting.reason}${detail}`;
-    }
-    return undefined;
-}
-// Benign transient reasons the kubelet reports while a Pod is still coming up.
-function isBlockingWaitReason(reason) {
-    return reason !== "PodInitializing" && reason !== "ContainerCreating";
-}
-function truncateDetail(text) {
-    const trimmed = text.trim();
-    return trimmed.length > MAX_FAILURE_DETAIL ? `${trimmed.slice(0, MAX_FAILURE_DETAIL)}…` : trimmed;
-}
-function is404(err) {
-    const e = err;
-    return e?.statusCode === 404 || e?.code === 404 || e?.response?.statusCode === 404;
-}
-function msg(err) {
-    if (err instanceof Error)
-        return err.message;
-    if (typeof err === "string")
-        return err;
-    try {
-        return JSON.stringify(err);
-    }
-    catch {
-        return String(err);
-    }
-}
 //# sourceMappingURL=backend.js.map