@nylorun/runtime 0.9.0-beta → 0.10.0-beta

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.10.0-beta
+
+### Minor Changes
+
+- c49efed: **Runtime Clients and Admin API (supporting packages).**
+
+  - **core:** `AdminStatusSchema`, Project-link schemas, `ERROR_CODES` (launcher codes include `platform_unsupported`, `launcher_failed`, `downgrade_refused`), `admin-status` feature, `newPrincipalId`, `compareVersions`.
+  - **runtime:** `/v1/admin/status` (alias `/v1/admin/host`), loopback/`Origin`/content-type checks; the launcher ships as this package's `nylorun-runtime` bin (source under `src/launcher/`, not in `exports`) and runs the Host on the Node it runs on.
+  - **studio:** `nylorun-studio` binary; connects via `resolveConnection`; waits for `dev`; never calls Admin API or writes `.nylorun/`.
+
+  **Prerequisites:** developers install Node 24+ and `@nylorun/runtime` (`npm install --global @nylorun/runtime`) themselves; no package downloads Node or the Runtime, and there are no per-platform Runtime packages. Launcher commands: `version`, `up`, `down`, `restart`, `run`, `status`, `logs` (launcher protocol 1).
+
+- c49efed: **Breaking (pre-1.0 minor):** Replace a single SQLite Runtime per Project or home directory with a **Runtime Host** that serves isolated **Tenants**, selected by `Nylorun-Tenant` and negotiated with `Nylorun-Protocol` (protocol `2`, feature `runtime-tenants`). Vocabulary: Host root + Tenant + Project link.
+
+  - **core:** `PROTOCOL_VERSION = 2`, `HOST_PROTOCOL`, `TENANT_HEADER`, `PROTOCOL_HEADER`, `newTenantId` / `isTenantId`, `checkCompatibility`; health schema gains `hostId` + `protocol` (`service: "nylorun-runtime"`); Tenant/admin wire schemas; Tenant model routes under `/v1/tenant/*`.
+  - **runtime:** Host process + Tenant module; Tenant model routes under `/v1/tenant/*`; `startEphemeralRuntime` for tests/embeds; executors via `PUT /v1/executors`; sandbox prefix `nylorun-<tenant-id>-`.
+  - **agents:** `createClient({ url, key, tenant })`; Transport sends Tenant + protocol headers; `/health` compatibility cache; `IncompatibleRuntimeError` with upgrade remedies.
+  - **cli:** Host root lifecycle (`runtime up|down|status|logs|restart|run`); Project link (`.nylorun/link.json` + `credentials.json`); `tenant` commands; `runtime status --env` exports `NYLORUN_RUNTIME_URL`, `NYLORUN_SERVER_KEY`, `NYLORUN_TENANT`; removed Project/home SQLite selectors.
+  - **studio:** `startStudio({ …, tenant: { id, name } })`; proxy forwards Tenant + protocol headers; UI shows Tenant name/short id.
+
+- fd9fd87: Add workflows: compose agents and `tool()` with `Chain`, `Switch`, `Parallel`, `Map`, and `Loop`. A workflow is a registered runnable (`kind: "workflow"`) with the same session API as an agent — `export const agents`, `saveAgent` (saves referenced agents first), `createSession`, `input` (`content` or `data`), `observe({ follow })`, `pending`, `approve`, `cancel`. Slots (`{ run, id?, input? }`) reshape data between nodes. The flow engine (`runFlowDurable`) returns effects only; `harness/src/loop/` and `runDurable` are unchanged.
+
+  HostEffect gains flow kinds `agent`, `tool` (node), `fn`, and `verify`, each with `path`, `key`, and `iterations`. The Runtime drives agent nodes through the public session contract (linked sessions, shared sandbox via `PutSession.sandbox`), offers `fn` / `verify` again on lease expiry, and routes executor Actions by `(workflowId, key)` with claim-scoped `ctx.sandbox`. Optional `message.manifest` is a turn-only variant of the session pin (turn manifests). Studio shows the manifest tree, live node status, and session links. Examples under `examples/agents/{chain,switch,parallel,map,loop,ship-feature}/`.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin harness to the tested release.
+- Updated dependencies [c49efed]
+- Updated dependencies [c49efed]
+- Updated dependencies [fd9fd87]
+- Updated dependencies
+  - @nylorun/core@0.5.0-beta
+  - @nylorun/harness@0.19.0-beta
+
 ## 0.9.0-beta
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,10 @@
 # @nylorun/runtime
 
