@nylorun/runtime 0.20.0-beta → 0.21.1-beta

package/dist/tenant/runtime.js

@@ -5,7 +5,6 @@ import { tenantModelGate } from "../gates/in-process.js";
 import { createKekFile, readVaultKek } from "../vault/kek.js";
 import { SigningKeys } from "./signing-keys.js";
 import { VaultService } from "../vault/service.js";
-import { CredentialSources } from "../vault/sources.js";
 import { McpPool } from "../mcp/pool.js";
 import { SandboxManager } from "../sandbox/manager.js";
 import { storeSandboxRecords } from "../sandbox/records.js";
@@ -22,7 +21,6 @@ import { sweep } from "./sweep.js";
 import { TenantWorkers, WORKER_ID, } from "./worker.js";
 import { authorize } from "./effects.js";
 import { inProcessToolGate } from "../gates/tool-gate.js";
-import { guardedFetch } from "./outbound.js";
 import { inProcessKeys } from "../keys/keys.js";
 import { tenantApi } from "../api/http/app.js";
 import { createFsBlobStore } from "../blob/index.js";
@@ -118,16 +116,7 @@ export class TenantRuntime {
             const opened = store;
             // A seeded Tenant setting wins over the Host default (A18).
             const seededBackend = await opened.tx((t) => t.getSetting("sandbox.backend"));
-            const vault = new VaultService({
-                store: opened,
-                kek: ensureKek,
-                // OAuth refresh and connect follow the Host's address policy (F9 C2).
-                fetch: config.vaultFetch ?? guardedFetch(config.delivery ?? {}),
-            });
-            const credentials = new CredentialSources({
-                vault,
-                ...(config.resolver ? { resolver: config.resolver } : {}),
-            });
+            const vault = new VaultService({ store: opened, kek: ensureKek });
             // `ctx` is assigned below; these callbacks only run once the Tenant is open.
             let ctx;
             const toolGate = hooks.toolGate ??
@@ -137,7 +126,14 @@ export class TenantRuntime {
                     logger: config.logger,
                 });
             const signingKeys = new SigningKeys({ tenantId: config.tenantId, kek: ensureKek });
-            const keys = hooks.keys ?? inProcessKeys({ store: opened, vault, signingKeys, kek: ensureKek });
+            const keys = hooks.keys ??
+                inProcessKeys({
+                    store: opened,
+                    vault,
+                    signingKeys,
+                    kek: ensureKek,
+                    policy: config.delivery ?? {},
+                });
             const harnessMode = hooks.harness ?? "memory";
             const inProcess = harnessMode === "memory" || harnessMode === "json";
             const preference = seededBackend ?? config.sandbox.backend;
