@telorun/runner-core 0.8.2 → 0.9.0

package/dist/session/watch-supervisor.js

@@ -0,0 +1,99 @@
+/** How often the supervisor wakes. Both of its jobs are coarse — a checkpoint
+ *  cadence and an idle window, both measured in minutes — so a fine tick would
+ *  buy nothing but wakeups. */
+const TICK_MS = 5_000;
+/**
+ * The two background jobs that make a watch session affordable, and they only
+ * work as a pair: a periodic workspace checkpoint, and an idle reap that deletes
+ * the pod while keeping the session record and that checkpoint.
+ *
+ * Aggressive reaping is what makes per-visitor watch sessions affordable, and
+ * the checkpoint is what makes aggressive reaping safe to do.
+ *
+ * The checkpoint is a CACHE, never the only copy. The runner is a single replica
+ * with an in-memory registry, so a redeploy or crash drops every suspended
+ * session — the editor holds the authoritative workspace, already diffs its own
+ * files against `GET /workspace`, and on a `404` at resume creates a new session
+ * and re-seeds from its own copy in one change set. What the checkpoint saves is
+ * that upload.
+ */
+export class WatchSupervisor {
+    deps;
+    timer = null;
+    /** Sessions with a checkpoint or suspend in flight, so a slow snapshot cannot
+     *  have a second one started on top of it every tick. */
+    busy = new Set();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => void this.tick(), TICK_MS);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (!this.timer)
+            return;
+        clearInterval(this.timer);
+        this.timer = null;
+    }
+    /** Exposed for tests, which drive the clock rather than waiting on it. */
+    async tick() {
+        const now = Date.now();
+        for (const entry of this.deps.registry.list()) {
+            if (entry.mode !== "watch")
+                continue;
+            if (entry.status.kind !== "running")
+                continue;
+            if (this.busy.has(entry.sessionId))
+                continue;
+            const idle = entry.subscribers === 0 &&
+                entry.idleSince !== null &&
+                now - entry.idleSince >= this.deps.idleMs;
+            if (idle) {
+                void this.run(entry, () => this.suspend(entry));
+            }
+            else if (entry.checkpointedAt === null ||
+                now - entry.checkpointedAt >= this.deps.checkpointMs) {
+                void this.run(entry, () => this.checkpoint(entry));
+            }
+        }
+    }
+    async run(entry, job) {
+        this.busy.add(entry.sessionId);
+        try {
+            await job();
+        }
+        catch (err) {
+            // A failed checkpoint is not a failed session: the editor still holds the
+            // authoritative copy, and the next tick retries. Reported rather than
+            // swallowed so an operator sees a workspace that has stopped answering.
+            this.deps.log?.warn({ err, sessionId: entry.sessionId }, "watch session checkpoint/suspend failed");
+        }
+        finally {
+            this.busy.delete(entry.sessionId);
+        }
+    }
+    async checkpoint(entry) {
+        const workspace = entry.session?.workspace;
+        if (!workspace)
+            return;
+        const files = await workspace.snapshot();
+        entry.checkpoint = { takenAt: new Date(), files };
+        entry.checkpointedAt = Date.now();
+    }
+    async suspend(entry) {
+        const session = entry.session;
+        if (!session?.suspend)
+            return;
+        // Snapshot BEFORE the pod goes: the volume dies with it. A snapshot that
+        // fails aborts the suspend rather than taking the pod down with an older
+        // checkpoint — the session stays up and the next tick tries again.
+        await this.checkpoint(entry);
+        await session.suspend();
+        entry.session = null;
+        this.deps.registry.emit(entry.sessionId, { type: "status", status: { kind: "suspended" } });
+    }
+}
+//# sourceMappingURL=watch-supervisor.js.map

package/dist/session/watch-supervisor.js.map

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

package/dist/session/workspace-app.d.ts

@@ -0,0 +1,4 @@
+/** The name the manifest is mounted under, in every backend. */
+export declare const WORKSPACE_APP_FILENAME = "telo.yaml";
+export declare function workspaceAppManifest(): string;
+//# sourceMappingURL=workspace-app.d.ts.map

package/dist/session/workspace-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-app.d.ts","sourceRoot":"","sources":["../../src/session/workspace-app.ts"],"names":[],"mappings":"AAIA,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,cAAc,CAAC;AAclD,wBAAgB,oBAAoB,IAAI,MAAM,CAO7C"}

package/dist/session/workspace-app.js