-The independent OSS HTTP execution host consumes `@nylorun/harness/run` and `@nylorun/core/contracts`. Cloud installs published `@nylorun/harness` from npm and does not import this Runtime package. Client authoring, sessions and connected executors belong to `@nylorun/agents`.
+The independent OSS **Runtime Host** consumes `@nylorun/harness/run` and
+`@nylorun/core/contracts`. Cloud installs published `@nylorun/harness` from npm
+and does not import this package. Client authoring and sessions belong to
+`@nylorun/agents`; Tenant lifecycle management belongs to `@nylorun/admin`.
+Vocabulary: [src/CONTEXT.md](./src/CONTEXT.md).
 
 Requires Node 24+. Build from the repository root:
 
@@ -9,43 +13,110 @@ npm install
 npm run build --workspace @nylorun/core
 npm run build --workspace @nylorun/harness
 npm run build --workspace @nylorun/runtime
-NYLORUN_SERVER_KEY='<separate-secret-at-least-16-characters>' npm start --workspace @nylorun/runtime
 ```
 
-Default address: `http://127.0.0.1:8787`. `HOST`, `PORT`, and `NYLORUN_SQLITE_PATH` configure binding and storage. Missing server credentials fail startup. The default model is a credential-free scripted development response. It does not simulate conversations, tools or provider compatibility.
+## Install and the launcher
 
-`NYLORUN_EXECUTORS_JSON` is an array of `{token, agentId, implementationVersion}`. Each secret must differ from the application server key and every other executor token. An optional `manifestHash` on an existing record is ignored and does not hide or reject work. SDK clients use `NYLORUN_RUNTIME_URL`, `NYLORUN_SERVER_KEY`, and `NYLORUN_EXECUTOR_KEY`; runtime executor scope is the agent id, never broadened by client input.
+Developers install the Runtime as a prerequisite; nothing downloads it for
+them ([runtime distribution](../docs/design/runtime-distribution.md)):
 
-For a model gateway, set `NYLORUN_MODEL_GATEWAY_URL`, `NYLORUN_MODEL_GATEWAY_KEY`, and `NYLORUN_MODEL`. The gateway receives `{model, call, context}` and returns a harness ModelCandidate or string. Provider credentials remain host configuration. The generic gateway requires an implementation of this envelope; it does not claim arbitrary provider wire compatibility. Alternatively supply a `ModelProvider` to `startRuntime`.
+```sh
+node --version                            # 24 or newer
+npm install --global @nylorun/runtime     # provides nylorun-runtime
+nylorun-runtime --version
+```
 
