@skaile/forge-agent-runtime 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.1.1
+
+- `app-runner-host`: a run whose `skaile serve` child exits, or whose connection is found dead on a command (`410`), is torn down immediately: credentials erased, scratch directory removed, listener closed, later requests `404`. The final error event is still delivered to `onEvent`. Before, the run stayed registered until its lease expired.
+- `POST /runs` answers `400` when `model` does not name an enabled `llm` provider of the snapshot (`<providerId>/<modelId>`), before any directory or process is created. Before it surfaced as an opaque `503` after startup.
+- Native tools stay disabled through `tools.allowed: ["WebFetch"]`, because the Workspaces schema has no explicit empty form; a test now asserts that `buildOmpToolArgs` turns the written agent definition into `--no-tools`.
+- Internal: the registry shape is validated once (`requireRegistryShape`) and `StartRunRequest.registry` is typed; routing uses one method table; the provider snapshot throws a domain error that the host maps to `400` instead of depending on the HTTP request module.
+
+## 1.1.0
+
+- New entry `@skaile/forge-agent-runtime/app-runner-host`: `createAppRunnerHost({ rootDir, authenticate, onEvent, appTools })`, an authenticated HTTP host that runs one isolated `omp` agent per request for an app that deploys it privately next to itself. Node-only; it imports no Nuxt, database or settings UI code, and the package root is unchanged.
+- Run lifecycle over HTTP: `POST /runs`, `POST /runs/:id/commands` (the Workspaces commands `prompt`, `cancel`, `reply`, `capability_register`, `capability_deregister`, `capability_result` only), `PATCH /runs/:id/lease`, idempotent `DELETE /runs/:id`. `authenticate` runs before anything is read from a request. An expired lease cancels the turn; a failed `onEvent` terminates the run without replay.
+- Each run has its own scratch workspace, HOME and `.skaile/providers.yml` snapshot, its own `skaile serve` child bound to `127.0.0.1` with a fresh WebSocket token, and an environment of exactly `PATH`, `LANG`, `HOME`, `SKAILE_HOME`, `TMPDIR`, the canonical `SKAILE_AIP_<ID>_KEY` provider keys, `APP_MCP_AUTHORIZATION` and `SKAILE_WS_AUTH_TOKEN`.
+- The child runs harness `omp` with native tools disabled. Its only tools are the host tools `mcp__<mcpName>__*` from one generated app MCP endpoint and the trusted `browserActionNames`, enforced through `tools.host_allowed`. No agent instances and no other MCP servers are declared.
+- Requires `@skaile/workspaces` ^6.11.0 (`tools.host_allowed`).
+
 ## 1.0.0
 
 - Initial release. Extracted from `@skaile/forge-common` 10.x without behaviour change: `AgentProcessManager`, `ProcessManagerAdapter`, the `AgentAdapter` contract, the harness registry, `BaseAgentManager`, `JsonlMessageStore`, `EventEmitterSubscriberTransport` and `FanoutTransport`.

package/README.md

@@ -40,6 +40,64 @@ must keep the child private:
   environment at startup, so agent processes never see it) and the client
   transport presents it. Absent: no authentication, as before.
 
