@telorun/runner-core 0.8.2 → 0.10.0

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,22 +175,63 @@ 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.
+ *
+ *  `agent` is where this session's co-resident agent answers, present only on
+ *  a session that requested one AND that this runner could route. An ENDPOINT
+ *  rather than a URL string because the no-proxy case is real — a docker
+ *  runner publishing to the host knows the port and not the hostname the
+ *  client reached it by, exactly as for an app's endpoint, so the client
+ *  fills an empty `host` from its own base URL. Carried here and not in
+ *  `endpoints` because the agent is session infrastructure: `endpoints` are
+ *  the ports the APPLICATIONS declared, and merging the two would make an
+ *  operator-run container look like part of the user's manifest. */
  | {
     kind: "running";
     endpoints?: RunnerEndpoint[];
     inspectUrl?: string;
+    agent?: RunnerEndpoint;
 } | {
     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 +248,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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"}

package/dist/contract.js

@@ -6,6 +6,15 @@
  */
 /** HTTP header carrying the accepted terms version on `POST /v1/sessions`. */
 export const ACCEPTED_TERMS_HEADER = "x-telo-accepted-terms";
+/** 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 const DEFAULT_APP_NAME = "app";
+/**
+ * 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 function isTerminal(status) {
     return status.kind === "exited" || status.kind === "failed" || status.kind === "stopped";
 }

package/dist/contract.js.map

@@ -1 +1 @@
-{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwCH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AAuH7D,MAAM,UAAU,UAAU,CAAC,MAAiB;IAC1C,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC;AAC3F,CAAC;AAeD,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAExB;IACA;IAEA;IAJlB,YACkB,IAAoC,EACpC,KAAwB,EACxC,OAAe,EACC,aAAsB;QAEtC,KAAK,CAAC,OAAO,CAAC,CAAC;QALC,SAAI,GAAJ,IAAI,CAAgC;QACpC,UAAK,GAAL,KAAK,CAAmB;QAExB,kBAAa,GAAb,aAAa,CAAS;QAGtC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF"}
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAwCH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,qBAAqB,GAAG,uBAAuB,CAAC;AA8G7D;;gEAEgE;AAChE,MAAM,CAAC,MAAM,gBAAgB,GAAG,KAAK,CAAC;AA2JtC;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,MAAiB;IAC1C,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC;AAC3F,CAAC;AA0DD,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAExB;IACA;IAEA;IAJlB,YACkB,IAAoC,EACpC,KAAwB,EACxC,OAAe,EACC,aAAsB;QAEtC,KAAK,CAAC,OAAO,CAAC,CAAC;QALC,SAAI,GAAJ,IAAI,CAAgC;QACpC,UAAK,GAAL,KAAK,CAAmB;QAExB,kBAAa,GAAb,aAAa,CAAS;QAGtC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF"}

package/dist/debug/ports-resolved.d.ts

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

package/dist/debug/ports-resolved.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports-resolved.d.ts","sourceRoot":"","sources":["../../src/debug/ports-resolved.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEpE,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,gBAAgB,CAAC;AAEhE;;uDAEuD;AACvD,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,EAAE,GAAG,SAAS,CAY9E;AAED;+BAC+B;AAC/B,wBAAgB,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAEpD"}

package/dist/debug/ports-resolved.js

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

package/dist/debug/ports-resolved.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports-resolved.js","sourceRoot":"","sources":["../../src/debug/ports-resolved.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAmB,MAAM,qBAAqB,CAAC;AAIpE;;uDAEuD;AACvD,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE3D;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAiB;IACjD,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,KAAK,oBAAoB;QAAE,OAAO,SAAS,CAAC;IACnF,MAAM,GAAG,GAAI,KAAK,CAAC,OAA2C,EAAE,KAAK,CAAC;IACtE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,KAAK,GAAkB,EAAE,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;QACxB,MAAM,IAAI,GAAI,KAA4B,EAAE,IAAI,CAAC;QACjD,MAAM,QAAQ,GAAI,KAAgC,EAAE,QAAQ,CAAC;QAC7D,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC;YAAE,SAAS;QAClE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,KAAsB,EAAE,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;+BAC+B;AAC/B,MAAM,UAAU,OAAO,CAAC,OAAoB;IAC1C,OAAO,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;AAC/C,CAAC"}

package/dist/debug/relay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"relay.d.ts","sourceRoot":"","sources":["../../src/debug/relay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAItD,MAAM,WAAW,iBAAiB;IAChC;2EACuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACrC,wCAAwC;IACxC,MAAM,EAAE,WAAW,CAAC;IACpB;;qDAEiD;IACjD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;CAChC;AAID;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB7E"}
+{"version":3,"file":"relay.d.ts","sourceRoot":"","sources":["../../src/debug/relay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAItD,MAAM,WAAW,iBAAiB;IAChC;2EACuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACrC,wCAAwC;IACxC,MAAM,EAAE,WAAW,CAAC;IACpB;;qDAEiD;IACjD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;CAChC;AAID;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6B7E"}

package/dist/debug/relay.js

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

package/dist/debug/relay.js.map

@@ -1 +1 @@
-{"version":3,"file":"relay.js","sourceRoot":"","sources":["../../src/debug/relay.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"relay.js","sourceRoot":"","sources":["../../src/debug/relay.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAgBvD,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAuB;IAC5D,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACtC,8EAA8E;IAC9E,0EAA0E;IAC1E,4EAA4E;IAC5E,sEAAsE;IACtE,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;gBAC3B,MAAM;gBACN,OAAO,EAAE;oBACP,MAAM,EAAE,mBAAmB;oBAC3B,GAAG,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACrE;aACF,CAAC,CAAC;YACH,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;gBACzB,MAAM,cAAc,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;gBACjD,SAAS;YACX,CAAC;YACD,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE;gBAC3C,WAAW,GAAG,EAAE,CAAC;YACnB,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAO;YAC3B,IAAI,CAAC,OAAO,EAAE,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACtE,CAAC;QACD,MAAM,cAAc,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAED,KAAK,UAAU,IAAI,CACjB,IAAgC,EAChC,OAAoC,EACpC,MAAmB,EACnB,IAA0B;IAE1B,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACvB,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,OAAO;YACjB,GAAG,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAC/C,IAAI,GAAW,CAAC;YAChB,4CAA4C;YAC5C,OAAO,CAAC,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;gBACxC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;gBAChC,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;gBACzB,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;gBAClC,IAAI,CAAC,KAAK;oBAAE,SAAS;gBACrB,OAAO,CAAC,KAAK,CAAC,CAAC;gBACf,sEAAsE;gBACtE,iCAAiC;gBACjC,MAAM,EAAE,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;gBAC7B,IAAI,EAAE,KAAK,IAAI;oBAAE,IAAI,CAAC,EAAE,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AAED;uDACuD;AACvD,SAAS,UAAU,CAAC,KAAa;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;YAAE,SAAS;QACtC,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QACzD,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACjD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;oDACoD;AACpD,SAAS,YAAY,CAAC,KAAa;IACjC,MAAM,IAAI,GAAG,KAAK;SACf,KAAK,CAAC,IAAI,CAAC;SACX,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;SAC1C,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC;SACxC,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAe,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/debug/run-projection.d.ts

@@ -0,0 +1,53 @@
+import { 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 declare class RunProjection {
+    private readonly registry;
+    private readonly sessionId;
+    /** 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;
+    constructor(registry: SessionRegistry, 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;
+    /** Attribute every app's next generation — the session-wide cases (initial,
+     *  resume) always move all of them together. */
+    expectAll(trigger: RunTrigger): void;
+    /** 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;
+    /**
+     * 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;
+    /** 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;
+}
+//# sourceMappingURL=run-projection.d.ts.map

package/dist/debug/run-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-projection.d.ts","sourceRoot":"","sources":["../../src/debug/run-projection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAa;IAOtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAP5B;;8EAE0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;gBAGvC,QAAQ,EAAE,eAAe,EACzB,SAAS,EAAE,MAAM;IAGpC;mFAC+E;IAC/E,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,IAAI;IAI9C;oDACgD;IAChD,SAAS,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;IAKpC;yDACqD;IACrD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;IA4B3C;;;;;OAKG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAY7E;4EACwE;IACxE,OAAO,CAAC,KAAK;CASd"}