@skaile/forge-agent-runtime 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.2.0
+
+- New in `@skaile/forge-agent-runtime/app-runner-host`: `createAgentRunner({ rootDir, onEvent, onRunEnd?, appTools })`, the run lifecycle of the app runner host without HTTP, for an app that runs its agents in-process. `start({ id?, model, registry, credentialEnv?, systemPrompt, mcpAuthorization?, expiresAt })` resolves with the run id; `command(runId, command)`, `lease(runId, expiresAt)`, `stop(runId)` (idempotent), `has(runId)` and `close()`. A run has the same isolation as a host run: own scratch workspace, HOME, `SKAILE_HOME` and provider snapshot, `--no-tools` with `tools.host_allowed`, the minimal child environment and a fresh WebSocket token. Refusals are `AgentRunnerError`s with a `code` (`invalid`, `conflict`, `not_found`, `starting`, `expired`, `ended`, `start_failed`, `closed`). `onRunEnd` reports a started run that is gone: stopped, reaped after its lease expired, exited, or failed event delivery. The caller's `credentialEnv` object is copied, never erased.
+- `createAppRunnerHost` is a thin HTTP wrapper over `createAgentRunner`. Its requests, statuses and isolation are unchanged.
+- The app MCP endpoint is optional: `appTools.mcpName` and `appTools.mcpUrl` are given together or not at all. Without them the run's `skaile.yaml` has no `mcp_servers`, `tools.host_allowed` lists only `browserActionNames` (now documented as the client capabilities), `APP_MCP_AUTHORIZATION` is not set, and `POST /runs` does not read `mcpAuthorization`.
+- Static `headers` of registry entries are validated (names to strings, `400` otherwise) and written to the run's `.skaile/providers.yml` unchanged, so a run can route its model calls through a header-driven proxy such as `@skaile/transform-proxy`.
+
+## 1.1.2
+
+- Busy-port retry: `AgentProcessManager.create` now also retries on a fresh port when `skaile serve` prints `<host>:<port> is already in use: another process listens there` (the text `@skaile/workspaces` 5.12 and later print instead of `EADDRINUSE`, and exit 1). Before, the retry never ran for those versions and the session failed on the first port clash. `EADDRINUSE` still matches for older versions; the check is the exported `isPortConflict`.
+- Accepts `@skaile/workspaces` 7: dependency range `^6.11.0 || ^7.0.0` (checked against 7.1.0; 7.0.0 removed model transforms only, which this package does not use). `@skaile/forge-settings` raised to `^1.1.1`, the first release that accepts `@skaile/workspaces` 7, so one copy of `@skaile/workspaces` is installed.
+
 ## 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.

package/README.md

@@ -67,11 +67,14 @@ 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.
+destination. `host.close()` terminates every run. `mcpName` and `mcpUrl` are
+optional but go together: without them a run has no MCP server, its only host
+tools are the client capabilities in `browserActionNames`, and `POST /runs` does
+not read `mcpAuthorization`.
 
 | 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` | 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 (only with an 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. |
@@ -87,17 +90,59 @@ What a run is:
 - **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`.
+  provider, `APP_MCP_AUTHORIZATION` (only with an MCP endpoint) 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`).
+  `base_url`, `headers` and `query_params`, are refused with `400`. Static `headers` (names to strings) are written
+  unchanged, so an app can route a run's model calls through a header-driven proxy.
+- **Tools.** Native omp tools are disabled. The host tool allowlist is `mcp__<mcpName>__*` (with an MCP endpoint)
+  plus the client capability 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`.
 
+### In-process runner
+
+`createAgentRunner` is the same run lifecycle without HTTP, for an app that hosts
+its agents itself and implements its tools as client capabilities. The host is a
+thin wrapper over it.
+
+```ts
+import { createAgentRunner } from "@skaile/forge-agent-runtime/app-runner-host";
+
+const runner = createAgentRunner({
+  rootDir: "/var/lib/app/runs",
+  onEvent: async (runId, event) => {
+    // e.g. answer `capability_invoked` with runner.command(runId, { type: "capability_result", ... })
+  },
+  onRunEnd: (runId) => {
+    // stopped, reaped after its lease expired, or its process exited
+  },
+  appTools: { browserActionNames: ["editor.document_outline", "editor.edit_document"] },
+});
+
+const runId = await runner.start({
+  model: "local/qwen",
+  registry, // AIProviderRegistryView; only enabled llm entries are kept
+  credentialEnv: { LOCAL_KEY: "…" }, // values of the registry's env: references
+  systemPrompt: "…",
+  expiresAt: Date.now() + 15 * 60_000,
+});
+await runner.command(runId, { type: "capability_register", capabilities: [/* client capabilities */] });
+await runner.command(runId, { type: "prompt", prompt: "…" });
+runner.lease(runId, Date.now() + 15 * 60_000);
+await runner.stop(runId);
+```
+
+A run has the same isolation as a host run. `start` checks everything first and
+creates nothing for an invalid input. Refusals are `AgentRunnerError`s whose
+`code` is `invalid`, `conflict`, `not_found`, `starting`, `expired`, `ended`,
+`start_failed` or `closed` (the host answers them `400`, `409`, `404`, `409`,
+`410`, `410`, `503`, `503`). `capability_register` may name only
+`browserActionNames`. `has(runId)` tells whether a run is still active;
+`close()` stops every run.
+
 ## Migrating from `@skaile/forge-common/server`
 
 Replace the import specifier; names are unchanged.

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

@@ -1,26 +1,97 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { AgentEvent } from '../index.mjs';
-import '@skaile/forge-settings/server';
+import { AIProviderRegistryView } from '@skaile/forge-settings/server';
+import { AgentCommand, AgentEvent } from '../index.mjs';
 
 /**
  * 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.
+ *
+ * `mcpName` and `mcpUrl` are given together or not at all. Without them a run has
+ * no MCP server and its only host tools are the client capabilities.
  */
 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;
+    mcpName?: string;
     /** `http(s)` URL of the app's MCP endpoint. */
-    mcpUrl: string;
+    mcpUrl?: string;
     /**
-     * Exact names of the browser-side actions a client may register with
-     * `capability_register`. Wildcards are not accepted here.
+     * Client capabilities: exact names of the tools a client may register with
+     * `capability_register` and answer with `capability_result` (browser actions,
+     * or tools an in-process host implements itself). Wildcards are not accepted here.
      */
     browserActionNames: readonly string[];
 }