+## App runner host
+
+`@skaile/forge-agent-runtime/app-runner-host` is an HTTP host an app deploys
+privately next to itself. Each request starts one isolated `omp` agent whose only
+tools are the app's own MCP endpoint and a fixed set of browser actions. It
+imports no Nuxt, database or settings UI code.
+
+```ts
+import { createServer } from "node:http";
+import { createAppRunnerHost } from "@skaile/forge-agent-runtime/app-runner-host";
+
+const host = createAppRunnerHost({
+  rootDir: "/var/lib/runner/runs", // private; one directory per run
+  authenticate: async (req) => req.headers.authorization === `Bearer ${process.env.RUNNER_TOKEN}`,
+  onEvent: async (runId, event) => {
+    // deliver to the app; a rejection terminates the run, events are never replayed
+  },
+  appTools: {
+    mcpName: "planner", // tools reach the model as mcp__planner__*
+    mcpUrl: "http://app:3000/mcp",
+    browserActionNames: ["app.ui.open_training"],
+  },
+});
+createServer((req, res) => void host.handler(req, res)).listen(8081, "0.0.0.0");
+```
+
+`appTools` is startup configuration. A request can never name a tool or a
+destination. `host.close()` terminates every run.
+
+| Request | Behaviour |
+|---|---|
+| `POST /runs` | Body `{ id, model, registry, credentialEnv, systemPrompt, mcpAuthorization, expiresAt }`. `id` is a UUID, `expiresAt` an ISO-8601 time or epoch milliseconds in the future, `mcpAuthorization` the full `Authorization` header value for the app MCP endpoint. `400` invalid, including a `model` whose `<providerId>` is not an enabled `llm` entry of the `registry` (refused before any directory or process exists), `409` id already active, `503` the runtime did not start, `201` started. |
+| `POST /runs/:id/commands` | One Workspaces command: `prompt`, `cancel`, `reply`, `capability_register`, `capability_deregister` or `capability_result`. `400` any other type or a malformed field, `404` no such run, `410` lease expired (except `cancel`) or the run's process has ended, `202` sent. `capability_register` accepts only the declared `browserActionNames`. |
+| `PATCH /runs/:id/lease` | Body `{ expiresAt }`. `400` not in the future, `404` no such run, `410` already expired. |
+| `DELETE /runs/:id` | Idempotent `204`. Stops the process and its listener, erases the run's credentials and removes its scratch directory. |
+
+`authenticate` is called first. `false` answers `401` and a throw `500`; the body
+is never read in either case. When a lease expires the turn is cancelled, further
+commands answer `410`, and the run is torn down a few seconds later. A run whose child process exits (or whose connection is found dead) is torn down at once: credentials erased, scratch removed, later requests answer `404`.
+
+What a run is:
+
+- **Process.** One `ProcessManagerAdapter` and one `skaile serve --harness omp` child per run, bound to
+  `127.0.0.1`, requiring a fresh random WebSocket token. The event subscription exists before the first command.
+- **Files.** `<rootDir>/<id>/` holds the workspace (`skaile.yaml`, `agent/agent.yaml`, `.skaile/providers.yml`),
+  `home/`, `skaile-home/` and `tmp/`. No secret is written to any of them.
+- **Environment.** Exactly `PATH`, `LANG`, `HOME`, `SKAILE_HOME`, `TMPDIR`, one `SKAILE_AIP_<ID>_KEY` per
+  provider, `APP_MCP_AUTHORIZATION` and `SKAILE_WS_AUTH_TOKEN`.
+- **Providers.** Only enabled `llm` entries are kept. Each credential must be an `env:NAME` reference; its value is
+  read from `credentialEnv` and handed to the child under the canonical `SKAILE_AIP_<ID>_KEY`, and the written
+  reference is rewritten to that name. `cmd:`, `keyring:` and `platform:` references, and `${NAME}` interpolation in
+  `base_url`, `headers` and `query_params`, are refused with `400`.
+- **Tools.** Native omp tools are disabled. The host tool allowlist is `mcp__<mcpName>__*` plus the browser action
+  names; the app MCP endpoint is the only MCP server and no agent instances are declared. This needs
+  `@skaile/workspaces` 6.11 (`tools.host_allowed`).
+
+A throwaway proof against the real `omp` binary is in `scripts/proof-app-runner-host.ts`.
+
 ## Migrating from `@skaile/forge-common/server`
 
 Replace the import specifier; names are unchanged.

package/dist/app-runner-host/index.d.mts

