@skaile/forge-agent-runtime 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 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`.
+- `AgentProcessConfig` and `AgentAdapterConfig` gain `host` and `wsAuthToken`. `host` becomes `--host` for `skaile serve` and the client dial address. `wsAuthToken` becomes `SKAILE_WS_AUTH_TOKEN` in the child environment and the client transport's `auth`. Both default to the previous behaviour when unset.
+- Credentials are resolved through `@skaile/forge-settings/server`; the package re-exports no credential helper.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthias Ortegro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# @skaile/forge-agent-runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The agent process lifecycle Skaile forge apps run on. It spawns a `skaile serve`
+subprocess per session, connects to it over WebSocket, and exposes the result
+through the `AgentAdapter` contract, a harness registry and a session manager
+base class.
+
+Node-only. The package imports no Nuxt, database, settings UI or Directus code.
+Credential helpers stay in `@skaile/forge-settings/server`; this package calls
+`registryCredentialEnv` from there to deliver provider credentials to the child
+and re-exports nothing from it.
+
+## Install
+
+```sh
+bun add @skaile/forge-agent-runtime @skaile/forge-settings @skaile/workspaces
+```
+
+## Entry point
+
+`@skaile/forge-agent-runtime`
+
+| Export | Purpose |
+|---|---|
+| `AgentProcessManager`, `AgentProcessConfig` | Spawn `skaile serve`, connect, send prompt/cancel, shut down. Emits `event:<id>` and `error:<id>`. |
+| `ProcessManagerAdapter`, `AgentAdapter`, `AgentAdapterConfig`, `AgentCommand`, `AgentEvent`, `AgentStatus` | One adapter per session behind the canonical contract. |
+| `createAdapterForHarness`, `registerHarness`, `listRegisteredHarnesses` | Harness name → adapter factory (`omp`, `claude-sdk`, fallback `omp`). |
+| `BaseAgentManager`, `ManagedSession` | Session lifecycle base class. A host implements `buildProcessKey`, `buildAdapterConfig`, `getMessagesDir`, `onSessionCreated` and optionally `onEvent`. |
+| `JsonlMessageStore`, `EventEmitterSubscriberTransport`, `FanoutTransport` | Session persistence and SSE fan-out used by `BaseAgentManager`. |
+
+## Private runner options
+
+`AgentProcessConfig` and `AgentAdapterConfig` accept two options for hosts that
+must keep the child private:
+
+- `host` — address `skaile serve` binds (`--host`) and the client dials. Absent:
+  the runtime's default bind and a client dial on `127.0.0.1`.
+- `wsAuthToken` — bearer token the child's WebSocket requires. It reaches the
+  child as `SKAILE_WS_AUTH_TOKEN` (the runtime deletes it from its own
+  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, `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`), `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.
+
+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.
+
+```ts
+// before
+import { AgentProcessManager, BaseAgentManager, JsonlMessageStore } from "@skaile/forge-common/server";
+// after
+import { AgentProcessManager, BaseAgentManager, JsonlMessageStore } from "@skaile/forge-agent-runtime";
+```
+
+`AgentProcessConfig` is no longer exported from `@skaile/forge-common/types`.
+
+## Development
+
+```sh
+bun install
+bun run build
+bun run typecheck
+bun run test
+```
+
+Releases publish from a `v*` tag through `.github/workflows/publish.yml` (npm
+trusted publishing).

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 };