@telorun/runner-core 0.8.1 → 0.9.0

package/README.md

@@ -9,6 +9,14 @@ and [`k8s-runner`](../../apps/k8s-runner)). It owns everything about a run
   `/v1/sessions/:id/io` WebSocket PTY);
 - the in-memory **session registry**, event/byte **ring buffers** (SSE + PTY
   replay with gap detection), and bundle-path traversal guards;
+- the **run projection** — per-app run outcomes derived from the kernel
+  lifecycle events already on the debug stream, so the runner never parses a
+  terminal to learn how a run ended;
+- the **watch supervisor** — the workspace checkpoint timer and the idle reaper;
+- the **workspace application** (`workspace-app/telo.yaml`), the manifest a watch
+  session's `workspace` container runs. It lives here because the workspace
+  surface is part of the `/v1` contract: both backends mount the same bytes, and
+  a copy per backend would be two manifests to hold in agreement;
 - graceful-shutdown helpers and base config parsing.
 
 ## The seam: `RunnerBackend`
@@ -25,11 +33,34 @@ interface RunnerBackend {
 }
 ```
 
+Every callback is qualified by the application it belongs to. A session runs one
+container per application — usually exactly one — and each has its own terminal,
+so the byte channel is keyed `(session, app)` rather than labelled on a merged
+stream. A single-app session carries the qualifier too, so no client needs two
+readings.
+
+A watch session's `BackendSession` additionally exposes `workspace`, `reload`,
+`setApps` and `suspend`: it is a workspace that runs continuously rather than one
+run, so its lifetime outlives every run inside it.
+
 Bundle delivery is the backend's responsibility (docker writes a shared-volume
-workdir; k8s stages a tarball for an initContainer fetch), so `start` receives
-the raw `bundle` rather than a pre-resolved path. `buildServer({ backend, config,
+workdir; k8s stages a tarball for an initContainer fetch, and a watch session
+seeds through the workspace container's own routes), so `start` receives the raw
+`bundle` rather than a pre-resolved path. `buildServer({ backend, config,
 version })` wires a backend into the full `/v1` app.
 
+## Two nouns, one stream
+
+`status` is the SESSION's state; `run` is one application's outcome. They are
+separate because a session can outlive its runs: a one-shot Runnable finishing in
+a watch session emits `run` with `phase: "completed"` and leaves `status:
+running`, so the next edit starts that app's next generation.
+
+Workload output travels neither — it goes over the byte channel (`/io`), which
+exists precisely because per-chunk events are wasteful for high-volume output.
+The `stdout` / `stderr` `RunEvent` variants that used to be declared here were
+emitted by nothing; they are gone rather than qualified.
+
 ## Development
 
 ```bash

package/dist/backend.d.ts

@@ -1,5 +1,6 @@
 import type { DebugFrame } from "@telorun/debug-wire";
-import type { AvailabilityReport, PortMapping, ProbeConfig, ReachabilityState, RunBundle, RunPhase, RunStatus, SessionConfig } from "./contract.js";
+import type { ResolvedRunnerApp } from "./config.js";
+import type { AvailabilityReport, ByteStreamTag, IoMode, PortMapping, ProbeConfig, ReachabilityState, RunBundle, RunnerEndpoint, RunPhase, RunStatus, SessionConfig, SessionMode, WorkspaceChangeSet, WorkspaceCheckpointFile, WorkspaceTree } from "./contract.js";
 /**
  * The seam between backend-neutral session machinery (routes, registry, SSE)
  * and a concrete workload runtime (docker container, kubernetes pod).
@@ -26,55 +27,138 @@ export interface RunnerBackend {
      *  in-memory, so a restart otherwise leaks running workloads. */
     reapOrphans?(): Promise<void>;
 }
-export interface BackendStartSpec {
-    sessionId: string;
-    bundle: RunBundle;
-    /** Bundle-relative entry path, already traversal-normalized by core. */
+/** One application container the backend must stand up. */
+export interface BackendAppSpec {
+    name: string;
+    /** Bundle-relative entry path, already traversal-normalized by core. Empty for
+     *  a self-contained app session, where the image's own entrypoint runs. */
     entryRelativePath: string;
-    env: Record<string, string>;
     ports: PortMapping[];
+    io: IoMode;
+}
+/**
+ * The DATA half of a workload launch — everything a start needs that is not a
+ * callback. Retained on the session entry so `resume` can build a fresh pod
+ * under the same session id from the same description, rather than a second,
+ * drifting copy of it.
+ */
+export interface WorkloadLaunch {
+    bundle: RunBundle;
+    env: Record<string, string>;
     config: SessionConfig;
     /** True for an operator-predefined app session (`POST /v1/apps/:name/sessions`):
      *  `config.image` is self-contained (app + controllers baked in), so the
      *  backend runs the image's own entrypoint and stages no bundle — `bundle`
      *  is an empty placeholder. */
     selfContained: boolean;
-    /** When true, launch the workload with `--inspect` and relay its kernel debug
+    /** When true, launch each app with `--inspect` and relay its kernel debug
      *  stream via `onDebug`. The inspect endpoint stays reachable only by the
-     *  runner — never published outward. */
+     *  runner — never published outward. Always true for a watch session: that
+     *  stream is where `run` events are projected from. */
     inspect: boolean;
+    /** `run` (one pod, terminal on exit, today's shape) or `watch` (a workspace
+     *  volume, `telo run --watch` per app, the pod outliving its runs). */
+    mode: SessionMode;
+    /** The applications to run, one container each. Never empty — core defaults a
+     *  request with no `apps` to a single entry. */
+    apps: BackendAppSpec[];
+    /** The resolved catalog entry for a co-resident agent container, when one was
+     *  requested. Its operator env goes on THAT container and nowhere else — the
+     *  credential boundary used to be structural (two pods) and is now a code
+     *  invariant (containers in one pod). */
+    agent?: ResolvedRunnerApp;
+}
+export interface BackendStartSpec extends WorkloadLaunch {
+    sessionId: string;
     /** Emit a lifecycle status. The backend drives `starting` → `running` →
-     *  terminal (`exited`/`failed`/`stopped`). */
+     *  terminal (`exited`/`failed`/`stopped`), or `suspended` on an idle reap. */
     onStatus(status: RunStatus): void;
     /** Emit a progress message for a coming-up phase (build / provision / boot).
      *  Additive to status — surfaces what's happening while the session is still
-     *  `starting`, driving the editor's spinner + step feed. */
-    onProgress(phase: RunPhase, message: string, done?: boolean): void;
-    /** Raw merged stdout/stderr (PTY) bytes from the workload. */
-    onOutput(chunk: Buffer): void;
-    /** A frame relayed from the workload's kernel debug stream. Only called when
-     *  `inspect` is true and the backend has connected to the inspect endpoint. */
-    onDebug(frame: DebugFrame): void;
+     *  `starting`. `app` is omitted for session-scoped provisioning. */
+    onProgress(phase: RunPhase, message: string, done?: boolean, app?: string): void;
+    /** Bytes from one app's terminal. `stream` is `tty` under a terminal attach
+     *  and `stdout`/`stderr` only where the transport genuinely separated them. */
+    onOutput(app: string, chunk: Buffer, stream: ByteStreamTag): void;
+    /** A frame relayed from one app's kernel debug stream. Only called when
+     *  `inspect` is true and the backend has connected to that app's endpoint. */
+    onDebug(app: string, frame: DebugFrame): void;
     /** Report a declared port's reachability from the runner network — `checking`
      *  while the workload comes up, then `reachable`, or `unreachable` after a
      *  timeout. Surfaced on the editor's endpoint badge, not the log stream. */
-    onReachability(port: number, state: ReachabilityState): void;
+    onReachability(app: string, port: number, state: ReachabilityState): void;
+    /** One app's workload ended on its own. A run session's workload ending IS the
+     *  session ending, so this is a watch-session concern: under `--watch` a
+     *  finished run leaves the container up, and a container that goes away has
+     *  died. Reported through the contract rather than by synthesizing a kernel
+     *  frame — that stream's contract is "frames relayed from the workload", and a
+     *  backend writing into it puts an event on the wire no kernel emitted. */
+    onRunEnded(app: string, outcome: {
+        code?: number;
+        reason?: string;
+    }): void;
+    /** An app's routable endpoint set changed after a reload re-read its declared
+     *  ports. */
+    onEndpoints(app: string, change: {
+        added?: RunnerEndpoint[];
+        removed?: RunnerEndpoint[];
+        rejected?: Array<{
+            port: number;
+            reason: string;
+        }>;
+    }): void;
     /** True once a user stop / shutdown has been requested — lets the backend
      *  classify a kill as `stopped` rather than `failed`. */
     isUserStopped(): boolean;
 }
 export interface BackendSession {
-    /** Write bytes to the workload's stdin (PTY). A no-op once the workload has
-     *  terminated, so callers need not track liveness. */
-    writeStdin(bytes: Uint8Array): void;
-    /** Resize the workload's PTY. */
-    resize(cols: number, rows: number): void;
+    /** Write bytes to one app's stdin. A no-op once that workload has terminated,
+     *  so callers need not track liveness. */
+    writeStdin(app: string, bytes: Uint8Array): void;
+    /** Resize one app's PTY. A no-op for an app running under `io: "streams"` —
+     *  the route rejects such a resize before it reaches here. */
+    resize(app: string, cols: number, rows: number): void;
     /** Resolves after the workload terminates and its terminal status has been
      *  emitted via `onStatus`. Never rejects — terminal failures surface as a
-     *  `failed` status. */
+     *  `failed` status. A watch session's workload outlives its runs, so this
+     *  settles only on stop, suspend, or the pod deadline. */
     readonly done: Promise<void>;
     /** Force-stop the workload. Idempotent and safe to call after natural exit
      *  (a backend should treat an already-gone workload as a no-op). */
     stop(): Promise<void>;
+    /** The workspace surface, present only on a watch session. Everything outside
+     *  the pod writes through here; the agent (inside it) writes the volume with
+     *  its own filesystem tools. */
+    readonly workspace?: WorkspaceAccess;
+    /** Re-run one app with no file change (`POST /v1/sessions/:id/reload`), by
+     *  touching its entry manifest through the same path every other write takes.
+     *  No signalling into the container, no shared PID namespace, no `exec` — RBAC
+     *  is unchanged. Watch sessions only. */
+    reload?(app: string): Promise<void>;
+    /** Replace the running app set. A pod's container list is fixed at creation,
+     *  so this checkpoints, deletes the pod and creates one with the new set —
+     *  the suspend/resume path, reused because it has to be. */
+    setApps?(apps: BackendAppSpec[]): Promise<void>;
+    /** Delete the workload, keeping nothing but what the caller already
+     *  checkpointed. `resume` builds a fresh one from that checkpoint. */
+    suspend?(): Promise<void>;
+}
+/** The `workspace` container's routes, proxied by the runner. Reading and
+ *  applying a change set are the only two shapes: a single-file write route
+ *  would be a second set of concurrency rules over the same directory. */
+export interface WorkspaceAccess {
+    tree(): Promise<WorkspaceTree>;
+    readFile(path: string): Promise<{
+        content: string;
+        size: number;
+    }>;
+    apply(changes: WorkspaceChangeSet): Promise<{
+        written: number;
+        deleted: number;
+    }>;
+    /** Whole-tree pull for the checkpoint timer and for suspend. Whole tree rather
+     *  than a delta log: a manifest workspace is small, and one shape is easier to
+     *  reason about than a replay that has to be correct. */
+    snapshot(): Promise<WorkspaceCheckpointFile[]>;
 }
 //# sourceMappingURL=backend.d.ts.map

package/dist/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,QAAQ,EACR,SAAS,EACT,aAAa,EACd,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B;wEACoE;IACpE,KAAK,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAExD;;8DAE0D;IAC1D,KAAK,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAEvD;;qEAEiE;IACjE,WAAW,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,CAAC;IAClB,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,MAAM,EAAE,aAAa,CAAC;IACtB;;;mCAG+B;IAC/B,aAAa,EAAE,OAAO,CAAC;IACvB;;4CAEwC;IACxC,OAAO,EAAE,OAAO,CAAC;IAEjB;kDAC8C;IAC9C,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAClC;;gEAE4D;IAC5D,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACnE,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;mFAC+E;IAC/E,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACjC;;gFAE4E;IAC5E,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAC7D;6DACyD;IACzD,aAAa,IAAI,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B;0DACsD;IACtD,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAEpC,iCAAiC;IACjC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzC;;2BAEuB;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7B;wEACoE;IACpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -11,6 +11,32 @@ export interface RunnerCoreConfig {
     exitTtlMs: number;
     replayBufferBytes: number;
     corsOrigins: string[] | "*";
+    watch: WatchSessionConfig;
+}
+/**
+ * Watch-session policy. Off by default and separately ceilinged, because a watch
+ * session is a materially different resource shape from a run: a pod that
+ * outlives its runs, whose concurrency is bounded by simultaneous EDITORS rather
+ * than simultaneous runs. Inheriting a run session's ceilings would size it for
+ * the opposite assumption.
+ */
+export interface WatchSessionConfig {
+    /** Server-side gate. Watch sessions are never client-requestable when off. */
+    enabled: boolean;
+    /** No SSE/WS subscriber for this long → suspend (pod deleted, checkpoint held). */
+    idleMs: number;
+    /** Pod deadline for a watch session. The agent and app containers share one
+     *  pod, so one deadline covers both: take the longer (agent) ceiling and let
+     *  idleness do the real work, or the conversation dies at an hour mid-turn. */
+    maxTtlSeconds: number;
+    maxSessions: number;
+    reloadLimitPerMinute: number;
+    /** How long a SUSPENDED 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. */
+    suspendedTtlMs: number;
+    /** How often the runner pulls a whole-tree workspace snapshot. */
+    checkpointMs: number;
 }
 export declare class RunnerConfigError extends Error {
 }
@@ -76,4 +102,5 @@ export declare function parseCorsOrigins(raw: string | undefined): string[] | "*
 export declare function loadCoreConfig(env: NodeJS.ProcessEnv, defaults?: {
     port?: number;
 }): RunnerCoreConfig;
+export declare function loadWatchConfig(env: NodeJS.ProcessEnv): WatchSessionConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;CAC7B;AAED,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAE/C,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,MAAM,CAOR;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAM5F;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,WAAW,GAAG,SAAS,CAQhF;AAsBD;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd;;6BAEyB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;wCACoC;IACpC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,CAmB7C;AAkCD;;wEAEwE;AACxE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAc1F;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,GAAG,CAMxE;AAED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,QAAQ,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,gBAAgB,CAiBlB"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IAC5B,KAAK,EAAE,kBAAkB,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAC;IACjB,mFAAmF;IACnF,MAAM,EAAE,MAAM,CAAC;IACf;;mFAE+E;IAC/E,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;8BAE0B;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAE/C,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,GACZ,MAAM,CAOR;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAM5F;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAO3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,WAAW,GAAG,SAAS,CAQhF;AAsBD;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd;;6BAEyB;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B;wCACoC;IACpC,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,SAAS,CAmB7C;AAkCD;;wEAEwE;AACxE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAc1F;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,GAAG,CAMxE;AAED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,QAAQ,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,gBAAgB,CAkBlB;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,kBAAkB,CA6B1E"}

package/dist/config.js

@@ -165,6 +165,18 @@ export function loadCoreConfig(env, defaults = {}) {
         exitTtlMs: parsePositiveInt(env.RUNNER_EXIT_TTL_MS, 4 * 60 * 60 * 1000, "RUNNER_EXIT_TTL_MS"),
         replayBufferBytes: parsePositiveInt(env.RUNNER_REPLAY_BUFFER_BYTES, 5_000_000, "RUNNER_REPLAY_BUFFER_BYTES"),
         corsOrigins: parseCorsOrigins(env.RUNNER_CORS_ORIGINS),
+        watch: loadWatchConfig(env),
+    };
+}
+export function loadWatchConfig(env) {
+    return {
+        enabled: parseBool(env.RUNNER_WATCH_SESSIONS, false, "RUNNER_WATCH_SESSIONS"),
+        idleMs: parsePositiveInt(env.RUNNER_WATCH_IDLE_SECONDS, 300, "RUNNER_WATCH_IDLE_SECONDS") * 1000,
+        maxTtlSeconds: parsePositiveInt(env.RUNNER_WATCH_MAX_TTL_SECONDS, 21600, "RUNNER_WATCH_MAX_TTL_SECONDS"),
+        maxSessions: parsePositiveInt(env.RUNNER_WATCH_MAX_SESSIONS, 8, "RUNNER_WATCH_MAX_SESSIONS"),
+        reloadLimitPerMinute: parsePositiveInt(env.RUNNER_WATCH_RELOAD_LIMIT, 30, "RUNNER_WATCH_RELOAD_LIMIT"),
+        suspendedTtlMs: parsePositiveInt(env.RUNNER_WATCH_SUSPENDED_TTL_SECONDS, 86400, "RUNNER_WATCH_SUSPENDED_TTL_SECONDS") * 1000,
+        checkpointMs: parsePositiveInt(env.RUNNER_WORKSPACE_CHECKPOINT_SECONDS, 30, "RUNNER_WORKSPACE_CHECKPOINT_SECONDS") * 1000,
     };
 }
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/contract.d.ts

@@ -42,11 +42,29 @@ export interface RunnerTerms {
 }
 /** HTTP header carrying the accepted terms version on `POST /v1/sessions`. */
 export declare const ACCEPTED_TERMS_HEADER = "x-telo-accepted-terms";
+/**
+ * How an application container's byte channel is attached.
+ *  - `tty`     — one merged stream, as a terminal produces. Resize works;
+ *                `CLICOLOR_FORCE` is injected.
+ *  - `streams` — stdout and stderr separated at the source. Resize is rejected
+ *                (meaningless with no PTY) and no colour is forced, so the app
+ *                sees the environment it would see in production.
+ * Nothing is invented at the transport layer: docker's non-TTY attach is already
+ * a multiplexed stream carrying a per-frame stream id, and the kubernetes attach
+ * subresource without a TTY already gives separate stdout/stderr channels.
+ */
+export type IoMode = "tty" | "streams";
 export interface RunnerFeatures {
-    /** Runner exposes a live PTY byte channel (`/v1/sessions/:id/io`). */
-    io: boolean;
+    /** Byte-channel attach modes this runner offers (`/v1/sessions/:id/io`). */
+    io: IoMode[];
     /** Runner can publish workload ports back to the client. */
     ports: boolean;
+    /** Watch sessions (`mode: "watch"`) are requestable. Server-gated: a runner
+     *  with watch disabled advertises `false` and rejects the field. */
+    watch: boolean;
+    /** Catalog names admissible as a session's co-resident `agent`. Empty/absent
+     *  when the operator configured none. */
+    agents?: string[];
 }
 /** An operator-predefined application the runner can launch by name. Only the
  *  identity is advertised — the image and the operator env injected into it
@@ -90,6 +108,10 @@ export interface RunBundle {
     files: Array<{
         relativePath: string;
         contents: string;
+        /** `utf8` when omitted. A checkpoint re-seeds a resumed session through this
+         *  same shape, and a workspace may hold a binary asset, so dropping anything
+         *  that is not text would silently lose a file across a suspend. */
+        encoding?: "utf8" | "base64";
     }>;
 }
 export type PortProtocol = "tcp" | "udp";
@@ -112,6 +134,39 @@ export interface RunnerEndpoint {
     /** Fully-qualified URL when the endpoint is fronted by a proxy/ingress. */
     url?: string;
 }
+/**
+ * How long a session lives relative to its runs.
+ *  - `run`   — one run. The workload exits and the session is terminal. Today's
+ *              behaviour, and the default.
+ *  - `watch` — a workspace that runs continuously. Each application container
+ *              runs `telo run --watch`, an edit costs a kernel reload rather
+ *              than a pod, and a completed one-shot run leaves the session up.
+ */
+export type SessionMode = "run" | "watch";
+/** The name a single-app session's one application takes when the request
+ *  declares no `apps` — so every `run` / `debug` / `endpoints` event names an
+ *  app, and no client needs two readings of the same stream. */
+export declare const DEFAULT_APP_NAME = "app";
+/**
+ * One application in a session — one container, one kernel, one watcher. Most
+ * workspaces have exactly one: an Application with several Services in its
+ * `targets:` is still one kernel. The multi-app case is two independent
+ * Applications, which genuinely cannot be merged (importing a `Telo.Application`
+ * is a hard error, so no manifest composes them).
+ */
+export interface SessionAppSpec {
+    /** Unique within the session and usable as a DNS label — it appears in the
+     *  container name and in every run event. */
+    name: string;
+    /** Bundle-relative entry manifest this app runs. */
+    entryRelativePath: string;
+    /** Ports this app declares. Unique across the WHOLE session: session hosts are
+     *  `<port>-<sessionId>.<base-domain>`, a single label, so two apps on one port
+     *  would collide with nothing to tell them apart. */
+    ports?: PortMapping[];
+    /** Terminal or separated streams; defaults to `tty`. */
+    io?: IoMode;
+}
 export interface StartSessionRequest {
     bundle: RunBundle;
     env: Record<string, string>;
@@ -120,15 +175,37 @@ export interface StartSessionRequest {
     /** Request the kernel debug stream. When true the runner launches the
      *  workload with `--inspect`, subscribes to the in-workload inspect endpoint
      *  (reachable only by the runner — never published outward), and relays each
-     *  frame to the client as a `debug` {@link RunEvent}. */
+     *  frame to the client as a `debug` {@link RunEvent}. A watch session always
+     *  runs with it on — that stream is where `run` events are projected from. */
     inspect?: boolean;
+    /** Defaults to `run`. */
+    mode?: SessionMode;
+    /** Catalog name of a co-resident agent container. At most one per session,
+     *  never per app: the agent's unit is the workspace, and two agents over one
+     *  workspace would contend on the same files and split one conversation in
+     *  half. Requires `mode: "watch"` — an agent with nothing watching its writes
+     *  is a silent no-op. */
+    agent?: string;
+    /** The applications this session runs, one container each. Omitted, it
+     *  defaults to a single app named `app` on the bundle's own entry with the
+     *  request's `ports` — so a single-app session is written exactly as before. */
+    apps?: SessionAppSpec[];
 }
+/**
+ * The SESSION's status — how the session itself is doing, not how any one run
+ * ended. The two are separate nouns on the same stream: a one-shot app finishing
+ * in a watch session emits `run.completed` and leaves the session `running`, so
+ * the next edit starts that app's next generation.
+ *
+ * `exited` belongs to a `run` session only, where the session IS the run.
+ */
 export type RunStatus = {
     kind: "starting";
 }
-/** `inspectUrl` is the kernel debug/inspection UI fronted by a proxy (set only
- *  when the session ran with `inspect` and the runner has a public base URL);
- *  absent when the inspect endpoint isn't externally reachable. */
+/** Every application container is up. `inspectUrl` is the kernel
+ *  debug/inspection UI fronted by a proxy (set only when the session ran with
+ *  `inspect` and the runner has a public base URL); absent when the inspect
+ *  endpoint isn't externally reachable. */
  | {
     kind: "running";
     endpoints?: RunnerEndpoint[];
@@ -136,6 +213,14 @@ export type RunStatus = {
 } | {
     kind: "exited";
     code: number;
+}
+/** Reaped for idleness: the pod is gone, the workspace checkpoint is held, and
+ *  `POST /v1/sessions/:id/resume` brings it back under the same session id.
+ *  NOT terminal — nothing is evicted on it. Best-effort by design: the runner
+ *  holds the checkpoint in memory, so a runner restart loses it and the editor
+ *  (which holds the authoritative workspace) re-seeds from its own copy. */
+ | {
+    kind: "suspended";
 } | {
     kind: "failed";
     message: string;
@@ -152,34 +237,133 @@ export type RunPhase = "build" | "provision" | "boot";
  *  runner from its own network. Drives the editor's endpoint badge
  *  (spinner → ok / error) instead of an app-log line. */
 export type ReachabilityState = "checking" | "reachable" | "unreachable";
-export type RunEvent = {
-    type: "stdout";
-    chunk: string;
+/** What started one generation of an application.
+ *  - `initial` — the session came up
+ *  - `watch`   — a file changed under the app's watcher
+ *  - `manual`  — `POST /v1/sessions/:id/reload`
+ *  - `resume`  — a suspended session was brought back, or the app set changed */
+export type RunTrigger = "initial" | "watch" | "manual" | "resume";
+/**
+ * A RUN outcome — one per app per reload generation, distinct from the session
+ * status above. `generation` is monotonic per app and starts at 1; it is counted
+ * by the runner from the kernel lifecycle events already on the debug stream, so
+ * it asks the kernel for nothing.
+ */
+export type RunOutcomeEvent = {
+    type: "run";
+    app: string;
+    generation: number;
+    phase: "started";
+    trigger: RunTrigger;
 } | {
-    type: "stderr";
-    chunk: string;
+    type: "run";
+    app: string;
+    generation: number;
+    phase: "completed";
+    code: number;
+    durationMs?: number;
 } | {
+    type: "run";
+    app: string;
+    generation: number;
+    phase: "failed";
+    reason: string;
+};
+/**
+ * Workload output does NOT travel this channel, in either mode — it goes over the
+ * byte channel (`/io`), which exists precisely because per-chunk events are
+ * wasteful for high-volume output. The `stdout` / `stderr` variants that used to
+ * be declared here were emitted by nothing: a contract in shape only.
+ */
+export type RunEvent = {
     type: "status";
     status: RunStatus;
-} | {
+}
+/** `app` is absent for session-scoped provisioning (scheduling, image pull) and
+ *  present once the message belongs to one application. */
+ | {
     type: "progress";
+    app?: string;
     phase: RunPhase;
     message: string;
     done?: boolean;
 }
-/** A frame relayed from the workload's kernel debug stream (kernel event or
- *  log line). Only emitted when the session was started with `inspect`. */
+/** A frame relayed from one app's kernel debug stream (kernel event or log
+ *  line). Only emitted when the session was started with `inspect`. */
  | {
     type: "debug";
+    app: string;
     frame: DebugFrame;
 }
-/** A reachability transition for one declared port, keyed by port. */
+/** A reachability transition for one declared port of one app. */
  | {
     type: "reachability";
+    app: string;
     port: number;
     state: ReachabilityState;
+} | RunOutcomeEvent
+/** An app's declared port set changed on reload and the runner re-patched the
+ *  Service and Ingress. Without this the app binds the new port inside the pod
+ *  and is simply unreachable: no ingress, no error, no event. */
+ | {
+    type: "endpoints";
+    app: string;
+    added?: RunnerEndpoint[];
+    removed?: RunnerEndpoint[];
+    /** A declared port that could not be routed (it collides with another app
+     *  in this session). Reported, never dropped. */
+    rejected?: Array<{
+        port: number;
+        reason: string;
+    }>;
 };
+/**
+ * Terminal = the session is over and the registry may schedule eviction.
+ * `suspended` is deliberately NOT terminal: the session record and its workspace
+ * checkpoint outlive the pod, and `resume` brings it back under the same id.
+ */
 export declare function isTerminal(status: RunStatus): boolean;
+/**
+ * Which stream a byte-channel chunk came from. Under `io: "tty"` every chunk is
+ * `tty` — the tag never asserts a split that does not exist, which is exactly the
+ * failure the deleted `stdout` / `stderr` run events represented.
+ */
+export type ByteStreamTag = "tty" | "stdout" | "stderr";
+/** One file in a workspace snapshot: its path and the sha256 of its bytes.
+ *  Hashing content — rather than comparing sizes or timestamps — is what makes
+ *  two snapshots diff into an exact change set. */
+export interface WorkspaceFileEntry {
+    path: string;
+    hash: string;
+}
+export interface WorkspaceTree {
+    files: WorkspaceFileEntry[];
+}
+/**
+ * An explicit write/delete list rather than a whole-tree PUT: a deletion has to
+ * be expressible, and a whole-tree PUT can only express it by treating absence as
+ * intent. A one-file save is a change set of one — there is deliberately no
+ * single-file write route, which would be a second set of concurrency rules.
+ */
+export interface WorkspaceChangeSet {
+    write?: Array<{
+        path: string;
+        content: string;
+        encoding?: "utf8" | "base64";
+    }>;
+    delete?: string[];
+}
+export interface WorkspaceApplyResult {
+    written: number;
+    deleted: number;
+}
+/** One file of a checkpoint — a tree entry plus the bytes needed to re-seed a
+ *  fresh pod. Text stays `utf8`; anything that is not valid text is carried
+ *  `base64`, so a binary asset survives a suspend/resume round trip. */
+export interface WorkspaceCheckpointFile extends WorkspaceFileEntry {
+    content: string;
+    encoding: "utf8" | "base64";
+}
 /**
  * Stages a session start can fail at. The docker/k8s backends share the
  * vocabulary; not every stage applies to every backend (`pull`/`inspect` are

package/dist/contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}