+/** Options of {@link createAgentRunner}: the run lifecycle without HTTP. */
+interface AgentRunnerOptions {
+    /** Private directory each run's scratch workspace is created under. */
+    rootDir: string;
+    /**
+     * 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): void | Promise<void>;
+    /**
+     * Called once when a run is gone for good: stopped, its lease expired and the
+     * grace period passed, its child exited, or its event delivery failed. Not
+     * called for a run whose start failed (`start` rejects instead).
+     */
+    onRunEnd?(runId: string): void;
+    appTools: AppRunnerTools;
+}
+/** Input of {@link AgentRunner.start}. */
+interface AgentRunStart {
+    /** UUID of the run. Absent: a random one. */
+    id?: string;
+    /** `<providerId>/<modelId>`; the provider must be an enabled `llm` entry of `registry`. */
+    model: string;
+    /** Provider registry the run's snapshot is built from (only enabled `llm` entries are kept). */
+    registry: AIProviderRegistryView;
+    /** Values of the `env:NAME` credential references of `registry`. Absent: none. */
+    credentialEnv?: Record<string, string>;
+    systemPrompt: string;
+    /**
+     * Full `Authorization` header value for the app MCP endpoint. Required when
+     * `appTools` names one; not used otherwise.
+     */
+    mcpAuthorization?: string;
+    /** End of the lease, epoch milliseconds in the future. */
+    expiresAt: number;
+}
+interface AgentRunner {
+    /**
+     * Start one isolated run and resolve with its id once the runtime is connected.
+     * Rejects with an {@link AgentRunnerError}: `invalid` (nothing was created),
+     * `conflict` (id already active), `closed`, or `start_failed` (scratch removed).
+     */
+    start(input: AgentRunStart): Promise<string>;
+    /**
+     * Send one Workspaces command to a run. `capability_register` may name only the
+     * client capabilities. Rejects with `not_found`, `starting`, `expired` (except
+     * `cancel`), `ended` (the run's process is gone; the run is torn down) or `invalid`.
+     */
+    command(runId: string, command: AgentCommand): Promise<void>;
+    /** Move a run's lease end to `expiresAt` (epoch milliseconds in the future). */
+    lease(runId: string, expiresAt: number): void;
+    /**
+     * Stop the process, erase the run's credentials and remove its scratch.
+     * Idempotent; an unknown id resolves.
+     */
+    stop(runId: string): Promise<void>;
+    /** Whether the run is active: started or starting, and not stopped, expired-and-reaped or exited. */
+    has(runId: string): boolean;
+    /** Stops every run and refuses new starts. */
+    close(): Promise<void>;
+}
+type AgentRunnerErrorCode = "invalid" | "conflict" | "not_found" | "starting" | "expired" | "ended" | "start_failed" | "closed";
+/** A refused runner call. The message is safe to show to the caller. */
+declare class AgentRunnerError extends Error {
+    readonly code: AgentRunnerErrorCode;
+    constructor(code: AgentRunnerErrorCode, message: string);
+}
 interface AppRunnerHostOptions {
     /** Private directory each run's scratch workspace is created under. */
     rootDir: string;
@@ -48,14 +119,27 @@ interface AppRunnerHost {
 }
 
 /**
- * Create the isolated app runner host.
+ * Create the isolated app runner host: authenticated HTTP over
+ * {@link createAgentRunner}.
  *
- * 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.
+ * One run is one `skaile serve` child 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 };
+/**
+ * Create the in-process agent runner: the run lifecycle of the app runner host
+ * without HTTP.
+ *
+ * One run is one `skaile serve` child (through {@link ProcessManagerAdapter}) with
+ * its own scratch workspace, HOME, `SKAILE_HOME` and provider snapshot. The child
+ * binds loopback, requires a fresh WebSocket token and gets a minimal environment.
+ * Its only tools are the app MCP endpoint, if configured, and the trusted client
+ * capabilities, as host tools.
+ */
+declare function createAgentRunner(options: AgentRunnerOptions): AgentRunner;
+
+export { AgentRunnerError, createAgentRunner, createAppRunnerHost };
+export type { AgentRunStart, AgentRunner, AgentRunnerErrorCode, AgentRunnerOptions, AppRunnerHost, AppRunnerHostOptions, AppRunnerTools };

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

@@ -1,26 +1,97 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { AgentEvent } from '../index.js';
-import '@skaile/forge-settings/server';
+import { AIProviderRegistryView } from '@skaile/forge-settings/server';
+import { AgentCommand, AgentEvent } from '../index.js';
 
 /**
  * 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.
+ *
+ * `mcpName` and `mcpUrl` are given together or not at all. Without them a run has
+ * no MCP server and its only host tools are the client capabilities.
  */
 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;
+    mcpName?: string;
     /** `http(s)` URL of the app's MCP endpoint. */
-    mcpUrl: string;
+    mcpUrl?: string;
     /**
-     * Exact names of the browser-side actions a client may register with
-     * `capability_register`. Wildcards are not accepted here.
+     * Client capabilities: exact names of the tools a client may register with
+     * `capability_register` and answer with `capability_result` (browser actions,
+     * or tools an in-process host implements itself). Wildcards are not accepted here.
      */
     browserActionNames: readonly string[];
 }