@@ -0,0 +1,61 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { AgentEvent } from '../index.mjs';
+import '@skaile/forge-settings/server';
+
+/**
+ * Trusted startup configuration naming what a run may reach. It is never taken
+ * from a request: a caller of the host can start and steer runs, it cannot widen
+ * what they are allowed to call.
+ */
+interface AppRunnerTools {
+    /**
+     * Name of the one generated MCP server. Its tools are offered to the model as
+     * the host tools `mcp__<mcpName>__<tool>`. Letters, digits, `_` and `-`; no `__`.
+     */
+    mcpName: string;
+    /** `http(s)` URL of the app's MCP endpoint. */
+    mcpUrl: string;
+    /**
+     * Exact names of the browser-side actions a client may register with
+     * `capability_register`. Wildcards are not accepted here.
+     */
+    browserActionNames: readonly string[];
+}
+interface AppRunnerHostOptions {
+    /** Private directory each run's scratch workspace is created under. */
+    rootDir: string;
+    /**
+     * Called for every request before anything is read from it. `false` answers
+     * 401; a throw answers 500. Neither parses the body.
+     */
+    authenticate(req: IncomingMessage): Promise<boolean>;
+    /**
+     * Receives every agent event of a run, in order, one at a time. A rejection
+     * terminates the run: events are never replayed.
+     */
+    onEvent(runId: string, event: AgentEvent): Promise<void>;
+    appTools: AppRunnerTools;
+}
+interface AppRunnerHost {
+    /**
+     * Request handler for `POST /runs`, `POST /runs/:id/commands`,
+     * `PATCH /runs/:id/lease` and `DELETE /runs/:id`. `req.url` is matched from the
+     * host root, so a caller that mounts the handler under a prefix strips it first.
+     */
+    handler(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /** Terminates every run, erases its credentials and scratch, and refuses new requests. */
+    close(): Promise<void>;
+}
+
+/**
+ * Create the isolated app runner host.
+ *
+ * One run is one `skaile serve` child (through {@link ProcessManagerAdapter}) with
+ * its own scratch workspace, HOME and provider snapshot. The child binds loopback
+ * and requires a fresh WebSocket token. Its only tools are the app MCP endpoint
+ * and the trusted browser actions, as host tools.
+ */
+declare function createAppRunnerHost(options: AppRunnerHostOptions): AppRunnerHost;
+
+export { createAppRunnerHost };
+export type { AppRunnerHost, AppRunnerHostOptions, AppRunnerTools };

package/dist/app-runner-host/index.d.ts

@@ -0,0 +1,61 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { AgentEvent } from '../index.js';
+import '@skaile/forge-settings/server';
+
+/**
+ * Trusted startup configuration naming what a run may reach. It is never taken
+ * from a request: a caller of the host can start and steer runs, it cannot widen
+ * what they are allowed to call.
+ */
+interface AppRunnerTools {
+    /**
+     * Name of the one generated MCP server. Its tools are offered to the model as
+     * the host tools `mcp__<mcpName>__<tool>`. Letters, digits, `_` and `-`; no `__`.
+     */
+    mcpName: string;
+    /** `http(s)` URL of the app's MCP endpoint. */
+    mcpUrl: string;
+    /**
+     * Exact names of the browser-side actions a client may register with
+     * `capability_register`. Wildcards are not accepted here.
+     */
+    browserActionNames: readonly string[];
+}
+interface AppRunnerHostOptions {
+    /** Private directory each run's scratch workspace is created under. */
+    rootDir: string;
+    /**
+     * Called for every request before anything is read from it. `false` answers
+     * 401; a throw answers 500. Neither parses the body.
+     */
+    authenticate(req: IncomingMessage): Promise<boolean>;
+    /**
+     * Receives every agent event of a run, in order, one at a time. A rejection
+     * terminates the run: events are never replayed.
+     */
+    onEvent(runId: string, event: AgentEvent): Promise<void>;
+    appTools: AppRunnerTools;
+}
+interface AppRunnerHost {
+    /**
+     * Request handler for `POST /runs`, `POST /runs/:id/commands`,
+     * `PATCH /runs/:id/lease` and `DELETE /runs/:id`. `req.url` is matched from the
+     * host root, so a caller that mounts the handler under a prefix strips it first.
+     */
+    handler(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /** Terminates every run, erases its credentials and scratch, and refuses new requests. */
+    close(): Promise<void>;
+}
+
+/**
+ * Create the isolated app runner host.
+ *
+ * One run is one `skaile serve` child (through {@link ProcessManagerAdapter}) with
+ * its own scratch workspace, HOME and provider snapshot. The child binds loopback
+ * and requires a fresh WebSocket token. Its only tools are the app MCP endpoint
+ * and the trusted browser actions, as host tools.
+ */
+declare function createAppRunnerHost(options: AppRunnerHostOptions): AppRunnerHost;
+
+export { createAppRunnerHost };
+export type { AppRunnerHost, AppRunnerHostOptions, AppRunnerTools };