@nylorun/runtime 0.15.2-beta → 0.17.0-beta

package/dist/tenant/advance.js

@@ -14,10 +14,19 @@
  * - **Epoch-checked writes.** Every transaction of the advance and of the engine host
  *   (`effects.ts`) runs through `ownedTx`/`ownedSession`, which checks the epoch first. A
  *   mismatch throws `ownership.lost` with no write; the advance stops and returns `done`.
- * - **Heartbeat.** While the segment runs, a timer scoped to the advance renews the lease
- *   (a column update). A failed renewal aborts the segment.
+ * - **Heartbeat.** While the segment runs the lease is renewed (a column update): by the
+ *   harness that holds the run (`lease.renew`), and by core until one takes it. A failed
+ *   renewal aborts the segment.
+ * - **Run token** (F5). Right after taking the lease the advance mints the run token its
+ *   gate calls present (`run-grants.ts`); each renewal re-mints it before it expires, and it
+ *   is dropped when the lease is lost or released. A harness gets it with its run.
  * - **Release** when the advance ends, whatever the outcome.
  *
+ * The segment runs in a harness (Harness API v1, `harness-api/`): the advance offers it with
+ * its `turn.start`, the in-process harness (or one attached to the Tenant) readies the
+ * session's MCP servers, runs the engine and reports how it ended, and the advance settles
+ * that exactly as it settled the engine's result.
+ *
  * Session outcomes never throw out of `advance`: a segment that throws is settled as a
  * failed turn. Only infrastructure errors (the Session Store is unreachable) throw, and the
  * execution retries them.
@@ -33,16 +42,17 @@
 import { runDurable, runFlowDurable, } from "@nylorun/harness/run";
 import { aggregateWaits, cancelSiblingWork, isWorkflowManifest, wakeLinkedWorkflow, } from "../core/flow-host.js";
 import { isOwnershipLost, ownedTx } from "../store/ownership.js";
-import { linkedAgentOutput, rebaseSessionState, sessionToolsOf, turnManifestOf, } from "./session.js";
-import { isRemoteMcpEffect, prepareMcp, recoversMcpCalls, recoversModelCalls, resolveEffect, } from "./effects.js";
+import { linkedAgentOutput } from "./session.js";
+import { isRemoteMcpEffect, recoversMcpCalls, recoversModelCalls } from "./effects.js";
 import { slimModelEffects } from "./slim.js";
-import { checkParity, foldTranscript, leanState, transcriptOf, transcriptUpdates, withTranscript, } from "./history.js";
+import { applyUpdates, leanState, transcriptShadow, withTranscript, } from "./history.js";
 import { command } from "./commands.js";
-import { usesFixtureModel } from "./model-setting.js";
-import { toolFixtureModel } from "../core/provider.js";
+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 { AdvanceAbort, AdvanceDeadlineError, abortKind, } from "./worker.js";
-/** The model of Tenants with the fixture-model setting (`model-setting.ts`). Stateless. */
-const fixture = toolFixtureModel();
 /**
  * A segment stopped by a `shutdown` or `ownership.lost` abort before it settled. Never
  * leaves `advance`.
@@ -55,13 +65,39 @@ class SegmentStopped extends Error {
         this.kind = kind;
     }
 }
+/**
+ * The harness holding the run went away without giving it back (`connection.lost`): an effect
+ * it was running may still be running, or may have died with it. Like a Worker that died, the
+ * advance keeps the lease, which lapses, so the next advance takes the session over and marks
+ * what was `invoking` `uncertain` (§11.4). Never leaves `advance`.
+ */
+class RunLost extends Error {
+    name = "RunLost";
+    constructor() {
+        super("The harness holding the run went away");
+    }
+}
 /** Throws `SegmentStopped` when the signal aborted for a reason that must not settle. */
 function stopIfLeaving(signal) {
     const kind = abortKind(signal);
     if (kind === "shutdown" || kind === "ownership.lost")
         throw new SegmentStopped(kind);
 }
+/** No harness took the segment (`HarnessApiServer.offer`): the advance is retried later. */
+class HarnessUnavailable extends Error {
+    name = "HarnessUnavailable";
+    constructor() {
+        super("No harness took the segment");
+    }
+}
 const DONE = { status: "done" };
