@nylorun/runtime 0.23.0-beta → 0.25.0-beta

package/dist/tenant/commands.js

@@ -22,19 +22,32 @@ import { resolveMessageManifest } from "../core/turn-manifest.js";
 import { canonical } from "../store/canonical.js";
 import { lockedSession, } from "./context.js";
 import { fail } from "./http.js";
+import { settleToolRow } from "../harness-api/tool-journal.js";
 import { accessOf } from "./auth.js";
-import { checkSandboxTurn } from "./sandboxes.js";
-import { rebaseSessionState, turnManifestOf, variantStore } from "./session.js";
+import { checkEnvironmentTurn } from "./environments.js";
+import { turnManifestOf, variantStore } from "./session.js";
 import { slimModelEffects } from "./slim.js";
 import { resolveMessageParts } from "../artifacts/parts.js";
+import { currentModelInputs } from "../model/catalog.js";
+import { endTurn, resumeTurn, startTurn } from "./turn-timing.js";
 /** A command's identity for idempotency: everything but the request id. */
 const semantic = (value) => {
     const { requestId: _, ...body } = value;
     return canonical(body);
 };
-export async function command(ctx, id, input, scope) {
+export async function command(ctx, id, input, scope, 
+/**
+ * The W3C trace context the request carried (R7.4): a `message` records it on its
+ * `command.message`, and the turn joins the caller's trace. Not part of the command's identity.
+ */
+options = {}) {
     const { store } = ctx;
     const cascadeCancelIds = [];
+    // What the Tenant's model reads, for a message that names a file (protocol 12): read before
+    // the session's transaction. Undefined without a model in the vault: nothing is refused.
+    const inputs = input.type === "message" && "parts" in input && input.parts.some((part) => part.type === "file")
+        ? await currentModelInputs(ctx)
+        : undefined;
     const response = await store.tx(async (t) => {
         const s = await lockedSession(t, id, accessOf(scope));
         const command = input;
@@ -53,6 +66,8 @@ export async function command(ctx, id, input, scope) {
             return existing.response;
         }
         let event;
+        // A tool call the Tool Gate held, which this `approve` answers (R5 step 2).
+        let held;
         // The turn a `cancel` ended, if one was active.
         let cancelledTurnId = null;
         if (command.type === "cancel") {
@@ -73,15 +88,24 @@ export async function command(ctx, id, input, scope) {
                     turnId: cancelledTurnId,
                 });
             if (cancelledTurnId !== null)
-                for (const effect of await t.effectsForTurn(id, cancelledTurnId, ["invoking"])) {
+                for (const effect of await t.effectsForTurn(id, cancelledTurnId, ["invoking", "held"])) {
+                    // A tool call ends `cancelled` with its `tool.completed` (R5.1); it may have run.
+                    if (effect.request.kind === "tool") {
+                        await settleToolRow(t, s, effect, {
+                            kind: "failed",
+                            code: "tool.cancelled",
+                            message: "The turn was cancelled while this call ran; it may have run.",
+                        }, { cancelled: true });
+                        continue;
+                    }
                     effect.status = "uncertain";
                     effect.error =
                         "Turn cancelled before model outcome was durably recorded";
                     await t.put("effects", effect.request.effectId, effect);
                 }
-            event = await t.event(id, cancelledTurnId, "turn.cancelled", {
-                reason: command.reason,
-            });
+            // The cancelled turn's span (R7.1): its duration, agent and totals.
+            const ended = cancelledTurnId !== null ? await endTurn(t, s, cancelledTurnId) : {};
+            event = await t.event(id, cancelledTurnId, "turn.cancelled", { reason: command.reason, ...ended }, commandWriter(scope));
             await slimModelEffects(t, id, cancelledTurnId);
             // The process running the advance aborts it on this signal (control.ts), sent at commit.
             await t.signal({
@@ -110,21 +134,43 @@ export async function command(ctx, id, input, scope) {
             }
         }
         else {
+            // A session opened before protocol 11 (migration 0020) or 13 (migration 0024) keeps its
+            // history but takes no turn.
+            if (s.closedReason !== undefined)
+                fail(409, s.closedReason === "protocol_11"
+                    ? "This session was opened before protocol 11: open a new session that names an Environment."
+                    : "This session was opened before protocol 13, on a manifest the Runtime no longer runs: register the agent again (manifest 7) and open a new session.", { code: "session_closed" });
             if (command.type === "message") {
                 if (!["idle", "completed", "failed", "cancelled"].includes(s.status))
                     fail(409, "Session has active or unresolved work");
                 // Every turn start on a sandbox: it exists, the token's grants reach it, and no other
                 // session's turn holds it.
-                await checkSandboxTurn(t, s, scope, ctx);
+                await checkEnvironmentTurn(t, s, scope, ctx);
                 s.turnStartState = s.state;
                 // A new turn folds from the latest snapshot: a cancel or failure only reverts this turn.
                 if (s.history?.snapshot !== undefined)
                     s.history = { ...s.history, from: s.history.snapshot };
                 s.activeTurnId = randomUUID();
-                // File parts name artifacts the caller may read; each is pinned to a version now.
+                startTurn(s);
+                if (options.trace)
+                    s.turnTrace = options.trace;
+                else
+                    delete s.turnTrace;
+                // File parts name artifacts the caller may read; each is pinned to a version now. An
+                // agent's model must read each one (a workflow passes them on as data).
                 const parts = "parts" in command
-                    ? await resolveMessageParts(t, command.parts, id, accessOf(scope))
+                    ? await resolveMessageParts(t, command.parts, id, accessOf(scope), isWorkflowManifest(s.manifest) ? undefined : inputs)
                     : undefined;
+                if (parts && parts.refused.length > 0)
+                    fail(422, `The model does not read ${parts.refused
+                        .map((part) => `${part.name} (${part.reason})`)
+                        .join(", ")}.`, { code: "attachment_unsupported", details: { parts: parts.refused } });
+                // The files the session's messages named: `read_artifact` reads them again (protocol 12).
+                if (parts) {
+                    const named = parts.pinned.flatMap((part) => (part.type === "file" ? [part.artifactId] : []));
+                    if (named.length > 0)
+                        s.fileArtifacts = [...new Set([...(s.fileArtifacts ?? []), ...named])];
+                }
                 const data = "data" in command ? command.data : undefined;
                 if (isWorkflowManifest(s.manifest)) {
                     const input = "content" in command
@@ -151,7 +197,6 @@ export async function command(ctx, id, input, scope) {
                         fail(400, resolved.message);
                     }
                     else {
-                        rebaseSessionState(s, resolved.hash);
                         s.checkpoint = createDurableCheckpoint({
                             manifest: resolved.manifest,
                             sessionId: id,
@@ -169,6 +214,25 @@ export async function command(ctx, id, input, scope) {
                     }
                 }
             }
+            else if (command.type === "approve" &&
+                (held = await heldCall(t, s, command.interactionId)) !== undefined) {
+                // A tool call the Tool Gate held for approval (R5 step 2). Approved: the replay sends it
+                // again and the gate runs it. Denied: it fails to the model as `tool.denied`, unsent.
+                if (s.status !== "paused")
+                    fail(409, "Session is not awaiting a response");
+                if (command.approved) {
+                    held.status = "invoking";
+                    const by = principalOf(scope);
+                    held.approval = { approved: true, at: new Date().toISOString(), ...(by ? { by } : {}) };
+                    await t.put("effects", held.request.effectId, held);
+                }
+                else
+                    await settleToolRow(t, s, held, {
+                        kind: "failed",
+                        code: "tool.denied",
+                        message: "A person denied this call; it was not sent.",
+                    });
+            }
             else if (isWorkflowManifest(s.manifest)) {
                 // Approvals owned by linked agent sessions must be answered there (WF-R52).
                 const conflict = await foreignInteractionConflict({
@@ -221,10 +285,13 @@ export async function command(ctx, id, input, scope) {
                     segment: (s.checkpoint?.segment ?? 0) + 1,
                 });
             }
+            // A paused turn goes on: its wait for a person is not its running time (R7.1).
+            resumeTurn(s);
             s.status = "runnable";
             s.waits = undefined;
-            // A flow answers each interaction in the same segment: the interaction names the cause.
-            const cause = command.type !== "message" && isWorkflowManifest(s.manifest)
+            // A flow answers each interaction in the same segment, as a held tool call's approval is
+            // answered (R5 step 2): the interaction names the cause.
+            const cause = command.type !== "message" && (isWorkflowManifest(s.manifest) || held !== undefined)
                 ? command.interactionId
                 : s.checkpoint.segment;
             const commandWake = {
@@ -232,7 +299,7 @@ export async function command(ctx, id, input, scope) {
                 dedupeKey: `${command.type}:${s.activeTurnId}:${cause}`,
             };
             await t.wake(id, commandWake);
-            event = await t.event(id, s.activeTurnId, `command.${command.type}`, command);
+            event = await t.event(id, s.activeTurnId, `command.${command.type}`, command.type === "message" && options.trace ? { ...command, trace: options.trace } : command, commandWriter(scope));
         }
         await t.put("sessions", id, s);
         // Direct cancel of a linked agent fails that node with agent.cancelled (WF-R54). The agent
@@ -272,3 +339,37 @@ export async function command(ctx, id, input, scope) {
     }
     return response;
 }
+/** Core's own commands (R4.9): the flow host's, and a drain's cancels. */
+const CORE_PRINCIPALS = { "flow-host": "flow-host", drain: "core" };
+/**
+ * Who sent a command (R4.9), from its credential and never its body: a client over the Runtime
+ * API (an application, or a person through it or a token), or core itself.
+ */
+export function commandWriter(scope) {
+    if (scope.kind === "application" && CORE_PRINCIPALS[scope.principalId] !== undefined)
+        return {
+            source: { kind: "core", id: "runtime" },
+            principal: { kind: CORE_PRINCIPALS[scope.principalId], id: scope.principalId },
+        };
+    const principal = scope.kind === "subject" || scope.kind === "token"
+        ? { kind: "subject", id: scope.subject }
+        : { kind: "application", id: scope.kind === "anonymous" ? "anonymous" : scope.principalId };
+    return { source: { kind: "client", id: principal.id }, principal };
+}
+/** The held tool call of the session's active turn that `interactionId` names (R5 step 2). */
+async function heldCall(t, s, interactionId) {
+    const row = await t.get("effects", interactionId);
+    if (row?.status !== "held")
+        return undefined;
+    if (row.request.sessionId !== s.id || row.request.turnId !== s.activeTurnId)
+        return undefined;
+    return row;
+}
+/** Who answered: the principal (its subject, when it acts for one), or the token's subject. */
+function principalOf(scope) {
+    if (scope.kind === "token")
+        return `${scope.issuer}:${scope.subject}`;
+    if (scope.kind === "subject")
+        return `${scope.principalId}:${scope.subject}`;
+    return "principalId" in scope ? scope.principalId : undefined;
+}

package/dist/tenant/context.d.ts

@@ -18,7 +18,6 @@ import type { SessionHistory } from "./history.js";
 import type { IssuerScope, SubjectScope, TenantEnvelope } from "@nylorun/core/contracts";
 import type { DurableCheckpoint, FlowCheckpoint } from "@nylorun/harness/run";
 import type { AgentManifest, JsonValue, SandboxManifest } from "@nylorun/core/define";
-import type { CredentialSelection } from "@nylorun/core/contracts";
 import type { OutboxRequest, SessionStore, Tx } from "../store/types.js";
 import type { FlowLimits } from "../core/limits.js";
 import type { ModelProvider } from "../core/provider.js";
@@ -40,6 +39,8 @@ import type { SigningKeys } from "./signing-keys.js";
 import type { BlobStore } from "../blob/index.js";
 import type { WorkspaceReader } from "../artifacts/workspace.js";
 import type { RunGrants } from "./run-grants.js";
+import type { TraceOptions } from "../traces/options.js";
+import type { TraceContext } from "../traces/ids.js";
 export interface Session {
     id: string;
     agentId: string;
@@ -49,7 +50,7 @@ export interface Session {
     manifestHash: string;
     /**
      * The hash of the definition the session was opened from; `manifestHash` differs when the
-     * Runtime pinned its own capabilities beside it (R2b C11). Absent on older sessions.
+     * Runtime pinned its `runtime` block on it (R2b C11). Absent on older sessions.
      */
     definitionHash?: string;
     /** Validated turn-manifest variants, keyed by hash (loops.md §4.2). */
@@ -74,26 +75,55 @@ export interface Session {
      * turn it started (`linkedTurnEnd` in `core/flow-host.ts`).
      */
     lastTurnId?: string;
+    /** When the active turn started (R7.1, `turn-timing.ts`); absent on a turn started before. */
+    turnStartedAt?: string;
+    /** How long the active turn has waited paused for a person, in ms (R7.1). */
+    pausedMs?: number;
+    /** Since when the active turn waits paused (R7.1); absent while it runs. */
+    pausedAt?: string;
+    /**
+     * The trace context the active turn's message arrived with (R7.4): its trace is the caller's,
+     * and the context core hands on (to the harness, tools and sandbox commands) is in it.
+     */
+    turnTrace?: TraceContext;
     creation: unknown;
-    vaultIds?: readonly string[];
-    credentialSelections?: readonly CredentialSelection[];
     mcpSnapshot?: McpSnapshot;
     mcpDiagnostics?: readonly McpDiagnostic[];
-    /** Session id that keys the shared sandbox; absent means this session owns it. */
-    sandboxOwnerId?: string;
     /**
-     * The sandbox resource the session is attached to (`sandbox: { id }`): its workspace is the
-     * sandbox's, shared with every session attached to it, and it outlives the session.
+     * The Environment the session names (`environment`, protocol 11): its sandbox is the
+     * session's (the Environment's id keys the workspace) and its vault holds the session's
+     * credentials. It outlives the session.
+     */
+    environmentId?: string;
+    /** The Environment's recipe version when the session opened (shown, never enforced). */
+    environmentVersion?: number;
+    /**
+     * The harness that runs the session's turns (R4.1), pinned when it opened: its Environment's
+     * harness, else `nylorun`. Absent on a session opened before R4: ours (`harnessOf`).
      */
-    sandboxId?: string;
+    harness?: string;
     /**
-     * The sandbox chosen when the session was opened, resolved against the Tenant's limits, or
-     * inherited from the session it shares with. Absent when the session has no sandbox or its
-     * definition declares one (`.sandbox()`).
+     * A flow agent's linked session: the session whose turn opened the flow tree. Its sessions
+     * share the tree's Environment, and their turns nest in the root's, so they do not hold the
+     * Environment against each other (`checkEnvironmentTurn`).
+     */
+    flowRootId?: string;
+    /**
+     * The Environment's sandbox spec when the session opened (kinds `virtual` and `pod`).
+     * Absent without an Environment, or for kind `none`.
      */
     sandbox?: SandboxManifest;
-    /** Where `sandbox` came from: `sandbox` is a sandbox resource's spec. */
-    sandboxSource?: "default" | "inline" | "shared" | "sandbox";
+    /**
+     * Why the session takes no new turn: `protocol_11` for a session opened before protocol 11
+     * (migration 0020), `protocol_13` for one opened before protocol 13 (migration 0024). Its
+     * history stays readable.
+     */
+    closedReason?: string;
+    /**
+     * The artifacts the session's messages named (protocol 12): `read_artifact` reads these
+     * Tenant-wide ones beside the session's own. Absent until a message names a file.
+     */
+    fileArtifacts?: string[];
 }
 export type AuthScope = {
     kind: "application";
@@ -110,7 +140,7 @@ export type AuthScope = {
 }
 /**
  * A trusted issuer's token (Host feature `trusted-issuers`, F9-D12): one subject, with the
- * issuer's scopes, agents and sandbox grants, until `expiresAt` (ms). Only its expiry ends it.
+ * issuer's scopes, agents and Environment grants, until `expiresAt` (ms). Only its expiry ends it.
  */
  | {
     kind: "token";
@@ -120,8 +150,8 @@ export type AuthScope = {
     /** The issuer's scopes the token holds, which may add `studio`. */
     scopes: ReadonlySet<IssuerScope>;
     agents: ReadonlySet<string> | "*";
-    /** The sandboxes it reaches: exact ids or `p/*` prefixes. Absent or empty reaches none. */
-    sandboxes?: readonly string[];
+    /** The Environments it reaches: exact ids or `p/*` prefixes. Absent or empty reaches none. */
+    environments?: readonly string[];
     expiresAt: number;
     /** The token's `jti`, or a hash of it. */
     tokenId: string;
@@ -151,7 +181,7 @@ export interface TenantContext {
      */
     readonly mcp?: McpPool;
     /**
-     * The workspace capability (F6.2): the Tenant's SandboxManager with an in-process harness,
+     * The workspace feature (F6.2): the Tenant's SandboxManager with an in-process harness,
      * else the harness that serves workspaces (`harness-api/workspace.ts`).
      */
     readonly sandbox: WorkspacePort;
@@ -183,6 +213,11 @@ export interface TenantContext {
      * this process's `sandbox` today; over the Harness API's `workspace.read` from F6.2.
      */
     readonly workspaces: WorkspaceReader;
+    /**
+     * How the trace route (R7.5) makes spans: the resource and the content the installation exports
+     * (R7.2). Absent: `service.name` `nylorun`, no content.
+     */
+    readonly traces?: TraceOptions;
     /**
      * The run token of each session an advance of this process owns (F5): the credential the
      * HTTP gate clients present for that session's model and MCP calls (`run-grants.ts`).
@@ -232,7 +267,7 @@ export interface TenantContext {
     abortLocal(sessionId: string, turnId?: string): void;
     /**
      * Sandbox pods (F7.2): the sandboxes service and the Runtime image pods copy the engine from.
-     * Absent without a cluster (`nylorun sandbox enable`): kind `pod` is `sandbox_unavailable`.
+     * Absent without a cluster (`nylorun local sandbox enable`): kind `pod` is `environment_unavailable`.
      */
     readonly pods?: TenantPods;
     /**
@@ -275,14 +310,11 @@ export interface Lease {
 export declare function ownedSession(t: Tx, lease: Lease, id: string): Promise<Session>;
 /** The session read in its own transaction, or a 404. */
 export declare function loadSession(ctx: TenantContext, id: string, access?: SessionAccess): Promise<Session>;
-/**
- * A synchronous lookup over `start` and every session its `sandboxOwnerId` chain names, for
- * the sandbox-sharing helpers, which walk that chain synchronously.
- */
-export declare function sandboxLookup(t: Tx, start: string | undefined): Promise<(id: string) => Session | undefined>;
 /** The sandboxes service a Tenant drives its pod sandboxes with (`TenantContext.pods`). */
 export interface TenantPods {
     readonly client: SandboxesClient;
     /** The Runtime image the pods copy the engine from (`NYLORUN_SANDBOX_HARNESS_IMAGE`). */
     readonly harnessImage: string;
 }
+/** The harness a session runs (R4.1): the one it pinned, else ours. */
+export declare function harnessOf(session: Pick<Session, "harness">): string;

package/dist/tenant/context.js

@@ -1,3 +1,4 @@
+import { DEFAULT_HARNESS } from "@nylorun/core/contracts";
 import { fail } from "./http.js";
 /**
  * `access`, when set, limits the request to the owner's sessions of the allowed agents:
@@ -34,19 +35,7 @@ export async function ownedSession(t, lease, id) {
 export function loadSession(ctx, id, access) {
     return ctx.store.tx((t) => sessionOf(t, id, access));
 }
-/**
- * A synchronous lookup over `start` and every session its `sandboxOwnerId` chain names, for
- * the sandbox-sharing helpers, which walk that chain synchronously.
- */
-export async function sandboxLookup(t, start) {
-    const found = new Map();
-    let id = start;
-    while (id && !found.has(id)) {
-        const session = await t.get("sessions", id);
-        if (!session)
-            break;
-        found.set(id, session);
-        id = session.sandboxOwnerId;
-    }
-    return (sid) => found.get(sid);
+/** The harness a session runs (R4.1): the one it pinned, else ours. */
+export function harnessOf(session) {
+    return session.harness ?? DEFAULT_HARNESS;
 }

package/dist/tenant/effects.d.ts

@@ -42,6 +42,6 @@ export declare function recoversModelCalls(ctx: TenantContext): boolean;
 export declare function resolveNewFlowEffect(ctx: TenantContext, request: HostEffect, signal: AbortSignal, lease: Lease): Promise<EffectResolution>;
 /**
  * The credential of an MCP server or HTTP tool request made on behalf of a session: from its
- * attached vaults (`vault/sources.ts`).
+ * Environment's vault (`vault/sources.ts`).
  */
 export declare function authorize(ctx: TenantContext, sessionId: string, request: McpCredentialRequest): Promise<AuthorizeResult>;

package/dist/tenant/effects.js

@@ -4,9 +4,9 @@ import { mayDispatchMore } from "../core/limits.js";
 import { sessionCredentials } from "../vault/sources.js";
 import { isRemoteMcpCall } from "../harness/calls.js";
 import { isHttpToolCall } from "../gates/http-tool.js";
-import { owningSandboxSessionId, sandboxSpecOf, sessionSandboxSpec, } from "../sandbox/share.js";
-import { withPlatformTools, withSandboxCapability } from "../sandbox/session-sandbox.js";
-import { loadSession, ownedSession, sandboxLookup, sessionOf, } from "./context.js";
+import { sandboxSpecOf } from "../sandbox/share.js";
+import { withRuntimeTools, withSandbox } from "../sandbox/session-sandbox.js";
+import { loadSession, ownedSession, sessionOf, } from "./context.js";
 import { fail } from "./http.js";
 import { turnManifestOf } from "./session.js";
 import { command } from "./commands.js";
@@ -85,11 +85,14 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
             }
         }
         const active = await countActiveFlowWork(t, request.sessionId, request.turnId);
+        // When the run journaled the effect (R7.1); a queued effect keeps it once dispatched.
+        const startedAt = existing?.startedAt ?? new Date().toISOString();
         if (!mayDispatchMore(active, ctx.flowLimits)) {
             if (!existing || existing.status !== "queued")
                 await t.put("effects", request.effectId, {
                     request,
                     status: "queued",
+                    startedAt,
                 });
             return resolved({ status: "pending" });
         }
@@ -101,19 +104,32 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
                 value: {
                     kind: "failed",
                     code: "tool.unavailable",
-                    message: `The tool stage '${request.key ?? request.path ?? ""}' runs your code, and the Runtime runs no code of yours during a session`,
+                    message: `The tool stage '${request.key ?? request.path ?? ""}' runs your code, but the Runtime runs agents from their manifests alone`,
                 },
             };
-            await t.put("effects", request.effectId, { request, status: "completed", outcome });
-            await t.event(workflow.id, workflow.activeTurnId, "node.started", {
+            await t.put("effects", request.effectId, {
+                request,
+                status: "completed",
+                outcome,
+                startedAt,
+                settledAt: startedAt,
+            });
+            const node = {
                 path: request.path,
                 kind: "tool",
                 key: request.key,
                 ...(request.iterations !== undefined ? { iterations: request.iterations } : {}),
+            };
+            await t.event(workflow.id, workflow.activeTurnId, "node.started", node);
+            // Nothing ran (R7.1): the stage's outcome row says so.
+            await t.event(workflow.id, workflow.activeTurnId, "node.completed", {
+                ...node,
+                effectId: request.effectId,
+                status: "failed",
             });
             return resolved({ status: "completed", outcome });
         }
-        return { kind: "agent", workflow };
+        return { kind: "agent", workflow, startedAt };
     });
     if (step.kind === "resolved")
         return step.resolution;
@@ -130,6 +146,7 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
             request,
             status: "pending",
             agentSessionId,
+            startedAt: step.startedAt,
         });
         await t.put("links", agentSessionId, {
             workflowSessionId: workflow.id,
@@ -145,14 +162,10 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
         if (exists)
             return;
         const definition = leafDefinition(workflow, body, request);
-        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);
-        // Without one, an agent with MCP or HTTP tools still reads its stored results (R2b C11).
-        const pinned = inherited?.manifest ? inherited : platformTools(definition.manifest);
+        // The tree's Environment reaches every agent in it: its sandbox, with its tools, and its vault.
+        const inherited = inheritedSandbox(workflow, definition);
+        // Without one, the agent still gets its runtime block: read_artifact (R2b C11) and its skill tools.
+        const pinned = inherited?.manifest ? inherited : runtimeTools(definition.manifest);
         const created = {
             id: agentSessionId,
             agentId: body.agentId,
@@ -167,14 +180,18 @@ export async function resolveNewFlowEffect(ctx, request, signal, lease) {
                 requestId: `flow-put-${request.effectId}`,
                 agentId: body.agentId,
                 ownerUserId: workflow.ownerUserId,
-                ...(sandboxOwnerId ? { sandbox: { session: sandboxOwnerId } } : {}),
+                ...(workflow.environmentId === undefined ? {} : { environment: workflow.environmentId }),
             },
-            vaultIds: workflow.vaultIds,
-            credentialSelections: workflow.credentialSelections,
-            ...(sandboxOwnerId ? { sandboxOwnerId } : {}),
-            ...(inherited
-                ? { sandbox: inherited.spec, sandboxSource: "shared" }
-                : {}),
+            flowRootId: workflow.flowRootId ?? workflow.id,
+            ...(workflow.environmentId === undefined
+                ? {}
+                : {
+                    environmentId: workflow.environmentId,
+                    ...(workflow.environmentVersion === undefined
+                        ? {}
+                        : { environmentVersion: workflow.environmentVersion }),
+                }),
+            ...(inherited ? { sandbox: inherited.spec } : {}),
         };
         await t.put("sessions", agentSessionId, created);
     });
@@ -240,25 +257,23 @@ function inheritedSandbox(owner, definition) {
         return undefined;
     if (isWorkflowManifest(definition.manifest))
         return { spec };
-    const sandboxed = withSandboxCapability(definition.manifest, spec);
+    const sandboxed = withSandbox(definition.manifest, spec);
     if (!sandboxed.ok)
         throw new Error(sandboxed.message);
     return { spec, manifest: sandboxed.manifest, manifestHash: sandboxed.manifestHash };
 }
-/** A linked agent session's `read_artifact` without a sandbox (R2b C11); undefined for none. */
-function platformTools(manifest) {
+/** A linked agent session's `runtime` block without a sandbox (R2b C11); undefined for a workflow. */
+function runtimeTools(manifest) {
     if (isWorkflowManifest(manifest))
         return undefined;
-    const pinned = withPlatformTools(manifest);
-    if (pinned === undefined)
-        return undefined;
+    const pinned = withRuntimeTools(manifest);
     if (!pinned.ok)
         throw new Error(pinned.message);
     return { manifest: pinned.manifest, manifestHash: pinned.manifestHash };
 }
 /**
  * The credential of an MCP server or HTTP tool request made on behalf of a session: from its
- * attached vaults (`vault/sources.ts`).
+ * Environment's vault (`vault/sources.ts`).
  */
 export async function authorize(ctx, sessionId, request) {
     const s = await loadSession(ctx, sessionId);

package/dist/tenant/environment-manifests.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Environment manifests (protocol 14, D63): `/v1/environment-manifests/{name}`, named and
+ * versioned definitions of a kind of Environment, saved like agents.
+ *
+ * - **Versions.** A save whose manifest hashes the same as the latest answers it unchanged;
+ *   any other writes the next version. A version is never changed or deleted alone.
+ * - **No Environment changes.** Saving a version reaches no Environment: an Environment is made
+ *   from one version and keeps it for life (`putEnvironment`). The plan counts those behind.
+ * - **Plan and drift.** `?dryRun=true` answers what a save would do and saves nothing: the
+ *   changes from the latest, every reason the Runtime would refuse it (the Tenant's limits,
+ *   missing artifacts), warnings, and how many Environments stay on older versions.
+ *   `If-Match: <version>` refuses (`412 manifest_changed`) a save whose latest version moved
+ *   since the client read it; `0` asks for a manifest that does not exist yet.
+ * - **Every client is equal** (Q12): a version records who saved it (`savedBy`), and nothing is
+ *   read-only by where it was saved from.
+ */
+import { type EnvironmentManifest, type EnvironmentManifestPlan, type EnvironmentManifestVersions, type EnvironmentManifestView, type PutEnvironmentManifestRequest, type SaveEnvironmentManifestResponse } from "@nylorun/core/contracts";
+import { type RecipeRequest } from "../sandbox/resolve.js";
+import type { AuthScope, TenantContext } from "./context.js";
+/** What an environment manifest asks of an Environment's recipe. */
+export declare function manifestRecipeRequest(manifest: EnvironmentManifest): RecipeRequest;
+/** The hash a manifest's version records: equal manifests hash the same. */
+export declare function environmentManifestHash(manifest: EnvironmentManifest): string;
+/** Each field that differs between `before` and `after`, by path; arrays compare whole. */
+export declare function manifestChanges(before: unknown, after: unknown, path?: string): {
+    path: string;
+    from?: unknown;
+    to?: unknown;
+}[];
+/**
+ * `PUT /v1/environment-manifests/{name}`: saves `body` as manifest `name`'s next version, or
+ * answers the latest unchanged; with `dryRun`, the plan of that save and nothing saved.
+ */
+export declare function saveEnvironmentManifest(ctx: TenantContext, name: string, body: PutEnvironmentManifestRequest, scope: AuthScope, options: {
+    dryRun: true;
+    ifMatch?: number;
+}): Promise<EnvironmentManifestPlan>;
+export declare function saveEnvironmentManifest(ctx: TenantContext, name: string, body: PutEnvironmentManifestRequest, scope: AuthScope, options?: {
+    dryRun?: false;
+    ifMatch?: number;
+}): Promise<SaveEnvironmentManifestResponse>;
+/** `GET /v1/environment-manifests/{name}` (the latest) and `.../versions/{n}`. */
+export declare function getEnvironmentManifest(ctx: TenantContext, name: string, version?: number): Promise<EnvironmentManifestView>;
+/** `GET /v1/environment-manifests`: each manifest's latest version. */
+export declare function listEnvironmentManifests(ctx: TenantContext): Promise<{
+    manifests: EnvironmentManifestView[];
+}>;
+/** `GET /v1/environment-manifests/{name}/versions`: every version, newest first. */
+export declare function environmentManifestVersions(ctx: TenantContext, name: string): Promise<EnvironmentManifestVersions>;
+/**
+ * `DELETE /v1/environment-manifests/{name}`: deletes every version, refused while any Environment
+ * was made from one (`409 manifest_in_use`): the Environment names the version it runs.
+ */
+export declare function deleteEnvironmentManifest(ctx: TenantContext, name: string): Promise<{
+    name: string;
+    deleted: boolean;
+}>;