@telorun/runner-core 0.5.2 → 0.7.0

package/dist/routes/sessions.js

@@ -4,10 +4,13 @@ import { BundlePathError, normalizeBundlePath } from "../session/bundle-path.js"
 import { generateSessionId } from "../session/session-id.js";
 import { SessionLimitError } from "../session/registry.js";
 import { streamSessionEvents } from "../sse/channel.js";
+// `bundle`/`config` are schema-optional because an `app` session needs neither;
+// the route enforces their presence for regular bundle sessions.
 const startBodySchema = {
     type: "object",
-    required: ["bundle", "env", "config"],
+    required: ["env"],
     properties: {
+        app: { type: "string", minLength: 1 },
         bundle: {
             type: "object",
             required: ["entryRelativePath", "files"],
@@ -112,30 +115,68 @@ export function sessionsRoute(deps) {
 }
 async function startSession(app, deps, body, reply) {
     const sessionId = generateSessionId();
+    // App sessions launch an operator-predefined image by name: the catalog
+    // resolves the image and operator env server-side, so the client can neither
+    // pick the image nor reach the secrets — the catalog IS the gate, and an
+    // unknown name is rejected here.
+    const appEntry = body.app === undefined ? undefined : deps.apps?.[body.app];
+    if (body.app !== undefined && !appEntry) {
+        const offered = Object.keys(deps.apps ?? {});
+        reply.code(400).send({
+            error: "unknown_app",
+            message: `app '${body.app}' is not offered by this runner` +
+                (offered.length > 0
+                    ? ` — offered apps: ${offered.join(", ")}`
+                    : " — it offers no predefined applications") +
+                " (see /v1/capabilities).",
+        });
+        return;
+    }
+    if (!appEntry && (!body.bundle || !body.config)) {
+        reply.code(400).send({
+            error: "invalid_request",
+            message: "'bundle' and 'config' are required unless launching a predefined app via 'app'.",
+        });
+        return;
+    }
+    let bundle;
     let entryRelative;
-    try {
-        // Traversal guard for the entry path and every bundle file — a `../foo`
-        // would let the workload read or execute paths outside its session dir.
-        // Validated here (backend-neutral) so a bad path is a 400, not a backend
-        // 500, regardless of how the backend ultimately delivers the bundle.
-        entryRelative = normalizeBundlePath(body.bundle.entryRelativePath);
-        for (const file of body.bundle.files)
-            normalizeBundlePath(file.relativePath);
+    let config;
+    if (appEntry) {
+        // Self-contained image — no bundle to deliver; the entry path is an unused
+        // placeholder so the backend spec stays total.
+        bundle = { entryRelativePath: "telo.yaml", files: [] };
+        entryRelative = bundle.entryRelativePath;
+        config = { image: appEntry.image, pullPolicy: appEntry.pullPolicy };
     }
-    catch (err) {
-        if (err instanceof BundlePathError) {
-            reply.code(400).send({ error: "invalid_bundle", message: err.message });
-            return;
+    else {
+        bundle = body.bundle;
+        config = body.config;
+        try {
+            // Traversal guard for the entry path and every bundle file — a `../foo`
+            // would let the workload read or execute paths outside its session dir.
+            // Validated here (backend-neutral) so a bad path is a 400, not a backend
+            // 500, regardless of how the backend ultimately delivers the bundle.
+            entryRelative = normalizeBundlePath(bundle.entryRelativePath);
+            for (const file of bundle.files)
+                normalizeBundlePath(file.relativePath);
         }
-        throw err;
-    }
-    // Backend config gate (e.g. an image allowlist). The advertised capabilities
-    // constrain the editor; this enforces the same against any client.
-    if (deps.validateConfig) {
-        const message = deps.validateConfig(body.config);
-        if (message) {
-            reply.code(400).send({ error: "invalid_config", message });
-            return;
+        catch (err) {
+            if (err instanceof BundlePathError) {
+                reply.code(400).send({ error: "invalid_bundle", message: err.message });
+                return;
+            }
+            throw err;
+        }
+        // Backend config gate (e.g. an image allowlist). The advertised capabilities
+        // constrain the editor; this enforces the same against any client. App
+        // sessions skip it — their image comes from the catalog, not the client.
+        if (deps.validateConfig) {
+            const message = deps.validateConfig(config);
+            if (message) {
+                reply.code(400).send({ error: "invalid_config", message });
+                return;
+            }
         }
     }
     let entry;
@@ -149,15 +190,24 @@ async function startSession(app, deps, body, reply) {
         }
         throw err;
     }
+    // For an app session, drop client-supplied values for any env key the
+    // catalog defines (a client must never override operator-held values, which
+    // include secrets), then inject the operator's values.
+    const clientEnv = appEntry
+        ? {
+            ...Object.fromEntries(Object.entries(body.env).filter(([key]) => !(key in appEntry.env))),
+            ...appEntry.env,
+        }
+        : body.env;
     // Surface a TELO_REGISTRY_URL to the workload so the telo CLI inside picks
-    // it up. Precedence: body.env explicit value > body.config.registryUrl
-    // (per-request override) > runner's own default. Trim client-supplied URLs
-    // so stray whitespace from an editor input doesn't flow into the workload.
-    const configRegistryUrl = body.config.registryUrl?.trim() || undefined;
+    // it up. Precedence: explicit env value > config.registryUrl (per-request
+    // override) > runner's own default. Trim client-supplied URLs so stray
+    // whitespace from an editor input doesn't flow into the workload.
+    const configRegistryUrl = config.registryUrl?.trim() || undefined;
     const registryUrl = configRegistryUrl ?? deps.defaultRegistryUrl;
-    const sessionEnv = registryUrl && !("TELO_REGISTRY_URL" in body.env)
-        ? { ...body.env, TELO_REGISTRY_URL: registryUrl }
-        : body.env;
+    const sessionEnv = registryUrl && !("TELO_REGISTRY_URL" in clientEnv)
+        ? { ...clientEnv, TELO_REGISTRY_URL: registryUrl }
+        : clientEnv;
     // Respond as soon as the session is registered — BEFORE the backend starts.
     // `backend.start()` now spans the on-cluster image build and pod bring-up,
     // which can take seconds-to-minutes; awaiting it here would hide the event
@@ -173,11 +223,12 @@ async function startSession(app, deps, body, reply) {
     deps.backend
         .start({
         sessionId,
-        bundle: body.bundle,
+        bundle,
         entryRelativePath: entryRelative,
         env: sessionEnv,
         ports: body.ports ?? [],
-        config: body.config,
+        config,
+        selfContained: appEntry !== undefined,
         inspect: body.inspect ?? false,
         onStatus: (status) => deps.registry.emit(sessionId, { type: "status", status }),
         onProgress: (phase, message, done) => deps.registry.emit(sessionId, { type: "progress", phase, message, done }),
@@ -190,6 +241,7 @@ async function startSession(app, deps, body, reply) {
             if (isEventFrame(frame))
                 deps.registry.emit(sessionId, { type: "debug", frame });
         },
+        onReachability: (port, state) => deps.registry.emit(sessionId, { type: "reachability", port, state }),
         isUserStopped: () => entry.userStopped,
     })
         .then(async (session) => {

package/dist/routes/sessions.js.map

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

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import { type FastifyBaseLogger, type FastifyInstance } from "fastify";
 import type { RunnerBackend } from "./backend.js";
-import type { RunnerCoreConfig } from "./config.js";
+import type { ResolvedRunnerApp, RunnerCoreConfig } from "./config.js";
 import type { RunnerCapabilities, SessionConfig } from "./contract.js";
 import { SessionRegistry } from "./session/registry.js";
 export interface ServerDeps {
@@ -16,8 +16,13 @@ export interface ServerDeps {
     /** Runner's default registry URL, passed to workloads as TELO_REGISTRY_URL. */
     defaultRegistryUrl?: string;
     /** Backend config gate, enforced on `POST /v1/sessions` before the workload
-     *  starts (e.g. an `image` allowlist). Rejects with `400 invalid_config`. */
+     *  starts (e.g. an `image` allowlist). Rejects with `400 invalid_config`.
+     *  Not consulted for app sessions — their image comes from `apps`. */
     validateConfig?: (config: SessionConfig) => string | undefined;
+    /** Operator-predefined applications launchable by name (usually
+     *  `loadResolvedApps(process.env)`). Advertised on /v1/capabilities as
+     *  `apps` descriptors; the session route resolves and gates against it. */
+    apps?: Record<string, ResolvedRunnerApp>;
     registry?: SessionRegistry;
 }
 export interface ServerHandle {

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAIhF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAMvE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,gBAAgB,CAAC;IACzB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB;;;4EAGwE;IACxE,YAAY,EAAE,kBAAkB,GAAG,CAAC,MAAM,kBAAkB,CAAC,CAAC;IAC9D,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;iFAC6E;IAC7E,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/D,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,eAAe,CAAC;IACrB,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,CA8CzE;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAAC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAcf"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,KAAK,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,SAAS,CAAC;AAIhF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,KAAK,EAAuB,kBAAkB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAM5F,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,aAAa,CAAC;IACvB,MAAM,EAAE,gBAAgB,CAAC;IACzB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB;;;4EAGwE;IACxE,YAAY,EAAE,kBAAkB,GAAG,CAAC,MAAM,kBAAkB,CAAC,CAAC;IAC9D,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;0EAEsE;IACtE,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/D;;+EAE2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IACzC,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,eAAe,CAAC;IACrB,QAAQ,EAAE,eAAe,CAAC;CAC3B;AAED,wBAAsB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,YAAY,CAAC,CA4DzE;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,eAAe,EACzB,GAAG,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAAC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/dist/server.js

@@ -25,11 +25,19 @@ export async function buildServer(deps) {
             exitTtlMs: deps.config.exitTtlMs,
             replayBufferBytes: deps.config.replayBufferBytes,
         });
+    // The app catalog is injected into the served capabilities document here, so
+    // what /v1/capabilities advertises and what the session route accepts can
+    // never drift — both come from `deps.apps`.
+    const appDescriptors = Object.values(deps.apps ?? {}).map(({ name, title, description }) => ({ name, title, description }));
+    const withApps = (caps) => appDescriptors.length > 0 ? { ...caps, apps: appDescriptors } : caps;
+    const capabilitiesGetter = typeof deps.capabilities === "function"
+        ? () => withApps(deps.capabilities())
+        : withApps(deps.capabilities);
     // Terms are stable across the process — resolve the capabilities once for them
     // even when `capabilities` is a getter (the route still re-resolves per request).
-    const capabilitiesValue = typeof deps.capabilities === "function" ? deps.capabilities() : deps.capabilities;
+    const capabilitiesValue = typeof capabilitiesGetter === "function" ? capabilitiesGetter() : capabilitiesGetter;
     await app.register(healthRoute(deps.version));
-    await app.register(capabilitiesRoute(deps.capabilities));
+    await app.register(capabilitiesRoute(capabilitiesGetter));
     await app.register(probeRoute({ backend: deps.backend }));
     await app.register(sessionsRoute({
         backend: deps.backend,
@@ -40,6 +48,7 @@ export async function buildServer(deps) {
         // The capabilities document is the single source of the runner's terms;
         // the session route enforces what /v1/capabilities advertises.
         terms: capabilitiesValue.terms,
+        apps: deps.apps,
     }));
     await app.register(ioRoute({ registry, corsOrigins: deps.config.corsOrigins }));
     return { app, registry };

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,OAAyD,MAAM,SAAS,CAAC;AAChF,OAAO,IAAI,MAAM,eAAe,CAAC;AACjC,OAAO,SAAS,MAAM,oBAAoB,CAAC;AAK3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAyBxD,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAgB;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC;QAClB,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE;KACxC,CAAC,CAAC;IAEH,2EAA2E;IAC3E,6EAA6E;IAC7E,mEAAmE;IACnE,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE;QACvB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;QAC/B,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,CAAC;KAC9C,CAAC,CAAC;IAEH,MAAM,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAE9B,MAAM,QAAQ,GACZ,IAAI,CAAC,QAAQ;QACb,IAAI,eAAe,CAAC;YAClB,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;YACpC,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;YAChC,iBAAiB,EAAE,IAAI,CAAC,MAAM,CAAC,iBAAiB;SACjD,CAAC,CAAC;IAEL,+EAA+E;IAC/E,kFAAkF;IAClF,MAAM,iBAAiB,GACrB,OAAO,IAAI,CAAC,YAAY,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC;IAEpF,MAAM,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9C,MAAM,GAAG,CAAC,QAAQ,CAAC,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IACzD,MAAM,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC1D,MAAM,GAAG,CAAC,QAAQ,CAChB,aAAa,CAAC;QACZ,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ;QACR,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;QACpC,kBAAkB,EAAE,IAAI,CAAC,kBAAkB;QAC3C,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,wEAAwE;QACxE,+DAA+D;QAC/D,KAAK,EAAE,iBAAiB,CAAC,KAAK;KAC/B,CAAC,CACH,CAAC;IACF,MAAM,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;IAEhF,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,QAAyB,EACzB,GAA6C;IAE7C,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;IACtF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAC9B,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,wCAAwC,CAAC,CAAC;IAC3E,MAAM,OAAO,CAAC,GAAG,CACf,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACvB,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC;QAC9B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,EAAE,wCAAwC,CAAC,CAAC;QAC1F,CAAC;IACH,CAAC,CAAC,CACH,CAAC;AACJ,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/runner-core",
-  "version": "0.5.2",
+  "version": "0.7.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",

package/src/abortable-delay.ts

@@ -0,0 +1,24 @@
+/**
+ * Resolve after `ms`, or immediately when `signal` aborts. Safe to call in a
+ * poll loop on a shared signal: it removes its abort listener on the timer path
+ * (so repeated calls can't accumulate listeners) and fast-paths an
+ * already-aborted signal (so a loop tears down promptly instead of waiting out
+ * one more interval). The timer is `unref`'d so a pending delay can't keep the
+ * process alive on its own.
+ */
+export function abortableDelay(ms: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal.aborted) return resolve();
+    let timer: ReturnType<typeof setTimeout>;
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      resolve();
+    };
+    timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    timer.unref?.();
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/app-catalog.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+
+import { loadAppsFromEnv, loadResolvedApps, RunnerConfigError } from "./config.js";
+
+describe("loadAppsFromEnv", () => {
+  it("returns undefined when RUNNER_APPS is unset (no apps offered)", () => {
+    expect(loadAppsFromEnv({})).toBeUndefined();
+  });
+
+  it("parses a valid catalog", () => {
+    const catalog = loadAppsFromEnv({
+      RUNNER_APPS: JSON.stringify({
+        tool: {
+          image: "acme/tool:1.2.0",
+          env: { SERVICE_TOKEN: "tok-op" },
+          pullPolicy: "never",
+        },
+      }),
+    })!;
+    expect(catalog.tool.image).toBe("acme/tool:1.2.0");
+    expect(catalog.tool.env).toEqual({ SERVICE_TOKEN: "tok-op" });
+  });
+
+  it("rejects malformed JSON and invalid entries loudly", () => {
+    expect(() => loadAppsFromEnv({ RUNNER_APPS: "{nope" })).toThrow(RunnerConfigError);
+    expect(() => loadAppsFromEnv({ RUNNER_APPS: '{"x":{}}' })).toThrow(/needs a non-empty string 'image'/);
+    expect(() => loadAppsFromEnv({ RUNNER_APPS: '{"x":{"image":"i","env":["nope"]}}' })).toThrow(
+      /invalid 'env'/,
+    );
+    expect(() =>
+      loadAppsFromEnv({ RUNNER_APPS: '{"x":{"image":"i","pullPolicy":"sometimes"}}' }),
+    ).toThrow(/pullPolicy/);
+  });
+});
+
+describe("loadResolvedApps", () => {
+  it("is empty when RUNNER_APPS is unset", () => {
+    expect(loadResolvedApps({})).toEqual({});
+  });
+
+  it("applies defaults to the configured catalog", () => {
+    const resolved = loadResolvedApps({
+      RUNNER_APPS: '{"tool":{"image":"acme/tool:1"}}',
+    });
+    expect(resolved.tool).toEqual({
+      name: "tool",
+      image: "acme/tool:1",
+      env: {},
+      pullPolicy: "missing",
+      title: undefined,
+      description: undefined,
+    });
+  });
+});

package/src/backend.ts

@@ -4,6 +4,7 @@ import type {
   AvailabilityReport,
   PortMapping,
   ProbeConfig,
+  ReachabilityState,
   RunBundle,
   RunPhase,
   RunStatus,
@@ -47,6 +48,11 @@ export interface BackendStartSpec {
   env: Record<string, string>;
   ports: PortMapping[];
   config: SessionConfig;
+  /** True for an operator-predefined app session (`StartSessionRequest.app`):
+   *  `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
    *  stream via `onDebug`. The inspect endpoint stays reachable only by the
    *  runner — never published outward. */
@@ -64,6 +70,10 @@ export interface BackendStartSpec {
   /** 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;
+  /** 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;
   /** True once a user stop / shutdown has been requested — lets the backend
    *  classify a kill as `stopped` rather than `failed`. */
   isUserStopped(): boolean;

package/src/config.ts

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 
-import type { RunnerTerms } from "./contract.js";
+import type { PullPolicy, RunnerTerms } from "./contract.js";
 
 /**
  * Backend-neutral runner configuration. Concrete runners (docker, k8s) extend
@@ -91,6 +91,121 @@ function hashTermsVersion(body: string): string {
   return createHash("sha256").update(body).digest("hex").slice(0, 12);
 }
 
+/**
+ * An operator-predefined application entry in `RUNNER_APPS`. The catalog is the
+ * whole gate: a client launches an app by name and can neither pick the image
+ * nor read the injected env, so no allowlist beyond the catalog is needed.
+ *
+ * The catalog may embed secrets (`env` values), so treat the whole `RUNNER_APPS`
+ * value as secret material (docker: a `.env.local` file; k8s: source it from a
+ * Secret). Only `name`/`title`/`description` are ever advertised outward —
+ * `image` and `env` never leave the runner.
+ */
+export interface RunnerAppConfig {
+  image: string;
+  /** Env injected verbatim into the app's workload (operator secrets included).
+   *  A client-supplied value for any key defined here is dropped — operator
+   *  values always win. */
+  env?: Record<string, string>;
+  /** Workload image pull policy (default `missing`); `always` keeps a moving
+   *  tag like `latest-slim` fresh. */
+  pullPolicy?: PullPolicy;
+  title?: string;
+  description?: string;
+}
+
+/** A validated catalog entry with defaults applied, keyed back by its name. */
+export interface ResolvedRunnerApp {
+  name: string;
+  image: string;
+  env: Record<string, string>;
+  pullPolicy: PullPolicy;
+  title?: string;
+  description?: string;
+}
+
+const PULL_POLICIES: readonly string[] = ["missing", "always", "never"];
+
+/**
+ * Parse the `RUNNER_APPS` JSON catalog ({ "<name>": RunnerAppConfig }).
+ * Returns `undefined` when unset (no apps offered). Malformed JSON or entries
+ * are a hard `RunnerConfigError` — a broken catalog must not silently drop
+ * the apps.
+ */
+export function loadAppsFromEnv(
+  env: NodeJS.ProcessEnv,
+): Record<string, RunnerAppConfig> | undefined {
+  const raw = env.RUNNER_APPS?.trim();
+  if (!raw) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new RunnerConfigError(`RUNNER_APPS is not valid JSON: ${(err as Error).message}`);
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new RunnerConfigError("RUNNER_APPS must be a JSON object mapping app name → app config.");
+  }
+  // Null-prototype map so an app literally named `__proto__` is stored as a
+  // plain key rather than mutating the object's prototype.
+  const catalog: Record<string, RunnerAppConfig> = Object.create(null);
+  for (const [name, value] of Object.entries(parsed)) {
+    catalog[name] = validateAppEntry(name, value);
+  }
+  return catalog;
+}
+
+function validateAppEntry(name: string, value: unknown): RunnerAppConfig {
+  const fail = (detail: string): never => {
+    throw new RunnerConfigError(`RUNNER_APPS entry '${name}' ${detail}`);
+  };
+  if (name.trim() === "") fail("has an empty name.");
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    fail("must be an object.");
+  }
+  const entry = value as Record<string, unknown>;
+  if (typeof entry.image !== "string" || entry.image.trim() === "") {
+    fail("needs a non-empty string 'image'.");
+  }
+  if (
+    entry.env !== undefined &&
+    (entry.env === null ||
+      typeof entry.env !== "object" ||
+      Array.isArray(entry.env) ||
+      Object.values(entry.env).some((v) => typeof v !== "string"))
+  ) {
+    fail("has an invalid 'env' — expected an object of string values.");
+  }
+  if (entry.pullPolicy !== undefined && !PULL_POLICIES.includes(entry.pullPolicy as string)) {
+    fail(`has an invalid 'pullPolicy' — expected one of ${PULL_POLICIES.join(", ")}.`);
+  }
+  for (const key of ["title", "description"] as const) {
+    if (entry[key] !== undefined && typeof entry[key] !== "string") {
+      fail(`has an invalid '${key}' — expected a string.`);
+    }
+  }
+  return entry as unknown as RunnerAppConfig;
+}
+
+/** The catalog runners pass to `buildServer`: `RUNNER_APPS` validated with
+ *  defaults applied; empty when unset. The catalog is pure operator
+ *  configuration — runner-core knows nothing about any specific app. */
+export function loadResolvedApps(env: NodeJS.ProcessEnv): Record<string, ResolvedRunnerApp> {
+  const catalog = loadAppsFromEnv(env) ?? {};
+  const resolved: Record<string, ResolvedRunnerApp> = Object.create(null);
+  for (const [name, entry] of Object.entries(catalog)) {
+    resolved[name] = {
+      name,
+      image: entry.image,
+      env: entry.env ?? {},
+      pullPolicy: entry.pullPolicy ?? "missing",
+      title: entry.title,
+      description: entry.description,
+    };
+  }
+  return resolved;
+}
+
 export function parseCorsOrigins(raw: string | undefined): string[] | "*" {
   if (raw === undefined || raw.trim() === "" || raw.trim() === "*") return "*";
   return raw

package/src/contract.ts

@@ -29,6 +29,10 @@ export interface RunnerCapabilities {
    *  with `428 terms_required` unless the client sends `x-telo-accepted-terms`
    *  matching `terms.version`. The editor surfaces it and records acceptance. */
   terms?: RunnerTerms;
+  /** Operator-predefined applications this runner can launch by name
+   *  (`StartSessionRequest.app`). Absent/empty when none are offered — clients
+   *  hide the corresponding entry points. */
+  apps?: RunnerAppDescriptor[];
 }
 
 /** An operator-defined agreement. `version` is opaque and operator-controlled;
@@ -49,6 +53,18 @@ export interface RunnerFeatures {
   ports: boolean;
 }
 
+/** An operator-predefined application the runner can launch by name. Only the
+ *  identity is advertised — the image and the operator env injected into it
+ *  stay server-side, so a client can never pick the image or reach the
+ *  secrets. Which apps exist is pure operator configuration (`RUNNER_APPS`);
+ *  the runner has no built-in knowledge of any specific app. */
+export interface RunnerAppDescriptor {
+  /** Wire id requested via `StartSessionRequest.app`. */
+  name: string;
+  title?: string;
+  description?: string;
+}
+
 /** A JSON Schema document, kept structurally open so runner-core need not depend
  *  on a JSON-Schema type package. The editor treats it as `JSONSchema7`. */
 export type JsonSchema = Record<string, unknown>;
@@ -103,10 +119,17 @@ export interface RunnerEndpoint {
 }
 
 export interface StartSessionRequest {
-  bundle: RunBundle;
+  /** Launch an operator-predefined application by name (see
+   *  {@link RunnerAppDescriptor}) instead of a client bundle. The runner
+   *  resolves the image and injects the app's operator env server-side;
+   *  `bundle` and `config.image` are ignored. */
+  app?: string;
+  /** Required unless `app` is set. */
+  bundle?: RunBundle;
   env: Record<string, string>;
   ports?: PortMapping[];
-  config: SessionConfig;
+  /** Required unless `app` is set. */
+  config?: SessionConfig;
   /** 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
@@ -131,6 +154,11 @@ export type RunStatus =
  */
 export type RunPhase = "build" | "provision" | "boot";
 
+/** Per-port reachability of a running session's declared ports, watched by the
+ *  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 }
   | { type: "stderr"; chunk: string }
@@ -138,7 +166,9 @@ export type RunEvent =
   | { type: "progress"; 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`. */
-  | { type: "debug"; frame: DebugFrame };
+  | { type: "debug"; frame: DebugFrame }
+  /** A reachability transition for one declared port, keyed by port. */
+  | { type: "reachability"; port: number; state: ReachabilityState };
 
 export function isTerminal(status: RunStatus): boolean {
   return status.kind === "exited" || status.kind === "failed" || status.kind === "stopped";

package/src/debug/relay.ts

@@ -1,5 +1,7 @@
 import type { DebugFrame } from "@telorun/debug-wire";
 
+import { abortableDelay } from "../abortable-delay.js";
+
 export interface DebugRelayOptions {
   /** The workload's inspect SSE endpoint, e.g. `http://telo-run-<id>:9230/events`.
    *  Reachable only by the runner over the backend's private network. */
@@ -34,7 +36,7 @@ export async function relayDebugStream(opts: DebugRelayOptions): Promise<void> {
         headers: { accept: "text/event-stream" },
       });
       if (!res.ok || !res.body) {
-        await delay(RECONNECT_DELAY_MS, signal);
+        await abortableDelay(RECONNECT_DELAY_MS, signal);
         continue;
       }
       await pump(res.body, onFrame, signal);
@@ -42,7 +44,7 @@ export async function relayDebugStream(opts: DebugRelayOptions): Promise<void> {
       if (signal.aborted) return;
       opts.onError?.(err instanceof Error ? err : new Error(String(err)));
     }
-    await delay(RECONNECT_DELAY_MS, signal);
+    await abortableDelay(RECONNECT_DELAY_MS, signal);
   }
 }
 
@@ -87,18 +89,3 @@ function parseSseData(block: string): DebugFrame | null {
     return null;
   }
 }
-
-function delay(ms: number, signal: AbortSignal): Promise<void> {
-  return new Promise((resolve) => {
-    if (signal.aborted) return resolve();
-    const timer = setTimeout(() => {
-      signal.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    const onAbort = (): void => {
-      clearTimeout(timer);
-      resolve();
-    };
-    signal.addEventListener("abort", onAbort, { once: true });
-  });
-}