+/** How soon an advance whose segment no harness took is tried again. */
+const UNAVAILABLE_RETRY_MS = 1000;
+/**
+ * How long a pod sandbox's segment waits for its engine (F7.2): a pod that is starting, or
+ * resuming, takes longer than a harness that is already connected.
+ */
+const POD_OFFER_WAIT_MS = 60_000;
 /** Shortest `busy` retry, so a lease about to lapse is not polled in a tight loop. */
 const MIN_RETRY_MS = 25;
 /**
@@ -88,13 +124,33 @@ export async function advance(ctx, id, signal) {
         signal.addEventListener("abort", forward, { once: true });
     ctx.work.running.set(id, controller);
     ctx.work.runningTurns.set(id, taken.session.activeTurnId ?? null);
-    const heartbeat = startHeartbeat(ctx, lease, controller);
+    // A harness renews the lease once it holds the run; until then, and without one, core does.
+    const run = { agentId: taken.session.agentId, activeTurnId: taken.session.activeTurnId };
+    const heartbeat = startHeartbeat(ctx, lease, controller, run);
     let result = DONE;
+    let release = true;
+    const placed = {};
     try {
-        await runSegment(ctx, lease, taken.session, controller.signal);
+        await grantRun(ctx, lease, run);
+        await runRemoteSegment(ctx, lease, taken.session, controller, run, () => heartbeat.stop(), placed);
     }
     catch (error) {
-        if (error instanceof SegmentStopped && error.kind === "shutdown") {
+        if (error instanceof RunLost) {
+            ctx.config.logger.warn("advance lost its harness; the lease lapses and the session is taken over", {
+                sessionId: id,
+                epoch: lease.epoch,
+            });
+            release = false;
+            result = { status: "busy", retryAfterMs: ctx.ownerLeaseMs };
+        }
+        else if (error instanceof HarnessUnavailable) {
+            ctx.config.logger.warn("advance found no harness; session left for the next advance", {
+                sessionId: id,
+                epoch: lease.epoch,
+            });
+            result = { status: "busy", retryAfterMs: UNAVAILABLE_RETRY_MS };
+        }
+        else if (error instanceof SegmentStopped && error.kind === "shutdown") {
             // Left for the next advance, which resumes from the checkpoint once this one releases.
             ctx.config.logger.info("advance stopped for shutdown; session left for the next advance", {
                 sessionId: id,
@@ -112,21 +168,44 @@ export async function advance(ctx, id, signal) {
     }
     finally {
         heartbeat.stop();
+        dropRunGrant(ctx, lease);
         signal.removeEventListener("abort", forward);
         if (ctx.work.running.get(id) === controller) {
             ctx.work.running.delete(id);
             ctx.work.runningTurns.delete(id);
         }
         // Best effort: a release that fails leaves a lease that simply expires.
-        await ctx.store
-            .tx((t) => t.releaseOwnership(id, lease.owner, lease.epoch))
-            .catch((error) => ctx.config.logger.warn("advance failed to release ownership", {
-            sessionId: id,
-            message: error instanceof Error ? error.message : String(error),
-        }));
+        if (release)
+            await ctx.store
+                .tx((t) => t.releaseOwnership(id, lease.owner, lease.epoch))
+                .catch((error) => ctx.config.logger.warn("advance failed to release ownership", {
+                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);
     }
     return result;
 }
+/** Why a pod sandbox 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`;
+    const state = pod.pod;
+    if (state.desired === "deleted")
+        return `Sandbox ${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`;
+    if (state.observed === "failed")
+        return `Sandbox ${pod.id} failed to start: ${state.reason ?? "its pod was not ready"}`;
+    return undefined;
+}
 /**
  * Takes ownership of `id` in one transaction, takes over from a dead owner, and marks the
  * session `running` when it has a runnable checkpoint. Releases again when there is
@@ -195,122 +274,66 @@ export async function takeOver(t, s, options = {}) {
     return marked;
 }
 /**
- * Renews the lease every third of its length while the advance runs; aborts it when lost.
- * Stops renewing once the advance is aborted (cancel, deadline, Worker stop): an advance that
- * does not wind down within the lease is taken over when it lapses (`worker.ts`).
+ * Runs one segment in a harness and settles it. Throws only `ownership.lost`, `SegmentStopped`,
+ * `HarnessUnavailable` and infrastructure errors. `onTaken` runs when a harness takes the run.
  */