@@ -0,0 +1,26 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** The name the manifest is mounted under, in every backend. */
+export const WORKSPACE_APP_FILENAME = "telo.yaml";
+/**
+ * The workspace application's manifest, read from the package rather than
+ * inlined as a string: it is a Telo manifest, so it must stay a `.yaml` file the
+ * repo's own `telo check` and formatter see. It lives in runner-core because the
+ * workspace surface is part of the `/v1` session contract — both backends mount
+ * the same bytes, and a copy per backend would be two manifests to hold in
+ * agreement.
+ *
+ * Read once and memoized: it never changes within a process.
+ */
+let cached;
+export function workspaceAppManifest() {
+    if (cached !== undefined)
+        return cached;
+    // `dist/session/` at runtime, `src/session/` under a source run — three levels
+    // up is the package root either way.
+    const here = dirname(fileURLToPath(import.meta.url));
+    cached = readFileSync(join(here, "..", "..", "workspace-app", WORKSPACE_APP_FILENAME), "utf8");
+    return cached;
+}
+//# sourceMappingURL=workspace-app.js.map

package/dist/session/workspace-app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-app.js","sourceRoot":"","sources":["../../src/session/workspace-app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,gEAAgE;AAChE,MAAM,CAAC,MAAM,sBAAsB,GAAG,WAAW,CAAC;AAElD;;;;;;;;;GASG;AACH,IAAI,MAA0B,CAAC;AAE/B,MAAM,UAAU,oBAAoB;IAClC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IACxC,+EAA+E;IAC/E,qCAAqC;IACrC,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,sBAAsB,CAAC,EAAE,MAAM,CAAC,CAAC;IAC/F,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/session/workspace-client.d.ts

@@ -0,0 +1,33 @@
+import type { WorkspaceAccess } from "../backend.js";
+import type { WorkspaceChangeSet, WorkspaceCheckpointFile, WorkspaceTree } from "../contract.js";
+/**
+ * HTTP client for the `workspace` container's surface, shared by both backends:
+ * the container is the same image running the same manifest whether it is a
+ * sibling container on a docker network or a container in a kubernetes pod, so
+ * only the base URL differs.
+ *
+ * The runner reaches it over its own network (a pod IP, a container address) and
+ * proxies it outward. It is never published.
+ */
+export declare class WorkspaceClient implements WorkspaceAccess {
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    constructor(baseUrl: string, timeoutMs?: number);
+    tree(): Promise<WorkspaceTree>;
+    readFile(path: string): Promise<{
+        content: string;
+        size: number;
+    }>;
+    apply(changes: WorkspaceChangeSet): Promise<{
+        written: number;
+        deleted: number;
+    }>;
+    snapshot(): Promise<WorkspaceCheckpointFile[]>;
+    /** Re-run one app with no file change: rewrite its entry manifest with the
+     *  bytes it already holds, through the same write path everything else takes.
+     *  That is what makes `reload` need no signalling into the container, no
+     *  shared PID namespace and no `exec` — RBAC is unchanged. */
+    touch(path: string): Promise<void>;
+    private request;
+}
+//# sourceMappingURL=workspace-client.d.ts.map

package/dist/session/workspace-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-client.d.ts","sourceRoot":"","sources":["../../src/session/workspace-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EACV,kBAAkB,EAClB,uBAAuB,EACvB,aAAa,EACd,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;GAQG;AACH,qBAAa,eAAgB,YAAW,eAAe;IAEnD,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBADT,OAAO,EAAE,MAAM,EACf,SAAS,SAAS;IAG/B,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC;IAI9B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAOlE,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAIjF,QAAQ,IAAI,OAAO,CAAC,uBAAuB,EAAE,CAAC;IAQpD;;;kEAG8D;IACxD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAQ1B,OAAO;CAsBtB"}

package/dist/session/workspace-client.js

@@ -0,0 +1,62 @@
+/**
+ * HTTP client for the `workspace` container's surface, shared by both backends:
+ * the container is the same image running the same manifest whether it is a
+ * sibling container on a docker network or a container in a kubernetes pod, so
+ * only the base URL differs.
+ *
+ * The runner reaches it over its own network (a pod IP, a container address) and
+ * proxies it outward. It is never published.
+ */
+export class WorkspaceClient {
+    baseUrl;
+    timeoutMs;
+    constructor(baseUrl, timeoutMs = 30_000) {
+        this.baseUrl = baseUrl;
+        this.timeoutMs = timeoutMs;
+    }
+    async tree() {
+        return this.request("GET", "/workspace");
+    }
+    async readFile(path) {
+        return this.request("GET", `/workspace/file?path=${encodeURIComponent(path)}`);
+    }
+    async apply(changes) {
+        return this.request("POST", "/workspace", changes);
+    }
+    async snapshot() {
+        const body = await this.request("GET", "/workspace/snapshot");
+        return body.files;
+    }
+    /** Re-run one app with no file change: rewrite its entry manifest with the
+     *  bytes it already holds, through the same write path everything else takes.
+     *  That is what makes `reload` need no signalling into the container, no
+     *  shared PID namespace and no `exec` — RBAC is unchanged. */
+    async touch(path) {
+        const file = await this.request("GET", `/workspace/file?path=${encodeURIComponent(path)}&encoding=base64`);
+        await this.apply({ write: [{ path, content: file.content, encoding: "base64" }] });
+    }
+    async request(method, path, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                signal: controller.signal,
+                ...(body === undefined
+                    ? {}
+                    : { headers: { "content-type": "application/json" }, body: JSON.stringify(body) }),
+            });
+            const text = await response.text();
+            if (!response.ok) {
+                // Surfaced, never swallowed: a workspace that has stopped answering is
+                // the one failure that makes every later edit silently do nothing.
+                throw new Error(`workspace ${method} ${path} failed: ${response.status} ${text.slice(0, 500)}`);
+            }
+            return JSON.parse(text);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=workspace-client.js.map

