@telorun/runner-core 0.8.2 → 0.9.0

package/src/session/watch-supervisor.ts

@@ -0,0 +1,112 @@
+import type { SessionEntry, SessionRegistry } from "./registry.js";
+
+export interface WatchSupervisorDeps {
+  registry: SessionRegistry;
+  /** No SSE/WS subscriber for this long → suspend. */
+  idleMs: number;
+  /** How often to pull a whole-tree workspace snapshot. */
+  checkpointMs: number;
+  log?: { warn(obj: unknown, msg: string): void };
+}
+
+/** 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 {
+  private timer: NodeJS.Timeout | null = 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. */
+  private readonly busy = new Set<string>();
+
+  constructor(private readonly deps: WatchSupervisorDeps) {}
+
+  start(): void {
+    if (this.timer) return;
+    this.timer = setInterval(() => void this.tick(), TICK_MS);
+    this.timer.unref?.();
+  }
+
+  stop(): void {
+    if (!this.timer) return;
+    clearInterval(this.timer);
+    this.timer = null;
+  }
+
+  /** Exposed for tests, which drive the clock rather than waiting on it. */
+  async tick(): Promise<void> {
+    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));
+      }
+    }
+  }
+
+  private async run(entry: SessionEntry, job: () => Promise<void>): Promise<void> {
+    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);
+    }
+  }
+
+  private async checkpoint(entry: SessionEntry): Promise<void> {
+    const workspace = entry.session?.workspace;
+    if (!workspace) return;
+    const files = await workspace.snapshot();
+    entry.checkpoint = { takenAt: new Date(), files };
+    entry.checkpointedAt = Date.now();
+  }
+
+  private async suspend(entry: SessionEntry): Promise<void> {
+    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" } });
+  }
+}

package/src/session/workspace-app.ts

@@ -0,0 +1,27 @@
+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: string | undefined;
+
+export function workspaceAppManifest(): string {
+  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;
+}

package/src/session/workspace-client.ts

@@ -0,0 +1,80 @@
+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 class WorkspaceClient implements WorkspaceAccess {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly timeoutMs = 30_000,
+  ) {}
+
+  async tree(): Promise<WorkspaceTree> {
+    return this.request<WorkspaceTree>("GET", "/workspace");
+  }
+
+  async readFile(path: string): Promise<{ content: string; size: number }> {
+    return this.request<{ content: string; size: number }>(
+      "GET",
+      `/workspace/file?path=${encodeURIComponent(path)}`,
+    );
+  }
+
+  async apply(changes: WorkspaceChangeSet): Promise<{ written: number; deleted: number }> {
+    return this.request<{ written: number; deleted: number }>("POST", "/workspace", changes);
+  }
+
+  async snapshot(): Promise<WorkspaceCheckpointFile[]> {
+    const body = await this.request<{ files: WorkspaceCheckpointFile[] }>(
+      "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: string): Promise<void> {
+    const file = await this.request<{ content: string }>(
+      "GET",
+      `/workspace/file?path=${encodeURIComponent(path)}&encoding=base64`,
+    );
+    await this.apply({ write: [{ path, content: file.content, encoding: "base64" }] });
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    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) as T;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}

package/src/session/workspace-marker.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+
+import type { RunBundle } from "../contract.js";
+import {
+  WORKSPACE_MARKER_CONTENTS,
+  WORKSPACE_MARKER_FILENAME,
+  workspaceMarkerWrite,
+} from "./workspace-marker.js";
+
+const bundle = (paths: string[]): RunBundle => ({
+  entryRelativePath: "telo.yaml",
+  files: paths.map((relativePath) => ({ relativePath, contents: "x" })),
+});
+
+describe("workspaceMarkerWrite", () => {
+  it("seeds the marker at the workspace root", () => {
+    // Its LOCATION is what anchors the cache: the kernel walks up from an app's
+    // entry manifest, so the marker has to sit at the root, not beside an app.
+    expect(workspaceMarkerWrite(bundle(["telo.yaml", "worker.yaml"]))).toEqual([
+      { path: WORKSPACE_MARKER_FILENAME, content: WORKSPACE_MARKER_CONTENTS },
+    ]);
+  });
+
+  it("leaves a workspace that brings its own marker alone", () => {
+    // A project that really is a Telo workspace has a marker with a real
+    // `modules:` list; overwriting it would change what `telo release` finds.
+    expect(workspaceMarkerWrite(bundle(["telo.yaml", WORKSPACE_MARKER_FILENAME]))).toEqual([]);
+  });
+
+  it("writes a marker the workspace parser accepts", () => {
+    // An empty `modules:` is a hard error in that parser, so a marker seeded
+    // with one would be a file this repo's own tooling rejects.
+    expect(WORKSPACE_MARKER_CONTENTS).toMatch(/^modules: \[.+\]$/m);
+  });
+});

