@nylorun/runtime 0.23.0-beta → 0.24.0-beta

package/dist/tenant/advance.js

@@ -40,10 +40,13 @@
  * already recorded; an `ownership.lost` leaves the session to the advance that owns it.
  */
 import { runDurable, runFlowDurable, } from "@nylorun/harness/run";
+import { redactTokens } from "../harness-api/redact.js";
 import { aggregateWaits, cancelSiblingWork, isWorkflowManifest, wakeLinkedWorkflow, } from "../core/flow-host.js";
 import { isOwnershipLost, ownedTx } from "../store/ownership.js";
 import { endAdvance } from "./scheduler.js";
-import { isGateToolEffect, recoversModelCalls, recoversToolCalls } from "./effects.js";
+import { harnessOf } from "./context.js";
+import { HARNESS_ID } from "../sandbox/placement.js";
+import { recoversModelCalls } from "./effects.js";
 import { slimModelEffects } from "./slim.js";
 import { applyUpdates, leanState, transcriptShadow, withTranscript, } from "./history.js";
 import { command } from "./commands.js";
@@ -51,7 +54,8 @@ import { exportOutputs } from "../artifacts/export.js";
 import { dropRunGrant, grantRun } from "./run-grants.js";
 import { startHeartbeat } from "../harness-api/renew.js";
 import { buildTurnStart, startSegment } from "../harness-api/start.js";