+/** Options of {@link createAgentRunner}: the run lifecycle without HTTP. */
+interface AgentRunnerOptions {
+    /** Private directory each run's scratch workspace is created under. */
+    rootDir: string;
+    /**
+     * 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): void | Promise<void>;
+    /**
+     * Called once when a run is gone for good: stopped, its lease expired and the
+     * grace period passed, its child exited, or its event delivery failed. Not
+     * called for a run whose start failed (`start` rejects instead).
+     */
+    onRunEnd?(runId: string): void;
+    appTools: AppRunnerTools;
+}
+/** Input of {@link AgentRunner.start}. */
+interface AgentRunStart {
+    /** UUID of the run. Absent: a random one. */
+    id?: string;
+    /** `<providerId>/<modelId>`; the provider must be an enabled `llm` entry of `registry`. */
+    model: string;
+    /** Provider registry the run's snapshot is built from (only enabled `llm` entries are kept). */
+    registry: AIProviderRegistryView;
+    /** Values of the `env:NAME` credential references of `registry`. Absent: none. */
+    credentialEnv?: Record<string, string>;
+    systemPrompt: string;
+    /**
+     * Full `Authorization` header value for the app MCP endpoint. Required when
+     * `appTools` names one; not used otherwise.
+     */
+    mcpAuthorization?: string;
+    /** End of the lease, epoch milliseconds in the future. */
+    expiresAt: number;
+}
+interface AgentRunner {
+    /**
+     * Start one isolated run and resolve with its id once the runtime is connected.
+     * Rejects with an {@link AgentRunnerError}: `invalid` (nothing was created),
+     * `conflict` (id already active), `closed`, or `start_failed` (scratch removed).
+     */
+    start(input: AgentRunStart): Promise<string>;
+    /**
+     * Send one Workspaces command to a run. `capability_register` may name only the
+     * client capabilities. Rejects with `not_found`, `starting`, `expired` (except
+     * `cancel`), `ended` (the run's process is gone; the run is torn down) or `invalid`.
+     */
+    command(runId: string, command: AgentCommand): Promise<void>;
+    /** Move a run's lease end to `expiresAt` (epoch milliseconds in the future). */
+    lease(runId: string, expiresAt: number): void;
+    /**
+     * Stop the process, erase the run's credentials and remove its scratch.
+     * Idempotent; an unknown id resolves.
+     */
+    stop(runId: string): Promise<void>;
+    /** Whether the run is active: started or starting, and not stopped, expired-and-reaped or exited. */
+    has(runId: string): boolean;
+    /** Stops every run and refuses new starts. */
+    close(): Promise<void>;
+}
+type AgentRunnerErrorCode = "invalid" | "conflict" | "not_found" | "starting" | "expired" | "ended" | "start_failed" | "closed";
+/** A refused runner call. The message is safe to show to the caller. */
+declare class AgentRunnerError extends Error {
+    readonly code: AgentRunnerErrorCode;
+    constructor(code: AgentRunnerErrorCode, message: string);
+}
 interface AppRunnerHostOptions {
     /** Private directory each run's scratch workspace is created under. */
     rootDir: string;
@@ -48,14 +119,27 @@ interface AppRunnerHost {
 }
 
 /**
- * Create the isolated app runner host.
+ * Create the isolated app runner host: authenticated HTTP over
+ * {@link createAgentRunner}.
  *
- * 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.
+ * One run is one `skaile serve` child 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 };
+/**
+ * Create the in-process agent runner: the run lifecycle of the app runner host
+ * without HTTP.
+ *
+ * One run is one `skaile serve` child (through {@link ProcessManagerAdapter}) with
+ * its own scratch workspace, HOME, `SKAILE_HOME` and provider snapshot. The child
+ * binds loopback, requires a fresh WebSocket token and gets a minimal environment.
+ * Its only tools are the app MCP endpoint, if configured, and the trusted client
+ * capabilities, as host tools.
+ */
+declare function createAgentRunner(options: AgentRunnerOptions): AgentRunner;
+
+export { AgentRunnerError, createAgentRunner, createAppRunnerHost };
+export type { AgentRunStart, AgentRunner, AgentRunnerErrorCode, AgentRunnerOptions, AppRunnerHost, AppRunnerHostOptions, AppRunnerTools };

package/dist/app-runner-host/index.mjs

@@ -1,9 +1,9 @@
-import { randomBytes } from 'node:crypto';
-import { join, resolve } from 'node:path';
 import { consola } from 'consola';
-import { P as ProcessManagerAdapter } from '../shared/forge-agent-runtime.B1LZr0Sl.mjs';
-import { registryEntries, isEntryEnabled, entryPolicyRefusal, providerCredentialEnvName, parseCredentialRef, writeProviderLayer } from '@skaile/forge-settings/server';
 import { rm, mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { registryEntries, isEntryEnabled, entryPolicyRefusal, providerCredentialEnvName, parseCredentialRef, writeProviderLayer } from '@skaile/forge-settings/server';
+import { randomUUID, randomBytes } from 'node:crypto';
+import { P as ProcessManagerAdapter } from '../shared/forge-agent-runtime.ByEe8ijq.mjs';
 import 'node:events';
 import 'node:child_process';
 import 'node:fs';
@@ -13,22 +13,38 @@ import 'picocolors';
 import '@skaile/workspaces/sdk/client';
 import '@skaile/workspaces/sdk/transport/ws/client';
 
+class AgentRunnerError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "AgentRunnerError";
+  }
+}
 const APP_MCP_AUTHORIZATION_ENV = "APP_MCP_AUTHORIZATION";
 const MCP_NAME = /^[A-Za-z0-9_-]+$/;