@@ -242,7 +238,6 @@ export class TenantRuntime {
                 reads: hooks.reads,
                 store: opened,
                 vault,
-                credentials,
                 ...(mcp ? { mcp } : {}),
                 sandbox,
                 flowLimits,
@@ -266,8 +261,9 @@ export class TenantRuntime {
                 ownerLeaseMs: config.ownerLeaseMs ?? DEFAULT_OWNER_LEASE_MS,
                 wake: async (sessionId, wake) => {
                     if (ctx.closing || ctx.closed)
-                        return;
+                        return false;
                     await execution.wake(config.tenantId, sessionId, wake);
+                    return true;
                 },
                 abortLocal: (sessionId, turnId) => abortLocal(ctx, sessionId, "cancel", turnId),
                 ...(hooks.pods ? { pods: hooks.pods } : {}),

package/dist/tenant/sessions.js

@@ -10,7 +10,7 @@ import { aggregateWaits, isWorkflowManifest } from "../core/flow-host.js";
 import { canonical } from "../store/canonical.js";
 import { validateSandboxAttach } from "../core/sandbox-routes.js";
 import { resolveSandbox } from "../sandbox/resolve.js";
-import { withSandboxCapability } from "../sandbox/session-sandbox.js";
+import { withPlatformTools, withSandboxCapability } from "../sandbox/session-sandbox.js";
 import { declaredSandboxes, sandboxSpecOf, sessionSandboxSpec, } from "../sandbox/share.js";
 import { effectiveSandboxConfig, readSandboxConfig } from "../sandbox/tenant-config.js";
 import { checkPlacement, requirePods } from "../sandbox/placement.js";
@@ -156,12 +156,14 @@ export async function putSession(ctx, id, body, access, options = {}) {
         checkPlacement(await readSandboxConfig(t), sandbox.kind);
         if (sandbox.kind === "pod")
             await requirePods(ctx.pods, `Sandbox ${sandbox.sandboxId}`);
+        const pinned = sandbox.manifest === undefined ? platformTools(definition) : sandbox;
         const created = {
             id,
             agentId: body.agentId,
             ownerUserId: body.ownerUserId,
-            manifest: sandbox.manifest ?? definition.manifest,
-            manifestHash: sandbox.manifestHash ?? definition.manifestHash,
+            manifest: pinned.manifest ?? definition.manifest,
+            manifestHash: pinned.manifestHash ?? definition.manifestHash,
+            definitionHash: definition.manifestHash,
             implementationVersion: definition.implementationVersion,
             info: body.info,
             status: "idle",
@@ -232,6 +234,20 @@ async function sessionSandbox(t, body, definition, options) {
         return fail(resolved.status, resolved.errors.join(" "));
     return pin(definition, resolved.spec, resolved.source);
 }
+/**
+ * The manifest a session without a sandbox pins: its agents' `read_artifact` (R2b C11), when
+ * one has a remote MCP server or an HTTP tool; nothing otherwise, and for a workflow.
+ */
+function platformTools(definition) {
+    if (isWorkflowManifest(definition.manifest))
+        return {};
+    const pinned = withPlatformTools(definition.manifest);
+    if (pinned === undefined)
+        return {};
+    if (!pinned.ok)
+        return fail(400, pinned.message);
+    return { manifest: pinned.manifest, manifestHash: pinned.manifestHash };
+}
 async function pin(definition, spec, source) {
     // A workflow's manifest stays as registered: its agents inherit the sandbox when they start.
     if (isWorkflowManifest(definition.manifest))
@@ -269,6 +285,7 @@ export async function sessionView(t, s) {
         agentId: s.agentId,
         ownerUserId: s.ownerUserId,
         manifestHash: s.manifestHash,
+        ...(s.definitionHash === undefined ? {} : { definitionHash: s.definitionHash }),
         implementationVersion: s.implementationVersion,
         status: s.status,
         activeTurnId: s.activeTurnId,

package/dist/tenant/store-pg.js

@@ -55,6 +55,15 @@ export function createPostgresTenantOpener(options) {
                 from: opened.migrated.from,
                 to: opened.migrated.to,
             });
+        // Protocol 10 removed the vault's `oauth` credential type: the migration deleted them.
+        for (const removed of opened.removedCredentials)
+            logger?.warn("oauth_credential_removed", {
+                tenantId,
+                vaultId: removed.vaultId,
+                credentialId: removed.credentialId,
+                url: removed.url,
+                message: "MCP OAuth credentials are gone (protocol 10): store a key for this server in a vault, or reach it through a gateway",
+            });
         let reads;
         try {
             reads = createPostgresReadStore(options.sql, tenantId);

package/dist/tenant/sweep.d.ts

@@ -1,5 +1,19 @@
 import type { TenantContext } from "./context.js";
+/**
+ * How old a wake outbox row is before the sweep delivers it: longer than a delivery after
+ * commit takes, so the sweep seldom sends a wake its commit is still sending. Sending one
+ * twice is harmless either way (the idempotency key).
+ */
+export declare const WAKE_GRACE_MS = 2000;
+/** How often the orphan scan runs after the first pass of a Tenant opened on this process. */
+export declare const ORPHAN_SCAN_MS = 60000;
 export declare function sweep(ctx: TenantContext): Promise<void>;
+/**
+ * Deliver the wake outbox rows written before `before` (oldest first, one batch) and delete
+ * the delivered ones. A row the Tenant declines (it is closing) stays. Returns the ids of the
+ * rows delivered.
+ */
+export declare function deliverPendingWakes(ctx: Pick<TenantContext, "store" | "wake">, before?: Date): Promise<string[]>;
 /** Settle pending workflow `agent` effects whose linked turn already finished. */
 export declare function reconcileLinkedAgents(ctx: Pick<TenantContext, "store" | "wake">): Promise<void>;
 /** Wake `running`/`runnable` sessions without a live owner. Returns the ids woken. */

package/dist/tenant/sweep.js

@@ -1,21 +1,32 @@
 /**
  * The Tenant sweep (architecture §12.3, "Timers"): one self-re-arming pass per Tenant, armed
  * with `DurableExecution.armSweep` when the Tenant opens. It replaces every in-process timer
- * and startup scan the Tenant runtime used to keep:
+ * and startup scan the Tenant runtime used to keep. It reconciles the Session Store with what
+ * Durable Session Execution was asked to do; it never decides when a session advances:
  *
- * 1. **Linked agents.** Pending workflow `agent` effects whose linked turn already settled
+ * 1. **Wakes.** Wake outbox rows (`Tx.wake`) are delivered again and deleted: a delivery
+ *    after commit that failed, or that a crash between the commit and the send cut off. The
+ *    first pass on this process takes every row, so a previous process's are not left
+ *    waiting; later passes take the rows older than `WAKE_GRACE_MS`. Each row carries the
+ *    idempotency key it was first sent with, so a wake the execution did accept before the
+ *    crash, or one still being sent after its commit, causes no second advance.
+ * 2. **Linked agents.** Pending workflow `agent` effects whose linked turn already settled
  *    are completed and the workflow is woken (a crash between the two, or data written by an
- *    older Runtime). One transaction per effect, child session locked before its workflow.
- * 2. **Orphaned sessions.** `running` or `runnable` sessions with no owner, or an owner whose
- *    lease expired, are woken with reason `recover`: a wake lost between commit and send, or
- *    a Worker that died mid-advance (the advance then takes over, §11.4).
- * 3. **Sandboxes.** Idle sandboxes are stopped, records of compute no longer held are marked
+ *    older Runtime).
+ * 3. **Orphaned sessions.** On this process's first pass for the Tenant, then at most every
+ *    `ORPHAN_SCAN_MS`: `running` or `runnable` sessions with no owner, or an owner whose lease
+ *    expired, are woken with reason `recover`. Neither a lost wake (step 1) nor a Worker that
+ *    died mid-advance (the execution retries that advance, which takes over, §11.4) needs it:
+ *    it is the backstop for what the execution itself lost or ended without an advance, such
+ *    as an in-process execution's queue when its process stopped, an advance for a Tenant not
+ *    open on its Worker, an invocation an operator killed, or Restate's state wiped (§17.11).
+ * 4. **Sandboxes.** Idle sandboxes are stopped, records of compute no longer held are marked
  *    stopped, and sandboxes whose session or sandbox resource is gone are removed, by the
  *    workspace capability (`harness-api/workspace.ts`: here, or in the harness that serves
  *    workspaces). Idle MCP connections of the in-process harness are closed.
- * 4. **Control signals.** Signals on the control bus older than `SIGNAL_RETENTION_MS` are
+ * 5. **Control signals.** Signals on the control bus older than `SIGNAL_RETENTION_MS` are
  *    deleted: followers read back only the last two minutes (`store/postgres/control.ts`).
- * 5. **Hooks.** Callbacks registered with `ctx.onSweep`.
+ * 6. **Hooks.** Callbacks registered with `ctx.onSweep`.
  *
  * Every step runs one transaction per session it changes (a linked agent and its workflow
  * share one, child first), so the sweep follows the lock order in `store/types.ts`. A failing
@@ -26,13 +37,41 @@ import { pendingAgentEffects, reconcilePendingAgentEffect, } from "../core/flow-
 const BATCH = 100;
 /** How long a control signal is kept after it was written. */
 const SIGNAL_RETENTION_MS = 60 * 60 * 1000;
+/**
+ * How old a wake outbox row is before the sweep delivers it: longer than a delivery after
+ * commit takes, so the sweep seldom sends a wake its commit is still sending. Sending one
+ * twice is harmless either way (the idempotency key).
+ */
+export const WAKE_GRACE_MS = 2000;
+/** How often the orphan scan runs after the first pass of a Tenant opened on this process. */
+export const ORPHAN_SCAN_MS = 60_000;
+/** Each open Tenant's sweep state on this process: when its orphan scan last ran. */
+const passes = new WeakMap();
 export async function sweep(ctx) {
     if (ctx.closing || ctx.closed)
         return;
     const now = new Date();
+    const first = !passes.has(ctx);
+    const pass = passes.get(ctx) ?? {};
+    passes.set(ctx, pass);
+    const scanOrphans = pass.orphansAt === undefined || now.getTime() - pass.orphansAt >= ORPHAN_SCAN_MS;
     const steps = [
+        [
+            "wakes",
+            () => deliverPendingWakes(ctx, first ? now : new Date(now.getTime() - WAKE_GRACE_MS)),
+        ],
         ["linked", () => reconcileLinkedAgents(ctx)],
-        ["orphans", () => wakeOrphanedSessions(ctx, now)],
+        ...(scanOrphans
+            ? [
+                [
+                    "orphans",
+                    async () => {
+                        await wakeOrphanedSessions(ctx, now);
+                        pass.orphansAt = now.getTime();
+                    },
+                ],
+            ]
+            : []),
         [
             "sandboxes",
             () => ctx.sandbox.sweep({
@@ -68,6 +107,26 @@ export async function sweep(ctx) {
     if (failure)
         throw failure.error;
 }
+/**
+ * Deliver the wake outbox rows written before `before` (oldest first, one batch) and delete
+ * the delivered ones. A row the Tenant declines (it is closing) stays. Returns the ids of the
+ * rows delivered.
+ */
+export async function deliverPendingWakes(ctx, before = new Date()) {
+    const pending = await ctx.store.tx((t) => t.pendingWakes(before, BATCH));
+    const delivered = [];
+    try {
+        for (const row of pending)
+            if ((await ctx.wake(row.sessionId, row.wake)) !== false)
+                delivered.push(row.id);
+    }
+    finally {
+        // Delivered ones go even when a later one fails, so they are not sent again.
+        if (delivered.length > 0)
+            await ctx.store.tx((t) => t.deleteWakes(delivered));
+    }
+    return delivered;
+}
 /** Settle pending workflow `agent` effects whose linked turn already finished. */
 export async function reconcileLinkedAgents(ctx) {
     const { store } = ctx;

package/dist/tenant/tool-results.d.ts

@@ -0,0 +1,57 @@
+import type { HostEffect } from "@nylorun/harness/run";
+import type { TenantContext } from "./context.js";
+/** The most of one tool result that is recorded inline (Q22): 32 KiB, as JSON. */
+export declare const TOOL_RESULT_INLINE_BYTES: number;
+/** How much of a stored result's start, and of its end, the preview keeps. */
+export declare const PREVIEW_HEAD_BYTES: number;
+export declare const PREVIEW_TAIL_BYTES = 1024;
+/**
+ * The most one step's results may hold together: a step's results are one transcript entry, so
+ * one event, which must stay well under S2's 1 MiB record.
+ */
+export declare const STEP_RESULTS_BUDGET_BYTES: number;
+/** A result's cap once its step's budget is spent: a stub naming its artifact. */
+export declare const TOOL_RESULT_STUB_BYTES = 512;
+/** A result this small is never shaped, nor counted against its step's budget. */
+export declare const TOOL_RESULT_SMALL_BYTES = 1024;
+/** The call whose outcome is shaped, and the session its artifacts belong to. */
+export interface ShapedCall {
+    readonly request: HostEffect;
+    readonly session: {
+        readonly id: string;
+        readonly ownerUserId: string;
+    };
+    /** A remote MCP tool's: its output may be the server's content parts. */
+    readonly mcp: boolean;
+    /** This result's cap (`resultLimit`). Default `TOOL_RESULT_INLINE_BYTES`. */
+    readonly limit?: number;
+}
+/** A result's cap when the other results of its step already took `used` bytes. */
+export declare function resultLimit(used: number): number;
+/** The JSON size of `value` in bytes: what it adds to an event or a prompt. */
+export declare function jsonBytes(value: unknown): number;
+/**
+ * What a tool outcome's result weighs in its step's transcript entry: a completed one's output,
+ * a failed one's message; 0 for anything else, such as a model call's outcome.
+ */
+export declare function resultBytes(value: unknown): number;
+/**
+ * False for an outcome `shapeToolOutcome` returns as it is, whatever made it: a model call's, a
+ * small tool result with no parts. Spares a look at the effect for most outcomes.
+ */
+export declare function mayNeedShaping(value: unknown): boolean;
+/**
+ * The outcome `value` of `call`, shaped to fit its cap (see the module comment). An outcome that
+ * fits and has no binary part comes back as it is.
+ */
+export declare function shapeToolOutcome(ctx: TenantContext, call: ShapedCall, value: unknown, signal: AbortSignal): Promise<unknown>;
+/**
+ * The start and end of `text` in whole characters, `budget` bytes split four to one: by default
+ * the first `PREVIEW_HEAD_BYTES` and the last `PREVIEW_TAIL_BYTES`.
+ */
+export declare function previewOf(text: string, budget?: number): string;
+/**
+ * The nearest character boundary of the UTF-8 `bytes` at or before (`down`) or at or after
+ * (`up`) byte `at`: never inside a character.
+ */
+export declare function utf8Boundary(bytes: Uint8Array, at: number, direction: "down" | "up"): number;

package/dist/tenant/tool-results.js

@@ -0,0 +1,298 @@
+/**
+ * Tool results that fit (R2b C11, Q22–Q24): core shapes what an agent's remote MCP tool or HTTP
+ * tool returned before it records the outcome (`harness-api/record.ts`), so no journal row,
+ * event or prompt holds more of one result than the inline cap. The gate already refused an
+ * answer past 8 MiB (`mcp.too-large`, `http.too-large`).
+ *
+ * - An `image`, `audio` or blob `resource` part becomes a file artifact of the session, and the
+ *   part says `{artifactId, version, contentType, size}`. An image also goes to the model as a
+ *   file (`ToolOutcome.files`), which the model call shows to a model that reads images (Q23).
+ * - Text or JSON past `TOOL_RESULT_INLINE_BYTES` (32 KiB, Q22) becomes a file artifact, and the
+ *   model gets `{truncated: true, artifactId, size, preview}`: the first 4 KiB and the last 1 KiB.
+ *   In a result of several parts each part is shaped alone, the largest text first, until the
+ *   whole fits; one that still does not is stored whole.
+ * - A `resource_link` stays a link, never fetched, and a text resource that fits stays inline.
+ * - A failed outcome's message is cut to its start and end.
+ * - When an artifact cannot be stored (the Tenant's artifact limits, an Object store that
+ *   fails), the preview stays and `dropped` says why the rest is gone: a result never passes
+ *   the cap. Only an abort throws.
+ * - **One step's results share a budget** (`STEP_RESULTS_BUDGET_BYTES`, 256 KiB), since the
+ *   transcript keeps a step's results in one entry, one event: the record seam counts what the
+ *   step's other results took, under the session lock, and gives this one the rest as its cap
+ *   (`resultLimit`). Once the budget is spent, a result past `TOOL_RESULT_SMALL_BYTES` becomes a
+ *   stub naming its artifact, its preview cut to fit `TOOL_RESULT_STUB_BYTES`.
+ *
+ * The model reads a stored result with `read_artifact` (`artifact-tool.ts`). Artifacts are the
+ * session's, saved by our engine (`source: "engine"`), with the turn and the tool call on their
+ * `artifact.created` event.
+ */
+import { READ_ARTIFACT_MAX_BYTES } from "@nylorun/core/define";
+import { MODEL_FILE_MAX_BYTES, extensionFor, isModelImage, isText, normalizeContentType, } from "../artifacts/media-types.js";
+import { uploadArtifact } from "../artifacts/service.js";
+import { DEFAULT_CONTENT_TYPE } from "../blob/index.js";
+import { HttpError } from "./http.js";
+import { toolIds } from "./transcript.js";
+/** The most of one tool result that is recorded inline (Q22): 32 KiB, as JSON. */
+export const TOOL_RESULT_INLINE_BYTES = READ_ARTIFACT_MAX_BYTES;
+/** How much of a stored result's start, and of its end, the preview keeps. */
+export const PREVIEW_HEAD_BYTES = 4 * 1024;
+export const PREVIEW_TAIL_BYTES = 1024;
+/**
+ * The most one step's results may hold together: a step's results are one transcript entry, so
+ * one event, which must stay well under S2's 1 MiB record.
+ */
+export const STEP_RESULTS_BUDGET_BYTES = 256 * 1024;
+/** A result's cap once its step's budget is spent: a stub naming its artifact. */
+export const TOOL_RESULT_STUB_BYTES = 512;
+/** A result this small is never shaped, nor counted against its step's budget. */
+export const TOOL_RESULT_SMALL_BYTES = 1024;
+/** A result's cap when the other results of its step already took `used` bytes. */
+export function resultLimit(used) {
+    return Math.max(TOOL_RESULT_STUB_BYTES, Math.min(TOOL_RESULT_INLINE_BYTES, STEP_RESULTS_BUDGET_BYTES - used));
+}
+/** The JSON size of `value` in bytes: what it adds to an event or a prompt. */
+export function jsonBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value) ?? "null");
+}
+/**
+ * What a tool outcome's result weighs in its step's transcript entry: a completed one's output,
+ * a failed one's message; 0 for anything else, such as a model call's outcome.
+ */
+export function resultBytes(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return 0;
+    const outcome = value;
+    if (outcome.kind === "failed")
+        return typeof outcome.message === "string" ? Buffer.byteLength(outcome.message) : 0;
+    if (outcome.kind !== "completed" || outcome.output === undefined)
+        return 0;
+    return jsonBytes(outcome.output);
+}
+/**
+ * False for an outcome `shapeToolOutcome` returns as it is, whatever made it: a model call's, a
+ * small tool result with no parts. Spares a look at the effect for most outcomes.
+ */
+export function mayNeedShaping(value) {
+    const output = value?.output;
+    if (value?.kind === "completed" && Array.isArray(output))
+        return true;
+    return resultBytes(value) > TOOL_RESULT_SMALL_BYTES;
+}
+/**
+ * The outcome `value` of `call`, shaped to fit its cap (see the module comment). An outcome that
+ * fits and has no binary part comes back as it is.
+ */
+export async function shapeToolOutcome(ctx, call, value, signal) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return value;
+    const outcome = value;
+    const limit = call.limit ?? TOOL_RESULT_INLINE_BYTES;
+    if (outcome.kind === "failed" && typeof outcome.message === "string")
+        return Buffer.byteLength(outcome.message) > limit
+            ? { ...outcome, message: cutMessage(outcome.message, limit) }
+            : value;
+    if (outcome.kind !== "completed" || outcome.output === undefined)
+        return value;
+    const shaping = { ...call, limit, ctx, signal, files: [] };
+    let output = outcome.output;
+    if (call.mcp && isContentParts(output))
+        output = await shapeParts(shaping, output);
+    let truncated = false;
+    if (jsonBytes(output) > limit) {
+        output = await storedWhole(shaping, output);
+        truncated = true;
+    }
+    if (output === outcome.output)
+        return value;
+    return {
+        ...outcome,
+        output,
+        ...(shaping.files.length > 0 ? { files: shaping.files } : {}),
+        ...(truncated ? { truncated: true } : {}),
+    };
+}
+/** True for an MCP `content` array: objects with a `type` each. */
+function isContentParts(value) {
+    return (Array.isArray(value) &&
+        value.length > 0 &&
+        value.every((part) => !!part &&
+            typeof part === "object" &&
+            !Array.isArray(part) &&
+            typeof part.type === "string"));
+}
+/** An MCP result's parts: binary ones stored, then the largest text ones until the whole fits. */
+async function shapeParts(shaping, parts) {
+    const shaped = [];
+    for (const [index, part] of parts.entries())
+        shaped.push(await shapeBinary(shaping, part, index));
+    const texts = shaped
+        .map((part, index) => ({ index, bytes: textOf(part) === undefined ? 0 : jsonBytes(part) }))
+        .filter((item) => item.bytes > 0)
+        .sort((a, b) => b.bytes - a.bytes);
+    for (const { index } of texts) {
+        if (jsonBytes(shaped) <= shaping.limit)
+            break;
+        const part = shaped[index];
+        const text = textOf(part);
+        const resource = part.type === "resource" ? part.resource : undefined;
+        const contentType = resource ? textType(resource.mimeType) : "text/plain; charset=utf-8";
+        const kept = await store(shaping, text, contentType, nameOf(shaping, contentType, index));
+        shaped[index] = withPreview({
+            type: part.type,
+            ...(resource && typeof resource.uri === "string" ? { uri: resource.uri } : {}),
+            truncated: true,
+            ...kept,
+        }, text, shaping.limit);
+    }
+    return shaped;
+}
+/** An `image`, `audio` or blob `resource` part, stored; any other part as it is. */
+async function shapeBinary(shaping, part, index) {
+    const resource = part.type === "resource" && part.resource && typeof part.resource === "object"
+        ? part.resource
+        : undefined;
+    const data = part.type === "image" || part.type === "audio"
+        ? part.data
+        : resource !== undefined
+            ? resource.blob
+            : undefined;
+    if (typeof data !== "string")
+        return part;
+    const declared = resource ? resource.mimeType : part.mimeType;
+    const contentType = (typeof declared === "string" ? normalizeContentType(declared) : undefined) ??
+        DEFAULT_CONTENT_TYPE;
+    const name = nameOf(shaping, contentType, index);
+    const kept = await store(shaping, Buffer.from(data, "base64"), contentType, name);
+    // An image the model reads goes to it as a file, beside the part (Q23).
+    if (part.type === "image" &&
+        "artifactId" in kept &&
+        isModelImage(contentType) &&
+        kept.size <= MODEL_FILE_MAX_BYTES)
+        shaping.files.push({
+            mediaType: contentType,
+            reference: { artifactId: kept.artifactId, version: kept.version, name },
+        });
+    return {
+        type: part.type,
+        ...(resource && typeof resource.uri === "string" ? { uri: resource.uri } : {}),
+        ...("artifactId" in kept ? kept : { contentType, ...kept }),
+    };
+}
+/** The text a part carries inline: a text part's, or a text resource's. */
+function textOf(part) {
+    if (part.type === "text" && typeof part.text === "string")
+        return part.text;
+    if (part.type === "resource" && part.resource && typeof part.resource === "object") {
+        const text = part.resource.text;
+        if (typeof text === "string")
+            return text;
+    }
+    return undefined;
+}
+function textType(declared) {
+    const type = typeof declared === "string" ? normalizeContentType(declared) : undefined;
+    return type !== undefined && isText(type) ? type : "text/plain; charset=utf-8";
+}
+/** `value` stored whole, as text or JSON, and the preview the model gets. */
+async function storedWhole(shaping, value) {
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    const contentType = typeof value === "string" ? "text/plain; charset=utf-8" : "application/json";
+    const kept = await store(shaping, text, contentType, nameOf(shaping, contentType));
+    return withPreview({ truncated: true, ...kept }, text, shaping.limit);
+}
+/**
+ * `stub` with the preview of `text`: the first 4 KiB and the last 1 KiB, or less, so that the
+ * whole fits `limit` (a step's budget spent, R2b C11); none when even a little does not.
+ */
+function withPreview(stub, text, limit) {
+    let budget = Math.min(PREVIEW_HEAD_BYTES + PREVIEW_TAIL_BYTES, limit);
+    for (;;) {
+        const shaped = { ...stub, preview: previewOf(text, budget) };
+        const over = jsonBytes(shaped) - limit;
+        if (over <= 0 || budget === 0)
+            return shaped;
+        budget = budget - over < 64 ? 0 : budget - over;
+    }
+}
+/** Stores `body` as an artifact of the call's session, or says why it was not. */
+async function store(shaping, body, contentType, name) {
+    const bytes = typeof body === "string" ? Buffer.from(body, "utf8") : body;
+    const { ctx, request, session, signal } = shaping;
+    const ids = toolIds(request.context);
+    try {
+        const saved = await uploadArtifact(ctx, {
+            name,
+            contentType,
+            sessionId: session.id,
+            source: "engine",
+            turnId: request.turnId,
+            ...("callId" in ids ? { callId: ids.callId } : {}),
+        }, bytes, 
+        // Into the call's own session only.
+        { owner: session.ownerUserId }, signal);
+        return {
+            artifactId: saved.artifact.artifactId,
+            version: saved.version.version,
+            contentType: saved.version.contentType,
+            size: saved.version.size,
+        };
+    }
+    catch (error) {
+        if (signal.aborted)
+            throw error;
+        // A limit is the Tenant's to raise; any other failure is the store's. Never the bytes.
+        ctx.config.logger.warn("tool_result_not_stored", {
+            session: session.id,
+            effect: request.effectId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return {
+            dropped: error instanceof HttpError
+                ? `The result could not be stored as an artifact: ${error.message}`
+                : "The result could not be stored as an artifact",
+            size: bytes.byteLength,
+        };
+    }
+}
+/** A name for a stored result: the tool's, with the part's number and the type's extension. */
+function nameOf(shaping, contentType, index) {
+    const tool = (shaping.request.toolName ?? "tool").replace(/[^A-Za-z0-9_.-]/gu, "_");
+    const extension = extensionFor(contentType) ?? "bin";
+    return `${tool.slice(0, 200)}-result${index === undefined ? "" : `-${index + 1}`}.${extension}`;
+}
+/**
+ * The start and end of `text` in whole characters, `budget` bytes split four to one: by default
+ * the first `PREVIEW_HEAD_BYTES` and the last `PREVIEW_TAIL_BYTES`.
+ */
+export function previewOf(text, budget = PREVIEW_HEAD_BYTES + PREVIEW_TAIL_BYTES) {
+    const bytes = Buffer.from(text, "utf8");
+    if (bytes.byteLength <= budget)
+        return text;
+    if (budget <= 0)
+        return "";
+    const tailBytes = Math.floor(budget / 5);
+    const head = utf8Boundary(bytes, budget - tailBytes, "down");
+    const tail = utf8Boundary(bytes, bytes.byteLength - tailBytes, "up");
+    return `${bytes.subarray(0, head).toString("utf8")}\n…\n${bytes.subarray(tail).toString("utf8")}`;
+}
+/** A message past `limit`: its start and end, and how long it was. */
+function cutMessage(message, limit) {
+    const note = `\n(The message was ${Buffer.byteLength(message)} bytes; its middle is not shown.)`;
+    const budget = Math.min(PREVIEW_HEAD_BYTES + PREVIEW_TAIL_BYTES, limit - note.length - 16);
+    return `${previewOf(message, Math.max(0, budget))}${note}`;
+}
+/**
+ * The nearest character boundary of the UTF-8 `bytes` at or before (`down`) or at or after
+ * (`up`) byte `at`: never inside a character.
+ */
+export function utf8Boundary(bytes, at, direction) {
+    let position = Math.max(0, Math.min(at, bytes.byteLength));
+    const inside = (index) => index < bytes.byteLength && (bytes[index] & 0xc0) === 0x80;
+    if (direction === "down")
+        while (position > 0 && inside(position))
+            position -= 1;
+    else
+        while (inside(position))
+            position += 1;
+    return position;
+}