package/src/session/workspace-marker.ts

@@ -0,0 +1,39 @@
+import type { RunBundle, WorkspaceChangeSet } from "../contract.js";
+
+/** 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: RunBundle,
+): NonNullable<WorkspaceChangeSet["write"]> {
+  const provided = bundle.files.some((f) => f.relativePath === WORKSPACE_MARKER_FILENAME);
+  if (provided) return [];
+  return [{ path: WORKSPACE_MARKER_FILENAME, content: WORKSPACE_MARKER_CONTENTS }];
+}

package/src/sse/channel.ts

@@ -64,9 +64,14 @@ export async function streamSessionEvents(args: SseStreamArgs): Promise<void> {
   let heartbeat: NodeJS.Timeout | null = 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 = (): void => {
     if (closed) return;
     closed = true;
+    releaseSubscriber();
     if (heartbeat) clearInterval(heartbeat);
     if (unsubscribe) unsubscribe();
     if (!raw.writableEnded) raw.end();

package/workspace-app/telo.yaml

@@ -0,0 +1,228 @@
+kind: Telo.Application
+metadata:
+  name: TeloWorkspace
+  version: 0.1.0
+  description: |
+    The workspace surface of a watch session: an HTTP API over the session's
+    shared volume that the runner proxies to `/v1/sessions/:id/workspace`.
+
+    It is runner INFRASTRUCTURE, not agent functionality — part of the `/v1`
+    session contract — so the runner owns it and the co-resident agent is one
+    more writer on the volume beside the application containers, using its own
+    filesystem tools rather than these routes. Hanging this off the agent's
+    catalog image would invert the dependency (a session contract resting on an
+    application the operator configures) and would need a second implementation
+    for the agentless case, with the contract depending on the two staying in
+    agreement.
+
+    It runs the plain kernel image (`telorun/node`) over this manifest, mounted
+    read-only from a ConfigMap. There is deliberately no third image to build:
+    the whole surface is four routes over the `fs` module's tree primitives.
+imports:
+  Http: oci://ghcr.io/telorun/http-server@0.29.0#sha256-6OIi1b-_cF4uMZ3O20EWRWAJn6JbgomkE4amBBMofqM
+  Fs: oci://ghcr.io/telorun/fs@0.9.4#sha256-w8NLcREIq8SvxtsrULgRVKMPXISnR4iJd7LxeFnBFGM
+  Run: oci://ghcr.io/telorun/run@0.26.0#sha256-ZhW56yiMCImqBh0wJ4mVaUvh5WuUVIaWErASFx--wCY
+ports:
+  http:
+    env: PORT
+    default: 8099
+variables:
+  root:
+    env: WORKSPACE_DIR
+    type: string
+    default: /workspace
+  # Base names skipped at any depth. Declared once because the two readers below
+  # are the tree the editor DIFFS and the snapshot that RE-SEEDS a resumed pod:
+  # if they drift, a file survives one and not the other. These are caches a
+  # workspace can always rebuild — deliberately not `dist`, which in a hand-written
+  # workspace is ordinary content, and dropping it would lose it across a suspend.
+  excluded:
+    env: WORKSPACE_EXCLUDE
+    type: array
+    default: [node_modules, .telo, .git]
+targets:
+  - !ref server
+---
+# The tree primitives, all rooted at the shared volume. `cwd` is not a security
+# boundary — the runner normalizes every client-supplied path before it gets
+# here, the same traversal guard a session bundle passes through.
+kind: Fs.TreeSnapshot
+metadata: { name: treeSnapshot }
+cwd: !cel "variables.root"
+---
+kind: Fs.TreeSync
+metadata: { name: treeSync }
+cwd: !cel "variables.root"
+---
+kind: Fs.File
+metadata: { name: readFile }
+cwd: !cel "variables.root"
+---
+# Whole-tree pull for the runner's checkpoint timer and for suspend. Contents are
+# ALWAYS base64: a checkpoint has to round-trip a workspace exactly, and deciding
+# text-versus-binary per file would be a guess that silently corrupts whichever
+# file it gets wrong. A manifest workspace is small, so the encoding overhead is
+# not worth a heuristic.
+kind: Run.Projection
+metadata: { name: readAll }
+inputType:
+  kind: Telo.JsonSchema
+  schema:
+    type: object
+    required: [files]
+    properties:
+      files:
+        type: array
+        items:
+          type: object
+          required: [path, hash]
+          properties:
+            path: { type: string }
+            hash: { type: string }
+collection: !cel "inputs.files"
+concurrency: 8
+steps:
+  - name: read
+    invoke: !ref readFile
+    inputs:
+      path: !cel "item.path"
+      encoding: base64
+outputs:
+  path: !cel "item.path"
+  hash: !cel "item.hash"
+  content: !cel "steps.read.result.content"
+  encoding: base64
+---
+kind: Run.Sequence
+metadata: { name: snapshot }
+steps:
+  - name: tree
+    invoke: !ref treeSnapshot
+    inputs:
+      exclude: !cel "variables.excluded"
+  - name: read
+    invoke: !ref readAll
+    inputs:
+      files: !cel "steps.tree.result.files"
+outputs:
+  files: !cel "steps.read.result"
+---
+kind: Http.Api
+metadata: { name: api }
+routes:
+  # The content-hash tree the editor diffs against its own files. Hashing content
+  # rather than comparing sizes or timestamps is what makes two snapshots diff
+  # into an exact change set.
+  - request:
+      path: /workspace
+      method: GET
+    handler: !ref treeSnapshot
+    inputs:
+      exclude: !cel "variables.excluded"
+    returns:
+      - status: 200
+        content:
+          application/json:
+            body:
+              files: !cel "result.files"
+    catches:
+      - status: 500
+        content:
+          application/json:
+            body:
+              error: !cel "error.message"
+  # An explicit write/delete list, not a whole-tree PUT: a deletion has to be
+  # expressible, and a whole-tree PUT can only express it by treating absence as
+  # intent. There is deliberately no single-file write route — a one-file save is
+  # a change set of one, and a second write path would be a second set of
+  # concurrency rules over the same directory.
+  - request:
+      path: /workspace
+      method: POST
+      schema:
+        body:
+          type: object
+          properties:
+            write:
+              type: array
+              items:
+                type: object
+                required: [path, content]
+                properties:
+                  path: { type: string }
+                  content: { type: string }
+                  encoding: { type: string, enum: [utf8, base64] }
+            delete:
+              type: array
+              items: { type: string }
+    handler: !ref treeSync
+    inputs:
+      write: !cel "has(request.body.write) ? request.body.write : []"
+      delete: !cel "has(request.body.delete) ? request.body.delete : []"
+    returns:
+      - status: 200
+        content:
+          application/json:
+            body:
+              written: !cel "result.written"
+              deleted: !cel "result.deleted"
+    catches:
+      - status: 500
+        content:
+          application/json:
+            body:
+              error: !cel "error.message"
+  - request:
+      path: /workspace/file
+      method: GET
+      schema:
+        query:
+          type: object
+          required: [path]
+          properties:
+            path: { type: string }
+            encoding: { type: string, enum: [utf8, base64] }
+    handler: !ref readFile
+    inputs:
+      path: !cel "request.query.path"
+      encoding: !cel "has(request.query.encoding) ? request.query.encoding : 'utf8'"
+    returns:
+      - status: 200
+        content:
+          application/json:
+            body:
+              content: !cel "result.content"
+              size: !cel "result.size"
+    catches:
+      - status: 500
+        content:
+          application/json:
+            body:
+              error: !cel "error.message"
+  - request:
+      path: /workspace/snapshot
+      method: GET
+    handler: !ref snapshot
+    returns:
+      - status: 200
+        content:
+          application/json:
+            body:
+              files: !cel "result.files"
+    catches:
+      - status: 500
+        content:
+          application/json:
+            body:
+              error: !cel "error.message"
+---
+kind: Http.Server
+metadata: { name: server }
+# Pod-local only. The runner reaches it by pod IP over the cluster network and
+# proxies it outward; nothing here is published via Service or Ingress, and the
+# container holds no credentials of any kind.
+host: 0.0.0.0
+port: !cel "ports.http"
+mounts:
+  - path: /
+    mount: !ref api