package/dist/session/workspace-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-client.js","sourceRoot":"","sources":["../../src/session/workspace-client.ts"],"names":[],"mappings":"AAOA;;;;;;;;GAQG;AACH,MAAM,OAAO,eAAe;IAEP;IACA;IAFnB,YACmB,OAAe,EACf,YAAY,MAAM;QADlB,YAAO,GAAP,OAAO,CAAQ;QACf,cAAS,GAAT,SAAS,CAAS;IAClC,CAAC;IAEJ,KAAK,CAAC,IAAI;QACR,OAAO,IAAI,CAAC,OAAO,CAAgB,KAAK,EAAE,YAAY,CAAC,CAAC;IAC1D,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAY;QACzB,OAAO,IAAI,CAAC,OAAO,CACjB,KAAK,EACL,wBAAwB,kBAAkB,CAAC,IAAI,CAAC,EAAE,CACnD,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,OAA2B;QACrC,OAAO,IAAI,CAAC,OAAO,CAAuC,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC;IAC3F,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAC7B,KAAK,EACL,qBAAqB,CACtB,CAAC;QACF,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED;;;kEAG8D;IAC9D,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAC7B,KAAK,EACL,wBAAwB,kBAAkB,CAAC,IAAI,CAAC,kBAAkB,CACnE,CAAC;QACF,MAAM,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;IACrF,CAAC;IAEO,KAAK,CAAC,OAAO,CAAI,MAAc,EAAE,IAAY,EAAE,IAAc;QACnE,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACnE,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;gBACrD,MAAM;gBACN,MAAM,EAAE,UAAU,CAAC,MAAM;gBACzB,GAAG,CAAC,IAAI,KAAK,SAAS;oBACpB,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;aACrF,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,uEAAuE;gBACvE,mEAAmE;gBACnE,MAAM,IAAI,KAAK,CAAC,aAAa,MAAM,IAAI,IAAI,YAAY,QAAQ,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;YAClG,CAAC;YACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;QAC/B,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;CACF"}

package/dist/session/workspace-marker.d.ts

@@ -0,0 +1,25 @@
+import type { RunBundle, WorkspaceChangeSet } from "../contract.js";
+/** The kernel anchors its `.telo` cache at the directory holding this file. */
+export declare const WORKSPACE_MARKER_FILENAME = "telo-workspace.yaml";
+/**
+ * The marker a session's workspace root carries.
+ *
+ * Its LOCATION is what matters here: the kernel walks up from an app's entry
+ * manifest looking for it and anchors the `.telo` cache at the directory that
+ * holds it. Without one, each app anchors on its OWN entry directory, so two
+ * apps in one workspace resolve the same module twice into two caches — and an
+ * app in a subdirectory gets a third.
+ *
+ * `modules:` is release scope and is read by `telo release` alone, which never
+ * runs in a session. It is written anyway because an empty list is a hard error
+ * in the parser, and a file this repo's own tooling would reject is not one to
+ * seed into a user's workspace.
+ */
+export declare const WORKSPACE_MARKER_CONTENTS = "# Marks the root of this session's workspace.\n#\n# The Telo kernel anchors its module cache (.telo) at the directory holding this\n# file, so every application in this workspace resolves its imports once into one\n# cache instead of once per app.\nmodules: [\"*\"]\n";
+/**
+ * The marker, unless the workspace already brings its own. A user whose project
+ * really is a Telo workspace has a marker with a real \`modules:\` list, and
+ * overwriting it would silently change what \`telo release\` discovers.
+ */
+export declare function workspaceMarkerWrite(bundle: RunBundle): NonNullable<WorkspaceChangeSet["write"]>;
+//# sourceMappingURL=workspace-marker.d.ts.map