-```ts
-import { startRuntime } from '@nylorun/runtime/core';
-const runtime = await startRuntime({
-  sqlitePath: './nylorun.sqlite',
-  serverToken: process.env.NYLORUN_SERVER_KEY!,
-  executors: [], // Configure exact scoped executor credentials before customer actions.
-  port: 8787,
-});
-// Application owns lifecycle.
-await runtime.close();
+The **launcher** (`nylorun-runtime`, source in `src/launcher/`, not listed in
+`exports`) starts, stops and restarts the Host on the Node it runs on, from
+this package. Clients (CLI, desktop apps) find it on PATH and run it as a
+process; prefer `nylorun runtime up`. A project may instead add this package
+as a devDependency to pin its Runtime version; do not make it an application
+production dependency. For tests and ephemeral embeds, use
+`startEphemeralRuntime()` from `@nylorun/runtime/core`. See
+[MIGRATION.md](../MIGRATION.md#runtime-clients-and-admin-api-breaking-beta) and
+[building a desktop client](../docs/building-a-desktop-client.md).
+
+Default address: loopback port `8787` (persisted in `host.json`). The Host root
+is `NYLORUN_HOME` or `~/.nylorun`. Tenants live under `tenants/<tenantId>/`.
+
+## Layout
+
+```text
+<host root>/
+  host.json                 # format 1: hostId, bind, port, runtimeVersion, …
+  host-state.json           # pid, url — removed on shutdown
+  host-credentials.json     # adminKey (0600)
+  runtime.log
+  tenants/<tenantId>/       # envelope, SQLite, KEK, logs, sandboxes, …
+  trash/                    # deleted Tenants
 ```
 
-The session-first `/v1` API is specified in [HOST_CONTRACT.md](../harness/HOST_CONTRACT.md). `/health` confirms HTTP liveness; `/ready` checks SQLite and scheduler availability. Readiness is not a provider connectivity probe or functional correctness claim. Application tokens authorize definition/session APIs, while exact scoped executor credentials authorize authenticated SSE `/v1/executors/connect`, action discovery, claims, renewal and results. Session observers cannot claim actions.
+## HTTP surface
+
+| Route | Auth | Notes |
+| --- | --- | --- |
+| `GET /health` | none | `service: "nylorun-runtime"`, `hostId`, protocol `{min,max,features}` (includes `admin-status`), pid |
+| `GET /ready` | none | Listener up and Tenant discovery finished |
+| `GET /v1/admin/status` | admin key | `AdminStatusSchema`; alias `GET /v1/admin/host` |
+| `/v1/admin/tenants*` | admin key | Create / list / get / delete Tenants |
+| `POST /v1/admin/host/shutdown` | admin key | Launcher-private; not in `@nylorun/admin` |
+| `/v1/*` Tenant routes | application or executor | Require `Nylorun-Tenant` + `Nylorun-Protocol` |
+
+Every route checks `Host` first (`421 host_rejected`), rejects any `Origin`
+(`403 origin_rejected`, no CORS headers), and rejects non-JSON bodies with
+`415 unsupported_media_type`. Missing or unsupported protocol → `426` before
+authentication. Unknown, quarantined or rejected Tenant credentials → opaque
+`404` with identical body.
+
+## Embedding and tests
 
-SQLite transactions persist session checkpoints, command receipts, individual effects/actions, waits and canonical history. Actions are committed before notifications. Accepted execution is detached from HTTP request lifetime. Restart schedules persisted runnable sessions; model intents lacking recorded outcomes become uncertain. Expired customer claims become uncertain and are not automatically repeated. `GET /v1/sessions/:id` exposes waits, outstanding actions and uncertain effect summaries. Cancellation ends the current turn; a later message can start another turn from the state preceding the cancelled turn. Canonical events and uncertain external work remain inspectable. Reconciliation operations are not implemented in this pass.
+Tests and ephemeral embeds use `startEphemeralRuntime()` from
+`@nylorun/runtime/core`: private Host on port 0, temporary Host root, one Tenant,
+returns `{ url, tenantId, applicationKey, adminKey, close() }`.
 
-One process owns each SQLite database. A local PID lock rejects concurrent owners and recovers only when the recorded process no longer exists. Shared/network filesystems and multiple replicas are unsupported. Keep the database and its WAL/journal together; do not delete persisted effects separately from checkpoints. Invalid lock contents or PID reuse fail closed and require operator inspection. TLS and external ingress belong to deployment infrastructure.
+Register executors with `PUT /v1/executors` using the application principal
+(application-mode `connectAgents` does this with derived tokens). Model gateway
+and sandbox backend are Tenant configuration (vault / seed), not Host process
+env.
 
-The vault holds two scopes. End-user vaults each belong to one `ownerUserId` and store URL-bound credentials for outbound calls such as MCP. The host scope stores model provider credentials the Runtime uses when it calls a provider; Studio and `nylorun configure` can keep multiple providers and select the active provider/model. Secret values are encrypted with AES-256-GCM under a key-encryption key. Set `NYLORUN_VAULT_KEK` to 32 bytes encoded as base64, or allow the host to create `.nylorun/vault-kek` (mode 0600) on the first write. A database that already holds vault ciphertext will not open without that key. Reads return metadata only.
+## Session behaviour
 
-Agents that declare `.use(sandbox())` get Runtime-executed `bash`, `read`, `write`, `edit`, `grep` and `glob` tools. The Runtime owns each sandbox: one per session, created on the first sandbox tool call, stopped after its idle timeout, and reattached with its files on the next call, including after a restart. On first use the Runtime probes its backends in order and keeps the choice for its lifetime: a microsandbox microVM (macOS on Apple Silicon, or Linux with `/dev/kvm`), then the in-process virtual shell (`just-bash`). Set `NYLORUN_SANDBOX=microsandbox` or `virtual` to force one; a forced backend never falls back. `GET /v1/host/sandbox` reports the selection, and `nylorun doctor sandbox` shows the same probe. Virtual workspaces live in `sandboxes/` beside the SQLite file. Tool calls emit `sandbox.state` and `sandbox.exec` session events. A sandbox call interrupted by a crash becomes uncertain and is never re-run. `microsandbox` is an optional dependency pinned to an exact version. See [the sandbox design](../docs/design/sandboxes.md) for guarantees and limitations.
+The session-first `/v1` API is specified in
+[HOST_CONTRACT.md](../harness/HOST_CONTRACT.md). Application tokens authorize
+definition/session APIs; executor credentials authorize authenticated SSE
+connect, action discovery, claims, renewal and results. Session observers cannot
+claim actions.
 
-## Local project workflow
+SQLite transactions persist session checkpoints, command receipts, individual
+effects/actions, waits and canonical history — **per Tenant**. One process owns
+each Tenant database (`.runtime-lock`). Keep the database and its WAL/journal
+together. Vault ciphertext needs that Tenant's own KEK.
 
-Install `@nylorun/cli` (generated projects already include it). Use `nylorun up` and `nylorun dev` in a generated project. It loads the exported `agents` registry from `agents/index.ts`, starts this Runtime in a separate process, and, when no host model credential is stored, prompts in an interactive terminal and writes it to the vault. It then registers manifests, connects scoped SDK executors, and opens Studio. Use `--no-studio` or `--no-open` as needed. Runtime binds loopback on port 8787 (`PORT` override). The CLI creates separate server and executor credentials with mode 0600 in `.nylorun/local-credentials.json`; SQLite defaults to `.nylorun/runtime.sqlite`.
+Agents that declare `.use(sandbox())` get Runtime-executed sandbox tools. The
+Tenant owns each sandbox; backend names are prefixed `nylorun-<tenant-id>-`.
+
+## Local Project workflow
+
+Install `@nylorun/cli` as a devDependency. `nylorun runtime up` starts the Host
+via the launcher; `nylorun dev` creates or uses a Project link and runs
+`src/main.ts` under `tsx watch`. Studio is `nylorun-studio` / `npm run studio`.
+
+```sh
+eval "$(npx nylorun runtime status --env)"
+# → NYLORUN_RUNTIME_URL, NYLORUN_SERVER_KEY, NYLORUN_TENANT
+```
 
-`nylorun serve [entry]` loads `dist/agents/index.js` by default and runs without Studio/watch, attaching to the Runtime that `nylorun up` started. It uses the same first-start prompt. `nylorun configure` replaces the host credential against a Runtime that is already listening. `nylorun studio` attaches using the project's local server credential (or `NYLORUN_SERVER_KEY`). Studio can replace an API-key credential. If `MODEL_PROVIDER`, `MODEL`, and `MODEL_PROVIDER_API_KEY` are already set, the first start seeds the vault from them and does not prompt. Existing `.env` model settings and `.nylorun/auth.json` are imported once the same way. No provider request occurs during that setup. `NYLORUN_DEV_MODEL=fixture` and `NYLORUN_MODEL_GATEWAY_URL` remain separate from the vault.
+## Troubleshooting
 
-Definitions have no `agent.run()`; applications use `@nylorun/agents`. The previous in-process host (`Runtime`, `serveAgents`, `openSession`, `httpModel`, `localSessions`, and the AG-UI route) has been removed; remove any remaining usage from applications.
+| Symptom | What to do |
+| --- | --- |
+| Tenant `locked` | Another process holds `.runtime-lock`. `nylorun tenant status` prints `repair` |
+| `kek-missing` | Restore the Tenant KEK beside the database |
+| `corrupt` / `migration-failed` / `envelope-invalid` | Follow `nylorun tenant status` repair string |
+| `schema-too-new` / `host_schema_newer` | Upgrade the Host build (`nylorun runtime restart`) |
+| `426 protocol_unsupported` | Upgrade clients or Host to a compatible set |
+| `421 host_rejected` / `403 origin_rejected` | Call from main process / Node; loopback Host only |
+| Port in use | Explicit `--port` fails closed. First setup may pick a free loopback port |
+| Logs | `nylorun runtime logs [--follow]` |
 
-Source changes restart the local stack. Start a new session after definition or implementation edits; live upgrades are deferred. `GET /v1/agents` and `GET /v1/sessions?agentId=...` are server-authenticated local discovery conveniences.
+Definitions have no `agent.run()`; applications use `@nylorun/agents`.

package/dist/adapters/media.d.ts

@@ -19,6 +19,6 @@ export declare class MediaStore {
     private readMetadata;
     private directory;
 }
-export declare function localMedia(options?: {
-    root?: string;
+export declare function localMedia(options: {
+    root: string;
 }): MediaStore;

package/dist/adapters/media.js

@@ -106,6 +106,6 @@ function omitCreatedAt(asset) {
 function safe(value) {
     return value !== "." && value !== ".." && /^[a-zA-Z0-9._-]+$/u.test(value);
 }
-export function localMedia(options = {}) {
-    return new MediaStore(options.root ?? join(process.cwd(), ".data", "media"));
+export function localMedia(options) {
+    return new MediaStore(options.root);
 }

package/dist/adapters/observe.d.ts

@@ -2,7 +2,8 @@
 export declare function jsonlObserver(options: {
     readonly agentId: string;
     readonly sessionId: string;
-    readonly root?: string;
+    readonly root: string;
+    readonly env?: Readonly<Record<string, string | undefined>>;
 }): {
     (event: {
         readonly type: string;

package/dist/adapters/observe.js

@@ -4,10 +4,9 @@ import { scrub } from "../redact.js";
 import { projectSecrets } from "../model/settings.js";
 /** Local JSONL observer. Writes raw engine events beside session durability files. */
 export function jsonlObserver(options) {
-    const root = options.root ?? join(process.cwd(), ".data", "sessions");
-    const directory = join(root, safe(options.agentId), safe(options.sessionId));
+    const directory = join(options.root, safe(options.agentId), safe(options.sessionId));
     const file = join(directory, "observe.jsonl");
-    const secrets = projectSecrets();
+    const secrets = projectSecrets(options.root, options.env ?? {});
     return (event) => {
         const line = `${JSON.stringify(scrub(event, secrets))}\n`;
         void mkdir(directory, { recursive: true })

package/dist/assets.d.ts

@@ -1,2 +1,2 @@
-/** Resolve authored catalogs and subprocess assets in source or a built application. */
-export declare function projectAsset(path: string): string;
+/** Resolve authored catalogs and subprocess assets under an explicit project root. */
+export declare function projectAsset(path: string, root?: string): string;

package/dist/assets.js

@@ -1,8 +1,10 @@
 import { existsSync } from "node:fs";
 import { resolve, relative } from "node:path";
-/** Resolve authored catalogs and subprocess assets in source or a built application. */
-export function projectAsset(path) {
-    const root = process.cwd();
+/** Resolve authored catalogs and subprocess assets under an explicit project root. */
+export function projectAsset(path, root) {
+    if (!root) {
+        throw new Error("projectAsset requires an explicit project root");
+    }
     const source = resolve(root, path);
     if (relative(root, source).startsWith(".."))
         throw new Error("Asset must be inside the project.");

package/dist/core/executors.d.ts

@@ -7,15 +7,23 @@ import type { ExecutorScope } from "@nylorun/core/contracts";
 export declare const hashToken: (token: string) => string;
 export interface ExecutorRecord extends ExecutorScope {
     readonly tokenHash: string;
-    /** False for scopes supplied through NYLORUN_EXECUTORS_JSON, which are never written to SQLite. */
+    /** Always true under Runtime Tenants; startup env executors are removed (D8). */
     readonly persisted: boolean;
     readonly updatedAt: string;
+    /** Application principal that last registered this executor, when known. */
+    readonly principalId?: string;
 }
+/**
+ * Rejects tokens that are weak, empty of agent identity, or whose hash equals any
+ * application principal hash (A5). Replaces the old `serverToken` equality check.
+ */
 export declare function assertExecutorCredential(executor: {
     agentId: string;
     implementationVersion: string;
     token: string;
-}, serverToken: string): void;
+}, applicationHashes: readonly string[]): void;
+/** Mint a 32-byte hex application/executor key for tests and CLI bootstrap. */
+export declare function mintBearerToken(): string;
 export declare class ExecutorRegistry {
     private readonly byHash;
     private readonly byAgent;
@@ -26,6 +34,7 @@ export declare class ExecutorRegistry {
     upsert(record: ExecutorRecord): {
         rotated: boolean;
         previousHash?: string;
+        previousPrincipalId?: string;
     };
     remove(agentId: string): ExecutorRecord | undefined;
     private write;

package/dist/core/executors.js

@@ -1,4 +1,4 @@
-import { createHash, timingSafeEqual } from "node:crypto";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 const equals = (a, b) => {
     const aa = Buffer.from(a), bb = Buffer.from(b);
     return aa.length === bb.length && timingSafeEqual(aa, bb);
@@ -9,13 +9,23 @@ const equals = (a, b) => {
  * SQLite at rest. This is not a password KDF and must not be used for one.
  */
 export const hashToken = (token) => createHash("sha256").update(token, "utf8").digest("hex");
-export function assertExecutorCredential(executor, serverToken) {
+/**
+ * Rejects tokens that are weak, empty of agent identity, or whose hash equals any
+ * application principal hash (A5). Replaces the old `serverToken` equality check.
+ */
+export function assertExecutorCredential(executor, applicationHashes) {
+    const tokenHash = hashToken(executor.token);
+    const matchesApplication = applicationHashes.some((hash) => equals(hash, tokenHash));
     if (executor.token.length < 16 ||
-        equals(executor.token, serverToken) ||
+        matchesApplication ||
         !executor.agentId ||
         !executor.implementationVersion)
         throw new Error("Executor tokens require independent credentials and an agent id");
 }
+/** Mint a 32-byte hex application/executor key for tests and CLI bootstrap. */
+export function mintBearerToken() {
+    return randomBytes(32).toString("hex");
+}
 export class ExecutorRegistry {
     byHash = new Map();
     byAgent = new Map();
@@ -40,7 +50,13 @@ export class ExecutorRegistry {
         this.write(record);
         if (!previous || previous.tokenHash === record.tokenHash)
             return { rotated: false };
-        return { rotated: true, previousHash: previous.tokenHash };
+        return {
+            rotated: true,
+            previousHash: previous.tokenHash,
+            ...(previous.principalId === undefined
+                ? {}
+                : { previousPrincipalId: previous.principalId }),
+        };
     }
     remove(agentId) {
         const record = this.byAgent.get(agentId);

package/dist/core/flow-host.d.ts

@@ -0,0 +1,264 @@
+import type { Action, LiveEvent } from "@nylorun/core/contracts";
+import type { JsonValue, WorkflowManifest } from "@nylorun/core/define";
+import type { EffectResolution, HostEffect } from "@nylorun/harness/run";
+import { type FlowLimits } from "./limits.js";
+/** Deterministic agent session id: derive(workflowSessionId, path, …parts). */
+export declare function deriveSessionId(workflowSessionId: string, path: string, ...parts: string[]): string;
+/**
+ * Linked agent session id for a flow agent effect.
+ * Verifier agents (`context.role === "verify-agent"`) get a unique session per
+ * (path, turnId, iterations) so prior verdicts cannot leak across Loop iterations.
+ */
+export declare function deriveAgentEffectSessionId(workflowSessionId: string, path: string, request: {
+    readonly turnId: string;
+    readonly iterations?: string;
+    readonly context?: Record<string, unknown>;
+}): string;
+export declare function isWorkflowManifest(manifest: unknown): manifest is WorkflowManifest;
+/** Flow tool-node effect: `tool` with path/key and no agent capabilityId. */
+export declare function isFlowToolEffect(request: HostEffect): boolean;
+export declare function isFlowEffect(request: HostEffect): boolean;
+export type FlowLink = {
+    readonly workflowSessionId: string;
+    readonly path: string;
+    readonly effectId: string;
+    readonly turnId: string;
+};
+export type FlowHostStore = {
+    get<T = any>(table: string, id: string): T | undefined;
+    put(table: string, id: string, body: unknown): void;
+    all<T = any>(table: string): T[];
+    event(sessionId: string, turnId: string | null, type: string, payload: unknown): LiveEvent;
+};
+export type FlowHostSession = {
+    id: string;
+    agentId: string;
+    ownerUserId: string;
+    manifest: any;
+    manifestHash: string;
+    implementationVersion: string;
+    status: string;
+    activeTurnId: string | null;
+    info?: any;
+    vaultIds?: readonly string[];
+    credentialSelections?: readonly unknown[];
+    creation?: unknown;
+    waits?: unknown;
+    lastOutput?: JsonValue;
+    error?: string;
+};
+export type FlowWait = {
+    readonly sessionId: string;
+    readonly path: string;
+    readonly interactionId: string;
+    readonly kind: string;
+    readonly invocationId?: string;
+    readonly wait?: unknown;
+    readonly status?: string;
+};
+export type CancelSiblingResult = {
+    readonly cancelledActions: string[];
+    readonly uncertainActions: string[];
+    readonly agentSessionIds: string[];
+};
+export type CascadeCancelPlan = {
+    /** Linked agent sessions to cancel, deepest path first. */
+    readonly agentSessionIds: string[];
+    readonly pendingActionIds: string[];
+    readonly claimedActionIds: string[];
+};
+/**
+ * Resolve flow effects: agent (via session contract), tool nodes, fn, verify.
+ * Runtime never writes agent session state — only issues commands.
+ */
+export declare function resolveFlowEffect(input: {
+    readonly request: HostEffect;
+    readonly store: FlowHostStore;
+    readonly session: FlowHostSession;
+    readonly limits?: FlowLimits;
+    readonly putLinkedSession: (args: {
+        id: string;
+        agentId: string;
+        ownerUserId: string;
+        vaultIds?: readonly string[];
+        credentialSelections?: readonly unknown[];
+    }) => FlowHostSession;
+    readonly sendMessage: (args: {
+        sessionId: string;
+        content?: string;
+        data?: JsonValue;
+        idempotencyKey: string;
+        requestId: string;
+    }) => {
+        turnId: string | null;
+    };
+    readonly readSession: (id: string) => FlowHostSession | undefined;
+    readonly publish: (event: LiveEvent) => void;
+    readonly notify: () => void;
+    readonly schedule: (sessionId: string) => void;
+}): EffectResolution;
+/** Active agent turns + pending/claimed actions for one workflow turn. */
+export declare function countActiveFlowWork(store: FlowHostStore, workflowSessionId: string, turnId: string): number;
+/** After an agent turn settles, wake the owning workflow if linked. */
+export declare function wakeLinkedWorkflow(input: {
+    readonly agentSessionId: string;
+    readonly store: FlowHostStore;
+    readonly output?: JsonValue;
+    readonly failed?: boolean;
+    readonly cancelled?: boolean;
+    readonly error?: string;
+    readonly schedule: (sessionId: string) => void;
+    readonly publish: (event: LiveEvent) => void;
+}): void;
+/** On Runtime start: settle pending agent effects whose linked turns already finished. */
+export declare function reconcilePendingAgentEffects(input: {
+    readonly store: FlowHostStore;
+    readonly schedule: (sessionId: string) => void;
+    readonly publish: (event: LiveEvent) => void;
+}): void;
+/** Re-offer orphaned fn/verify claims after a process restart (SD-P7 / WF-C9). */
+export declare function reofferOrphanedFnVerifyClaims(store: FlowHostStore): number;
+/**
+ * On lease expiry: fn/verify → pending again; tool nodes → uncertain (WF-R35, WF-R38).
+ * Returns whether any fn/verify was redelivered.
+ */
+export declare function applyFlowLeaseExpiry(input: {
+    readonly store: FlowHostStore;
+    readonly action: Action;
+    readonly now?: number;
+}): "reoffer" | "uncertain" | "skip";
+/** Emit loop.verified / loop.decided after fn/verify actions complete. */
+export declare function emitLoopActionEvents(input: {
+    readonly store: FlowHostStore;
+    readonly session: FlowHostSession;
+    readonly action: Action;
+    readonly value: unknown;
+    readonly publish: (event: LiveEvent) => void;
+}): void;
+export declare function emitNodeStarted(input: {
+    readonly store: FlowHostStore;
+    readonly session: FlowHostSession;
+    readonly publish: (event: LiveEvent) => void;
+}, payload: {
+    path: string;
+    kind: string;
+    key: string;
+    iterations?: string;
+}): LiveEvent;
+export declare function emitNodeCompleted(input: {
+    readonly store: FlowHostStore;
+    readonly session: FlowHostSession;
+    readonly publish: (event: LiveEvent) => void;
+}, payload: {
+    path: string;
+    iterations?: string;
+}): LiveEvent;
+export declare function emitNodeFailed(input: {
+    readonly store: FlowHostStore;
+    readonly session: FlowHostSession;
+    readonly publish: (event: LiveEvent) => void;
+}, payload: {
+    path: string;
+    iterations?: string;
+    error: {
+        code: string;
+        message: string;
+        path?: string;
+    };
+}): LiveEvent;
+export declare function emitSwitchSelected(input: {
+    readonly store: FlowHostStore;
+    readonly session: FlowHostSession;
+    readonly publish: (event: LiveEvent) => void;
+}, payload: {
+    path: string;
+    case: string;
+}): LiveEvent;
+export declare function emitMapItems(input: {
+    readonly store: FlowHostStore;
+    readonly session: FlowHostSession;
+    readonly publish: (event: LiveEvent) => void;
+}, payload: {
+    path: string;
+    count: number;
+}): LiveEvent;
+/** Path depth for deepest-first cancel ordering. */
+export declare function pathDepth(path: string): number;
+/**
+ * Plan a cancel cascade for a workflow session: linked agents deepest first,
+ * then pending → cancelled and claimed → uncertain actions (SD-P11 / WF-R53).
+ */
+export declare function planCancelCascade(input: {
+    readonly store: FlowHostStore;
+    readonly workflowSessionId: string;
+    readonly turnId: string | null;
+}): CascadeCancelPlan;
+/**
+ * Cancel sibling work under a Parallel/Map parent when one branch fails (PAR-R6).
+ * Agent turns listed in `agentSessionIds` are returned for the caller to cancel;
+ * pending actions → cancelled, claimed tool actions → uncertain.
+ * When `cancelEffectIds` is provided, those effects are marked cancelled and their
+ * paths are included in the sibling path set.
+ */
+export declare function cancelSiblingWork(input: {
+    readonly store: FlowHostStore;
+    readonly workflowSessionId: string;
+    readonly turnId: string;
+    /** Paths of siblings still running (not the failed branch). */
+    readonly siblingPaths?: readonly string[];
+    /** Effect ids the flow engine marked for fail-fast cancel. */
+    readonly cancelEffectIds?: readonly string[];
+}): CancelSiblingResult;
+/**
+ * Apply cancel fencing to workflow-session actions (pending→cancelled, claimed→uncertain).
+ */
+export declare function fenceWorkflowActions(input: {
+    readonly store: FlowHostStore;
+    readonly workflowSessionId: string;
+    readonly turnId: string | null;
+}): {
+    cancelled: string[];
+    uncertain: string[];
+};
+/**
+ * Aggregate human waits across the workflow session and linked agent sessions (WF-R51).
+ */
+export declare function aggregateWaits(input: {
+    readonly store: FlowHostStore;
+    readonly workflowSessionId: string;
+}): FlowWait[];
+/**
+ * Look up which session owns an interaction id. Used for 409 foreign approvals (WF-R52).
+ */
+export declare function findInteractionOwner(input: {
+    readonly store: FlowHostStore;
+    readonly workflowSessionId: string;
+    readonly interactionId: string;
+}): {
+    sessionId: string;
+    path: string;
+} | undefined;
+/**
+ * If approve/respond targets an interaction owned by a linked agent session,
+ * return a 409 message naming that session (WF-R52 / LOOP-A4).
+ */
+export declare function foreignInteractionConflict(input: {
+    readonly store: FlowHostStore;
+    readonly workflowSessionId: string;
+    readonly interactionId: string;
+}): {
+    status: 409;
+    message: string;
+    ownerSessionId: string;
+} | undefined;
+/**
+ * When concurrency slots free, re-enter the workflow so queued effects can start
+ * (status stays `queued` until `resolveFlowEffect` dispatches them).
+ */
+export declare function wakeForQueuedEffects(input: {
+    readonly store: FlowHostStore;
+    readonly workflowSessionId: string;
+    readonly turnId: string;
+    readonly limits: FlowLimits;
+    readonly schedule: (sessionId: string) => void;
+}): boolean;