-function startHeartbeat(ctx, lease, controller) {
-    const every = Math.max(10, Math.floor(ctx.ownerLeaseMs / 3));
-    let stopped = false;
-    let timer;
-    const beat = async () => {
-        if (controller.signal.aborted) {
-            stopped = true;
-            return;
-        }
-        try {
-            const renewed = await ctx.store.tx((t) => t.renewOwnership(lease.sessionId, lease.owner, lease.epoch, new Date(Date.now() + ctx.ownerLeaseMs)));
-            if (!renewed && !stopped) {
-                stopped = true;
-                controller.abort(new AdvanceAbort("ownership.lost", "Ownership lost"));
-                return;
-            }
-        }
-        catch (error) {
-            if (!stopped)
-                ctx.config.logger.warn("advance heartbeat failed", {
-                    sessionId: lease.sessionId,
-                    message: error instanceof Error ? error.message : String(error),
-                });
-        }
-        arm();
-    };
-    const arm = () => {
-        if (stopped)
-            return;
-        timer = setTimeout(() => void beat(), every);
-        timer.unref();
-    };
-    arm();
-    return {
-        stop() {
-            stopped = true;
-            clearTimeout(timer);
-        },
-    };
-}
-/** Segment rollover defaults (Model Calls §10), well inside the advance deadline. */
-const ROLLOVER_STEPS = 50;
-const ROLLOVER_MS = 20 * 60_000;
-/** Runs one segment and settles it. Throws only `ownership.lost` and infrastructure errors. */
-async function runSegment(ctx, lease, started, signal) {
-    const id = lease.sessionId;
+async function runRemoteSegment(ctx, lease, started, controller, run, onTaken, placed = {}) {
+    const { signal } = controller;
+    let end;
     try {
-        // prepareMcp mutates the session's mcpSnapshot; read current after it.
-        if (!isWorkflowManifest(started.manifest))
-            await prepareMcp(ctx, lease, signal);
-        const { current, fixtureModel } = await ownedTx(ctx.store, id, lease.epoch, async (t, current) => {
-            if (!isWorkflowManifest(current.manifest) && current.checkpoint) {
-                rebaseSessionState(current, current.checkpoint.manifestHash);
-                await adoptStoredTranscript(t, current);
-                const cp = current.checkpoint;
-                current.checkpoint = { ...cp, state: current.state };
-                await t.put("sessions", id, current);
-            }
-            return { current, fixtureModel: await usesFixtureModel(t) };
+        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.
+        const unusable = podUnusable(ctx, segment);
+        if (unusable)
+            throw new Error(unusable);
+        const pod = segment.pod?.id;
+        if (pod !== undefined)
+            placed.pod = pod;
+        end = await ctx.harness.offer({
+            lease,
+            start: buildTurnStart(ctx, segment),
+            controller,
+            transcript: segment.transcript,
+            run,
+            onTaken,
+            ...(pod === undefined ? {} : { pod, waitMs: POD_OFFER_WAIT_MS }),
         });
-        // One history (P0.3): the engine resumes from the transcript folded from the record.
-        let startTranscript = [];
-        let engineCheckpoint = current.checkpoint;
-        if (!isWorkflowManifest(current.manifest) && current.checkpoint) {
-            const cp = current.checkpoint;
-            if (cp.state) {
-                startTranscript = await foldSession(ctx, current);
-                checkParity(id, startTranscript, transcriptOf(cp.state));
-                engineCheckpoint = { ...cp, state: withTranscript(cp.state, startTranscript) };
-            }
+        if (end.kind === "unavailable") {
+            // A pod stopped, or not yet started: make sure it is asked to run.
+            if (pod !== undefined)
+                await ctx.sandboxSignal(pod, { kind: "reconcile" }).catch(() => undefined);
+            throw new HarnessUnavailable();
         }
-        const segment = fixtureModel ? { model: fixture } : {};
-        const host = {
-            resolveEffect: (e) => resolveEffect(ctx, e, signal, lease, segment),
-        };
-        const result = isWorkflowManifest(current.manifest)
-            ? await runFlowDurable({
-                manifest: current.manifest,
-                checkpoint: current.checkpoint,
-                signal,
-                host,
-                limits: ctx.flowLimits,
-            })
-            : await runDurable({
-                manifest: turnManifestOf(current),
-                checkpoint: engineCheckpoint,
-                signal,
-                sessionTools: sessionToolsOf(current.mcpSnapshot),
-                host,
-                yieldAfter: {
-                    steps: ctx.config.rollover?.steps ?? ROLLOVER_STEPS,
-                    ms: ctx.config.rollover?.ms ?? ROLLOVER_MS,
-                },
-            });
-        // The engine turns an abort into a `cancelled` (agents) or `failed` (workflows) result;
-        // only a user cancel may settle that, and it already did.
+        // Aborted before a harness took it: settled as an abort of the engine would be.
+        if (end.kind === "aborted")
+            throw signal.reason;
+        // 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;
+        if (output.thrown)
+            throw thrownError(output.thrown);
+        const result = resultOf(output, segment);
+        let cursor;
         if (signal.reason instanceof AdvanceDeadlineError &&
             (result.status === "cancelled" || result.status === "failed"))
             await settleFailure(ctx, lease, started, signal.reason);
         else {
-            const state = !isWorkflowManifest(current.manifest) &&
-                (result.status === "yielded" || result.status === "completed" || result.status === "paused") &&
-                "result" in result
-                ? result.result?.state
-                : undefined;
-            const updates = state ? transcriptUpdates(startTranscript, transcriptOf(state)) : [];
-            await settle(ctx, lease, started, result, updates);
+            const recorded = result.status === "yielded" || result.status === "completed" || result.status === "paused";
+            cursor = await settleTurn(ctx, lease, started, result, recorded ? output.transcript ?? [] : [], signal, segment.cursor);
         }
+        end.reply(cursor === undefined ? {} : { cursor });
     }
     catch (error) {
-        if (isOwnershipLost(error) || error instanceof SegmentStopped)
+        if (end?.kind === "output")
+            end.refuse(error);
+        if (isOwnershipLost(error) ||
+            error instanceof SegmentStopped ||
+            error instanceof HarnessUnavailable ||
+            error instanceof RunLost)
             throw error;
         stopIfLeaving(signal);
         // A segment stopped by its deadline fails with the deadline, not the abort it caused.
@@ -318,6 +341,47 @@ async function runSegment(ctx, lease, started, signal) {
         await settleFailure(ctx, lease, started, deadline ? signal.reason : error);
     }
 }
+/** The error an engine threw in the harness, as it would have been thrown here. */
+function thrownError(thrown) {
+    const error = new Error(thrown.message);
+    // A lost epoch stops the segment without a write, wherever it was noticed.
+    return thrown.code === "ownership_lost"
+        ? Object.assign(error, { code: "ownership.lost" })
+        : error;
+}
+/**
+ * A harness's output as the engine's result, so `settle` is unchanged. The checkpoint is the
+ * segment's own (with the agent's new state); in shadow mode the state gets back the transcript
+ * the harness edited.
+ */
+function resultOf(output, segment) {
+    const { current } = segment;
+    const status = output.status ?? "failed";
+    if (status === "waiting" || status === "uncertain")
+        return {
+            status,
+            checkpoint: current.checkpoint,
+            effectIds: output.effectIds ?? [],
+        };
+    let state = output.state;
+    if (state !== undefined && transcriptShadow())
+        state = withTranscript(state, applyUpdates(segment.transcript, output.transcript ?? []));
+    const checkpoint = state === undefined || isWorkflowManifest(current.manifest)
+        ? current.checkpoint
+        : { ...current.checkpoint, state };
+    return {
+        status,
+        checkpoint,
+        result: {
+            status,
+            ...(state === undefined ? {} : { state }),
+            ...(output.output === undefined ? {} : { output: output.output }),
+            ...(output.pending === undefined ? {} : { pending: output.pending }),
+            ...(output.error === undefined ? {} : { error: output.error }),
+        },
+        ...(output.cancelEffectIds ? { cancelEffectIds: output.cancelEffectIds } : {}),
+    };
+}
 /** Wake the workflow a linked agent belongs to, in the agent's settle transaction. */
 async function wakeWorkflowOf(ctx, t, agent, turnId, type, payload) {
     if (type === "turn.completed" || type === "turn.failed")
@@ -344,9 +408,25 @@ async function wakeWorkflowOf(ctx, t, agent, turnId, type, payload) {
             schedule: ctx.wake,
         });
 }
-/** Record a segment result, then cancel failed siblings and wake a linked workflow. */
-async function settle(ctx, lease, s, result, updates = []) {
+/**
+ * `settle`, then, for a completed turn, the turn-end export of its sandbox outputs (F8.2): after
+ * 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);
+    if (result.status === "completed")
+        await exportOutputs(ctx, lease.sessionId, s.activeTurnId, signal);
+    return kept;
+}
+/**
+ * Record a segment result, then cancel failed siblings and wake a linked workflow. Returns the
+ * 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) {
     const id = lease.sessionId;
+    let kept;
     const siblingCancelIds = await ownedTx(ctx.store, id, lease.epoch, async (t, current) => {
         const siblings = [];
         if (current.status === "cancelled" ||
@@ -381,7 +461,7 @@ async function settle(ctx, lease, s, result, updates = []) {
         if (result.status === "yielded") {
             // The turn goes on in a new segment: same turn, next checkpoint, woken right away.
             const finished = result.checkpoint;
-            await recordTranscript(t, id, s.activeTurnId, current, updates);
+            kept = (await recordTranscript(t, id, s.activeTurnId, current, updates)) ?? cursor;
             current.state = leanState(result.result.state);
             current.checkpoint = {
                 ...finished,
@@ -402,8 +482,11 @@ async function settle(ctx, lease, s, result, updates = []) {
         }
         const flow = isWorkflowManifest(current.manifest);
         if (!flow) {
-            if (result.status !== "failed")
-                await recordTranscript(t, id, s.activeTurnId, current, updates);
+            if (result.status !== "failed") {
+                const last = await recordTranscript(t, id, s.activeTurnId, current, updates);
+                if (result.status !== "cancelled")
+                    kept = last ?? cursor;
+            }
             current.state =
                 result.status === "failed"
                     ? current.turnStartState
@@ -480,6 +563,7 @@ async function settle(ctx, lease, s, result, updates = []) {
             /* agent may already be terminal */
         }
     }
+    return kept;
 }
 /** A segment threw: fail the turn, restore the turn-start state, wake a linked workflow. */
 async function settleFailure(ctx, lease, s, error) {
@@ -508,43 +592,17 @@ function leanCheckpoint(checkpoint) {
         return checkpoint;
     return { ...checkpoint, state: leanState(state) };
 }
-/** Appends a segment's transcript edits; a snapshot moves `history.snapshot`. */
+/**
+ * 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) {
+    let last;
     for (const update of updates) {
         const event = await t.event(id, turnId, "transcript.updated", update);
         if (update.keep === 0)
             s.history = { from: s.history?.from ?? event.seq, snapshot: event.seq };
+        last = event.seq;
     }
-}
-/**
- * A session written before transcripts were recorded keeps its transcript on its row: record
- * it once (the turn's starting transcript, then the turn so far), and store the row lean.
- */
-async function adoptStoredTranscript(t, s) {
-    if (s.history)
-        return;
-    const now = transcriptOf(s.state);
-    const start = s.activeTurnId ? transcriptOf(s.turnStartState) : now;
-    if (now.length === 0 && start.length === 0)
-        return;
-    let first;
-    const write = async (turnId, updates) => {
-        for (const update of updates) {
-            const event = await t.event(s.id, turnId, "transcript.updated", update);
-            first ??= event.seq;
-        }
-    };
-    await write(null, transcriptUpdates([], start));
-    if (s.activeTurnId)
-        await write(s.activeTurnId, transcriptUpdates(start, now));
-    s.history = { from: first ?? 0, snapshot: first ?? 0 };
-    s.state = leanState(s.state);
-    s.turnStartState = leanState(s.turnStartState);
-}
-/** The session's transcript, folded from its record from `history.from`. */
-async function foldSession(ctx, s) {
-    const rows = await ctx.store
-        .record()
-        .readRange(ctx.store.tenantId, s.id, s.history?.from ?? 0, Number.MAX_SAFE_INTEGER);
-    return foldTranscript(rows.map((row) => row.body));
+    return last;
 }

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

@@ -0,0 +1,5 @@
+import type { SandboxToolOutcome } from "@nylorun/core/contracts";
+import type { HostEffect } from "@nylorun/harness/run";
+import { type TenantContext } from "./context.js";
+export { isSaveArtifactCall } from "../harness/calls.js";
+export declare function callSaveArtifact(ctx: TenantContext, request: HostEffect, signal: AbortSignal): Promise<SandboxToolOutcome>;

package/dist/tenant/artifact-tool.js

@@ -0,0 +1,119 @@
+/**
+ * `nylorun.save_artifact` (F8.1): our engine's built-in tool that saves a file as an artifact
+ * of its session. The `nylorun.artifacts` capability comes with a session's sandbox
+ * (`sandbox/session-sandbox.ts`); the Runtime runs the tool itself, like the sandbox tools:
+ *
+ * - `path`: a file in the session's sandbox, read as bytes in the sandbox's queue;
+ * - `content`: text the model passes.
+ *
+ * The version commits with `artifact.created` (or `artifact.version.created`) on the session's
+ * stream, carrying the turn and the tool call. Expected problems (no such file, too large, the
+ * Tenant's total reached) are failed outcomes the model sees; only infrastructure errors throw.
+ */
+import { basename } from "node:path";
+import { SANDBOX_CAPABILITY_ID } from "@nylorun/core/define";
+import { isArtifactId } from "@nylorun/core/compatibility";
+import { readArtifactLimits } from "../artifacts/config.js";
+import { contentTypeFor, normalizeContentType } from "../artifacts/media-types.js";
+import { uploadArtifact } from "../artifacts/service.js";
+import { DEFAULT_CONTENT_TYPE } from "../blob/index.js";
+import { sandboxCapabilityOf } from "../sandbox/manager.js";
+import { sandboxWorkspaceOf } from "../sandbox/share.js";
+import { sandboxLookup, sessionOf } from "./context.js";
+import { HttpError } from "./http.js";
+import { manifestFor } from "./session.js";
+import { toolIds } from "./transcript.js";
+export { isSaveArtifactCall } from "../harness/calls.js";
+const failed = (code, message) => ({
+    kind: "failed",
+    code,
+    message,
+});
+export async function callSaveArtifact(ctx, request, signal) {
+    const input = (request.input ?? {});
+    const path = typeof input.path === "string" && input.path !== "" ? input.path : undefined;
+    const content = typeof input.content === "string" ? input.content : undefined;
+    if ((path === undefined) === (content === undefined))
+        return failed("artifact.invalid_input", "Give path or content, not both.");
+    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),
+            limits: await readArtifactLimits(t),
+            ours,
+        };
+    });
+    if (!ours)
+        return failed("artifact.not_found", `Artifact ${artifactId} is not an artifact of this session.`);
+    let bytes;
+    let fileName;
+    if (path !== undefined) {
+        const capability = sandboxCapabilityOf(manifestFor(s.manifest, request.agent), SANDBOX_CAPABILITY_ID, "read");
+        if (!capability)
+            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);
+        if (read.kind === "failed")
+            return read;
+        if (read.kind === "missing")
+            return failed("artifact.not_found", `${read.path} does not exist in the sandbox.`);
+        bytes = read.bytes;
+        fileName = basename(read.path);
+    }
+    else {
+        bytes = new TextEncoder().encode(content);
+        fileName = "artifact.txt";
+    }
+    const name = typeof input.name === "string" && input.name !== "" ? input.name : fileName;
+    let contentType;
+    if (typeof input.contentType === "string") {
+        const declared = normalizeContentType(input.contentType);
+        if (declared === undefined)
+            return failed("artifact.invalid_input", `${input.contentType} is not a media type.`);
+        contentType = declared;
+    }
+    else {
+        contentType = contentTypeFor(name);
+        if (content !== undefined && contentType === DEFAULT_CONTENT_TYPE)
+            contentType = "text/plain; charset=utf-8";
+    }
+    const ids = toolIds(request.context);
+    try {
+        const saved = await uploadArtifact(ctx, {
+            ...(artifactId !== undefined ? { artifactId } : { name }),
+            contentType,
+            sessionId: s.id,
+            source: "engine",
+            turnId: request.turnId,
+            ...("callId" in ids ? { callId: ids.callId } : {}),
+        }, bytes, 
+        // Our engine saves into its own session only.
+        { owner: s.ownerUserId }, signal);
+        return {
+            kind: "completed",
+            output: {
+                artifactId: saved.artifact.artifactId,
+                version: saved.version.version,
+                name: saved.artifact.name,
+                contentType: saved.version.contentType,
+                size: saved.version.size,
+                sha256: saved.version.sha256,
+            },
+        };
+    }
+    catch (error) {
+        if (error instanceof HttpError)
+            return failed(error.rejection.code === "limit_exceeded" ? "artifact.too_large" : "artifact.rejected", error.message);
+        throw error;
+    }
+}