@nylorun/runtime 0.22.0-beta → 0.24.0-beta

package/dist/adapters/execution/restate.js

@@ -25,37 +25,28 @@
  *   What a run answers arms its timers and its retry.
  *
  * Wakes, sandbox reconciles, timers and sweep arming go through the ingress as one-way
- * sends, so an API node can call them without ever calling `start`. A wake a commit asked for
- * comes from the Session Store's wake outbox (`Tx.wake`) with an idempotency key, so a send
- * repeated after its answer was lost causes no second advance.
+ * sends (`@restatedev/restate-sdk-clients`), so an API node can call them without ever
+ * calling `start`. Every send carries an idempotency key, which the client's retries need: a
+ * wake's dedupe key (the outbox gives every committed wake one), a reconcile's outbox key, a
+ * timer's `<key>@<at>`, a sandbox timer's `<timer>@<at>`, or one made for the call. A send
+ * repeated after its answer was lost therefore starts no second invocation.
  *
- * ## What Restate owns, and what the Session Store owns
- *
- * Restate owns when a session runs: it delivers each wake at least once, deduped by its
- * key for `dedupeRetentionMs`; runs at most one invocation per key at a time; retries an
- * invocation whose attempt failed, so an advance whose Worker died runs again and takes the
- * session over (§11.4); and keeps every timer: the busy re-wake, `NylorunTimer`,
- * `NylorunSandbox` and the `NylorunTenant` sweep chain. The Session Store (Postgres) owns
- * what happened: the checkpoint, the effect journal (`harness-api/record.ts`), the events
- * (the Record), and the wake outbox that hands each committed wake to Restate. Restate
- * journals no effect: an effect's intent and outcome commit with the session's events in
- * one transaction, under the advance's lease, and remote harnesses and pod engines write
- * them too, over the Harness API.
- *
- * Two Session Store mechanisms overlap Restate on purpose:
- *
- * - **The lease and its epoch** (§10.6). Restate's one invocation per key holds for an
- *   attempt, not for the code it started: an attempt that ends (abort timeout, a dropped
- *   connection) is retried while the previous attempt's handler may still run on its Worker,
- *   and a remote harness or pod engine may still hold the run. The epoch fences their writes,
- *   and `busy` answers the overlap.
- * - **The advance deadline** (`tenant/worker.ts`). Restate's abort timeout does not stop a
- *   running handler, so the Worker bounds each advance itself, below `timeouts`.
+ * What Restate owns and what the Session Store owns, and where the two overlap on purpose,
+ * is said once, under "Durable Session Execution" in `src/CONTEXT.md`.
  */
+import { randomUUID } from "node:crypto";
 import { createServer } from "node:http2";
 import * as restate from "@restatedev/restate-sdk";
+import * as clients from "@restatedev/restate-sdk-clients";
+import { retry } from "../../retry.js";
 import { DEFAULT_STOP_GRACE_MS, WAKE_REASONS, parseSessionKey, sessionKey, settleWithin, } from "../../execution/types.js";
 const HOUR_MS = 60 * 60 * 1000;
+/**
+ * How long one send through the ingress keeps retrying while the ingress is unreachable,
+ * overloaded, or answers 404 because a just-registered service has not reached it yet. The
+ * outbox's grace (`OUTBOX_GRACE_MS` in `tenant/sweep.ts`) is longer.
+ */
+export const SEND_RETRY_MS = 10_000;
 export function createRestateExecution(options) {
     return new RestateExecution(options);
 }
