@nylorun/runtime 0.16.0-beta → 0.19.0-beta

package/dist/api/openapi.js

@@ -1,11 +1,10 @@
 /**
- * The Runtime's OpenAPI 3.2 documents, generated from the routes as declared for serving:
- *
- * - the Tenant API (`tenantDocument`): every Tenant route, with `/health`, `/ready` and
- *   `/openapi.json`. Served at `GET /openapi.json`, packed as `@nylorun/runtime/openapi.json`
- *   and attached to each release.
- * - the Admin API (`adminDocument`): served at `GET /v1/admin/openapi.json` behind the admin
- *   key, packed as `@nylorun/runtime/admin-openapi.json`.
+ * The Runtime's two OpenAPI 3.2 documents, generated from the routes as declared for serving
+ * (protocol 8): the Runtime API (`runtimeDocument`: `/openapi/runtime.json`, alias
+ * `/openapi.json`, `@nylorun/runtime/openapi.json`) and the Management API (`managementDocument`:
+ * `/openapi/management.json`, `@nylorun/runtime/management-openapi.json`). Both are attached to
+ * each release. Each has described tags in the order a developer uses them; the Runtime API
+ * groups them (`x-tagGroups`).
  *
  * Event streams are `text/event-stream` with an `itemSchema` (OpenAPI 3.2). Nothing here reads
  * the environment: the same Runtime makes the same document.
@@ -13,7 +12,6 @@
 import { OpenAPIRegistry, OpenApiGeneratorV32, } from "@asteasolutions/zod-to-openapi";
 import { HOST_PROTOCOL } from "@nylorun/core/compatibility";
 import { HealthResponseSchema, ReadyResponseSchema } from "@nylorun/core/contracts";
-import { createAdminApi } from "../host/admin-api.js";
 import { RUNTIME_VERSION } from "../version.js";
 import { tenantApi } from "./http/app.js";
 const PROTOCOL = {
@@ -49,7 +47,7 @@ function hostRoutes() {
         path: "/ready",
         tags: ["Host"],
         summary: "Check the Runtime is ready",
-        description: "The listeners, the Tenant (open), Postgres, Restate and S2.",
+        description: "The listener, the Tenant (open), Postgres, Restate and S2, and the open Tenant's harnesses.",
         responses: {
             200: {
                 description: "Ready",
@@ -58,80 +56,306 @@ function hostRoutes() {
             503: { description: "Not ready: `checks` says what is not" },
         },
     });
+    route({
+        method: "get",
+        path: "/openapi/runtime.json",
+        tags: ["Host"],
+        summary: "Get the Runtime API's document",
+        description: "This document. `/openapi.json` is the same.",
+        responses: { 200: { description: "The Runtime API's OpenAPI document" } },
+    });
     route({
         method: "get",
         path: "/openapi.json",
         tags: ["Host"],
-        summary: "Get this document",
-        responses: { 200: { description: "The Tenant API's OpenAPI document" } },
+        summary: "Get the Runtime API's document (alias)",
+        responses: { 200: { description: "The Runtime API's OpenAPI document" } },
+    });
+    route({
+        method: "get",
+        path: "/openapi/management.json",
+        tags: ["Host"],
+        summary: "Get the Management API's document",
+        responses: { 200: { description: "The Management API's OpenAPI document" } },
     });
     return registry;
 }
 function tenantSchemes(registry) {
-    registry.registerComponent("securitySchemes", "applicationKey", bearer("An application key of the Tenant, or a key derived from the admin key. With `Nylorun-Subject` and `Nylorun-Scopes`, it acts for that person, narrowed to those scopes."));
-    registry.registerComponent("securitySchemes", "subjectToken", bearer("A subject token (`POST /v1/tokens`): one person and one role of the access policy, for at most 15 minutes.", "JWT"));
-    registry.registerComponent("securitySchemes", "deliveryToken", bearer("The delivery token the Runtime signs each Action delivery with (`Nylorun-Signature`), sent back by the Action endpoint. It reaches only that Action's heartbeat, result and sandbox routes, while that delivery is current, for at most 15 minutes.", "JWT"));
-    registry.registerComponent("securitySchemes", "publishableKey", {
-        type: "apiKey",
-        in: "header",
-        name: "Nylorun-Key",
-        description: "A publishable key, sent by a browser page on one of its origins. Public by design: it grants the access policy's anonymous scopes.",
-    });
+    registry.registerComponent("securitySchemes", "applicationKey", bearer("An application key of the Tenant (`PUT /v1/tenant/keys/{keyId}`), or Studio's key, derived from the admin key. With `Nylorun-Subject` and `Nylorun-Scopes`, it acts for that person, narrowed to those scopes. Never accepted from a browser (`Origin`)."));
+    registry.registerComponent("securitySchemes", "managementKey", bearer("A management key of the Tenant (role `management`): it reaches the Management API (`/v1/tenant/*`) and `/v1/me`, as itself, never for a subject. Issued only on the Tenant's machine (`nylorun-operate keys put <id> --role management`) or from `NYLORUN_MANAGEMENT_KEY_FILE`. Never accepted from a browser (`Origin`)."));
+    registry.registerComponent("securitySchemes", "issuerToken", bearer("A JWT from a trusted issuer of the Host's identity file (Host feature `trusted-issuers`): one person, with the issuer's scopes, agents and sandbox grants, until it expires. Accepted from servers and browsers alike; CORS is the operator's proxy's.", "JWT"));
 }
-let tenant;
-let admin;
-/** The Tenant API's document. */
-export function tenantDocument() {
-    if (tenant)
-        return tenant;
+const RUNTIME_TAGS = [
+    {
+        name: "Runtime",
+        group: "Get started",
+        description: "Check a Runtime is up and speaks your protocol, ask who your credential is, and read the public keys of the tokens it signs. `/health`, `/ready`, the JWKS and the documents need no key.",
+        operations: [
+            "GET /health",
+            "GET /ready",
+            "GET /v1/me",
+            "GET /v1/access/jwks",
+            "GET /openapi/runtime.json",
+            "GET /openapi.json",
+        ],
+    },
+    {
+        name: "Agents",
+        group: "Agents",
+        description: "The agents a Tenant can run: put a definition, list what is there. In `@nylorun/agents`.",
+        operations: ["PUT /v1/agents/{agentId}", "GET /v1/agents"],
+    },
+    {
+        name: "Definition files",
+        group: "Agents",
+        description: "The files a definition names by the SHA-256 of their bytes (each skill's folder): upload each once before putting the definition, which is refused while it names one the Runtime does not hold (`definition_files_missing`). `saveAgent` in `@nylorun/agents` does both.",
+        operations: ["PUT /v1/files/{file}", "HEAD /v1/files/{file}"],
+    },
+    {
+        name: "Sessions API",
+        group: "Sessions",
+        description: "A conversation with an agent: open a session, send commands, follow its events, read its history. In `@nylorun/agents`.",
+        operations: [
+            "PUT /v1/sessions/{sessionId}",
+            "GET /v1/sessions",
+            "GET /v1/sessions/{sessionId}",
+            "POST /v1/sessions/{sessionId}/commands",
+            "GET /v1/sessions/{sessionId}/events",
+            "GET /v1/sessions/{sessionId}/items",
+            "GET /v1/sessions/{sessionId}/manifest",
+            "GET /v1/sessions/{sessionId}/usage",
+            "GET /v1/sessions/{sessionId}/calls/model",
+            "POST /v1/sessions/{sessionId}/sandbox/{tool}",
+        ],
+    },
+    {
+        name: "AG-UI",
+        group: "Sessions",
+        description: "The same sessions through AG-UI: a thread is one session per person, agent and thread, and each run is a turn.",
+        operations: [
+            "POST /v1/ag-ui/agents/{agentId}",
+            "GET /v1/ag-ui/agents/{agentId}/threads/{threadId}/events",
+            "GET /v1/ag-ui/agents/{agentId}/threads/{threadId}/messages",
+            "POST /v1/ag-ui/agents/{agentId}/threads/{threadId}/cancel",
+        ],
+    },
+    {
+        name: "A2A",
+        group: "Sessions",
+        description: "The same sessions through Agent2Agent: a context is one session per subject, agent and `contextId`, and a task is one turn. The card is how an A2A client finds the agent.",
+        operations: ["GET /v1/a2a/agents/{agentId}/card", "POST /v1/a2a/agents/{agentId}"],
+    },
+    {
+        name: "Sandboxes",
+        group: "Sandboxes & artifacts",
+        description: "Isolated machines an agent works in: create or find one, watch its lifecycle, stop, reset or delete it. In `@nylorun/agents`.",
+        operations: [
+            "PUT /v1/sandboxes/{sandboxId}",
+            "GET /v1/sandboxes",
+            "GET /v1/sandboxes/{sandboxId}",
+            "GET /v1/sandboxes/{sandboxId}/events",
+            "POST /v1/sandboxes/{sandboxId}/stop",
+            "POST /v1/sandboxes/{sandboxId}/reset",
+            "DELETE /v1/sandboxes/{sandboxId}",
+        ],
+    },
+    {
+        name: "Artifacts",
+        group: "Sandboxes & artifacts",
+        description: "Files and folders agents and people produce, versioned, with short-lived capability links to share them. In `@nylorun/agents`.",
+        operations: [
+            "POST /v1/artifacts",
+            "GET /v1/artifacts",
+            "GET /v1/artifacts/{artifactId}",
+            "POST /v1/artifacts/{artifactId}/versions",
+            "GET /v1/artifacts/{artifactId}/versions/{version}/content",
+            "GET /v1/artifacts/{artifactId}/versions/{version}/tree",
+            "GET /v1/artifacts/{artifactId}/versions/{version}/files/{path}",
+            "GET /v1/artifacts/{artifactId}/versions/{version}/diff",
+            "GET /v1/artifacts/{artifactId}/versions/{version}/zip",
+            "POST /v1/artifacts/{artifactId}/links",
+            "GET /v1/artifact-links/{token}",
+            "DELETE /v1/artifacts/{artifactId}",
+        ],
+    },
+];
+const MANAGEMENT_TAGS = [
+    {
+        name: "Tenant",
+        description: "The Tenant's status, and seeding or resetting it. `admin.tenant` in `@nylorun/admin`.",
+        operations: [
+            "GET /v1/tenant",
+            "PUT /v1/tenant/config/seed",
+            "POST /v1/tenant/reset",
+            "GET /v1/me",
+            "GET /openapi/management.json",
+        ],
+    },
+    {
+        name: "Application keys",
+        description: "The keys app servers call the Runtime API with: create, rotate, list and delete them. Management keys come only from the Tenant's machine. `admin.keys`.",
+        operations: ["GET /v1/tenant/keys", "PUT /v1/tenant/keys/{keyId}", "DELETE /v1/tenant/keys/{keyId}"],
+    },
+    {
+        name: "Models",
+        description: "Model providers, their credentials, the model the Tenant uses, what it spent, every model call for export, and the budgets that cap it. `admin.models`.",
+        operations: [
+            "GET /v1/tenant/models",
+            "GET /v1/tenant/providers",
+            "GET /v1/tenant/model",
+            "PUT /v1/tenant/model",
+            "PUT /v1/tenant/model/selection",
+            "GET /v1/tenant/usage",
+            "GET /v1/tenant/calls/model",
+            "GET /v1/tenant/budgets",
+            "PUT /v1/tenant/budgets",
+        ],
+    },
+    {
+        name: "Vaults",
+        description: "The installation's credentials for agents' tools: API keys and MCP OAuth connections. Sessions attach a vault by id. `admin.vaults`.",
+        operations: [
+            "POST /v1/tenant/vaults",
+            "GET /v1/tenant/vaults",
+            "GET /v1/tenant/vaults/{vaultId}",
+            "DELETE /v1/tenant/vaults/{vaultId}",
+            "POST /v1/tenant/vaults/{vaultId}/credentials",
+            "GET /v1/tenant/vaults/{vaultId}/credentials",
+            "GET /v1/tenant/vaults/{vaultId}/credentials/{credentialId}",
+            "POST /v1/tenant/vaults/{vaultId}/credentials/{credentialId}",
+            "DELETE /v1/tenant/vaults/{vaultId}/credentials/{credentialId}",
+            "POST /v1/tenant/vaults/{vaultId}/oauth/start",
+            "GET /v1/oauth/callback",
+        ],
+    },
+    {
+        name: "Signing keys",
+        description: "The keys the Runtime signs capability links and run tokens with; their public halves are the Runtime API's JWKS. `admin.signingKeys`.",
+        operations: [
+            "GET /v1/tenant/signing-keys",
+            "POST /v1/tenant/signing-keys/rotate",
+            "POST /v1/tenant/signing-keys/{kid}/revoke",
+        ],
+    },
+    {
+        name: "Settings",
+        description: "The Tenant's sandbox and artifact settings. `admin.settings`.",
+        operations: [
+            "GET /v1/tenant/sandbox",
+            "PUT /v1/tenant/sandbox",
+            "GET /v1/tenant/artifacts",
+            "PUT /v1/tenant/artifacts",
+        ],
+    },
+];
+const METHODS = ["get", "head", "put", "post", "delete", "patch"];
+const SERVERS = [
+    {
+        url: "{origin}",
+        description: "A Runtime: a local Tenant (`nylorun start`), or where yours runs",
+        variables: { origin: { default: "http://localhost:8787" } },
+    },
+];
+/** The `#/components/schemas/…` names `value` refers to, followed through `schemas`. */
+function referencedSchemas(value, schemas) {
+    const found = new Set();
+    const walk = (node) => {
+        if (Array.isArray(node))
+            return node.forEach(walk);
+        if (!node || typeof node !== "object")
+            return;
+        for (const [key, child] of Object.entries(node)) {
+            if (key === "$ref" && typeof child === "string" && child.startsWith("#/components/schemas/")) {
+                const name = child.slice("#/components/schemas/".length);
+                if (!found.has(name)) {
+                    found.add(name);
+                    walk(schemas[name]);
+                }
+            }
+            else
+                walk(child);
+        }
+    };
+    walk(value);
+    return found;
+}
+/** One reference document: `tags`' operations of `all`, in their order, with what they use. */
+function document(all, tags, info) {
+    const paths = {};
+    for (const tag of tags)
+        for (const name of tag.operations) {
+            const [method, path] = name.split(" ");
+            const operation = all.paths?.[path]?.[method.toLowerCase()];
+            if (!operation)
+                throw new Error(`The Runtime has no operation ${name}`);
+            (paths[path] ??= {})[method.toLowerCase()] = { ...operation, tags: [tag.name] };
+        }
+    const schemas = (all.components?.schemas ?? {});
+    const used = referencedSchemas(paths, schemas);
+    const schemes = new Set();
+    for (const item of Object.values(paths))
+        for (const operation of Object.values(item))
+            for (const requirement of (operation.security ?? []))
+                for (const scheme of Object.keys(requirement))
+                    schemes.add(scheme);
+    const groups = [...new Set(tags.flatMap((tag) => (tag.group ? [tag.group] : [])))];
+    return {
+        ...all,
+        info: { ...all.info, ...info },
+        tags: tags.map((tag) => ({ name: tag.name, description: tag.description })),
+        ...(groups.length
+            ? {
+                "x-tagGroups": groups.map((group) => ({
+                    name: group,
+                    tags: tags.filter((tag) => tag.group === group).map((tag) => tag.name),
+                })),
+            }
+            : {}),
+        paths,
+        components: {
+            ...all.components,
+            schemas: Object.fromEntries(Object.entries(schemas).filter(([name]) => used.has(name))),
+            securitySchemes: Object.fromEntries(Object.entries(all.components?.securitySchemes ?? {}).filter(([name]) => schemes.has(name))),
+        },
+    };
+}
+let built;
+/** Both reference documents, built once from every route; throws when one is left out. */
+function documents() {
+    if (built)
+        return built;
     const host = hostRoutes();
     tenantSchemes(host);
-    tenant = new OpenApiGeneratorV32([
+    const all = new OpenApiGeneratorV32([
         ...host.definitions,
         ...tenantApi().openAPIRegistry.definitions,
     ]).generateDocument({
         openapi: "3.2.0",
-        info: {
-            title: "Nylorun Runtime: Tenant API",
-            version: RUNTIME_VERSION,
-            description: "Agents, sessions and their events, vaults, access and the Tenant's settings. A Runtime serves one Tenant: its URL is the Tenant's, and no request names it. Every request sends `Nylorun-Protocol`. Who may call each operation is its `security` and its `x-nylorun-credentials`, `x-nylorun-scopes` (the subject scopes that reach it) and `x-nylorun-browser` fields.",
-            "x-nylorun-protocol": PROTOCOL,
-        },
-        servers: [
-            {
-                url: "{origin}",
-                description: "A Runtime: a local Tenant (`nylorun start`), or where yours runs",
-                variables: { origin: { default: "http://localhost:8787" } },
-            },
-        ],
+        info: { title: "Nylorun Runtime", version: RUNTIME_VERSION, "x-nylorun-protocol": PROTOCOL },
+        servers: SERVERS,
     });
-    return tenant;
+    const listed = new Set([...RUNTIME_TAGS, ...MANAGEMENT_TAGS].flatMap((tag) => tag.operations));
+    for (const [path, item] of Object.entries(all.paths ?? {}))
+        for (const method of METHODS)
+            if (item[method] && !listed.has(`${method.toUpperCase()} ${path}`))
+                throw new Error(`${method.toUpperCase()} ${path} is in no reference tag (api/openapi.ts)`);
+    built = {
+        runtime: document(all, RUNTIME_TAGS, {
+            title: "Nylorun Runtime API",
+            description: "For developers: agents, sessions (with AG-UI and A2A), sandboxes and artifacts, through `@nylorun/agents`. Every Tenant serves it on its one URL, beside the Management API (`/openapi/management.json`). Every request sends `Nylorun-Protocol`. Who may call each operation is its `security` and its `x-nylorun-credentials` and `x-nylorun-scopes` (the subject scopes that reach it) fields: an application key (servers) or a trusted issuer's token (browsers and apps).",
+        }),
+        management: document(all, MANAGEMENT_TAGS, {
+            title: "Nylorun Management API",
+            description: "For operators: the Tenant's models, vaults, signing keys, settings and application keys, at `/v1/tenant/*` on the Tenant's URL, through `@nylorun/admin`. Every operation takes a management key, acting as itself: never for a subject and never from a browser. Management keys are issued only on the Tenant's machine (`nylorun key put <id> --management`) or from `NYLORUN_MANAGEMENT_KEY_FILE`.",
+        }),
+    };
+    return built;
 }
-/** The Admin API's document. */
-export function adminDocument() {
-    if (admin)
-        return admin;
-    // Only the routes' declarations are read: nothing is served from this app.
-    const api = createAdminApi({
-        status: () => Promise.reject(new Error("Not served")),
-        shutdown: () => { },
-    });
-    api.openAPIRegistry.registerComponent("securitySchemes", "adminKey", bearer("The Host's admin key (`host-credentials.json`). Never a Tenant bearer."));
-    admin = new OpenApiGeneratorV32(api.openAPIRegistry.definitions).generateDocument({
-        openapi: "3.2.0",
-        info: {
-            title: "Nylorun Runtime: Admin API",
-            version: RUNTIME_VERSION,
-            description: "The Host's status, its Tenant's state and shutdown, with the admin key. Served on the operator listener when the Host has one; the public listener answers these routes with the opaque 404.",
-            "x-nylorun-protocol": PROTOCOL,
-        },
-        servers: [
-            {
-                url: "{origin}",
-                description: "The operator listener: a local Tenant's, or where yours runs",
-                variables: { origin: { default: "http://localhost:8788" } },
-            },
-        ],
-    });
-    return admin;
+/** The Runtime API's document: `/openapi/runtime.json` and `/openapi.json`. */
+export function runtimeDocument() {
+    return documents().runtime;
+}
+/** The Management API's document: `/openapi/management.json`. */
+export function managementDocument() {
+    return documents().management;
 }

package/dist/artifacts/links.js

@@ -2,14 +2,14 @@
  * Capability links (protocol 6): a short-lived URL that opens one artifact version with no
  * other credential, for UIs, `<img>` tags and sharing. The token in the path is an ES256 JWT
  * (`typ: nylorun-artifact+jwt`) signed with the Tenant's current signing key by the keys
- * service, like subject and delivery tokens: `sub` is the artifact, `ver` the version, `aud`
- * `nylorun-artifact`, and it lives at most `ARTIFACT_LINK_MAX_TTL_SECONDS` (the subject-token
- * maximum, so a key rotation never revokes a live link). A link opens nothing once its artifact
+ * service, like run tokens: `sub` is the artifact, `ver` the version, `aud`
+ * `nylorun-artifact`, and it lives at most `ARTIFACT_LINK_MAX_TTL_SECONDS` (`TOKEN_TTL_MAX_SECONDS`,
+ * so a key rotation never revokes a live link). A link opens nothing once its artifact
  * is deleted. A folder's link (F8.2) opens its zip, or with a `path` claim one of its files.
  */
 import { randomUUID } from "node:crypto";
 import { errors, jwtVerify } from "jose";
-import { ARTIFACT_LINK_DEFAULT_TTL_SECONDS, ARTIFACT_LINK_MAX_TTL_SECONDS, ARTIFACT_LINK_TOKEN_TYPE, subjectTokenIssuer, } from "@nylorun/core/contracts";
+import { ARTIFACT_LINK_DEFAULT_TTL_SECONDS, ARTIFACT_LINK_MAX_TTL_SECONDS, ARTIFACT_LINK_TOKEN_TYPE, tenantTokenIssuer, } from "@nylorun/core/contracts";
 import { isArtifactId } from "@nylorun/core/compatibility";
 import { failOpaque, HttpError } from "../tenant/http.js";
 import { CLOCK_TOLERANCE_SECONDS, tokenKeyId } from "../tenant/jwt.js";
@@ -24,7 +24,7 @@ export async function mintArtifactLink(ctx, link) {
     const { token } = await ctx.keys.sign({
         typ: ARTIFACT_LINK_TOKEN_TYPE,
         claims: {
-            iss: subjectTokenIssuer(ctx.config.tenantId),
+            iss: tenantTokenIssuer(ctx.config.tenantId),
             aud: ARTIFACT_LINK_AUDIENCE,
             sub: link.artifactId,
             ver: link.version,
@@ -57,7 +57,7 @@ export async function verifyArtifactLink(ctx, raw) {
     try {
         const verified = await jwtVerify(raw, await ctx.signingKeys.publicKey(row), {
             algorithms: ["ES256"],
-            issuer: subjectTokenIssuer(ctx.config.tenantId),
+            issuer: tenantTokenIssuer(ctx.config.tenantId),
             audience: ARTIFACT_LINK_AUDIENCE,
             typ: ARTIFACT_LINK_TOKEN_TYPE,
             clockTolerance: CLOCK_TOLERANCE_SECONDS,

package/dist/artifacts/service.js

@@ -11,7 +11,7 @@
  *   module, after re-checking the Tenant total under the quota lock. Until it commits the object
  *   is garbage, and a failed commit deletes it.
  * - **Access mirrors sessions.** An application principal reaches every artifact. A request acting
- *   for a person (a subject token or subject headers) reaches only artifacts of that person's
+ *   for a person (a trusted issuer's token or subject headers) reaches only artifacts of that person's
  *   sessions; another person's, or a Tenant-wide one, is the same 404 as a missing artifact.
  *
  * Lock order, the same in every write: the session, then the quota lock, then the artifact row.

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

@@ -1,5 +1,5 @@
-import type { ActionOutcome } from "@nylorun/core/contracts";
-import type { JsonValue, WorkflowManifest } from "@nylorun/core/define";
+import type { EffectOutcome } from "@nylorun/core/contracts";
+import { type JsonValue, type WorkflowManifest } from "@nylorun/core/define";
 import type { HostEffect } from "@nylorun/harness/run";
 import type { Wake } from "../execution/types.js";
 import type { EffectDoc, Tx } from "../store/types.js";
@@ -20,6 +20,31 @@ export declare function isWorkflowManifest(manifest: unknown): manifest is Workf
 /** 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;
+/**
+ * What a flow `agent` effect sends its linked session (D12): the stage's input, and, when the
+ * engine sent the flow's own input beside it, that input first as the original request. Pure,
+ * so a replayed effect sends the same message.
+ */
+export declare function linkedMessageInput(body: {
+    readonly input: JsonValue;
+    readonly flowInput?: JsonValue;
+}): JsonValue;
+/**
+ * Settle a flow `agent` effect with its linked turn's outcome, in the caller's transaction,
+ * which holds the workflow session's lock. A verifier agent's verdict is recorded as
+ * `loop.verified`; an outcome that is not a verdict fails the Loop in the engine instead.
+ */
+export declare function settleAgentEffect(input: {
+    readonly t: Tx;
+    readonly effect: FlowEffect;
+    readonly outcome: EffectOutcome;
+}): Promise<void>;
+/**
+ * Record a Loop verifier's verdict as `loop.verified`: a verifier agent's output, or an HTTP
+ * verifier's answer (`role: "verify-http"`, a completed HTTP outcome). Anything that is not a
+ * verdict records nothing; the engine fails the Loop on it.
+ */
+export declare function recordVerdict(t: Tx, request: HostEffect, value: unknown): Promise<void>;
 export type FlowLink = {
     readonly workflowSessionId: string;
     readonly path: string;
@@ -60,30 +85,28 @@ export type FlowWait = {
     readonly path: string;
     readonly interactionId: string;
     readonly kind: string;
+    /** The interaction as asked (`prompt`, `metadata`), when the wait records it. */
+    readonly interaction?: unknown;
     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 deliveringActionIds: string[];
 };
 /** Wakes a session after commit (`DurableExecution.wake` through the Tenant context). */
 type Schedule = (sessionId: string, wake: Wake) => void | Promise<void>;
 /** Effect documents as the flow host writes them. */
 export type FlowEffect = EffectDoc & {
     agentSessionId?: string;
-    outcome?: ActionOutcome;
+    outcome?: EffectOutcome;
     error?: string;
 };
-/** Active agent turns + pending/delivering actions for one workflow turn. */
+/** Active agent turns + tool nodes in flight for one workflow turn. */
 export declare function countActiveFlowWork(t: Tx, workflowSessionId: string, turnId: string): Promise<number>;
 /** The `commands` document key of a session command's idempotency key (`tenant/commands.ts`). */
 export declare function commandKey(sessionId: string, idempotencyKey: string): string;
@@ -134,10 +157,7 @@ export declare function reconcilePendingAgentEffect(input: {
 }): Promise<boolean>;
 /** 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 delivering → uncertain actions (SD-P11 / WF-R53).
- */
+/** Plan a cancel cascade for a workflow session: linked agents deepest first (SD-P11 / WF-R53). */
 export declare function planCancelCascade(input: {
     readonly t: Tx;
     readonly workflowSessionId: string;
@@ -145,8 +165,7 @@ export declare function planCancelCascade(input: {
 }): Promise<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, delivering tool actions → uncertain.
+ * Agent turns listed in `agentSessionIds` are returned for the caller to cancel.
  * When `cancelEffectIds` is provided, those effects are marked cancelled and their
  * paths are included in the sibling path set.
  */
@@ -159,18 +178,12 @@ export declare function cancelSiblingWork(input: {
     /** Effect ids the flow engine marked for fail-fast cancel. */
     readonly cancelEffectIds?: readonly string[];
 }): Promise<CancelSiblingResult>;
-/**
- * Apply cancel fencing to workflow-session actions (pending→cancelled,
- * delivering→uncertain).
- */
-export declare function fenceWorkflowActions(input: {
+/** Cancel a cancelled workflow turn's queued effects, which never started. */
+export declare function cancelQueuedEffects(input: {
     readonly t: Tx;
     readonly workflowSessionId: string;
     readonly turnId: string | null;
-}): Promise<{
-    cancelled: string[];
-    uncertain: string[];
-}>;
+}): Promise<string[]>;
 /**
  * Aggregate human waits across the workflow session and linked agent sessions (WF-R51).
  */
@@ -178,6 +191,14 @@ export declare function aggregateWaits(input: {
     readonly t: Tx;
     readonly workflowSessionId: string;
 }): Promise<FlowWait[]>;
+/**
+ * The workflow-owned interaction `interactionId` among a workflow's `waits` (a tool node that
+ * asked), or undefined.
+ */
+export declare function flowInteractionOf(raw: unknown, workflowSessionId: string, interactionId: string): {
+    readonly id: string;
+    readonly kind: string;
+} | undefined;
 /**
  * Look up which session owns an interaction id. Used for 409 foreign approvals (WF-R52).
  */