+function appMcpOf(tools) {
+  if (tools.mcpName === void 0 || tools.mcpUrl === void 0) return void 0;
+  return { name: tools.mcpName, url: tools.mcpUrl };
+}
 function assertAppTools(tools) {
-  if (!MCP_NAME.test(tools.mcpName) || tools.mcpName.includes("__")) {
-    throw new TypeError(
-      "appTools.mcpName must contain only letters, digits, '_' and '-', and no '__'"
-    );
-  }
-  let url;
-  try {
-    url = new URL(tools.mcpUrl);
-  } catch {
-    throw new TypeError("appTools.mcpUrl must be an absolute URL");
+  if (tools.mcpName === void 0 !== (tools.mcpUrl === void 0)) {
+    throw new TypeError("appTools.mcpName and appTools.mcpUrl must be given together");
   }
-  if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new TypeError("appTools.mcpUrl must be an http(s) URL");
+  if (tools.mcpName !== void 0) {
+    if (!MCP_NAME.test(tools.mcpName) || tools.mcpName.includes("__")) {
+      throw new TypeError(
+        "appTools.mcpName must contain only letters, digits, '_' and '-', and no '__'"
+      );
+    }
+    let url;
+    try {
+      url = new URL(tools.mcpUrl);
+    } catch {
+      throw new TypeError("appTools.mcpUrl must be an absolute URL");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+      throw new TypeError("appTools.mcpUrl must be an http(s) URL");
+    }
   }
   for (const name of tools.browserActionNames) {
     if (typeof name !== "string" || name === "" || name.includes("*") || name.startsWith("mcp__")) {
@@ -39,40 +55,175 @@ function assertAppTools(tools) {
   }
 }
 function hostAllowedFor(tools) {
-  return [`mcp__${tools.mcpName}__*`, ...tools.browserActionNames];
+  const mcp = appMcpOf(tools);
+  return [...mcp ? [`mcp__${mcp.name}__*`] : [], ...tools.browserActionNames];
 }
 
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-
-class RequestError extends Error {
-  constructor(status, message) {
-    super(message);
-    this.status = status;
-    this.name = "RequestError";
-  }
-}
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function isUuid(value) {
   return typeof value === "string" && UUID.test(value);
 }
-function requireRegistryShape(registry) {
-  if (!isRecord(registry)) throw new RequestError(400, "'registry' must be an object");
+function isModelArgument(model) {
+  return model !== "" && !/\s/.test(model) && !model.startsWith("-");
+}
+function isSingleHeaderValue(value) {
+  return value !== "" && !/[\u0000-\u001f\u007f]/.test(value);
+}
+
+function runPaths(rootDir, runId) {
+  const root = join(rootDir, runId);
+  return {
+    root,
+    workspace: join(root, "workspace"),
+    home: join(root, "home"),
+    skaileHome: join(root, "skaile-home"),
+    tmp: join(root, "tmp")
+  };
+}
+async function createRunDirs(paths) {
+  await rm(paths.root, { recursive: true, force: true });
+  await mkdir(paths.root, { recursive: true, mode: 448 });
+  await Promise.all(
+    [paths.workspace, paths.home, paths.skaileHome, paths.tmp].map(
+      (dir) => mkdir(dir, { mode: 448 })
+    )
+  );
+}
+async function removeRunDirs(paths) {
+  await rm(paths.root, { recursive: true, force: true, maxRetries: 3 });
+}
+class SnapshotError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SnapshotError";
+  }
+}
+function assertRegistryShape(registry) {
+  if (!isRecord(registry)) throw new SnapshotError("'registry' must be an object");
   if (Array.isArray(registry.order) && !isRecord(registry.providers)) {
-    throw new RequestError(400, "'registry.providers' must be an object");
+    throw new SnapshotError("'registry.providers' must be an object");
   }
   const view = registry;
   for (const [id, entry] of registryEntries(view)) {
     if (!isRecord(entry) || typeof entry.kind !== "string") {
-      throw new RequestError(400, `registry entry '${id}' needs a 'kind'`);
+      throw new SnapshotError(`registry entry '${id}' needs a 'kind'`);
     }
     if (entry.credential !== void 0 && !isRecord(entry.credential)) {
-      throw new RequestError(400, `registry entry '${id}': 'credential' must be an object`);
+      throw new SnapshotError(`registry entry '${id}': 'credential' must be an object`);
+    }
+    if (entry.headers !== void 0 && (!isRecord(entry.headers) || Object.values(entry.headers).some((value) => typeof value !== "string"))) {
+      throw new SnapshotError(`registry entry '${id}': 'headers' must map names to strings`);
     }
   }
   return view;
 }
+function prepareProviderSnapshot(registry, credentialEnv) {
+  const providers = {};
+  const env = {};
+  const names = /* @__PURE__ */ new Set();
+  for (const [id, entry] of registryEntries(registry)) {
+    if (entry.kind !== "llm" || !isEntryEnabled(entry)) continue;
+    const interpolation = entryPolicyRefusal(
+      { ...entry, credential: void 0 },
+      { envNames: [] }
+    );
+    if (interpolation) throw new SnapshotError(`registry entry '${id}': ${interpolation}`);
+    const canonical = providerCredentialEnvName(id);
+    if (names.has(canonical)) {
+      throw new SnapshotError(
+        `registry entry '${id}' collides with another entry's credential name`
+      );
+    }
+    names.add(canonical);
+    const ref = entry.credential?.ref;
+    if (ref === void 0) {
+      providers[id] = { ...entry };
+      continue;
+    }
+    const parsed = parseCredentialRef(ref);
+    if (parsed?.form !== "env") {
+      throw new SnapshotError(
+        `registry entry '${id}': only env: credential references are allowed`
+      );
+    }
+    const secret = credentialEnv[parsed.name];
+    if (secret) env[canonical] = secret;
+    providers[id] = {
+      ...entry,
+      credential: { ...entry.credential, ref: `env:${canonical}` }
+    };
+  }
+  const providerIds = Object.keys(providers);
+  if (providerIds.length === 0) {
+    throw new SnapshotError("'registry' has no enabled llm provider");
+  }
+  return { providers, providerIds, credentialEnv: env };
+}
+function requireModelProvider(model, snapshot) {
+  if (!snapshot.providerIds.some((id) => model.startsWith(`${id}/`) && model.length > id.length + 1)) {
+    throw new SnapshotError(
+      "'model' must name an enabled llm provider of the registry: '<providerId>/<modelId>'"
+    );
+  }
+}
+async function writeRunWorkspace(paths, input) {
+  const mcp = appMcpOf(input.appTools);
+  const skaileYaml = {
+    agent: { definition: "./agent", prompt: input.systemPrompt },
+    ...mcp && {
+      mcp_servers: [
+        {
+          id: mcp.name,
+          transport: "http",
+          url: mcp.url,
+          headers: { Authorization: `env:${APP_MCP_AUTHORIZATION_ENV}` }
+        }
+      ]
+    }
+  };
+  const agentYaml = {
+    name: "app-runner",
+    version: "1.0.0",
+    tools: { allowed: ["WebFetch"], host_allowed: hostAllowedFor(input.appTools) }
+  };
+  await mkdir(join(paths.workspace, "agent"), { recursive: true, mode: 448 });
+  await writeFile(join(paths.workspace, "skaile.yaml"), `${JSON.stringify(skaileYaml, null, 2)}
+`);
+  await writeFile(
+    join(paths.workspace, "agent", "agent.yaml"),
+    `${JSON.stringify(agentYaml, null, 2)}
+`
+  );
+  writeProviderLayer(join(paths.workspace, ".skaile", "providers.yml"), input.snapshot.providers);
+}
+function baseChildEnv(paths) {
+  return {
+    PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+    LANG: process.env.LANG ?? "C.UTF-8",
+    HOME: paths.home,
+    SKAILE_HOME: paths.skaileHome,
+    TMPDIR: paths.tmp
+  };
+}
+
+class RequestError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "RequestError";
+  }
+}
+function requireRegistryShape(registry) {
+  try {
+    return assertRegistryShape(registry);
+  } catch (err) {
+    if (err instanceof SnapshotError) throw new RequestError(400, err.message);
+    throw err;
+  }
+}
 function requireRecord(body) {
   if (!isRecord(body)) throw new RequestError(400, "request body must be a JSON object");
   return body;
@@ -94,12 +245,12 @@ function parseExpiry(value, now) {
   if (at <= now) throw new RequestError(400, "'expiresAt' must be in the future");
   return at;
 }
-function parseStartRequest(body, now) {
+function parseStartRequest(body, now, withMcp) {
   const record = requireRecord(body);
   const id = record.id;
   if (!isUuid(id)) throw new RequestError(400, "'id' must be a UUID");
   const model = requireString(record, "model");
-  if (/\s/.test(model) || model.startsWith("-")) {
+  if (!isModelArgument(model)) {
     throw new RequestError(400, "'model' must be '<providerId>/<modelId>' without whitespace");
   }
   const registry = requireRegistryShape(record.registry);
@@ -113,9 +264,12 @@ function parseStartRequest(body, now) {
   if (typeof record.systemPrompt !== "string") {
     throw new RequestError(400, "'systemPrompt' must be a string");
   }
-  const mcpAuthorization = requireString(record, "mcpAuthorization");
-  if (/[\u0000-\u001f\u007f]/.test(mcpAuthorization)) {
-    throw new RequestError(400, "'mcpAuthorization' must be a single header value");
+  let mcpAuthorization;
+  if (withMcp) {
+    mcpAuthorization = requireString(record, "mcpAuthorization");
+    if (!isSingleHeaderValue(mcpAuthorization)) {
+      throw new RequestError(400, "'mcpAuthorization' must be a single header value");
+    }
   }
   return {
     id,
@@ -123,7 +277,7 @@ function parseStartRequest(body, now) {
     registry,
     credentialEnv: { ...credentialEnv },
     systemPrompt: record.systemPrompt,
-    mcpAuthorization,
+    ...mcpAuthorization !== void 0 && { mcpAuthorization },
     expiresAt: parseExpiry(record.expiresAt, now)
   };
 }
@@ -205,163 +359,41 @@ function parseCommand(body, browserActionNames) {
   }
 }
 
-function runPaths(rootDir, runId) {
-  const root = join(rootDir, runId);
-  return {
-    root,
-    workspace: join(root, "workspace"),
-    home: join(root, "home"),
-    skaileHome: join(root, "skaile-home"),
-    tmp: join(root, "tmp")
-  };
-}
-async function createRunDirs(paths) {
-  await rm(paths.root, { recursive: true, force: true });
-  await mkdir(paths.root, { recursive: true, mode: 448 });
-  await Promise.all(
-    [paths.workspace, paths.home, paths.skaileHome, paths.tmp].map(
-      (dir) => mkdir(dir, { mode: 448 })
-    )
-  );
-}
-async function removeRunDirs(paths) {
-  await rm(paths.root, { recursive: true, force: true, maxRetries: 3 });
-}
-class SnapshotError extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "SnapshotError";
-  }
-}
-function prepareProviderSnapshot(registry, credentialEnv) {
-  const providers = {};
-  const env = {};
-  const names = /* @__PURE__ */ new Set();
-  for (const [id, entry] of registryEntries(registry)) {
-    if (entry.kind !== "llm" || !isEntryEnabled(entry)) continue;
-    const interpolation = entryPolicyRefusal(
-      { ...entry, credential: void 0 },
-      { envNames: [] }
-    );
-    if (interpolation) throw new SnapshotError(`registry entry '${id}': ${interpolation}`);
-    const canonical = providerCredentialEnvName(id);
-    if (names.has(canonical)) {
-      throw new SnapshotError(
-        `registry entry '${id}' collides with another entry's credential name`
-      );
-    }
-    names.add(canonical);
-    const ref = entry.credential?.ref;
-    if (ref === void 0) {
-      providers[id] = { ...entry };
-      continue;
-    }
-    const parsed = parseCredentialRef(ref);
-    if (parsed?.form !== "env") {
-      throw new SnapshotError(
-        `registry entry '${id}': only env: credential references are allowed`
-      );
-    }
-    const secret = credentialEnv[parsed.name];
-    if (secret) env[canonical] = secret;
-    providers[id] = {
-      ...entry,
-      credential: { ...entry.credential, ref: `env:${canonical}` }
-    };
-  }
-  const providerIds = Object.keys(providers);
-  if (providerIds.length === 0) {
-    throw new SnapshotError("'registry' has no enabled llm provider");
-  }
-  return { providers, providerIds, credentialEnv: env };
-}
-function requireModelProvider(model, snapshot) {
-  if (!snapshot.providerIds.some((id) => model.startsWith(`${id}/`) && model.length > id.length + 1)) {
-    throw new SnapshotError(
-      "'model' must name an enabled llm provider of the registry: '<providerId>/<modelId>'"
-    );
-  }
-}
-async function writeRunWorkspace(paths, input) {
-  const { appTools } = input;
-  const skaileYaml = {
-    agent: { definition: "./agent", prompt: input.systemPrompt },
-    mcp_servers: [
-      {
-        id: appTools.mcpName,
-        transport: "http",
-        url: appTools.mcpUrl,
-        headers: { Authorization: `env:${APP_MCP_AUTHORIZATION_ENV}` }
-      }
-    ]
-  };
-  const agentYaml = {
-    name: "app-runner",
-    version: "1.0.0",
-    tools: { allowed: ["WebFetch"], host_allowed: hostAllowedFor(appTools) }
-  };
-  await mkdir(join(paths.workspace, "agent"), { recursive: true, mode: 448 });
-  await writeFile(join(paths.workspace, "skaile.yaml"), `${JSON.stringify(skaileYaml, null, 2)}
-`);
-  await writeFile(
-    join(paths.workspace, "agent", "agent.yaml"),
-    `${JSON.stringify(agentYaml, null, 2)}
-`
-  );
-  writeProviderLayer(join(paths.workspace, ".skaile", "providers.yml"), input.snapshot.providers);
-}
-function baseChildEnv(paths) {
-  return {
-    PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
-    LANG: process.env.LANG ?? "C.UTF-8",
-    HOME: paths.home,
-    SKAILE_HOME: paths.skaileHome,
-    TMPDIR: paths.tmp
-  };
-}
-
-const log = consola.withTag("app-runner-host");
-const MAX_BODY_BYTES = 4 * 1024 * 1024;
+const log$1 = consola.withTag("app-runner-host");
 const MAX_TIMER_MS = 2 ** 31 - 1;
 const EXPIRY_GRACE_MS = 5e3;
 const CHILD_HOST = "127.0.0.1";
-function json(res, status, body) {
-  if (res.headersSent) {
-    res.end();
-    return;
-  }
-  if (body === void 0) {
-    res.writeHead(status).end();
-    return;
-  }
-  res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(body));
+function erase(record) {
+  for (const key of Object.keys(record)) delete record[key];
 }
-async function readJson(req) {
-  const declared = Number(req.headers["content-length"]);
-  if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
-    throw new RequestError(413, "request body too large");
+function validateStart(input, withMcp, now) {
+  if (input.id !== void 0 && !isUuid(input.id)) {
+    throw new AgentRunnerError("invalid", "'id' must be a UUID");
+  }
+  if (typeof input.model !== "string" || !isModelArgument(input.model)) {
+    throw new AgentRunnerError(
+      "invalid",
+      "'model' must be '<providerId>/<modelId>' without whitespace"
+    );
   }
-  const chunks = [];
-  let size = 0;
-  for await (const chunk of req) {
-    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-    size += buffer.length;
-    if (size > MAX_BODY_BYTES) throw new RequestError(413, "request body too large");
-    chunks.push(buffer);
+  if (typeof input.systemPrompt !== "string") {
+    throw new AgentRunnerError("invalid", "'systemPrompt' must be a string");
   }
-  try {
-    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
-  } catch {
-    throw new RequestError(400, "request body is not valid JSON");
+  if (withMcp) {
+    const value = input.mcpAuthorization;
+    if (typeof value !== "string" || !isSingleHeaderValue(value)) {
+      throw new AgentRunnerError("invalid", "'mcpAuthorization' must be a single header value");
+    }
+  }
+  if (!Number.isFinite(input.expiresAt) || input.expiresAt <= now) {
+    throw new AgentRunnerError("invalid", "'expiresAt' must be in the future");
   }
 }
-function erase(record) {
-  for (const key of Object.keys(record)) delete record[key];
-}
-function createAppRunnerHost(options) {
+function createAgentRunner(options) {
   assertAppTools(options.appTools);
   const rootDir = resolve(options.rootDir);
-  const { appTools, authenticate, onEvent } = options;
+  const { appTools, onEvent, onRunEnd } = options;
+  const withMcp = appMcpOf(appTools) !== void 0;
   const runs = /* @__PURE__ */ new Map();
   let closed = false;
   function tearDown(run) {
@@ -372,7 +404,7 @@ function createAppRunnerHost(options) {
       try {
         await run.adapter.disconnect();
       } catch (err) {
-        log.warn(`[${run.id}] disconnect failed: ${err.message}`);
+        log$1.warn(`[${run.id}] disconnect failed: ${err.message}`);
       }
       await run.pump?.catch(() => {
       });
@@ -380,9 +412,16 @@ function createAppRunnerHost(options) {
       try {
         await removeRunDirs(run.paths);
       } catch (err) {
-        log.warn(`[${run.id}] scratch removal failed: ${err.message}`);
+        log$1.warn(`[${run.id}] scratch removal failed: ${err.message}`);
       }
       if (runs.get(run.id) === run) runs.delete(run.id);
+      if (run.started && onRunEnd) {
+        try {
+          onRunEnd(run.id);
+        } catch (err) {
+          log$1.warn(`[${run.id}] onRunEnd failed: ${err.message}`);
+        }
+      }
     })();
     return run.teardown;
   }
@@ -398,7 +437,7 @@ function createAppRunnerHost(options) {
         await onEvent(run.id, event);
       }
     } catch (err) {
-      log.error(`[${run.id}] event delivery failed; terminating: ${err.message}`);
+      log$1.error(`[${run.id}] event delivery failed; terminating: ${err.message}`);
       void tearDown(run);
     }
   }
@@ -416,33 +455,53 @@ function createAppRunnerHost(options) {
   async function expire(run) {
     if (run.state !== "running") return;
     run.state = "expired";
-    log.info(`[${run.id}] lease expired`);
+    log$1.info(`[${run.id}] lease expired`);
     run.reapTimer = setTimeout(() => void tearDown(run), EXPIRY_GRACE_MS);
     run.reapTimer.unref();
     try {
       await run.adapter.abort();
     } catch (err) {
-      log.warn(`[${run.id}] cancel on expiry failed: ${err.message}`);
+      log$1.warn(`[${run.id}] cancel on expiry failed: ${err.message}`);
     }
   }
-  async function start(request, snapshot) {
-    const paths = runPaths(rootDir, request.id);
+  function findRun(runId) {
+    const run = isUuid(runId) ? runs.get(runId) : void 0;
+    if (!run || run.teardown) throw new AgentRunnerError("not_found", "no such run");
+    return run;
+  }
+  async function start(input) {
+    validateStart(input, withMcp, Date.now());
+    if (closed) throw new AgentRunnerError("closed", "runner is closed");
+    const id = input.id ?? randomUUID();
+    if (runs.has(id))
+      throw new AgentRunnerError("conflict", "a run with this id is already active");
+    const callerEnv = { ...input.credentialEnv };
+    let snapshot;
+    try {
+      snapshot = prepareProviderSnapshot(assertRegistryShape(input.registry), callerEnv);
+      requireModelProvider(input.model, snapshot);
+    } catch (err) {
+      erase(callerEnv);
+      if (err instanceof SnapshotError) throw new AgentRunnerError("invalid", err.message);
+      throw err;
+    }
+    const paths = runPaths(rootDir, id);
     const wsAuthToken = randomBytes(32).toString("base64url");
-    const mcpEnv = { [APP_MCP_AUTHORIZATION_ENV]: request.mcpAuthorization };
+    const mcpEnv = withMcp ? { [APP_MCP_AUTHORIZATION_ENV]: input.mcpAuthorization } : {};
     const credentialEnv = { ...baseChildEnv(paths), ...snapshot.credentialEnv };
     const run = {
-      id: request.id,
+      id,
       paths,
       state: "starting",
-      expiresAt: request.expiresAt,
+      expiresAt: input.expiresAt,
       adapter: new ProcessManagerAdapter(),
-      secrets: [request.credentialEnv, snapshot.credentialEnv, credentialEnv, mcpEnv]
+      secrets: [callerEnv, snapshot.credentialEnv, credentialEnv, mcpEnv]
     };
-    runs.set(run.id, run);
+    runs.set(id, run);
     run.startup = (async () => {
       await createRunDirs(paths);
       await writeRunWorkspace(paths, {
-        systemPrompt: request.systemPrompt,
+        systemPrompt: input.systemPrompt,
         snapshot,
         appTools
       });
@@ -450,7 +509,7 @@ function createAppRunnerHost(options) {
       await run.adapter.connect({
         projectDir: paths.workspace,
         harness: "omp",
-        model: request.model,
+        model: input.model,
         registry: snapshot.providers,
         providers: snapshot.providerIds,
         credentialEnv,
@@ -461,73 +520,159 @@ function createAppRunnerHost(options) {
       if (run.teardown) throw new Error("run was terminated while starting");
       if (!run.adapter.isConnected()) throw new Error("runtime exited while starting");
       run.adapter.getProcessManager().on(`error:${paths.workspace}`, () => {
-        log.warn(`[${run.id}] runtime process exited; tearing the run down`);
+        log$1.warn(`[${run.id}] runtime process exited; tearing the run down`);
         run.exited = true;
         void tearDown(run);
       });
       run.state = "running";
+      run.started = true;
       armLease(run);
     })();
     try {
       await run.startup;
     } catch (err) {
-      log.error(`[${run.id}] start failed: ${err.message}`);
+      log$1.error(`[${id}] start failed: ${err.message}`);
       await tearDown(run);
-      throw err;
+      throw new AgentRunnerError("start_failed", "runner could not be started");
     }
-    return run;
-  }
-  async function startRun(req, res) {
-    const request = parseStartRequest(await readJson(req), Date.now());
-    if (runs.has(request.id)) throw new RequestError(409, "a run with this id is already active");
-    let snapshot;
-    try {
-      snapshot = prepareProviderSnapshot(request.registry, request.credentialEnv);
-      requireModelProvider(request.model, snapshot);
-    } catch (err) {
-      if (err instanceof SnapshotError) throw new RequestError(400, err.message);
-      throw err;
+    return id;
+  }
+  async function command(runId, cmd) {
+    const run = findRun(runId);
+    if (cmd.type === "capability_register") {
+      const list = Array.isArray(cmd.capabilities) ? cmd.capabilities : [];
+      for (const entry of list) {
+        if (!appTools.browserActionNames.includes(entry?.name)) {
+          throw new AgentRunnerError(
+            "invalid",
+            `capability '${String(entry?.name)}' is not a declared client capability`
+          );
+        }
+      }
+    }
+    if (run.state === "starting") throw new AgentRunnerError("starting", "run is still starting");
+    if (run.state === "expired" && cmd.type !== "cancel") {
+      throw new AgentRunnerError("expired", "run lease has expired");
     }
     try {
-      const run = await start(request, snapshot);
-      json(res, 201, { id: run.id, expiresAt: new Date(run.expiresAt).toISOString() });
+      await run.adapter.sendCommand(cmd);
     } catch {
-      json(res, 503, { error: "runner could not be started" });
+      void tearDown(run);
+      throw new AgentRunnerError("ended", "run process has ended");
     }
   }
-  function findRun(id) {
-    const run = isUuid(id) ? runs.get(id) : void 0;
-    if (!run || run.teardown) throw new RequestError(404, "no such run");
-    return run;
+  function lease(runId, expiresAt) {
+    const run = findRun(runId);
+    if (!Number.isFinite(expiresAt) || expiresAt <= Date.now()) {
+      throw new AgentRunnerError("invalid", "'expiresAt' must be in the future");
+    }
+    if (run.state === "starting") throw new AgentRunnerError("starting", "run is still starting");
+    if (run.state === "expired") throw new AgentRunnerError("expired", "run lease has expired");
+    run.expiresAt = expiresAt;
+    armLease(run);
   }
-  async function sendCommand(req, res, id) {
-    const run = findRun(id);
-    const command = parseCommand(await readJson(req), appTools.browserActionNames);
-    if (run.state === "starting") throw new RequestError(409, "run is still starting");
-    if (run.state === "expired" && command.type !== "cancel") {
-      throw new RequestError(410, "run lease has expired");
+  async function stop(runId) {
+    const run = isUuid(runId) ? runs.get(runId) : void 0;
+    if (run) await terminate(run);
+  }
+  return {
+    start,
+    command,
+    lease,
+    stop,
+    has(runId) {
+      const run = isUuid(runId) ? runs.get(runId) : void 0;
+      return run !== void 0 && !run.teardown;
+    },
+    async close() {
+      closed = true;
+      await Promise.all([...runs.values()].map((run) => terminate(run)));
     }
+  };
+}
+
+const log = consola.withTag("app-runner-host");
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+const STATUS = {
+  invalid: 400,
+  not_found: 404,
+  conflict: 409,
+  starting: 409,
+  expired: 410,
+  ended: 410,
+  closed: 503,
+  start_failed: 503
+};
+function json(res, status, body) {
+  if (res.headersSent) {
+    res.end();
+    return;
+  }
+  if (body === void 0) {
+    res.writeHead(status).end();
+    return;
+  }
+  res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(body));
+}
+async function readJson(req) {
+  const declared = Number(req.headers["content-length"]);
+  if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+    throw new RequestError(413, "request body too large");
+  }
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > MAX_BODY_BYTES) throw new RequestError(413, "request body too large");
+    chunks.push(buffer);
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    throw new RequestError(400, "request body is not valid JSON");
+  }
+}
+async function viaRunner(call) {
+  try {
+    return await call();
+  } catch (err) {
+    if (err instanceof AgentRunnerError) throw new RequestError(STATUS[err.code], err.message);
+    throw err;
+  }
+}
+function createAppRunnerHost(options) {
+  const { appTools, authenticate, onEvent } = options;
+  const runner = createAgentRunner({ rootDir: options.rootDir, onEvent, appTools });
+  const withMcp = appMcpOf(appTools) !== void 0;
+  let closed = false;
+  async function startRun(req, res) {
+    const request = parseStartRequest(await readJson(req), Date.now(), withMcp);
     try {
-      await run.adapter.sendCommand(command);
-    } catch {
-      void tearDown(run);
-      throw new RequestError(410, "run process has ended");
+      const id = await viaRunner(() => runner.start(request));
+      json(res, 201, { id, expiresAt: new Date(request.expiresAt).toISOString() });
+    } finally {
+      for (const key of Object.keys(request.credentialEnv)) delete request.credentialEnv[key];
     }
+  }
+  function requireRun(id) {
+    if (!runner.has(id)) throw new RequestError(404, "no such run");
+  }
+  async function sendCommand(req, res, id) {
+    requireRun(id);
+    const command = parseCommand(await readJson(req), appTools.browserActionNames);
+    await viaRunner(() => runner.command(id, command));
     json(res, 202, { accepted: true });
   }
   async function renewLease(req, res, id) {
-    const run = findRun(id);
+    requireRun(id);
     const expiresAt = parseLeaseRequest(await readJson(req), Date.now());
-    if (run.state === "starting") throw new RequestError(409, "run is still starting");
-    if (run.state === "expired") throw new RequestError(410, "run lease has expired");
-    run.expiresAt = expiresAt;
-    armLease(run);
+    await viaRunner(() => runner.lease(id, expiresAt));
     json(res, 200, { expiresAt: new Date(expiresAt).toISOString() });
   }
   async function deleteRun(_req, res, id) {
     if (!isUuid(id)) throw new RequestError(404, "no such run");
-    const run = runs.get(id);
-    if (run) await terminate(run);
+    await runner.stop(id);
     json(res, 204);
   }
   const collectionRoutes = /* @__PURE__ */ new Map([["POST", startRun]]);
@@ -578,9 +723,9 @@ function createAppRunnerHost(options) {
     },
     async close() {
       closed = true;
-      await Promise.all([...runs.values()].map((run) => terminate(run)));
+      await runner.close();
     }
   };
 }
 
-export { createAppRunnerHost };
+export { AgentRunnerError, createAgentRunner, createAppRunnerHost };

package/dist/index.d.mts

@@ -2,7 +2,7 @@ import { EventEmitter } from 'node:events';
 import { AgentClient } from '@skaile/workspaces/sdk/client';
 import { AgentCommand, AgentEvent as AgentEvent$1, MessageV2 } from '@skaile/workspaces/sdk/types';
 import { AIProviderRegistryView } from '@skaile/forge-settings/server';
-import { a as AgentAdapter, b as AgentAdapterConfig, c as AgentCommand$1, A as AgentEvent, d as AgentStatus } from './shared/forge-agent-runtime.DlNAoPjs.mjs';
+import { b as AgentAdapter, c as AgentAdapterConfig, A as AgentCommand$1, a as AgentEvent, d as AgentStatus } from './shared/forge-agent-runtime.BqEbyTAQ.mjs';
 import { SubscriberTransport, SessionDispatcher, MessageStore } from '@skaile/workspaces/sdk/session';
 
 /**
@@ -87,6 +87,12 @@ interface AgentProcessConfig {
      */
     wsAuthToken?: string;
 }
+/**
+ * True when the child's stderr says its port was taken. Two texts exist:
+ * `EADDRINUSE` (the raw Node error, skaile before 5.12) and
+ * `<host>:<port> is already in use: ...` (`skaile serve` 5.12+, which exits 1).
+ */
+declare function isPortConflict(stderrLines: readonly string[]): boolean;
 declare class AgentProcessManager extends EventEmitter {
     private processes;
     constructor();
@@ -471,5 +477,5 @@ declare class FanoutTransport {
     get subscriberCount(): number;
 }
 
-export { AgentAdapter, AgentAdapterConfig, AgentCommand$1 as AgentCommand, AgentEvent, AgentProcessManager, AgentStatus, BaseAgentManager, EventEmitterSubscriberTransport, FanoutTransport, JsonlMessageStore, ProcessManagerAdapter, createAdapterForHarness, listRegisteredHarnesses, registerHarness };
+export { AgentAdapter, AgentAdapterConfig, AgentCommand$1 as AgentCommand, AgentEvent, AgentProcessManager, AgentStatus, BaseAgentManager, EventEmitterSubscriberTransport, FanoutTransport, JsonlMessageStore, ProcessManagerAdapter, createAdapterForHarness, isPortConflict, listRegisteredHarnesses, registerHarness };
 export type { AgentProcessConfig, ManagedSession };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { EventEmitter } from 'node:events';
 import { AgentClient } from '@skaile/workspaces/sdk/client';
 import { AgentCommand, AgentEvent as AgentEvent$1, MessageV2 } from '@skaile/workspaces/sdk/types';
 import { AIProviderRegistryView } from '@skaile/forge-settings/server';
-import { a as AgentAdapter, b as AgentAdapterConfig, c as AgentCommand$1, A as AgentEvent, d as AgentStatus } from './shared/forge-agent-runtime.DlNAoPjs.js';
+import { b as AgentAdapter, c as AgentAdapterConfig, A as AgentCommand$1, a as AgentEvent, d as AgentStatus } from './shared/forge-agent-runtime.BqEbyTAQ.js';
 import { SubscriberTransport, SessionDispatcher, MessageStore } from '@skaile/workspaces/sdk/session';
 
 /**
@@ -87,6 +87,12 @@ interface AgentProcessConfig {
      */
     wsAuthToken?: string;
 }
+/**
+ * True when the child's stderr says its port was taken. Two texts exist:
+ * `EADDRINUSE` (the raw Node error, skaile before 5.12) and
+ * `<host>:<port> is already in use: ...` (`skaile serve` 5.12+, which exits 1).
+ */
+declare function isPortConflict(stderrLines: readonly string[]): boolean;
 declare class AgentProcessManager extends EventEmitter {
     private processes;
     constructor();
@@ -471,5 +477,5 @@ declare class FanoutTransport {
     get subscriberCount(): number;
 }
 
-export { AgentAdapter, AgentAdapterConfig, AgentCommand$1 as AgentCommand, AgentEvent, AgentProcessManager, AgentStatus, BaseAgentManager, EventEmitterSubscriberTransport, FanoutTransport, JsonlMessageStore, ProcessManagerAdapter, createAdapterForHarness, listRegisteredHarnesses, registerHarness };
+export { AgentAdapter, AgentAdapterConfig, AgentCommand$1 as AgentCommand, AgentEvent, AgentProcessManager, AgentStatus, BaseAgentManager, EventEmitterSubscriberTransport, FanoutTransport, JsonlMessageStore, ProcessManagerAdapter, createAdapterForHarness, isPortConflict, listRegisteredHarnesses, registerHarness };
 export type { AgentProcessConfig, ManagedSession };

package/dist/index.mjs

@@ -1,4 +1,5 @@
-import { P as ProcessManagerAdapter, A as AgentProcessManager } from './shared/forge-agent-runtime.B1LZr0Sl.mjs';
+import { P as ProcessManagerAdapter, A as AgentProcessManager } from './shared/forge-agent-runtime.ByEe8ijq.mjs';
+export { i as isPortConflict } from './shared/forge-agent-runtime.ByEe8ijq.mjs';
 import { EventEmitter } from 'node:events';
 import { mkdir, appendFile, readFile } from 'node:fs/promises';
 import { join } from 'node:path';

package/dist/shared/{forge-agent-runtime.DlNAoPjs.d.mts → forge-agent-runtime.BqEbyTAQ.d.mts}

@@ -119,4 +119,4 @@ interface AgentAdapter {
     disconnect(): Promise<void>;
 }
 
-export type { AgentEvent as A, AgentAdapter as a, AgentAdapterConfig as b, AgentCommand as c, AgentStatus as d };
+export type { AgentCommand as A, AgentEvent as a, AgentAdapter as b, AgentAdapterConfig as c, AgentStatus as d };

package/dist/shared/{forge-agent-runtime.DlNAoPjs.d.ts → forge-agent-runtime.BqEbyTAQ.d.ts}

@@ -119,4 +119,4 @@ interface AgentAdapter {
     disconnect(): Promise<void>;
 }
 
-export type { AgentEvent as A, AgentAdapter as a, AgentAdapterConfig as b, AgentCommand as c, AgentStatus as d };
+export type { AgentCommand as A, AgentEvent as a, AgentAdapter as b, AgentAdapterConfig as c, AgentStatus as d };

package/dist/shared/{forge-agent-runtime.B1LZr0Sl.mjs → forge-agent-runtime.ByEe8ijq.mjs}

@@ -36,6 +36,9 @@ async function allocatePort() {
   }
   throw new Error("Could not find a free port for skaile serve");
 }
+function isPortConflict(stderrLines) {
+  return stderrLines.some((l) => l.includes("EADDRINUSE") || l.includes("is already in use"));
+}
 function dialHost(host) {
   if (!host) return "127.0.0.1";
   return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
@@ -210,7 +213,7 @@ class AgentProcessManager extends EventEmitter {
       try {
         await this.waitForReady(id, managed, 2e4);
       } catch (err) {
-        const portConflict = managed.stderrBuffer.some((l) => l.includes("EADDRINUSE"));
+        const portConflict = isPortConflict(managed.stderrBuffer);
         try {
           if (managed.child.exitCode === null) managed.child.kill("SIGKILL");
         } catch {
@@ -535,4 +538,4 @@ class ProcessManagerAdapter {
   }
 }
 
-export { AgentProcessManager as A, ProcessManagerAdapter as P };
+export { AgentProcessManager as A, ProcessManagerAdapter as P, isPortConflict as i };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skaile/forge-agent-runtime",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Agent process lifecycle for Skaile forge apps: spawns `skaile serve`, connects over WebSocket, and exposes the AgentAdapter, harness registry and session manager. Node-only.",
   "type": "module",
   "packageManager": "bun@1.3.9",
@@ -42,8 +42,8 @@
     "lint": "biome lint --fix --unsafe src tests"
   },
   "dependencies": {
-    "@skaile/forge-settings": "^1.0.0",
-    "@skaile/workspaces": "^6.11.0",
+    "@skaile/forge-settings": "^1.1.1",
+    "@skaile/workspaces": "^6.11.0 || ^7.0.0",
     "consola": "^3.4.2",
     "picocolors": "^1.1.1"
   },