@@ -69,6 +60,7 @@ export class RestateExecution {
     inflight = new Set();
     names;
     ingressUrl;
+    ingress;
     adminUrl;
     sweepIntervalMs;
     constructor(options) {
@@ -83,6 +75,18 @@ export class RestateExecution {
             sandbox: `${prefix}NylorunSandbox`,
         };
         this.ingressUrl = options.ingressUrl.replace(/\/+$/, "");
+        this.ingress = clients.connect({
+            url: this.ingressUrl,
+            retry: {
+                maxAttempts: false,
+                maxDuration: SEND_RETRY_MS,
+                initialInterval: 100,
+                maxInterval: 2000,
+                // A just-registered service can take a moment to reach the ingress.
+                shouldRetry: (failure) => clients.defaultShouldRetry(failure) ||
+                    (failure.kind === "response" && failure.status === 404),
+            },
+        });
         this.adminUrl = options.adminUrl.replace(/\/+$/, "");
         this.sweepIntervalMs = options.sweepIntervalMs ?? 5000;
     }
@@ -93,28 +97,27 @@ export class RestateExecution {
     async wake(tenantId, sessionId, wake) {
         if (!WAKE_REASONS.includes(wake.reason))
             throw new Error(`Unknown wake reason: ${String(wake.reason)}`);
-        await this.send(this.names.session, sessionKey(tenantId, sessionId), "advance", { reason: wake.reason }, wake.dedupeKey);
+        await this.send(this.names.session, sessionKey(tenantId, sessionId), "advance", { reason: wake.reason }, wake.dedupeKey ?? randomUUID());
     }
     async sandbox(tenantId, sandboxId, signal) {
         const key = sessionKey(tenantId, sandboxId);
         if (signal.kind === "reconcile")
-            await this.send(this.names.sandbox, key, "reconcile", {});
+            await this.send(this.names.sandbox, key, "reconcile", {}, signal.key ?? randomUUID());
         else
-            await this.send(this.names.sandbox, key, "arm", {
-                timer: signal.timer,
-                at: signal.at,
-            });
+            await this.send(this.names.sandbox, key, "arm", { timer: signal.timer, at: signal.at }, 
+            // Arming a timer for the same time again changes nothing.
+            `${signal.timer}@${signal.at}`);
     }
     async timer(tenantId, key, at) {
-        await this.send(this.names.timer, sessionKey(tenantId, key), "set", {
-            at: at.getTime(),
-        });
+        const ms = at.getTime();
+        await this.send(this.names.timer, sessionKey(tenantId, key), "set", { at: ms }, `${key}@${ms}`);
     }
     async armSweep(tenantId) {
-        await this.send(this.names.tenant, tenantKey(tenantId), "arm", {});
+        // A key of its own: a later arm (a Host opening the Tenant again) must still run.
+        await this.send(this.names.tenant, tenantKey(tenantId), "arm", {}, randomUUID());
     }
     async disarmSweep(tenantId) {
-        await this.send(this.names.tenant, tenantKey(tenantId), "disarm", {});
+        await this.send(this.names.tenant, tenantKey(tenantId), "disarm", {}, randomUUID());
     }
     /**
      * Readiness: the admin API (`/health`), which `start` registers with, and the
@@ -311,7 +314,7 @@ export class RestateExecution {
                     if ((await ctx.get(`at:${input.timer}`)) !== input.at)
                         return;
                     ctx.clear(`at:${input.timer}`);
-                    await runSandbox(ctx, input.timer === "retry" ? "reconcile" : input.timer);
+                    await runSandbox(ctx, input.timer === "idle" ? "idle" : "reconcile");
                 },
             },
             options: serviceOptions,
@@ -366,51 +369,62 @@ export class RestateExecution {
             },
         };
     }
-    /** One-way send through the ingress. Retries while the ingress is unreachable or overloaded. */
+    /**
+     * One-way send through the ingress (`@restatedev/restate-sdk-clients`). Every send carries
+     * an idempotency key, so the client's retries (`SEND_RETRY_MS`), and a send repeated after
+     * its answer was lost, start one invocation: the request's own key where it has one (an
+     * outbox row's, a timer's time), or one made for this call.
+     */
     async send(service, key, handler, body, idempotencyKey) {
-        const url = `${this.ingressUrl}/${service}/${encodeURIComponent(key)}/${handler}/send`;
-        const headers = { "content-type": "application/json" };
-        if (idempotencyKey !== undefined)
-            headers["idempotency-key"] = idempotencyKey;
-        await withRetry(`Restate send to ${service}/${handler}`, 10_000, async () => {
-            const response = await fetch(url, {
-                method: "POST",
-                headers,
-                body: JSON.stringify(body),
-                signal: AbortSignal.timeout(10_000),
+        try {
+            await this.ingress.send({
+                service,
+                handler,
+                key,
+                parameter: body,
+                opts: clients.SendOpts.from({ idempotencyKey, timeout: 10_000 }),
             });
-            if (response.ok) {
-                await response.body?.cancel();
-                return;
-            }
-            const text = await response.text().catch(() => "");
-            const error = new Error(`Restate ingress ${response.status} for ${service}/${handler}: ${text}`);
-            // A just-registered service can take a moment to reach the ingress.
-            throw response.status >= 500 || response.status === 404 || response.status === 429
-                ? error
-                : new PermanentError(error.message);
-        });
+        }
+        catch (error) {
+            const message = error instanceof clients.HttpCallError
+                ? `Restate ingress ${error.status}: ${error.responseText}`
+                : error instanceof Error
+                    ? error.message
+                    : String(error);
+            throw new Error(`Restate send to ${service}/${handler} failed: ${message}`, { cause: error });
+        }
     }
     /** Registers the Worker endpoint with the admin API, retrying until Restate is up. */
     async register(uri) {
         const force = this.options.forceRegistration ?? true;
-        await withRetry("Restate deployment registration", this.options.registrationTimeoutMs ?? 60_000, async () => {
+        const registered = await retry(async () => {
             const response = await fetch(`${this.adminUrl}/deployments`, {
                 method: "POST",
                 headers: { "content-type": "application/json" },
                 body: JSON.stringify({ uri, force }),
                 signal: AbortSignal.timeout(30_000),
             });
-            if (response.ok) {
-                await response.body?.cancel();
-                return;
-            }
+            if (response.ok)
+                return (await response.json().catch(() => ({})))
+                    .services;
             const text = await response.text().catch(() => "");
             const message = `Restate admin ${response.status} registering ${uri}: ${text}`;
             // Discovery failures (Restate cannot reach the endpoint yet) come back
             // as 4xx/5xx; keep trying until the deadline.
             throw new Error(message);
+        }, { minMs: 100, maxMs: 2000, deadlineMs: this.options.registrationTimeoutMs ?? 60_000 }).catch((error) => {
+            throw new Error(`Restate deployment registration failed: ${error.message}`, {
+                cause: error,
+            });
         });
+        // Without `force`, Restate answers a URL already registered with the deployment it has
+        // there, without discovering the endpoint again: one with other services is refused here.
+        const names = new Set((registered ?? []).map((service) => service.name));
+        const missing = Object.values(this.names).filter((name) => !names.has(name));
+        if (registered && missing.length > 0)
+            throw new Error(`Restate deployment registration failed: ${uri} is registered with other services ` +
+                `(missing ${missing.join(", ")}); register this Worker at a URL of its own ` +
+                "(NYLORUN_WORKER_VERSION)");
     }
 }
 /**
@@ -501,26 +515,6 @@ function tenantKey(tenantId) {
 function sqlString(value) {
     return `'${value.replaceAll("'", "''")}'`;
 }
-class PermanentError extends Error {
-}
-async function withRetry(what, timeoutMs, attempt) {
-    const deadline = Date.now() + timeoutMs;
-    let delay = 100;
-    for (;;) {
-        try {
-            await attempt();
-            return;
-        }
-        catch (error) {
-            if (error instanceof PermanentError || Date.now() + delay > deadline)
-                throw new Error(`${what} failed: ${error.message}`, {
-                    cause: error,
-                });
-            await new Promise((resolve) => setTimeout(resolve, delay));
-            delay = Math.min(delay * 2, 2000);
-        }
-    }
-}
 function sdkLogger(log) {
     return (meta, message, ...rest) => {
         const parts = [message, ...rest].map((part) => part instanceof Error ? part.stack ?? part.message : String(part));

package/dist/adapters/replication/pgoutput.d.ts

@@ -13,6 +13,8 @@ export interface PgoutputSourceOptions {
     publication?: string;
     /** The schema of the record tables. Default `nylorun_streams`. */
     schema?: string;
+    /** The connections' `application_name`. Default `nylorun-stream-relay`. */
+    applicationName?: string;
     /** Wait between attempts to take the slot. Default 5 s. */
     retryMs?: number;
     log?: (message: string, fields?: Record<string, unknown>) => void;

package/dist/adapters/replication/pgoutput.js

@@ -1,7 +1,9 @@
 /**
  * The stream relay's change source on Postgres logical replication (Durable Streams §7.1,
  * §7.4, §7.6): a persistent `pgoutput` slot on the `nylorun_stream_relay` publication, read
- * with `pg-logical-replication`. The only file importing it (with `pg`, which it needs).
+ * with `pg-logical-replication`. The only file importing it (with `pg`, which it needs). The
+ * trace projector (R7.2) reads the same publication from a slot of its own
+ * (`traces/projector.ts`); for it a fresh slot means nothing to reconcile.
  *
  * - **One reader per slot.** Postgres lets one connection hold a slot, so every Runtime
  *   process can run a source and exactly one is active; the others retry every few seconds
@@ -25,12 +27,13 @@ export function createPgoutputSource(options) {
     const publication = options.publication ?? "nylorun_stream_relay";
     const schema = options.schema ?? "nylorun_streams";
     const retryMs = options.retryMs ?? 5000;
+    const applicationName = options.applicationName ?? "nylorun-stream-relay";
     const { tenantId } = options;
     const log = options.log ?? (() => { });
     const pool = new pg.Pool({
         connectionString: options.connectionString,
         max: 2,
-        application_name: "nylorun-stream-relay",
+        application_name: applicationName,
     });
     let service;
     let stopped = false;
@@ -72,7 +75,7 @@ export function createPgoutputSource(options) {
         // `stop()` during `prepareSlot` had no service to stop: do not start one it cannot.
         if (stopped)
             return;
-        const current = new LogicalReplicationService({ connectionString: options.connectionString, application_name: "nylorun-stream-relay" }, { acknowledge: { auto: false, timeoutSeconds: 0 }, flowControl: { enabled: false } });
+        const current = new LogicalReplicationService({ connectionString: options.connectionString, application_name: applicationName }, { acknowledge: { auto: false, timeoutSeconds: 0 }, flowControl: { enabled: false } });
         service = current;
         let decoding;
         current.on("start", () => handlers.onActive({ fresh }));

package/dist/adapters/sandbox/local.d.ts

@@ -1,4 +1,4 @@
-import type { SandboxBackend } from "../../sandbox/types.js";
+import type { ExecRequest, ExecResult, SandboxBackend } from "../../sandbox/types.js";
 export interface LocalBackendOptions {
     /** Default `/workspace`. */
     readonly workspace?: string;
@@ -6,5 +6,13 @@ export interface LocalBackendOptions {
     readonly proxyEnv?: () => Readonly<Record<string, string>>;
     /** The base environment of commands (the engine's allowlisted one); `NYLORUN_*` is dropped. */
     readonly env: Readonly<Record<string, string | undefined>>;
+    /** The engine's `/harness` on the same volume, a disk root of its versions (R2d step 3). */
+    readonly harnessRoot?: string;
 }
+/**
+ * How the pod runs a command: `/bin/sh -c` in its own process group, with the base environment,
+ * the request's variables and the proxy of the moment. The sandbox tools and the disk's setup
+ * (`harness/setup.ts`) both run commands this way.
+ */
+export declare function localExec(options: LocalBackendOptions): (request: ExecRequest, signal: AbortSignal) => Promise<ExecResult>;
 export declare function localBackend(options: LocalBackendOptions): SandboxBackend;

package/dist/adapters/sandbox/local.js

@@ -49,10 +49,14 @@ function collector() {
         },
     };
 }
-export function localBackend(options) {
-    const workspace = options.workspace ?? SANDBOX_WORKSPACE;
-    const env = baseEnv(options.env, workspace);
-    const exec = (request, signal) => new Promise((resolve, reject) => {
+/**
+ * How the pod runs a command: `/bin/sh -c` in its own process group, with the base environment,
+ * the request's variables and the proxy of the moment. The sandbox tools and the disk's setup
+ * (`harness/setup.ts`) both run commands this way.
+ */
+export function localExec(options) {
+    const env = baseEnv(options.env, options.workspace ?? SANDBOX_WORKSPACE);
+    return (request, signal) => new Promise((resolve, reject) => {
         if (signal.aborted)
             return reject(signal.reason ?? new Error("Turn cancelled"));
         const child = spawn("/bin/sh", ["-c", request.command], {
@@ -102,10 +106,18 @@ export function localBackend(options) {
             });
         });
     });
+}
+export function localBackend(options) {
+    const workspace = options.workspace ?? SANDBOX_WORKSPACE;
+    const exec = localExec(options);
     const missing = (error) => error?.code === "ENOENT" || error?.code === "ENOTDIR";
     const handle = {
         workspace,
         exec,
+        diskRoots: {
+            workspace,
+            ...(options.harnessRoot === undefined ? {} : { harness: options.harnessRoot }),
+        },
         async readFile(path) {
             try {
                 return await readFile(path, "utf8");

package/dist/adapters/sandbox/virtual.js

@@ -1,5 +1,6 @@
 /**
- * Virtual backend: an emulated bash with a virtual filesystem, running in the Runtime process.
+ * Virtual backend: an emulated bash with a virtual filesystem, running in the harness's process
+ * (the harness container, or the Runtime process with NYLORUN_HARNESS=in-process).
  * `/workspace` is backed by a host directory so files survive stop and Runtime restarts.
  * It is not a VM boundary; it exists so the first run and CI work on any machine.
  */
@@ -67,6 +68,8 @@ export function virtualBackend(options) {
                 ...(network ? { network } : {}),
             });
             return {
+                // A virtual workspace's disk is its host directory: `/workspace` only.
+                diskRoots: { workspace: root },
                 async exec(request, signal) {
                     const controller = new AbortController();
                     let timedOut = false;

package/dist/adapters/streams/s2.js

@@ -58,6 +58,7 @@
  */
 import { AppendInput, AppendRecord, RangeNotSatisfiableError, S2, S2Error, SeqNumMismatchError, } from "@s2-dev/streamstore";
 import { parseBasin, tenantBasinName, validateBasinPrefix } from "../../streams/basin.js";
+import { sleep } from "../../retry.js";
 import {} from "../../streams/types.js";
 /** Records per unary read while reading history. */
 const HISTORY_PAGE = 1000;
@@ -357,16 +358,3 @@ function escapeRegExp(text) {
 function anySignal(...signals) {
     return AbortSignal.any(signals.filter((s) => s !== undefined));
 }
-function sleep(ms, signal) {
-    return new Promise((resolve) => {
-        if (signal.aborted)
-            return resolve();
-        const done = () => {
-            clearTimeout(timer);
-            signal.removeEventListener("abort", done);
-            resolve();
-        };
-        const timer = setTimeout(done, ms);
-        signal.addEventListener("abort", done, { once: true });
-    });
-}

package/dist/api/a2a/endpoint.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { readText } from "../http/body.js";
-import { tenantRoute } from "../http/define.js";
+import { TraceHeaders, tenantRoute } from "../http/define.js";
+import { traceContextOf } from "../../traces/ids.js";
 import { jsonResponse } from "../http/respond.js";
 import { a2aCall, a2aCard } from "./routes.js";
 const A2A_SPECIFICATION = {
@@ -63,6 +64,7 @@ export function a2aRoutes(api) {
                 "A2A-Version": z.string().optional().meta({ description: "Or the `A2A-Version` header: `1.0`" }),
             }),
             body: { required: true, content: { "application/json": { schema: JsonRpcRequest } } },
+            headers: TraceHeaders,
         },
         responses: {
             200: {
@@ -73,9 +75,11 @@ export function a2aRoutes(api) {
     }, async (c) => {
         const scope = c.get("scope");
         const version = c.env.incoming.headers["a2a-version"];
+        const trace = traceContextOf(c.req.raw.headers);
         return jsonResponse(200, await a2aCall(c.env.tenant, scope, c.req.param("agentId"), {
             body: () => readText(c.req.raw),
             version: typeof version === "string" ? version : (c.req.query("A2A-Version") ?? null),
+            ...(trace ? { trace } : {}),
         }, c.env.outgoing));
     });
 }

package/dist/api/a2a/routes.d.ts

@@ -1,5 +1,6 @@
 import type { ServerResponse } from "node:http";
 import { type AuthScope, type TenantContext } from "../../tenant/context.js";
+import type { TraceContext } from "../../traces/ids.js";
 /**
  * How long a blocking `SendMessage` waits for the task to end or ask for input. After it, the
  * task is returned `WORKING` and keeps running; the caller polls `GetTask`.
@@ -16,4 +17,5 @@ export declare function a2aCard(ctx: TenantContext, scope: AuthScope, agentId: s
 export declare function a2aCall(ctx: TenantContext, scope: AuthScope, agentId: string, input: {
     body: () => Promise<string>;
     version: string | null;
+    trace?: TraceContext;
 }, response: ServerResponse): Promise<unknown>;

package/dist/api/a2a/routes.js

@@ -50,7 +50,7 @@ export async function a2aCall(ctx, scope, agentId, input, response) {
     // A blocking call stops waiting when the caller hangs up; the task keeps running.
     const hangup = new AbortController();
     response.on("close", () => hangup.abort());
-    const caller = { ctx, scope, access, agentId };
+    const caller = { ctx, scope, access, agentId, ...(input.trace ? { trace: input.trace } : {}) };
     const { id } = envelope.request;
     try {
         checkVersion(input.version);
@@ -137,7 +137,7 @@ async function run(caller, sessionId, input,
 /** The error for a `409` conflict: the session is busy or no longer waiting. */
 conflict) {
     try {
-        const accepted = (await command(caller.ctx, sessionId, SessionCommandSchema.parse(input), caller.scope));
+        const accepted = (await command(caller.ctx, sessionId, SessionCommandSchema.parse(input), caller.scope, caller.trace ? { trace: caller.trace } : {}));
         return { turnId: accepted.turnId, cursor: accepted.cursor };
     }
     catch (error) {

package/dist/api/a2a/tasks.js

@@ -97,7 +97,8 @@ export function historyOf(events, contextId, taskId) {
                 add(clientMessageId(event), "ROLE_USER", [valuePart(payload.value)]);
                 break;
             case "message.assistant":
-                // Agents used as tools speak inside the turn; only the agent's own words are history.
+                // Agents used as tools speak inside the turn; only the agent's own words are history. A
+                // step that said nothing (`text: ""`, R7.1) is none.
                 if (!payload.agent && typeof payload.text === "string" && payload.text.trim() !== "")
                     add(event.eventId, "ROLE_AGENT", [{ text: payload.text }]);
                 break;

package/dist/api/ag-ui/endpoint.js

@@ -2,7 +2,8 @@ import { RESPONSE_ALREADY_SENT } from "@hono/node-server/utils/response";
 import { z } from "zod";
 import { EventSchemas, MessageSchema, RunAgentInputSchema } from "@ag-ui/core/schemas";
 import { readJson } from "../http/body.js";
-import { tenantRoute } from "../http/define.js";
+import { TraceHeaders, tenantRoute } from "../http/define.js";
+import { traceContextOf } from "../../traces/ids.js";
 import { jsonResponse } from "../http/respond.js";
 import { agUiCaller, cancelRun, reattachRun, startRun, threadMessages } from "./routes.js";
 import { sessionIdFor } from "./session-id.js";
@@ -56,11 +57,12 @@ export function agUiRoutes(api) {
                 required: true,
                 content: { "application/json": { schema: ref("AgUiRunAgentInput") } },
             },
+            headers: TraceHeaders,
         },
         responses: { 200: events("The run's events, from RUN_STARTED to its end") },
     }, async (c) => {
         const { scope, subject, access } = callerOf(c);
-        await startRun(c.env.tenant, scope, c.req.param("agentId"), { subject, access }, await readJson(c.req.raw), c.env.outgoing);
+        await startRun(c.env.tenant, scope, c.req.param("agentId"), { subject, access }, await readJson(c.req.raw), c.env.outgoing, traceContextOf(c.req.raw.headers));
         return RESPONSE_ALREADY_SENT;
     });
     tenantRoute(api, FOR_A_PERSON, {

package/dist/api/ag-ui/history.js

@@ -1,4 +1,4 @@
-import { parseTranscriptEvent } from "@nylorun/core/contracts";
+import { isEmptyAssistantMessage, parseTranscriptEvent, } from "@nylorun/core/contracts";
 import { outputText, toolResultOf } from "./translate.js";
 export function messagesFromEvents(items) {
     const messages = [];
@@ -37,6 +37,9 @@ export function messagesFromEvents(items) {
             });
             continue;
         }
+        // A step that said nothing is in the log for its timing (R7.1), never a message.
+        if (event.type === "message.assistant" && isEmptyAssistantMessage(event.payload))
+            continue;
         if (event.type === "message.assistant" && !event.payload.agent) {
             const p = event.payload;
             sawAssistant = true;

package/dist/api/ag-ui/routes.d.ts

@@ -1,6 +1,7 @@
 import type { ServerResponse } from "node:http";
 import { type Message } from "@ag-ui/core";
 import { type AuthScope, type SessionAccess, type TenantContext } from "../../tenant/context.js";
+import type { TraceContext } from "../../traces/ids.js";
 /**
  * Who an AG-UI request acts for, once its agent is known: a person (an issuer token's subject,
  * or `Nylorun-Subject`), who may use the agent; else 400, or the 404 of a missing agent.
@@ -13,7 +14,9 @@ export declare function agUiCaller(scope: AuthScope, agentId: string): {
 export declare function startRun(ctx: TenantContext, scope: AuthScope, agentId: string, caller: {
     subject: string;
     access: SessionAccess | undefined;
-}, body: unknown, response: ServerResponse): Promise<void>;
+}, body: unknown, response: ServerResponse, 
+/** The request's trace context (R7.4): the turn the run starts joins the caller's trace. */
+trace?: TraceContext): Promise<void>;
 /** `GET …/threads/:thread/messages`: the thread's messages; none before its first run. */
 export declare function threadMessages(ctx: TenantContext, id: string, access: SessionAccess | undefined): Promise<Message[]>;
 /**

package/dist/api/ag-ui/routes.js

@@ -33,7 +33,7 @@ import { fail, HttpError } from "../../tenant/http.js";
 import { observeSession, readHistory, StreamClosed, streamHolderOf, } from "../../tenant/session-streams.js";
 import { putSession, sessionView } from "../../tenant/sessions.js";
 import { mayUseAgent } from "../../tenant/auth.js";
-import { sandboxGrantsOf } from "../../tenant/sandboxes.js";
+import { environmentGrantsOf } from "../../tenant/environments.js";
 const HEARTBEAT_MS = 15_000;
 const TERMINAL = new Set([
     "turn.completed",
@@ -83,8 +83,7 @@ function sessionOptions(input, scope) {
         return {};
     const parsed = PutSessionRequestSchema.pick({
         info: true,
-        vaultIds: true,
-        credentialSelections: true,
+        environment: true,
     })
         .strict()
         .safeParse(raw);
@@ -99,11 +98,11 @@ function sessionOptions(input, scope) {
         });
     return parsed.data;
 }
-async function accepted(ctx, id, body, scope) {
-    const result = (await command(ctx, id, body, scope));
+async function accepted(ctx, id, body, scope, trace) {
+    const result = (await command(ctx, id, body, scope, trace ? { trace } : {}));
     return result?.cursor ?? null;
 }
-async function submit(ctx, id, input, scope) {
+async function submit(ctx, id, input, scope, trace) {
     if (input.resume?.length) {
         // The interaction's kind is on the session's pending view, not in its id.
         const view = (await ctx.store.tx(async (t) => sessionView(t, await sessionOf(t, id, accessOf(scope)))));
@@ -144,7 +143,7 @@ async function submit(ctx, id, input, scope) {
         requestId: randomUUID(),
         idempotencyKey: message.id,
         content: message.text,
-    }, scope);
+    }, scope, trace);
 }
 /**
  * Streams translated events until the run ends. Closing the connection stops the read, never
@@ -229,7 +228,9 @@ export function agUiCaller(scope, agentId) {
     return { subject, access: accessOf(scope) };
 }
 /** `POST /v1/ag-ui/agents/:agent`: start a run, and stream it on `response`. */
-export async function startRun(ctx, scope, agentId, caller, body, response) {
+export async function startRun(ctx, scope, agentId, caller, body, response, 
+/** The request's trace context (R7.4): the turn the run starts joins the caller's trace. */
+trace) {
     const parsed = RunAgentInputSchema.safeParse(body);
     if (!parsed.success)
         return fail(400, "Invalid RunAgentInput", { code: "invalid_request" });
@@ -245,12 +246,12 @@ export async function startRun(ctx, scope, agentId, caller, body, response) {
         ...sessionOptions(input, scope),
     }, caller.access, {
         createOnly: true,
-        ...(sandboxGrantsOf(scope) === undefined ? {} : { sandboxGrants: sandboxGrantsOf(scope) }),
+        ...(environmentGrantsOf(scope) === undefined ? {} : { environmentGrants: environmentGrantsOf(scope) }),
     });
     const translator = new RunTranslator(input.threadId, input.runId);
     let cursor;
     try {
-        cursor = await submit(ctx, id, input, scope);
+        cursor = await submit(ctx, id, input, scope, trace);
     }
     catch (error) {
         // A busy session or a limit is a run that could not start, not a transport failure.

package/dist/api/ag-ui/translate.js

@@ -4,7 +4,7 @@
  * `<callId>:result`, so live runs and `messagesFromEvents` agree.
  */
 import { EventType } from "@ag-ui/core";
-import { parseTranscriptEvent, } from "@nylorun/core/contracts";
+import { isEmptyAssistantMessage, parseTranscriptEvent, } from "@nylorun/core/contracts";
 /** The text a tool result shows; `undefined` while there is no result yet. */
 export function toolResultText(result) {
     const value = result;
@@ -89,7 +89,8 @@ export class RunTranslator {
         switch (event.type) {
             case "message.assistant": {
                 const p = event.payload;
-                if (p.agent)
+                // A step that said nothing is in the log for its timing (R7.1), never a message.
+                if (p.agent || isEmptyAssistantMessage(p))
                     return none;
                 this.sawAssistant = true;
                 return { events: assistantEvents(p), finished: false };