@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/tenant/effects.js

@@ -3,34 +3,50 @@ import { countActiveFlowWork, deriveAgentEffectSessionId, isFlowEffect, isFlowTo
 import { mayDispatchMore } from "../core/limits.js";
 import { canonical } from "../store/canonical.js";
 import { isOwnershipLost } from "../store/ownership.js";
-import { newStreamIncarnation } from "../streams/types.js";
-import { piModel } from "../model/pi-model.js";
 import { scrub } from "../redact.js";
-import { serversOf } from "../mcp/pool.js";
+import { findServer, serversOf } from "../mcp/pool.js";
 import { sandboxCapabilityOf } from "../sandbox/manager.js";
-import { owningSandboxSessionId, sandboxSpecOf } from "../sandbox/share.js";
+import { owningSandboxSessionId, sandboxSpecOf, sessionSandboxSpec, } from "../sandbox/share.js";
+import { withSandboxCapability } from "../sandbox/session-sandbox.js";
 import { loadSession, ownedSession, sandboxLookup, sessionOf, } from "./context.js";
 import { fail } from "./http.js";
 import { actionTarget, linkedAgentOutput, manifestFor, mcpToolOf, pinnedTool, turnManifestOf, } from "./session.js";
 import { command } from "./commands.js";
-import { assistantMessage, toolCompleted, toolIds } from "./transcript.js";
+import { offerAction } from "./delivery.js";
+import { assistantMessage, contextCompacted, modelFailed, toolCompleted, toolIds, } from "./transcript.js";
+import { classifyThrown } from "../model/classify.js";
 import { abortKind } from "./worker.js";
-export function invokeModel(ctx, request, signal, model) {
-    if (model)
-        return model(request, signal);
-    if (!ctx.useVaultModel)
-        return ctx.modelProvider(request, signal);
-    const adapter = piModel({
-        root: ctx.config.paths.home,
-        readHostModel: () => ctx.vault.readHostModel(),
-        writeHostCredential: (credential) => ctx.vault.updateHostCredential(credential),
-    });
-    return adapter(request.input, {
-        request: request.context.request,
-        invocationId: String(request.context.invocationId),
-        signal,
-        reportPreparedCall() { },
-    });
+/**
+ * Call the model for one effect. A provider failure comes back as a failure outcome
+ * (Model Calls §6), whichever provider serves the call; only an abort throws, and the
+ * advance decides what the abort means.
+ */
+export async function invokeModel(ctx, request, signal, model) {
+    try {
+        if (model)
+            return await model(request, signal);
+        if (!ctx.useVaultModel)
+            return await ctx.modelProvider(request, signal);
+        return await ctx.modelGate.call({
+            tenantId: ctx.config.tenantId,
+            sessionId: request.sessionId,
+            turnId: request.turnId,
+            agentId: request.agentId,
+            effectId: request.effectId,
+            invocationId: String(request.context.invocationId),
+            call: request.input,
+        }, signal);
+    }
+    catch (error) {
+        if (signal.aborted) {
+            // A call that outlives this process stops only when told to: on a user cancel. After a
+            // shutdown or a lost lease the next owner re-sends it and picks up its outcome (P1.2).
+            if (!model && ctx.useVaultModel && abortKind(signal) === "cancel" && ctx.modelGate.cancel)
+                await ctx.modelGate.cancel({ tenantId: ctx.config.tenantId, effectId: request.effectId });
+            throw error;
+        }
+        return classifyThrown(error);
+    }
 }
 /**
  * The outcome of a flow `agent` effect once the linked turn it started ended, or undefined
@@ -53,6 +69,32 @@ async function linkedOutcome(t, effect, agent) {
         },
     };
 }
+/**
+ * True when this Tenant's remote MCP calls outlive the process that sent them (the gates
+ * service, F4.1 G3): after a takeover or a shutdown, the journaled call is re-sent and joins
+ * the running call or gets its answer, instead of becoming `uncertain`.
+ */
+export function recoversMcpCalls(ctx) {
+    return ctx.toolGate.recovers === true;
+}
+/** True when `request` calls a tool of a remote (`streamable-http` or `sse`) MCP server. */
+export function isRemoteMcpEffect(s, request) {
+    if (request.kind !== "tool")
+        return false;
+    const tool = mcpToolOf(s, request);
+    if (!tool)
+        return false;
+    const declared = findServer(s.manifest, tool.agentId, tool.capabilityId, tool.serverName);
+    return declared !== undefined && declared.server.type !== "stdio";
+}
+/**
+ * True when this Tenant's vault-backed model calls outlive the process that sent them (the
+ * gates service, P1.2): after a takeover or a shutdown, the journaled call is re-sent and joins
+ * the running call or gets its outcome, instead of becoming `uncertain`.
+ */
+export function recoversModelCalls(ctx) {
+    return ctx.useVaultModel && ctx.modelGate.recovers === true;
+}
 /**
  * What an effect's journal row must match on replay. A delegation's context carries only the
  * parent's tool call id, for its events; rows journaled before it existed still match.
@@ -85,6 +127,22 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
                 throw new Error("Effect identity request drift");
             if (existing.status === "completed")
                 return resolved({ status: "completed", outcome: existing.outcome });
+            // A model call its previous owner left running at the gate: re-send it, same key and
+            // request, to join it or collect its outcome.
+            if (existing.status === "invoking" &&
+                request.kind === "model" &&
+                recoversModelCalls(ctx))
+                return { kind: "invoke", invoke: "model", journaled: existing.request };
+            // A remote MCP call its previous owner left running at the gate: the same, by effect id.
+            if (existing.status === "invoking" &&
+                recoversMcpCalls(ctx) &&
+                isRemoteMcpEffect(s, existing.request))
+                return {
+                    kind: "invoke",
+                    invoke: "mcp",
+                    journaled: existing.request,
+                    remote: true,
+                };
             if (request.kind === "agent" && existing.status === "pending") {
                 const agentSessionId = existing.agentSessionId;
                 if (agentSessionId) {
@@ -144,6 +202,7 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
             return {
                 kind: "invoke",
                 invoke: mcpTool ? "mcp" : sandboxTool ? "sandbox" : "model",
+                ...(mcpTool && isRemoteMcpEffect(s, request) ? { remote: true } : {}),
             };
         const tool = request.kind === "tool"
             ? pinnedTool(agentManifest, request.capabilityId, request.toolName)
@@ -159,8 +218,6 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
             context: request.context,
             status: "pending",
             generation: 0,
-            claimId: null,
-            leaseExpiresAt: null,
             ...(request.agent ? { agent: request.agent } : {}),
         };
         const action = request.kind === "hook"
@@ -189,7 +246,7 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
             ...(action.kind === "tool" ? toolIds(request.context) : {}),
             input: action.input,
         });
-        t.signalWork();
+        await offerAction(t, ctx, action);
         return resolved({ status: "pending" });
     });
     if (journaled.kind === "resolved")
@@ -203,10 +260,10 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
     try {
         // The intent is committed; the call itself runs outside any transaction.
         const value = invoke === "mcp"
-            ? await callMcpTool(ctx, request)
+            ? await callMcpTool(ctx, journaled.journaled ?? request, abortOn(signal, journaled.remote && recoversMcpCalls(ctx) ? ["cancel", "shutdown"] : ["cancel"]))
             : invoke === "sandbox"
                 ? await callSandboxTool(ctx, request, signal)
-                : await invokeModel(ctx, request, signal, segment.model);
+                : await invokeModel(ctx, journaled.journaled ?? request, signal, segment.model);
         return await store.tx(async (t) => {
             const s = await ownedSession(t, lease, request.sessionId);
             // Only a cancel discards an outcome in hand (§10.7). After any other abort (shutdown,
@@ -219,11 +276,23 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
             effect.status = "completed";
             effect.outcome = { value };
             await t.put("effects", request.effectId, effect);
-            const transcript = invoke === "model"
-                ? assistantMessage(request, value)
-                : toolCompleted(request, value);
-            if (transcript)
-                await t.event(s.id, request.turnId, invoke === "model" ? "message.assistant" : "tool.completed", transcript);
+            const failed = invoke === "model" ? modelFailed(request, value) : undefined;
+            // A summary call is never an assistant message; the last one publishes context.compacted.
+            const summarizing = invoke === "model" && Boolean(request.context.compaction);
+            const compacted = summarizing && !failed ? contextCompacted(request, value) : undefined;
+            const transcript = failed || summarizing
+                ? undefined
+                : invoke === "model"
+                    ? assistantMessage(request, value)
+                    : toolCompleted(request, value);
+            if (failed)
+                await t.event(s.id, request.turnId, "model.failed", failed);
+            if (compacted)
+                await t.event(s.id, request.turnId, "context.compacted", compacted);
+            if (transcript && invoke === "model")
+                await t.event(s.id, request.turnId, "message.assistant", transcript);
+            else if (transcript)
+                await t.event(s.id, request.turnId, "tool.completed", transcript);
             return { status: "completed", outcome: effect.outcome };
         });
     }
@@ -231,6 +300,18 @@ export async function resolveEffect(ctx, request, signal, lease, segment = {}) {
         // A lost epoch writes nothing: the new owner decides what the effect became.
         if (isOwnershipLost(error))
             throw error;
+        // A shutdown leaves a model call running at the gate, still `invoking`: the next advance
+        // re-sends it (P1.2). The segment stops for the shutdown as usual.
+        if (invoke === "model" && recoversModelCalls(ctx) && abortKind(signal) === "shutdown")
+            throw error;
+        // The same for a remote MCP call at the Tool Gate (G3). A user cancel stops it there: a
+        // keyed call outlives the request that sent it.
+        if (invoke === "mcp" && journaled.remote && recoversMcpCalls(ctx)) {
+            if (abortKind(signal) === "shutdown")
+                throw error;
+            if (abortKind(signal) === "cancel" && ctx.toolGate.cancel)
+                await ctx.toolGate.cancel({ tenantId: ctx.config.tenantId, effectId: request.effectId });
+        }
         await store.tx(async (t) => {
             const s = request.sessionId === lease.sessionId
                 ? await t.assertEpoch(request.sessionId, lease.epoch)
@@ -312,8 +393,6 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
                     context: request.context,
                     status: "pending",
                     generation: 0,
-                    claimId: null,
-                    leaseExpiresAt: null,
                     kind: request.kind,
                     path: request.path,
                     key: request.key,
@@ -329,8 +408,6 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
                     context: request.context,
                     status: "pending",
                     generation: 0,
-                    claimId: null,
-                    leaseExpiresAt: null,
                     kind: "tool",
                     path: request.path,
                     key: request.key,
@@ -353,7 +430,7 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
                 key: action.key,
                 input: action.input,
             });
-            t.signalWork();
+            await offerAction(t, ctx, action);
             return resolved({ status: "pending" });
         }
         return { kind: "agent", workflow };
@@ -388,15 +465,18 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
         if (exists)
             return;
         const definition = await leafDefinition(t, workflow, body, request);
-        const sandboxOwnerId = sandboxSpecOf(workflow.manifest) || workflow.sandboxOwnerId
-            ? owningSandboxSessionId(workflow, await sandboxLookup(t, workflow.sandboxOwnerId))
+        const lookup = await sandboxLookup(t, workflow.sandboxOwnerId);
+        const sandboxOwnerId = sessionSandboxSpec(workflow) || workflow.sandboxOwnerId
+            ? owningSandboxSessionId(workflow, lookup)
             : undefined;
+        // A sandbox chosen when the tree was opened reaches every agent in it, with its tools.
+        const inherited = inheritedSandbox(sandboxOwnerId === undefined ? undefined : lookup(sandboxOwnerId) ?? workflow, definition);
         const created = {
             id: agentSessionId,
             agentId: body.agentId,
             ownerUserId: workflow.ownerUserId,
-            manifest: definition.manifest,
-            manifestHash: definition.manifestHash,
+            manifest: inherited?.manifest ?? definition.manifest,
+            manifestHash: inherited?.manifestHash ?? definition.manifestHash,
             implementationVersion: definition.implementationVersion,
             status: "idle",
             activeTurnId: null,
@@ -410,7 +490,9 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
             credentialSelections: workflow.credentialSelections,
             pluginRoots: definition.pluginRoots ?? {},
             ...(sandboxOwnerId ? { sandboxOwnerId } : {}),
-            streamIncarnation: newStreamIncarnation(),
+            ...(inherited
+                ? { sandbox: inherited.spec, sandboxSource: "shared" }
+                : {}),
         };
         await t.put("sessions", agentSessionId, created);
     });
@@ -518,7 +600,25 @@ export async function prepareMcp(ctx, lease, signal) {
         await t.put("sessions", id, current);
     });
 }
-async function callMcpTool(ctx, request) {
+/**
+ * A signal that follows `signal` only for the abort kinds in `kinds`. An MCP call stops on a
+ * cancel; at the Tool Gate it also stops waiting on a shutdown, since the gate keeps the call
+ * for the next owner. Otherwise a shutdown or a deadline lets the call finish and records it,
+ * so the next advance replays it.
+ */
+function abortOn(signal, kinds) {
+    const controller = new AbortController();
+    const follow = () => {
+        if (kinds.includes(abortKind(signal)))
+            controller.abort(signal.reason);
+    };
+    if (signal.aborted)
+        follow();
+    else
+        signal.addEventListener("abort", follow, { once: true });
+    return controller.signal;
+}
+async function callMcpTool(ctx, request, signal) {
     const s = await loadSession(ctx, request.sessionId);
     const tool = mcpToolOf(s, request);
     if (!tool)
@@ -532,8 +632,25 @@ async function callMcpTool(ctx, request) {
         args: request.input,
         manifest: s.manifest,
         pluginRoots: s.pluginRoots ?? {},
+        effectId: request.effectId,
+        signal,
     });
 }
+/**
+ * The sandbox a linked session inherits from its tree's owner when that sandbox was chosen at
+ * open (pinned on the owner). A definition that declares its own sandbox keeps it, as before.
+ */
+function inheritedSandbox(owner, definition) {
+    const spec = owner?.sandbox;
+    if (!spec || sandboxSpecOf(definition.manifest))
+        return undefined;
+    if (isWorkflowManifest(definition.manifest))
+        return { spec };
+    const sandboxed = withSandboxCapability(definition.manifest, spec);
+    if (!sandboxed.ok)
+        throw new Error(sandboxed.message);
+    return { spec, manifest: sandboxed.manifest, manifestHash: sandboxed.manifestHash };
+}
 async function callSandboxTool(ctx, request, signal) {
     const { s, ownerId } = await ctx.store.tx(async (t) => {
         const s = await sessionOf(t, request.sessionId);

package/dist/tenant/endpoints.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Action endpoints (design: Action endpoints §4.2): where the Runtime delivers each agent's
+ * Actions, registered with the application key.
+ */
+import { type Endpoint, type PutEndpointsRequest } from "@nylorun/core/contracts";
+import type { EndpointRow } from "../store/types.js";
+import type { TenantContext } from "./context.js";
+/** An endpoint as the Tenant API answers it. */
+export declare function endpointView(row: EndpointRow): Endpoint;
+/** `GET /v1/endpoints`. */
+export declare function listEndpoints(ctx: TenantContext): Promise<{
+    endpoints: {
+        agentId: string;
+        url: string;
+        implementationVersion: string;
+        manifestHash?: string | undefined;
+        timeoutMs: number;
+        maxConcurrent: number;
+        health: {
+            lastDeliveryAt?: string | undefined;
+            lastSuccessAt?: string | undefined;
+            lastError?: {
+                code: string;
+                message: string;
+            } | undefined;
+            consecutiveFailures: number;
+            served?: {
+                implementationVersion: string;
+                manifestHash?: string | undefined;
+            } | undefined;
+        };
+        updatedAt: string;
+    }[];
+}>;
+/**
+ * `PUT /v1/endpoints`: upsert the batch in one transaction, then send the Actions already
+ * waiting for these agents. Answers every registered endpoint of the batch.
+ */
+export declare function putEndpoints(ctx: TenantContext, principalId: string, body: PutEndpointsRequest): Promise<{
+    endpoints: {
+        agentId: string;
+        url: string;
+        implementationVersion: string;
+        manifestHash?: string | undefined;
+        timeoutMs: number;
+        maxConcurrent: number;
+        health: {
+            lastDeliveryAt?: string | undefined;
+            lastSuccessAt?: string | undefined;
+            lastError?: {
+                code: string;
+                message: string;
+            } | undefined;
+            consecutiveFailures: number;
+            served?: {
+                implementationVersion: string;
+                manifestHash?: string | undefined;
+            } | undefined;
+        };
+        updatedAt: string;
+    }[];
+}>;
+/** `DELETE /v1/endpoints/:agentId`. The agent's pending Actions wait for a new endpoint. */
+export declare function deleteEndpoint(ctx: TenantContext, agentId: string): Promise<{
+    agentId: string;
+    deleted: true;
+}>;

package/dist/tenant/endpoints.js

@@ -0,0 +1,90 @@
+/**
+ * Action endpoints (design: Action endpoints §4.2): where the Runtime delivers each agent's
+ * Actions, registered with the application key.
+ */
+import { ENDPOINT_MAX_CONCURRENT_DEFAULT, ENDPOINT_TIMEOUT_DEFAULT_MS, } from "@nylorun/core/contracts";
+import { fail } from "./http.js";
+/** An endpoint as the Tenant API answers it. */
+export function endpointView(row) {
+    const served = row.servedImplementationVersion === undefined
+        ? undefined
+        : {
+            implementationVersion: row.servedImplementationVersion,
+            ...(row.servedManifestHash === undefined
+                ? {}
+                : { manifestHash: row.servedManifestHash }),
+        };
+    return {
+        agentId: row.agentId,
+        url: row.url,
+        implementationVersion: row.implementationVersion,
+        ...(row.manifestHash === undefined ? {} : { manifestHash: row.manifestHash }),
+        timeoutMs: row.timeoutMs,
+        maxConcurrent: row.maxConcurrent,
+        health: {
+            ...(row.lastDeliveryAt === undefined ? {} : { lastDeliveryAt: row.lastDeliveryAt }),
+            ...(row.lastSuccessAt === undefined ? {} : { lastSuccessAt: row.lastSuccessAt }),
+            ...(row.lastErrorCode === undefined
+                ? {}
+                : {
+                    lastError: {
+                        code: row.lastErrorCode,
+                        message: row.lastErrorMessage ?? "",
+                    },
+                }),
+            consecutiveFailures: row.consecutiveFailures,
+            ...(served ? { served } : {}),
+        },
+        updatedAt: row.updatedAt,
+    };
+}
+/** `GET /v1/endpoints`. */
+export async function listEndpoints(ctx) {
+    const rows = await ctx.store.tx((t) => t.listEndpoints());
+    return { endpoints: rows.map(endpointView) };
+}
+/**
+ * `PUT /v1/endpoints`: upsert the batch in one transaction, then send the Actions already
+ * waiting for these agents. Answers every registered endpoint of the batch.
+ */
+export async function putEndpoints(ctx, principalId, body) {
+    const updatedAt = new Date().toISOString();
+    const rows = await ctx.store.tx(async (t) => {
+        const saved = [];
+        for (const endpoint of body.endpoints) {
+            await t.putEndpoint({
+                agentId: endpoint.agentId,
+                url: endpoint.url,
+                implementationVersion: endpoint.implementationVersion,
+                ...(endpoint.manifestHash === undefined
+                    ? {}
+                    : { manifestHash: endpoint.manifestHash }),
+                timeoutMs: endpoint.timeoutMs ?? ENDPOINT_TIMEOUT_DEFAULT_MS,
+                maxConcurrent: endpoint.maxConcurrent ?? ENDPOINT_MAX_CONCURRENT_DEFAULT,
+                principalId,
+                updatedAt,
+            });
+            saved.push((await t.getEndpoint(endpoint.agentId)));
+        }
+        return saved;
+    });
+    // Actions already waiting for these agents go to their endpoint now.
+    const waiting = await ctx.store.tx(async (t) => {
+        const actions = [];
+        for (const endpoint of body.endpoints)
+            actions.push(...(await t.pendingActions(endpoint.agentId)));
+        return actions;
+    });
+    for (const action of waiting)
+        await ctx.deliver(action.actionId);
+    return { endpoints: rows.map(endpointView) };
+}
+/** `DELETE /v1/endpoints/:agentId`. The agent's pending Actions wait for a new endpoint. */
+export async function deleteEndpoint(ctx, agentId) {
+    await ctx.store.tx(async (t) => {
+        if (!(await t.getEndpoint(agentId)))
+            fail(404, "Endpoint not found");
+        await t.deleteEndpoint(agentId);
+    });
+    return { agentId, deleted: true };
+}

package/dist/tenant/ephemeral.d.ts

@@ -1,17 +1,23 @@
-import type { PostgresClient } from "../store/postgres/connect.js";
+import { type PostgresClient } from "../store/postgres/connect.js";
 import type { Logger, TenantModelConfig } from "./types.js";
 export interface StartEphemeralRuntimeOptions {
     /**
-     * Absolute Host root for `host.json`, the admin key and each Tenant's files (vault key,
+     * Absolute Host root for `host.json`, the admin key and the Tenant's files (vault key,
      * home, sandboxes). Caller creates any temporary directory. Session data never lands here.
      */
     hostRoot: string;
+    /** The Tenant's id when the database holds no Tenant yet. Default: a new id. */
     tenantId?: string;
+    /** The Tenant's name when the database holds no Tenant yet. Default `ephemeral`. */
     name?: string;
+    /** An application key for an application principal of the Tenant. Default: a new key. */
     applicationKey?: string;
     adminKey?: string;
     principalId?: string;
-    /** SHA-256 of a derived Studio key; registers principal `studio`. */
+    /**
+     * SHA-256 of the Studio key; registers principal `studio` with it. Default: the key the
+     * admin key derives (`deriveStudioToken` in `@nylorun/admin`).
+     */
     studioCredentialHash?: string;
     /** Allowlisted baseline for childEnv (e.g. PATH). Never read from ambient here. */
     baseline?: Readonly<Record<string, string>>;
@@ -19,15 +25,23 @@ export interface StartEphemeralRuntimeOptions {
     sandboxBackend?: "auto" | "virtual";
     /** When true, close() leaves hostRoot on disk. */
     retainRoot?: boolean;
+    /** Allow browser requests (an `Origin` with a publishable key). Default off. */
+    browserAccess?: boolean;
+    /** Serve the Admin API on its own loopback listener (`adminUrl`). Default off. */
+    operatorListener?: boolean;
     logger?: Logger;
     /**
-     * A Postgres pool: Tenants become schemas in it (`store-pg.ts`) instead of living in memory.
-     * The caller ends the pool; the schemas stay.
+     * The Postgres database of the Tenant (one Tenant per database): a pool, which the caller
+     * ends, or a URL, for which the Runtime opens a pool and ends it on `close()`. A database
+     * that already holds a Tenant serves that one. The data stays after `close()`; a test drops
+     * its database.
      */
-    database?: PostgresClient;
+    database: PostgresClient | string;
 }
 export interface EphemeralRuntime {
     url: string;
+    /** Where the Admin API answers: `url`, or the operator listener when requested. */
+    adminUrl: string;
     tenantId: string;
     applicationKey: string;
     adminKey: string;
@@ -36,7 +50,8 @@ export interface EphemeralRuntime {
     close(): Promise<void>;
 }
 /**
- * Private Host on port 0 with one Tenant (D9 / A19). Not durable (see the module comment).
+ * Private Host on port 0 serving one Tenant (D9 / A19). Durable only in its database (see the
+ * module comment).
  * Exported from `@nylorun/runtime` and `@nylorun/runtime/core`.
  */
 export declare function startEphemeralRuntime(options: StartEphemeralRuntimeOptions): Promise<EphemeralRuntime>;