@nylorun/runtime 0.23.0-beta → 0.25.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") {
@@ -304,13 +313,17 @@ async function runRemoteSegment(ctx, lease, started, controller, run, onTaken, p
         // Aborted before a harness took it: settled as an abort of the engine would be.
         if (end.kind === "aborted")
             throw signal.reason;
+        // The harness's own tools take names of this turn's tools (Harness API 3): the turn fails.
+        if (end.kind === "refused")
+            throw new Error(end.message);
         // Checked before the abort: whatever core's signal says, the run's effects are unaccounted for.
         if (end.kind === "released" && end.reason === "connection.lost")
             throw new RunLost();
         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 +333,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 +376,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 +424,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 +435,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 +448,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 +487,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 +509,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 +539,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 +551,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 +574,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 +600,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 +641,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 +651,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.d.ts

@@ -4,7 +4,7 @@ import type { HostEffect } from "@nylorun/harness/run";
 import { type TenantContext } from "./context.js";
 export { isReadArtifactCall, isSaveArtifactCall } from "../harness/calls.js";
 export declare function callSaveArtifact(ctx: TenantContext, request: HostEffect, signal: AbortSignal): Promise<SandboxToolOutcome>;
-/** What `read_artifact` returns: a page of a text artifact, or an image as a file. */
+/** What `read_artifact` returns: a page of a text artifact, or a file the model reads. */
 interface ReadOutcome {
     readonly kind: "completed";
     readonly output: Record<string, unknown>;

package/dist/tenant/artifact-tool.js

@@ -1,6 +1,6 @@
 /**
- * Our engine's built-in artifact tools, of the `nylorun.artifacts` capability
- * (`sandbox/session-sandbox.ts`). The Runtime runs them itself, like the sandbox tools.
+ * Our engine's built-in artifact tools, which the Runtime pins in a session agent's `runtime`
+ * block (`sandbox/session-sandbox.ts`). The Runtime runs them itself, like the sandbox tools.
  *
  * `save_artifact` (F8.1), which comes with a session's sandbox, saves a file as an artifact of
  * its session:
@@ -9,25 +9,28 @@
  * The version commits with `artifact.created` (or `artifact.version.created`) on the session's
  * stream, carrying the turn and the tool call.
  *
- * `read_artifact` (R2b C11, Q24), which an agent with a remote MCP server or an HTTP tool has,
- * reads a text artifact of its own session in pages of at most 32 KiB, from a byte `offset`:
- * how the model reads a tool result the Runtime stored because it was too large to show
- * (`tool-results.ts`). An image is shown to a model that reads images, as a file of the result.
- * It reaches only the session's own artifacts, never a Tenant-wide one or another session's.
+ * `read_artifact` (R2b C11, Q24; every agent since protocol 12) reads a text artifact in pages of
+ * at most 32 KiB, from a byte `offset`: how the model reads a tool result the Runtime stored
+ * because it was too large to show (`tool-results.ts`), and a file of an earlier turn again, by
+ * its reference line. Another file is shown as a file of the result when the Tenant's model reads
+ * its type, and refused (`artifact.unsupported`) when it does not. It reaches the session's own
+ * artifacts and the Tenant-wide ones its messages named (`Session.fileArtifacts`), never another
+ * session's. `version` picks a version; the latest by default.
  *
  * Expected problems (no such file, too large, the Tenant's total reached, not text) are failed
  * outcomes the model sees; only infrastructure errors throw.
  */
 import { basename } from "node:path";
-import { READ_ARTIFACT_MAX_BYTES, SANDBOX_CAPABILITY_ID, } from "@nylorun/core/define";
+import { READ_ARTIFACT_MAX_BYTES } from "@nylorun/core/define";
 import { isArtifactId } from "@nylorun/core/compatibility";
 import { readArtifactLimits } from "../artifacts/config.js";
-import { MODEL_FILE_MAX_BYTES, contentTypeFor, essence, isModelImage, isText, normalizeContentType, } from "../artifacts/media-types.js";
+import { contentTypeFor, essence, isText, normalizeContentType, unreadableReason, } from "../artifacts/media-types.js";
+import { currentModelInputs } from "../model/catalog.js";
 import { uploadArtifact } from "../artifacts/service.js";
 import { DEFAULT_CONTENT_TYPE } from "../blob/index.js";
-import { sandboxCapabilityOf } from "../sandbox/manager.js";
+import { sandboxToolSpec } 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 +50,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,
         };
@@ -63,15 +65,15 @@ export async function callSaveArtifact(ctx, request, signal) {
     let bytes;
     let fileName;
     if (path !== undefined) {
-        const capability = sandboxCapabilityOf(manifestFor(s.manifest, request.agent), SANDBOX_CAPABILITY_ID, "read");
-        if (!capability)
+        const spec = sandboxToolSpec(manifestFor(s.manifest, request.agent), "read");
+        if (!spec)
             return failed("artifact.no_sandbox", "This session has no sandbox to read a path from.");
         const read = await ctx.sandbox.readBytes({
             id: workspace.ownerId,
             activeTurnId: s.activeTurnId,
             manifest: s.manifest,
-            ...(workspace.sandboxId === undefined ? {} : { sandboxId: workspace.sandboxId }),
-        }, capability, path, limits.fileBytes, signal);
+            ...(workspace.environmentId === undefined ? {} : { environmentId: workspace.environmentId }),
+        }, spec, path, limits.fileBytes, signal);
         if (read.kind === "failed")
             return read;
         if (read.kind === "missing")
@@ -129,9 +131,12 @@ export async function callSaveArtifact(ctx, request, signal) {
 export async function callReadArtifact(ctx, request, signal) {
     const input = (request.input ?? {});
     const artifactId = typeof input.artifactId === "string" ? input.artifactId : "";
+    const wanted = input.version;
     const offset = input.offset ?? 0;
     const length = input.length ?? READ_ARTIFACT_MAX_BYTES;
     if (artifactId === "" ||
+        (wanted !== undefined &&
+            (typeof wanted !== "number" || !Number.isSafeInteger(wanted) || wanted < 1)) ||
         typeof offset !== "number" ||
         !Number.isSafeInteger(offset) ||
         offset < 0 ||
@@ -139,20 +144,25 @@ export async function callReadArtifact(ctx, request, signal) {
         !Number.isSafeInteger(length) ||
         length < 1 ||
         length > READ_ARTIFACT_MAX_BYTES)
-        return failed("artifact.invalid_input", `Give artifactId, an offset of 0 or more, and a length of 1 to ${READ_ARTIFACT_MAX_BYTES}.`);
+        return failed("artifact.invalid_input", `Give artifactId, a version of 1 or more if any, an offset of 0 or more, and a length of 1 to ${READ_ARTIFACT_MAX_BYTES}.`);
     const found = await ctx.store.tx(async (t) => {
         const s = await sessionOf(t, request.sessionId);
         if (!isArtifactId(artifactId))
             return undefined;
-        // Only an artifact of this session: never a Tenant-wide one, nor another session's.
+        // An artifact of this session, or a Tenant-wide one its messages named; never another
+        // session's.
         const artifact = await t.artifact(artifactId);
-        if (!artifact || artifact.sessionId !== s.id)
+        if (!artifact ||
+            (artifact.sessionId !== s.id &&
+                !(artifact.sessionId === null && s.fileArtifacts?.includes(artifact.id))))
             return undefined;
-        const version = await t.artifactVersion(artifact.id, artifact.latestVersion);
-        return version ? { artifact, version } : undefined;
+        const version = await t.artifactVersion(artifact.id, typeof wanted === "number" ? wanted : artifact.latestVersion);
+        return { artifact, version };
     });
     if (!found)
         return failed("artifact.not_found", `Artifact ${artifactId} is not an artifact of this session.`);
+    if (!found.version)
+        return failed("artifact.not_found", `Artifact ${artifactId} has no version ${String(wanted)}.`);
     const { artifact, version } = found;
     const about = {
         artifactId: artifact.id,
@@ -163,19 +173,29 @@ export async function callReadArtifact(ctx, request, signal) {
     };
     if (artifact.kind !== "file")
         return failed("artifact.not_text", `${artifact.name} is a folder; read_artifact reads a file.`);
-    if (isModelImage(version.contentType) && version.size <= MODEL_FILE_MAX_BYTES)
+    if (!isText(version.contentType)) {
+        // A file the Tenant's model reads goes to it beside the result (protocol 12). Without a
+        // model in the vault (a test's fake provider), text and images.
+        const inputs = (await currentModelInputs(ctx)) ?? ["text", "image"];
+        const reason = unreadableReason(version.contentType, inputs);
+        if (reason)
+            return failed("artifact.unsupported", `${artifact.name} is ${essence(version.contentType)}: ${reason}.`);
         return {
             kind: "completed",
             output: about,
             files: [
                 {
                     mediaType: version.contentType,
-                    reference: { artifactId: artifact.id, version: version.version, name: artifact.name },
+                    reference: {
+                        artifactId: artifact.id,
+                        version: version.version,
+                        name: artifact.name,
+                        size: version.size,
+                    },
                 },
             ],
         };
-    if (!isText(version.contentType))
-        return failed("artifact.not_text", `${artifact.name} is ${essence(version.contentType)}, not text; read_artifact reads text and shows images.`);
+    }
     if (offset > version.size || (offset === version.size && version.size > 0))
         return failed("artifact.invalid_input", `Offset ${offset} is past the end of ${artifact.name}, which is ${version.size} bytes.`);
     const end = Math.min(offset + length, version.size);

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;