@telorun/runner-core 0.6.0 → 0.8.0

package/dist/routes/sessions.js

@@ -1,8 +1,5 @@
-import { isEventFrame } from "@telorun/debug-wire";
-import { ACCEPTED_TERMS_HEADER, SessionStartError, } from "../contract.js";
 import { BundlePathError, normalizeBundlePath } from "../session/bundle-path.js";
-import { generateSessionId } from "../session/session-id.js";
-import { SessionLimitError } from "../session/registry.js";
+import { enforceTerms, portsSchema, startWorkloadSession } from "./session-start.js";
 import { streamSessionEvents } from "../sse/channel.js";
 const startBodySchema = {
     type: "object",
@@ -30,17 +27,7 @@ const startBodySchema = {
             type: "object",
             additionalProperties: { type: "string" },
         },
-        ports: {
-            type: "array",
-            items: {
-                type: "object",
-                required: ["port", "protocol"],
-                properties: {
-                    port: { type: "integer", minimum: 1, maximum: 65535 },
-                    protocol: { type: "string", enum: ["tcp", "udp"] },
-                },
-            },
-        },
+        ports: portsSchema,
         config: {
             type: "object",
             required: ["image", "pullPolicy"],
@@ -56,17 +43,8 @@ const startBodySchema = {
 export function sessionsRoute(deps) {
     return async (app) => {
         app.post("/v1/sessions", { schema: { body: startBodySchema } }, async (req, reply) => {
-            // Terms enforcement — the server is the source of truth, so a client that
-            // skips the editor gate still can't start a session without acknowledging
-            // the current terms version.
-            if (deps.terms) {
-                const raw = req.headers[ACCEPTED_TERMS_HEADER];
-                const accepted = Array.isArray(raw) ? raw[0] : raw;
-                if (accepted !== deps.terms.version) {
-                    reply.code(428).send({ error: "terms_required", terms: deps.terms });
-                    return;
-                }
-            }
+            if (!enforceTerms(req, reply, deps.terms))
+                return;
             return startSession(app, deps, req.body, reply);
         });
         app.get("/v1/sessions/:id", async (req, reply) => {
@@ -111,7 +89,6 @@ export function sessionsRoute(deps) {
     };
 }
 async function startSession(app, deps, body, reply) {
-    const sessionId = generateSessionId();
     let entryRelative;
     try {
         // Traversal guard for the entry path and every bundle file — a `../foo`
@@ -138,87 +115,14 @@ async function startSession(app, deps, body, reply) {
             return;
         }
     }
-    let entry;
-    try {
-        entry = deps.registry.register({ sessionId });
-    }
-    catch (err) {
-        if (err instanceof SessionLimitError) {
-            reply.code(409).send({ error: "too_many_sessions", message: err.message });
-            return;
-        }
-        throw err;
-    }
-    // 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;
-    const registryUrl = configRegistryUrl ?? deps.defaultRegistryUrl;
-    const sessionEnv = registryUrl && !("TELO_REGISTRY_URL" in body.env)
-        ? { ...body.env, TELO_REGISTRY_URL: registryUrl }
-        : body.env;
-    // 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
-    // stream until the workload is already up, so the client never sees build /
-    // provision / boot progress live. Returning the streamUrl first lets the
-    // client connect immediately; start runs in the background and its progress,
-    // output, and terminal status flow over the stream.
-    reply.code(201).send({
-        sessionId,
-        streamUrl: `/v1/sessions/${sessionId}/events`,
-        createdAt: entry.createdAt.toISOString(),
-    });
-    deps.backend
-        .start({
-        sessionId,
+    return startWorkloadSession(app, deps, {
         bundle: body.bundle,
         entryRelativePath: entryRelative,
-        env: sessionEnv,
+        env: body.env,
         ports: body.ports ?? [],
         config: body.config,
+        selfContained: false,
         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 }),
-        onOutput: (chunk) => deps.registry.pushBytes(sessionId, chunk),
-        // Relay only kernel *event* frames to the client. stdout/stderr already
-        // arrive over the byte channel (onOutput), so forwarding log frames would
-        // double the traffic and let log spam evict lifecycle events from the
-        // byte-capped replay buffer. The editor discards relayed logs anyway.
-        onDebug: (frame) => {
-            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) => {
-        entry.session = session;
-        // Pre-start DELETE race: a DELETE received during backend.start (e.g.
-        // while an image build was running) can't stop a workload that didn't
-        // exist yet — it set userStopped and returned 204. Now that the workload
-        // is live, honor the earlier DELETE.
-        if (entry.userStopped) {
-            try {
-                await session.stop();
-            }
-            catch (err) {
-                app.log.warn({ err, sessionId }, "failed to stop after race with pre-start DELETE");
-            }
-        }
-    })
-        .catch((err) => {
-        // The 201 is already sent, so a start failure surfaces as a terminal
-        // `failed` status on the stream (the registry schedules eviction on a
-        // terminal status; the SSE channel delivers it, then closes).
-        const message = err instanceof SessionStartError
-            ? `${err.stage}: ${err.message}`
-            : err instanceof Error
-                ? err.message
-                : String(err);
-        app.log.error({ err, sessionId }, "session start failed");
-        deps.registry.emit(sessionId, { type: "status", status: { kind: "failed", message } });
-    });
+    }, reply);
 }
 //# sourceMappingURL=sessions.js.map

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,14 @@ 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; sessions of them are created via
+     *  `POST /v1/apps/:name/sessions`. */
+    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;AAO5F,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;;;0CAGsC;IACtC,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,CAoEzE;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

@@ -1,6 +1,7 @@
 import Fastify from "fastify";
 import cors from "@fastify/cors";
 import websocket from "@fastify/websocket";
+import { appsRoute } from "./routes/apps.js";
 import { capabilitiesRoute } from "./routes/capabilities.js";
 import { healthRoute } from "./routes/health.js";
 import { ioRoute } from "./routes/io.js";
@@ -25,11 +26,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,
@@ -38,9 +47,16 @@ export async function buildServer(deps) {
         defaultRegistryUrl: deps.defaultRegistryUrl,
         validateConfig: deps.validateConfig,
         // The capabilities document is the single source of the runner's terms;
-        // the session route enforces what /v1/capabilities advertises.
+        // every session-creating route enforces what /v1/capabilities advertises.
         terms: capabilitiesValue.terms,
     }));
+    await app.register(appsRoute({
+        backend: deps.backend,
+        registry,
+        defaultRegistryUrl: deps.defaultRegistryUrl,
+        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":"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"}
+{"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.6.0",
+  "version": "0.8.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/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

@@ -48,6 +48,11 @@ export interface BackendStartSpec {
   env: Record<string, string>;
   ports: PortMapping[];
   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
    *  stream via `onDebug`. The inspect endpoint stays reachable only by the
    *  runner — never published outward. */

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
+   *  (`POST /v1/apps/:name/sessions`). 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: an app session is created via `POST /v1/apps/<name>/sessions`. */
+  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>;

package/src/index.ts

@@ -28,6 +28,7 @@ export { healthRoute } from "./routes/health.js";
 export { capabilitiesRoute } from "./routes/capabilities.js";
 export { probeRoute, type ProbeRouteDeps } from "./routes/probe.js";
 export { sessionsRoute, type SessionsRouteDeps } from "./routes/sessions.js";
+export { appsRoute, type AppsRouteDeps } from "./routes/apps.js";
 export { ioRoute, type IoRouteDeps } from "./routes/io.js";
 export { relayDebugStream, type DebugRelayOptions } from "./debug/relay.js";
 export {

package/src/routes/apps.ts

@@ -0,0 +1,106 @@
+import type { FastifyInstance, FastifyPluginAsync } from "fastify";
+
+import type { RunnerBackend } from "../backend.js";
+import type { ResolvedRunnerApp } from "../config.js";
+import type { PortMapping, RunnerTerms } from "../contract.js";
+import type { SessionRegistry } from "../session/registry.js";
+import { enforceTerms, portsSchema, startWorkloadSession } from "./session-start.js";
+
+export interface AppsRouteDeps {
+  backend: RunnerBackend;
+  registry: SessionRegistry;
+  /** The runner's own default registry URL, surfaced to the workload as
+   *  TELO_REGISTRY_URL when the request doesn't override it. */
+  defaultRegistryUrl?: string;
+  /** Terms gate shared with `POST /v1/sessions` — app sessions execute on the
+   *  operator's infrastructure just like runs, so they ride the same 428. */
+  terms?: RunnerTerms;
+  /** Operator-predefined applications launchable by name. The catalog is the
+   *  whole gate: the client picks a name, never an image, and the operator env
+   *  is injected server-side. */
+  apps?: Record<string, ResolvedRunnerApp>;
+}
+
+interface StartAppSessionBody {
+  env?: Record<string, string>;
+  ports?: PortMapping[];
+  inspect?: boolean;
+}
+
+const startAppBodySchema = {
+  type: "object",
+  properties: {
+    env: {
+      type: "object",
+      additionalProperties: { type: "string" },
+    },
+    ports: portsSchema,
+    inspect: { type: "boolean" },
+  },
+} as const;
+
+/**
+ * Creation door for operator-predefined app sessions. A client launches an app
+ * by name; the runner resolves the image and injects the app's operator env
+ * from the catalog (`RUNNER_APPS`). The created session lives in the SAME
+ * session collection as bundle sessions — the 201 carries the shared
+ * `/v1/sessions/:id/events` stream URL, and status/DELETE/io are served by the
+ * sessions routes.
+ */
+export function appsRoute(deps: AppsRouteDeps): FastifyPluginAsync {
+  return async (app: FastifyInstance) => {
+    app.post<{ Params: { name: string }; Body: StartAppSessionBody }>(
+      "/v1/apps/:name/sessions",
+      { schema: { body: startAppBodySchema } },
+      async (req, reply) => {
+        // Resolve the app before the terms gate: an unknown name is a 404
+        // regardless of terms (there's no workload to gate), and the catalog is
+        // already public on /v1/capabilities, so this leaks nothing.
+        const appEntry = deps.apps?.[req.params.name];
+        if (!appEntry) {
+          const offered = Object.keys(deps.apps ?? {});
+          reply.code(404).send({
+            error: "unknown_app",
+            message:
+              `app '${req.params.name}' is not offered by this runner` +
+              (offered.length > 0
+                ? ` — offered apps: ${offered.join(", ")}`
+                : " — it offers no predefined applications") +
+              " (see /v1/capabilities).",
+          });
+          return;
+        }
+
+        if (!enforceTerms(req, reply, deps.terms)) return;
+
+        // 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 = req.body?.env ?? {};
+        const env = {
+          ...Object.fromEntries(
+            Object.entries(clientEnv).filter(([key]) => !(key in appEntry.env)),
+          ),
+          ...appEntry.env,
+        };
+
+        return startWorkloadSession(
+          app,
+          deps,
+          {
+            // 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: [] },
+            entryRelativePath: "telo.yaml",
+            env,
+            ports: req.body?.ports ?? [],
+            config: { image: appEntry.image, pullPolicy: appEntry.pullPolicy },
+            selfContained: true,
+            inspect: req.body?.inspect ?? false,
+          },
+          reply,
+        );
+      },
+    );
+  };
+}