package/dist/session/workspace-marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-marker.d.ts","sourceRoot":"","sources":["../../src/session/workspace-marker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpE,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAE/D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,gRAMrC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,GAChB,WAAW,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAI1C"}

package/dist/session/workspace-marker.js

@@ -0,0 +1,35 @@
+/** The kernel anchors its `.telo` cache at the directory holding this file. */
+export const WORKSPACE_MARKER_FILENAME = "telo-workspace.yaml";
+/**
+ * The marker a session's workspace root carries.
+ *
+ * Its LOCATION is what matters here: the kernel walks up from an app's entry
+ * manifest looking for it and anchors the `.telo` cache at the directory that
+ * holds it. Without one, each app anchors on its OWN entry directory, so two
+ * apps in one workspace resolve the same module twice into two caches — and an
+ * app in a subdirectory gets a third.
+ *
+ * `modules:` is release scope and is read by `telo release` alone, which never
+ * runs in a session. It is written anyway because an empty list is a hard error
+ * in the parser, and a file this repo's own tooling would reject is not one to
+ * seed into a user's workspace.
+ */
+export const WORKSPACE_MARKER_CONTENTS = `# Marks the root of this session's workspace.
+#
+# The Telo kernel anchors its module cache (.telo) at the directory holding this
+# file, so every application in this workspace resolves its imports once into one
+# cache instead of once per app.
+modules: ["*"]
+`;
+/**
+ * The marker, unless the workspace already brings its own. A user whose project
+ * really is a Telo workspace has a marker with a real \`modules:\` list, and
+ * overwriting it would silently change what \`telo release\` discovers.
+ */
+export function workspaceMarkerWrite(bundle) {
+    const provided = bundle.files.some((f) => f.relativePath === WORKSPACE_MARKER_FILENAME);
+    if (provided)
+        return [];
+    return [{ path: WORKSPACE_MARKER_FILENAME, content: WORKSPACE_MARKER_CONTENTS }];
+}
+//# sourceMappingURL=workspace-marker.js.map

package/dist/session/workspace-marker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-marker.js","sourceRoot":"","sources":["../../src/session/workspace-marker.ts"],"names":[],"mappings":"AAEA,+EAA+E;AAC/E,MAAM,CAAC,MAAM,yBAAyB,GAAG,qBAAqB,CAAC;AAE/D;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;;;;;;CAMxC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAiB;IAEjB,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,yBAAyB,CAAC,CAAC;IACxF,IAAI,QAAQ;QAAE,OAAO,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,IAAI,EAAE,yBAAyB,EAAE,OAAO,EAAE,yBAAyB,EAAE,CAAC,CAAC;AACnF,CAAC"}

package/dist/sse/channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/sse/channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG5D,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAKnF,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,EAAE,cAAc,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;CAC7B;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAuF5E"}
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/sse/channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG5D,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAKnF,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,EAAE,cAAc,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;CAC7B;AAED,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CA4F5E"}

package/dist/sse/channel.js

@@ -44,10 +44,14 @@ export async function streamSessionEvents(args) {
     let unsubscribe = null;
     let heartbeat = null;
     let closed = false;
+    // An attached event stream is a live client. Idleness — no subscriber on
+    // either channel for the configured window — is what suspends a watch session.
+    const releaseSubscriber = registry.addSubscriber(sessionId);
     const cleanup = () => {
         if (closed)
             return;
         closed = true;
+        releaseSubscriber();
         if (heartbeat)
             clearInterval(heartbeat);
         if (unsubscribe)

package/dist/sse/channel.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/runner-core",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Backend-neutral core for Telo runners: the /v1 session contract, the RunnerBackend interface, the session registry, SSE/byte ring buffers, and bundle handling. Shared by docker-runner and k8s-runner.",
   "keywords": [
     "telo",
@@ -24,14 +24,15 @@
   },
   "files": [
     "dist/**",
-    "src/**"
+    "src/**",
+    "workspace-app/**"
   ],
   "dependencies": {
     "@fastify/cors": "^11.0.1",
     "@fastify/websocket": "^11.0.1",
     "fastify": "^5.12.1",
     "yaml": "^2.8.3",
-    "@telorun/debug-wire": "0.4.0"
+    "@telorun/debug-wire": "0.4.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/backend.ts

@@ -1,14 +1,22 @@
 import type { DebugFrame } from "@telorun/debug-wire";
 
+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";
 
 /**
@@ -40,59 +48,140 @@ export interface RunnerBackend {
   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;
+  /** 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 the workload's PTY. */
-  resize(cols: number, rows: number): 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[]>;
 }