-import { touchPodSandbox } from "./sandboxes.js";
+import { touchEnvironment } from "./environments.js";
+import { endTurn, pauseTurn } from "./turn-timing.js";
 import { AdvanceAbort, AdvanceDeadlineError, abortKind, } from "./worker.js";
 /**
  * A segment stopped by a `shutdown` or `ownership.lost` abort before it settled. Never
@@ -179,28 +183,27 @@ export async function advance(ctx, id, signal) {
                 sessionId: id,
                 message: error instanceof Error ? error.message : String(error),
             }));
-        // A pod sandbox's idle time counts from the end of each segment (D34).
-        if (placed.pod !== undefined)
-            await touchPodSandbox(ctx, placed.pod);
+        // The Environment was used: `deleteAfter`, and a pod's idle time (D34), count from the end
+        // of each segment.
+        if (placed.environment !== undefined)
+            await touchEnvironment(ctx, placed.environment);
     }
     return result;
 }
-/** Why a pod sandbox cannot run a segment, or undefined when it can. */
+/** Why a pod Environment cannot run a segment, or undefined when it can. */
 function podUnusable(ctx, segment) {
     const pod = segment.pod;
     if (!pod)
         return undefined;
     if (!ctx.pods)
-        return `Sandbox ${pod.id} is a pod sandbox, and this Runtime has no sandbox pods`;
+        return `Environment ${pod.id} is a pod Environment, and this Runtime has no sandbox pods`;
     const state = pod.pod;
     if (state.desired === "deleted")
-        return `Sandbox ${pod.id} was deleted`;
+        return `Environment ${pod.id} was deleted`;
     if (state.observed === "lost")
-        return `Sandbox ${pod.id} was lost: ${state.reason ?? "its volume is gone"}`;
-    if (state.observed === "expired")
-        return `Sandbox ${pod.id} expired`;
+        return `Environment ${pod.id} was lost: ${state.reason ?? "its volume is gone"}`;
     if (state.observed === "failed")
-        return `Sandbox ${pod.id} failed to start: ${state.reason ?? "its pod was not ready"}`;
+        return `Environment ${pod.id} failed to start: ${state.reason ?? "its pod was not ready"}`;
     return undefined;
 }
 /**
@@ -229,7 +232,6 @@ async function takeOwnership(ctx, id) {
         if (taken.takeover)
             await takeOver(t, s, {
                 recoversModelCalls: recoversModelCalls(ctx),
-                recoversToolCalls: recoversToolCalls(ctx),
             });
         if (!s.checkpoint || !["running", "runnable"].includes(s.status)) {
             await t.releaseOwnership(id, lease.owner, lease.epoch);
@@ -243,10 +245,12 @@ async function takeOwnership(ctx, id) {
 /**
  * Takeover (§10.5 step 2, §11.4), inside the transaction that took ownership: the dead
  * owner's `invoking` effects become `uncertain` and are never invoked again, except model
- * calls when the gate recovers them (P1.2) and remote MCP and HTTP tool calls when the Tool
- * Gate does (F4.1 G3): those stay `invoking`, and the replay re-sends them. When one belongs
- * to the active turn, the session becomes `uncertain` too, with an `effect.uncertain` event.
- * Mutates and writes `s`. Returns the effect ids it marked.
+ * calls when the gate recovers them (P1.2) and every tool call (R5.3): those stay `invoking`,
+ * and the replay decides. It re-sends a model call, and an MCP or HTTP tool call with the same
+ * key; a sandbox or core-served tool call fails to the model as `tool.interrupted`
+ * (`harness-api/tool-journal.ts`). When an effect marked `uncertain` belongs to the active
+ * turn, the session becomes `uncertain` too, with an `effect.uncertain` event. Mutates and
+ * writes `s`. Returns the effect ids it marked.
  */
 export async function takeOver(t, s, options = {}) {
     const marked = [];
@@ -254,7 +258,7 @@ export async function takeOver(t, s, options = {}) {
         // Still running at the gate, or finished there: the replay re-sends it (P1.2).
         if (options.recoversModelCalls && effect.request.kind === "model")
             continue;
-        if (options.recoversToolCalls && isGateToolEffect(s, effect.request))
+        if (effect.request.kind === "tool")
             continue;
         effect.status = "uncertain";
         effect.error ??= "The Worker running this effect stopped before its outcome was recorded";
@@ -279,13 +283,16 @@ async function runRemoteSegment(ctx, lease, started, controller, run, onTaken, p
     let end;
     try {
         const segment = await startSegment(ctx, lease, { harness: true });
-        // A pod sandbox's segment runs in its pod (F7.2), or fails when the pod cannot run it.
+        // A pod Environment's segment runs in its pod (F7.2), or fails when the pod cannot run it.
         const unusable = podUnusable(ctx, segment);
         if (unusable)
             throw new Error(unusable);
+        // A new volume being seeded from a disk version takes no turn until it holds it (R2d step 3).
+        if (segment.pod?.seeding)
+            throw new HarnessUnavailable();
         const pod = segment.pod?.id;
-        if (pod !== undefined)
-            placed.pod = pod;
+        if (started.environmentId !== undefined)
+            placed.environment = started.environmentId;
         end = await ctx.harness.offer({
             lease,
             start: buildTurnStart(ctx, segment),
@@ -293,6 +300,8 @@ async function runRemoteSegment(ctx, lease, started, controller, run, onTaken, p
             transcript: segment.transcript,
             run,
             onTaken,
+            // Only a connection of the session's harness takes its runs (R4.1).
+            harness: harnessOf(segment.current),
             ...(pod === undefined ? {} : { pod, waitMs: POD_OFFER_WAIT_MS }),
         });
         if (end.kind === "unavailable") {
@@ -310,7 +319,8 @@ async function runRemoteSegment(ctx, lease, started, controller, run, onTaken, p
         stopIfLeaving(signal);
         if (end.kind === "released")
             throw new SegmentStopped(end.reason === "ownership.lost" ? "ownership.lost" : "shutdown");
-        const { output } = end;
+        // A harness's output never carries the Runtime's own tokens into the record (R4).
+        const output = redactTokens(end.output);
         if (output.thrown)
             throw thrownError(output.thrown);
         const result = resultOf(output, segment);
@@ -320,7 +330,9 @@ async function runRemoteSegment(ctx, lease, started, controller, run, onTaken, p
             await settleFailure(ctx, lease, started, signal.reason);
         else {
             const recorded = result.status === "yielded" || result.status === "completed" || result.status === "paused";
-            cursor = await settleTurn(ctx, lease, started, result, recorded ? output.transcript ?? [] : [], signal, segment.cursor);
+            cursor = await settleTurn(ctx, lease, started, result, recorded ? output.transcript ?? [] : [], signal, segment.cursor, 
+            // The turn's end and its transcript are what the harness reported (R4.9).
+            { source: { kind: "harness", id: harnessOf(started) }, evidence: "claimed", runId: output.runId });
         }
         end.reply(cursor === undefined ? {} : { cursor });
     }
@@ -361,7 +373,8 @@ function resultOf(output, segment) {
             effectIds: output.effectIds ?? [],
         };
     let state = output.state;
-    if (state !== undefined && transcriptShadow())
+    // Our engine's transcript shadow (tests); another harness's state is stored as sent (R4.2).
+    if (state !== undefined && transcriptShadow() && ours(current))
         state = withTranscript(state, applyUpdates(segment.transcript, output.transcript ?? []));
     const checkpoint = state === undefined || isWorkflowManifest(current.manifest)
         ? current.checkpoint
@@ -408,8 +421,8 @@ async function wakeWorkflowOf(ctx, t, agent, turnId, type, payload) {
  * the turn has committed and while the advance still holds the lease. The harness hears back
  * after the export. The export never throws.
  */
-async function settleTurn(ctx, lease, s, result, updates, signal, cursor) {
-    const kept = await settle(ctx, lease, s, result, updates, cursor);
+async function settleTurn(ctx, lease, s, result, updates, signal, cursor, writer) {
+    const kept = await settle(ctx, lease, s, result, updates, cursor, writer);
     if (result.status === "completed")
         await exportOutputs(ctx, lease.sessionId, s.activeTurnId, signal);
     return kept;
@@ -419,7 +432,9 @@ async function settleTurn(ctx, lease, s, result, updates, signal, cursor) {
  * cursor of the transcript it recorded (`cursor` when it recorded no edit), or undefined when
  * the transcript was not kept.
  */
-async function settle(ctx, lease, s, result, updates = [], cursor) {
+async function settle(ctx, lease, s, result, updates = [], cursor, 
+/** Who reported the result (R4.9): the run's harness. */
+writer) {
     const id = lease.sessionId;
     let kept;
     const siblingCancelIds = await ownedTx(ctx.store, id, lease.epoch, async (t, current) => {
@@ -430,11 +445,24 @@ async function settle(ctx, lease, s, result, updates = [], cursor) {
         // A result can arrive during concurrent action persistence. Preserve the runnable marker.
         const resumeRequested = current.status === "runnable";
         if (result.status === "waiting" || result.status === "uncertain") {
+            // Tool calls the Tool Gate held for approval (R5 step 2): the turn pauses for a person.
+            const held = resumeRequested ? [] : await heldCalls(t, result.effectIds);
+            if (held.length > 0) {
+                current.status = "paused";
+                pauseTurn(current);
+                current.waits = held;
+                const payload = { interactions: held };
+                await t.event(id, s.activeTurnId, "turn.paused", payload);
+                await t.put("sessions", id, current);
+                await wakeWorkflowOf(ctx, t, current, s.activeTurnId, "turn.paused", payload);
+                return siblings;
+            }
             const linkedWaits = isWorkflowManifest(current.manifest)
                 ? await aggregateWaits({ t, workflowSessionId: id })
                 : [];
             if (linkedWaits.length > 0 && !resumeRequested) {
                 current.status = "paused";
+                pauseTurn(current);
                 current.waits = linkedWaits;
             }
             else {
@@ -456,8 +484,8 @@ async function settle(ctx, lease, s, result, updates = [], cursor) {
         if (result.status === "yielded") {
             // The turn goes on in a new segment: same turn, next checkpoint, woken right away.
             const finished = result.checkpoint;
-            kept = (await recordTranscript(t, id, s.activeTurnId, current, updates)) ?? cursor;
-            current.state = leanState(result.result.state);
+            kept = (await recordTranscript(t, id, s.activeTurnId, current, updates, writer)) ?? cursor;
+            current.state = leanOf(current, result.result.state);
             current.checkpoint = {
                 ...finished,
                 segment: finished.segment + 1,
@@ -478,16 +506,16 @@ async function settle(ctx, lease, s, result, updates = [], cursor) {
         const flow = isWorkflowManifest(current.manifest);
         if (!flow) {
             if (result.status !== "failed") {
-                const last = await recordTranscript(t, id, s.activeTurnId, current, updates);
+                const last = await recordTranscript(t, id, s.activeTurnId, current, updates, writer);
                 if (result.status !== "cancelled")
                     kept = last ?? cursor;
             }
             current.state =
                 result.status === "failed"
                     ? current.turnStartState
-                    : leanState(result.result.state);
+                    : leanOf(current, result.result.state);
         }
-        current.checkpoint = leanCheckpoint(result.checkpoint);
+        current.checkpoint = leanCheckpoint(current, result.checkpoint);
         current.status = result.status;
         current.waits =
             result.status === "paused" ? result.result.pending : undefined;
@@ -508,7 +536,11 @@ async function settle(ctx, lease, s, result, updates = [], cursor) {
             });
             siblings.push(...cancelResult.agentSessionIds);
         }
-        if (result.status !== "paused") {
+        // The turn's span (R7.1): a pause starts its wait; an end, its duration and totals.
+        const ended = result.status === "paused" ? undefined : await endTurn(t, current, s.activeTurnId);
+        if (result.status === "paused")
+            pauseTurn(current);
+        else {
             current.activeTurnId = null;
             if (s.activeTurnId)
                 current.lastTurnId = s.activeTurnId;
@@ -516,7 +548,7 @@ async function settle(ctx, lease, s, result, updates = [], cursor) {
         }
         const type = `turn.${result.status}`;
         const payload = result.status === "completed"
-            ? { output: result.result.output }
+            ? { output: result.result.output, ...ended }
             : result.status === "paused"
                 ? {
                     interactions: (result.result.pending ?? []).map((call) => ({
@@ -539,9 +571,10 @@ async function settle(ctx, lease, s, result, updates = [], cursor) {
                                 ? { path: result.result.error.path }
                                 : {}),
                         },
+                        ...ended,
                     }
-                    : {};
-        await t.event(id, s.activeTurnId, type, payload);
+                    : { ...ended };
+        await t.event(id, s.activeTurnId, type, payload, writer);
         await t.put("sessions", id, current);
         await wakeWorkflowOf(ctx, t, current, s.activeTurnId, type, payload);
         return siblings;
@@ -564,6 +597,37 @@ async function settle(ctx, lease, s, result, updates = [], cursor) {
     }
     return kept;
 }
+/**
+ * The approvals a waiting segment's held tool calls ask for (R5 step 2), as `turn.paused`
+ * interactions: each one's id is the call's effect id, which `approve` answers.
+ */
+async function heldCalls(t, effectIds) {
+    const held = [];
+    for (const effectId of effectIds) {
+        const row = await t.get("effects", effectId);
+        if (row?.status !== "held")
+            continue;
+        const request = row.request;
+        const context = (request.context ?? {});
+        const toolName = request.toolName ?? request.key ?? effectId;
+        const reason = row.hold?.reason ?? "The Tenant's tool policy asks a person about this call";
+        held.push({
+            invocationId: typeof context.invocationId === "string" ? context.invocationId : effectId,
+            ...(typeof context.callId === "string" ? { callId: context.callId } : {}),
+            interaction: {
+                id: effectId,
+                kind: "approval",
+                prompt: `Approve ${toolName}?`,
+                reason,
+                ...(row.server === undefined ? {} : { server: row.server }),
+                input: request.input ?? null,
+            },
+            status: "interaction",
+            toolName,
+        });
+    }
+    return held;
+}
 /** A segment threw: fail the turn, restore the turn-start state, wake a linked workflow. */
 async function settleFailure(ctx, lease, s, error) {
     const id = lease.sessionId;
@@ -574,7 +638,7 @@ async function settleFailure(ctx, lease, s, error) {
         current.status = "failed";
         current.state = current.turnStartState;
         current.error = error instanceof Error ? error.message : String(error);
-        const payload = { message: current.error };
+        const payload = { message: current.error, ...(await endTurn(t, current, current.activeTurnId)) };
         await t.event(id, current.activeTurnId, "turn.failed", payload);
         await slimModelEffects(t, id, current.activeTurnId);
         if (current.activeTurnId)
@@ -584,21 +648,30 @@ async function settleFailure(ctx, lease, s, error) {
         await wakeWorkflowOf(ctx, t, current, s.activeTurnId, "turn.failed", payload);
     });
 }
-/** `checkpoint` with its engine state stored lean (`history.ts`). */
-function leanCheckpoint(checkpoint) {
+/** Whether the session runs our harness, whose state core may store lean (R4.2). */
+const ours = (session) => harnessOf(session) === HARNESS_ID;
+/**
+ * `state` as the session row stores it: our engine's without its transcript (`history.ts`);
+ * another harness's as it sent it, never read (R4.2).
+ */
+function leanOf(session, state) {
+    return ours(session) ? leanState(state) : state;
+}
+/** `checkpoint` with its engine state stored lean (`leanOf`). */
+function leanCheckpoint(session, checkpoint) {
     const state = checkpoint?.state;
     if (!checkpoint || !state)
         return checkpoint;
-    return { ...checkpoint, state: leanState(state) };
+    return { ...checkpoint, state: leanOf(session, state) };
 }
 /**
  * Appends a segment's transcript edits; a snapshot moves `history.snapshot`. Returns the seq of
  * the last edit, if any.
  */
-async function recordTranscript(t, id, turnId, s, updates) {
+async function recordTranscript(t, id, turnId, s, updates, writer) {
     let last;
     for (const update of updates) {
-        const event = await t.event(id, turnId, "transcript.updated", update);
+        const event = await t.event(id, turnId, "transcript.updated", update, writer);
         if (update.keep === 0)
             s.history = { from: s.history?.from ?? event.seq, snapshot: event.seq };
         last = event.seq;

package/dist/tenant/artifact-tool.js

@@ -27,7 +27,7 @@ import { uploadArtifact } from "../artifacts/service.js";
 import { DEFAULT_CONTENT_TYPE } from "../blob/index.js";
 import { sandboxCapabilityOf } from "../sandbox/manager.js";
 import { sandboxWorkspaceOf } from "../sandbox/share.js";
-import { sandboxLookup, sessionOf } from "./context.js";
+import { sessionOf } from "./context.js";
 import { HttpError } from "./http.js";
 import { manifestFor } from "./session.js";
 import { jsonBytes, utf8Boundary } from "./tool-results.js";
@@ -47,13 +47,12 @@ export async function callSaveArtifact(ctx, request, signal) {
     const artifactId = typeof input.artifactId === "string" ? input.artifactId : undefined;
     const { s, workspace, limits, ours } = await ctx.store.tx(async (t) => {
         const s = await sessionOf(t, request.sessionId);
-        const lookup = await sandboxLookup(t, s.id);
         // A new version only of an artifact of this session.
         const ours = artifactId === undefined ||
             (isArtifactId(artifactId) && (await t.artifact(artifactId))?.sessionId === s.id);
         return {
             s,
-            workspace: sandboxWorkspaceOf(s, lookup),
+            workspace: sandboxWorkspaceOf(s),
             limits: await readArtifactLimits(t),
             ours,
         };
@@ -70,7 +69,7 @@ export async function callSaveArtifact(ctx, request, signal) {
             id: workspace.ownerId,
             activeTurnId: s.activeTurnId,
             manifest: s.manifest,
-            ...(workspace.sandboxId === undefined ? {} : { sandboxId: workspace.sandboxId }),
+            ...(workspace.environmentId === undefined ? {} : { environmentId: workspace.environmentId }),
         }, capability, path, limits.fileBytes, signal);
         if (read.kind === "failed")
             return read;

package/dist/tenant/commands.d.ts

@@ -1,3 +1,16 @@
-import type { SessionCommand } from "@nylorun/core/contracts";
+import type { EventWriter, SessionCommand } from "@nylorun/core/contracts";
 import { type AuthScope, type TenantContext } from "./context.js";
-export declare function command(ctx: TenantContext, id: string, input: SessionCommand, scope: AuthScope): Promise<unknown>;
+import type { TraceContext } from "../traces/ids.js";
+export declare function command(ctx: TenantContext, id: string, input: SessionCommand, scope: AuthScope, 
+/**
+ * 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?: {
+    trace?: TraceContext;
+}): Promise<unknown>;
+/**
+ * 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 declare function commandWriter(scope: AuthScope): EventWriter;

package/dist/tenant/commands.js

@@ -22,17 +22,24 @@ 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 { 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 = [];
     const response = await store.tx(async (t) => {
@@ -53,6 +60,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 +82,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,17 +128,25 @@ export async function command(ctx, id, input, scope) {
             }
         }
         else {
+            // A session opened before protocol 11 (migration 0020) keeps its history but takes no turn.
+            if (s.closedReason !== undefined)
+                fail(409, "This session was opened before protocol 11: open a new session that names an Environment.", { 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();
+                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.
                 const parts = "parts" in command
                     ? await resolveMessageParts(t, command.parts, id, accessOf(scope))
@@ -151,7 +177,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 +194,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 +265,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 +279,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 +319,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;
+}