@nylorun/runtime 0.26.0-beta → 0.28.0-beta

package/dist/reads/cursor.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { z } from "zod";
 import { decodeCursor } from "../record/index.js";
 import { fail } from "../tenant/http.js";
+import { maxHeaderSize } from "node:http";
 const schema = z
     .object({
     version: z.literal(1),
@@ -23,7 +24,8 @@ export function readCursor(tenant, route, filters) {
         decode(value) {
             if (value === undefined)
                 return undefined;
-            if (value.length > 4096 || !/^[A-Za-z0-9_-]+$/.test(value))
+            // A cursor comes back in a URL, which Node refuses past `http.maxHeaderSize` anyway.
+            if (value.length > maxHeaderSize || !/^[A-Za-z0-9_-]+$/.test(value))
                 return fail(400, "Invalid cursor", { code: "cursor_invalid" });
             let parsed;
             try {

package/dist/reads/types.d.ts

@@ -1,4 +1,4 @@
-import type { ArtifactKind, ArtifactPage, ModelCallExportPage, ModelCallsPage, EnvironmentPage, ToolCallsPage, SessionManifestView, SessionPage, SessionListItem, SessionUsageTotals, LiveEvent } from "@nylorun/core/contracts";
+import type { ArtifactKind, ArtifactPage, ModelCallExportPage, ModelCallsPage, ToolCallsPage, SessionManifestView, SessionPage, SessionListItem, SessionUsageTotals, LiveEvent } from "@nylorun/core/contracts";
 export type ReadAccess = {
     owner?: string;
     agents?: readonly string[];
@@ -6,7 +6,8 @@ export type ReadAccess = {
 export type SessionFilters = {
     agentId?: string;
     status?: SessionListItem["status"];
-    environmentId?: string;
+    /** Sessions that pinned a version of this agent manifest. */
+    manifest?: string;
     ownerUserId?: string;
 };
 export type PageOptions = {
@@ -33,6 +34,5 @@ export interface ReadStore {
      * for a turn the session never had.
      */
     turnEvents(id: string, turnId: string, access: ReadAccess): Promise<LiveEvent[]>;
-    environments(labels: Record<string, string>, page: PageOptions, access: ReadAccess, grants?: readonly string[]): Promise<EnvironmentPage>;
     close(): Promise<void>;
 }

package/dist/record/agent.d.ts

@@ -0,0 +1,27 @@
+import { type AgentEvent, type AgentEventPayload, type AgentEventType } from "@nylorun/core/contracts";
+/** The Agent stream's two statements, in the caller's transaction. */
+export interface AgentRecordWriter {
+    /** The seq the Agent's next event takes: one past its last, or 0. */
+    nextSeq(agentId: string): Promise<number>;
+    insert(row: {
+        agentId: string;
+        seq: number;
+        type: string;
+        body: AgentEvent;
+    }): Promise<void>;
+}
+export interface AgentAppendInput<T extends AgentEventType> {
+    tenantId: string;
+    agentId: string;
+    time: Date;
+    type: T;
+    payload: AgentEventPayload<T>;
+    /** The Tenant's Runtime limit `recordEntryBytes`, as for a session's events. */
+    maxEntryBytes: number;
+}
+/** Builds the event and checks it against the Agent event catalog. */
+export declare function buildAgentEvent<T extends AgentEventType>(input: AgentAppendInput<T> & {
+    seq: number;
+}): AgentEvent;
+/** Appends one event to the Agent's stream through `writer`. */
+export declare function appendAgentEvent<T extends AgentEventType>(writer: AgentRecordWriter, input: AgentAppendInput<T>): Promise<AgentEvent>;

package/dist/record/agent.js

@@ -0,0 +1,46 @@
+/**
+ * An Agent's lifecycle stream (blueprint D39, F7.1; an Environment's before protocol 16):
+ * `agent.created`, `agent.attached`, `agent.detached` and `agent.deleted` (and the rest of
+ * `AGENT_EVENT_TYPES`, egress-gate's `agent.egress` for every connection among them, D67), on
+ * the `nylorun.agent-event/1` envelope, numbered from 0 per Agent id in
+ * `nylorun_streams.agent_events`. The record module is its only writer, as for session events;
+ * the store runs the two statements through `AgentRecordWriter` in the caller's transaction, under
+ * the Agent row's lock (or, for an Agent being created, its new row).
+ *
+ * The stream lives in the record only: it is not published to the stream relay, so no S2 stream
+ * follows it yet. Clients read it with `GET /v1/agents/{id}/events`.
+ */
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { AGENT_EVENT_PAYLOADS, AGENT_EVENT_SCHEMA, AgentEventSchema, } from "@nylorun/core/contracts";
+import { InvalidEventError } from "./envelope.js";
+import { checkEntry } from "./append.js";
+/** Builds the event and checks it against the Agent event catalog. */
+export function buildAgentEvent(input) {
+    const payload = AGENT_EVENT_PAYLOADS[input.type];
+    const checkedPayload = payload.safeParse(input.payload);
+    if (!checkedPayload.success)
+        throw new InvalidEventError(input.type, z.prettifyError(checkedPayload.error));
+    const event = JSON.parse(JSON.stringify({
+        schema: AGENT_EVENT_SCHEMA,
+        eventId: randomUUID(),
+        tenantId: input.tenantId,
+        agentId: input.agentId,
+        seq: input.seq,
+        time: input.time.toISOString(),
+        type: input.type,
+        payload: input.payload,
+    }));
+    const checked = AgentEventSchema.safeParse(event);
+    if (!checked.success)
+        throw new InvalidEventError(input.type, z.prettifyError(checked.error));
+    return event;
+}
+/** Appends one event to the Agent's stream through `writer`. */
+export async function appendAgentEvent(writer, input) {
+    checkEntry(`The ${input.type} event's payload`, input.payload, input.maxEntryBytes);
+    const seq = await writer.nextSeq(input.agentId);
+    const event = buildAgentEvent({ ...input, seq });
+    await writer.insert({ agentId: input.agentId, seq, type: input.type, body: event });
+    return event;
+}

package/dist/record/append.d.ts

@@ -9,8 +9,37 @@
  * The two statements run through `RecordWriter`, which the store implements on its
  * transaction (`store/postgres/record-writer.ts`): the database driver stays behind
  * `store/postgres/` (session-store.md §3), and this module decides what is written.
+ *
+ * Every entry is held to the Tenant's Runtime limit `recordEntryBytes`, which the caller reads
+ * and passes: an event whose payload is larger is refused (`RecordEntryTooLargeError`) before
+ * anything is written, whoever wrote it, so no record reaches S2 past its 1 MiB.
+ */
+import { type EventPayload, type EventType, type EventWriter, type LiveEvent, type SessionEventOf } from "@nylorun/core/contracts";
+/**
+ * An entry larger than the Tenant's `recordEntryBytes`: `limit_exceeded`, `413` to an API client
+ * and the Harness API error code to a harness.
  */
-import type { EventPayload, EventType, EventWriter, LiveEvent, SessionEventOf } from "@nylorun/core/contracts";
+export declare class RecordEntryTooLargeError extends Error {
+    readonly bytes: number;
+    readonly maxBytes: number;
+    readonly code: "limit_exceeded";
+    readonly status = 413;
+    readonly rejection: {
+        readonly code: "limit_exceeded";
+        readonly details: {
+            readonly limit: "recordEntryBytes";
+            readonly bytes: number;
+            readonly maxBytes: number;
+        };
+    };
+    constructor(
+    /** What was refused, as the message names it: "The message.user event's payload". */
+    what: string, bytes: number, maxBytes: number);
+}
+/** The JSON size of an entry, in bytes: what the record holds of it. */
+export declare function entryBytes(value: unknown): number;
+/** Throws `RecordEntryTooLargeError` when `entry` is larger than `maxBytes`; `what` names it. */
+export declare function checkEntry(what: string, entry: unknown, maxBytes: number): void;
 /** The record's two statements, in the caller's transaction. */
 export interface RecordWriter {
     /**
@@ -42,10 +71,13 @@ export interface AppendInput<T extends EventType> {
     payload: EventPayload<T>;
     /** Who wrote it (R4.9). */
     writer?: EventWriter;
+    /** The Tenant's Runtime limit `recordEntryBytes`: the most bytes the payload may hold, as JSON. */
+    maxEntryBytes: number;
 }
 /**
  * Appends one event through `writer`. An event the catalog does not describe throws
- * `InvalidEventError` before its row is written; the caller's transaction then rolls back.
+ * `InvalidEventError`, and one past `maxEntryBytes` `RecordEntryTooLargeError`, before its row is
+ * written; the caller's transaction then rolls back.
  */
 export declare function appendEvent<T extends EventType>(writer: RecordWriter, input: AppendInput<T>): Promise<{
     event: SessionEventOf<T>;

package/dist/record/append.js

@@ -1,9 +1,58 @@
+/**
+ * The only write path into the record (Durable Streams §6, blueprint D27): the session's log
+ * head allocates the next sequence, the event is built on the envelope and checked against the
+ * catalog, and its row is written, both in the caller's transaction. The database holds one
+ * Tenant, so rows are keyed by session alone; the Tenant id is the caller's and goes into the
+ * envelope only. The caller holds the session row lock, which orders the session's appends,
+ * and passes the epoch it read under that lock.
+ *
+ * The two statements run through `RecordWriter`, which the store implements on its
+ * transaction (`store/postgres/record-writer.ts`): the database driver stays behind
+ * `store/postgres/` (session-store.md §3), and this module decides what is written.
+ *
+ * Every entry is held to the Tenant's Runtime limit `recordEntryBytes`, which the caller reads
+ * and passes: an event whose payload is larger is refused (`RecordEntryTooLargeError`) before
+ * anything is written, whoever wrote it, so no record reaches S2 past its 1 MiB.
+ */
+import { limitExceededMessage, } from "@nylorun/core/contracts";
 import { buildEvent } from "./envelope.js";
+/**
+ * An entry larger than the Tenant's `recordEntryBytes`: `limit_exceeded`, `413` to an API client
+ * and the Harness API error code to a harness.
+ */
+export class RecordEntryTooLargeError extends Error {
+    bytes;
+    maxBytes;
+    code = "limit_exceeded";
+    status = 413;
+    rejection;
+    constructor(
+    /** What was refused, as the message names it: "The message.user event's payload". */
+    what, bytes, maxBytes) {
+        super(limitExceededMessage(what, bytes, "recordEntryBytes", maxBytes));
+        this.bytes = bytes;
+        this.maxBytes = maxBytes;
+        this.name = "RecordEntryTooLargeError";
+        this.rejection = { code: "limit_exceeded", details: { limit: "recordEntryBytes", bytes, maxBytes } };
+    }
+}
+/** The JSON size of an entry, in bytes: what the record holds of it. */
+export function entryBytes(value) {
+    return Buffer.byteLength(JSON.stringify(value) ?? "null");
+}
+/** Throws `RecordEntryTooLargeError` when `entry` is larger than `maxBytes`; `what` names it. */
+export function checkEntry(what, entry, maxBytes) {
+    const bytes = entryBytes(entry);
+    if (bytes > maxBytes)
+        throw new RecordEntryTooLargeError(what, bytes, maxBytes);
+}
 /**
  * Appends one event through `writer`. An event the catalog does not describe throws
- * `InvalidEventError` before its row is written; the caller's transaction then rolls back.
+ * `InvalidEventError`, and one past `maxEntryBytes` `RecordEntryTooLargeError`, before its row is
+ * written; the caller's transaction then rolls back.
  */
 export async function appendEvent(writer, input) {
+    checkEntry(`The ${input.type} event's payload`, input.payload, input.maxEntryBytes);
     const { seq, generation } = await writer.advance(input.sessionId);
     const event = buildEvent({
         tenantId: input.tenantId,

package/dist/record/index.d.ts

@@ -8,5 +8,5 @@
  */
 export { buildEvent, InvalidEventError, type EventInput } from "./envelope.js";
 export { decodeCursor, encodeCursor } from "./cursor.js";
-export { appendEvent, type AppendInput, type RecordWriter } from "./append.js";
-export { appendEnvironmentEvent, buildEnvironmentEvent, type EnvironmentAppendInput, type EnvironmentRecordWriter, } from "./environment.js";
+export { RecordEntryTooLargeError, appendEvent, checkEntry, entryBytes, type AppendInput, type RecordWriter, } from "./append.js";
+export { appendAgentEvent, buildAgentEvent, type AgentAppendInput, type AgentRecordWriter, } from "./agent.js";

package/dist/record/index.js

@@ -8,5 +8,5 @@
  */
 export { buildEvent, InvalidEventError } from "./envelope.js";
 export { decodeCursor, encodeCursor } from "./cursor.js";
-export { appendEvent } from "./append.js";
-export { appendEnvironmentEvent, buildEnvironmentEvent, } from "./environment.js";
+export { RecordEntryTooLargeError, appendEvent, checkEntry, entryBytes, } from "./append.js";
+export { appendAgentEvent, buildAgentEvent, } from "./agent.js";

package/dist/redact.d.ts

@@ -8,7 +8,7 @@ export interface ScrubOptions {
     readonly counted?: (replacements: number) => void;
 }
 /**
- * `value` with each of `secrets` (those of at least 8 characters) replaced by `[redacted]`. By
+ * `value` with each of `secrets` (those of at least `harness.scrubMinChars`, 8 by default) replaced by `[redacted]`. By
  * default also any value under a key such as `token` or `secret`, and inline image data.
  */
 export declare function scrub(value: unknown, secrets: readonly string[], options?: ScrubOptions): unknown;

package/dist/redact.js

@@ -1,10 +1,11 @@
+import { hostTuning } from "./tuning.js";
 /**
- * `value` with each of `secrets` (those of at least 8 characters) replaced by `[redacted]`. By
+ * `value` with each of `secrets` (those of at least `harness.scrubMinChars`, 8 by default) replaced by `[redacted]`. By
  * default also any value under a key such as `token` or `secret`, and inline image data.
  */
 export function scrub(value, secrets, options = {}) {
     // The longest first, so a header value goes whole before the token inside it.
-    const sorted = secrets.filter((secret) => secret.length >= 8).sort((a, b) => b.length - a.length);
+    const sorted = secrets.filter((secret) => secret.length >= hostTuning().harness.scrubMinChars).sort((a, b) => b.length - a.length);
     let replaced = 0;
     const walk = (item) => {
         if (typeof item === "string") {

package/dist/sandbox/egress-token.d.ts

@@ -14,10 +14,10 @@
  * check (`EgressSandboxes.live`).
  */
 import type { SessionStore } from "../store/types.js";
-import { EGRESS_TOKEN_AUD, EGRESS_TOKEN_TYP, mintEgressToken, type EgressTokenRequest, type HostClaims, type HostTokenKeyCache, type HostTokenVerdict } from "../tenant/host-token.js";
+import { EGRESS_TOKEN_AUD, EGRESS_TOKEN_TYP, hostTokenTtlSeconds, mintEgressToken, type EgressTokenRequest, type HostClaims, type HostTokenKeyCache, type HostTokenVerdict } from "../tenant/host-token.js";
 export { EGRESS_TOKEN_AUD, EGRESS_TOKEN_TYP, mintEgressToken, type EgressTokenRequest };
-/** The longest lifetime an egress token has: a host token's. */
-export declare const EGRESS_TOKEN_MAX_TTL_SECONDS: number;
+/** The longest lifetime an egress token has: a host token's (`keys.hostTokenTtlSeconds`). */
+export declare const egressTokenMaxTtlSeconds: typeof hostTokenTtlSeconds;
 export type EgressClaims = HostClaims;
 export type EgressTokenVerdict = HostTokenVerdict;
 /** Public keys imported by key id; the key row is still read on every verification. */

package/dist/sandbox/egress-token.js

@@ -1,7 +1,7 @@
-import { EGRESS_TOKEN_AUD, EGRESS_TOKEN_TYP, HOST_TOKEN_TTL_SECONDS, mintEgressToken, verifyHostToken, } from "../tenant/host-token.js";
+import { EGRESS_TOKEN_AUD, EGRESS_TOKEN_TYP, hostTokenTtlSeconds, mintEgressToken, verifyHostToken, } from "../tenant/host-token.js";
 export { EGRESS_TOKEN_AUD, EGRESS_TOKEN_TYP, mintEgressToken };
-/** The longest lifetime an egress token has: a host token's. */
-export const EGRESS_TOKEN_MAX_TTL_SECONDS = HOST_TOKEN_TTL_SECONDS;
+/** The longest lifetime an egress token has: a host token's (`keys.hostTokenTtlSeconds`). */
+export const egressTokenMaxTtlSeconds = hostTokenTtlSeconds;
 /** Verifies an egress token of Tenant `tenantId`; refusal reasons are `egress_token_*`. */
 export function verifyEgressToken(store, tenantId, raw, cache = new Map()) {
     return verifyHostToken(store, tenantId, raw, "egress", cache);

package/dist/sandbox/join.js

@@ -32,10 +32,11 @@
  * which check failed.
  */
 import { createHash, timingSafeEqual } from "node:crypto";
-import { isEnvironmentId } from "@nylorun/core/contracts";
+import { isAgentId } from "@nylorun/core/contracts";
 import { recoverLostVolume, runPendingSeed } from "../artifacts/disk.js";
 import { recordSetup, setupFile, setupPlanOf, setupState, } from "./setup.js";
 import { mintHostTokens, staleHost, verifyHostToken, } from "../tenant/host-token.js";
+import { JOIN_TOKEN_MAX, POD_UID_PATTERN } from "@nylorun/core/harness-api";
 /** A refused join, renewal or host connection. */
 export class HostAuthError extends Error {
     status;
@@ -49,7 +50,7 @@ export class HostAuthError extends Error {
         this.reason = reason;
     }
 }
-const POD_UID = /^[A-Za-z0-9-]{1,64}$/;
+const POD_UID = POD_UID_PATTERN;
 const REFUSED = "The join was refused";
 export function sha256Hex(value) {
     return createHash("sha256").update(value).digest("hex");
@@ -86,12 +87,12 @@ export function hostAuthority(ctx) {
     return {
         async join(request) {
             const { sandboxId, podUid, joinToken, volumeId } = request;
-            if (!isEnvironmentId(sandboxId) ||
+            if (!isAgentId(sandboxId) ||
                 typeof podUid !== "string" ||
                 !POD_UID.test(podUid) ||
                 typeof joinToken !== "string" ||
                 joinToken.length === 0 ||
-                joinToken.length > 512 ||
+                joinToken.length > JOIN_TOKEN_MAX ||
                 (volumeId !== undefined && (typeof volumeId !== "string" || !POD_UID.test(volumeId))))
                 throw new HostAuthError(400, "A join is { sandboxId, podUid, joinToken }");
             const pods = ctx.pods;
@@ -135,7 +136,7 @@ export function hostAuthority(ctx) {
                     // A new, empty volume under the same Sandbox: the sandbox's files are gone.
                     const reason = "The sandbox's volume was replaced: its files are gone";
                     await t.updateEnvironmentPod(sandboxId, { observed: "lost", reason, hostEpoch: epoch }, now);
-                    await t.environmentEvent(sandboxId, "environment.lost", { reason });
+                    await t.agentEvent(sandboxId, "agent.lost", { reason });
                     // Its Sandbox is deleted; only a reset brings the sandbox back.
                     await t.signal({ type: "host.revoked", sandboxId, epoch });
                     await t.signalSandbox(sandboxId, { kind: "reconcile" });
@@ -149,9 +150,9 @@ export function hostAuthority(ctx) {
                 }, now);
                 if (pod.podUid !== podUid) {
                     if (pod.podUid !== undefined)
-                        await t.environmentEvent(sandboxId, "environment.relaunched", { hostEpoch: epoch });
+                        await t.agentEvent(sandboxId, "agent.relaunched", { hostEpoch: epoch });
                     else
-                        await t.environmentEvent(sandboxId, "environment.running", { hostEpoch: epoch });
+                        await t.agentEvent(sandboxId, "agent.running", { hostEpoch: epoch });
                 }
                 // The previous host's connection (an older epoch) serves nothing more, on any process.
                 await t.signal({ type: "host.revoked", sandboxId, epoch });

package/dist/sandbox/manager.d.ts

@@ -1,38 +1,17 @@
-/**
- * Sandbox Manager: owns sandbox lifecycle for the Runtime. One workspace per sandbox resource
- * (`sandbox: { id }`, keyed by the sandbox id), or per owning session for a sandbox chosen
- * inline or by the Tenant default (keyed by the session id); created on the first sandbox tool
- * call, stopped after its idle timeout, reattached on the next call. Each session's calls on a
- * workspace run in the order it sends them, and different sessions' calls run at the same time
- * (D66): the sessions of one Environment run their turns at once. Opening, stopping and removing
- * a workspace run alone: a stop or removal waits for the calls running, and calls that come after
- * it wait for it.
- *
- * The manager keeps no timers and reaches no store: it keeps its compute records through a
- * `SandboxRecords` port (the Tenant's `sandboxes` table in core's process, a file in a harness's)
- * and writes its events through `emit`. Its owner drives it: `stopIdle` stops sandboxes idle
- * past their timeout and marks records of compute this process no longer holds as stopped
- * (after a restart); `reconcile` removes workspaces whose owner is gone. `sweep` does both, the
- * reconcile once per process, as the Tenant sweep does in core's process.
- *
- * A session's skills (track R2 M4) are mounted on its workspace, read-only, one folder per
- * version (`/skills/<name>@<hash>/`, D66), before the first call that needs them (`skills.ts`);
- * their bytes come through the `definitionFile` port.
- */
 import type { EventPayload } from "@nylorun/core/contracts";
-import { type AgentManifest, type SandboxManifest, type SandboxToolName } from "@nylorun/core/define";
+import { type SandboxManifest, type SandboxToolName } from "@nylorun/core/define";
 import { type SandboxRecord, type SandboxRecords } from "./records.js";
 import { type SandboxSelection, type SandboxSelectionReport } from "./select.js";
+import { type FolderFiles } from "./skills.js";
+import { type SandboxToolLimits } from "@nylorun/harness";
 import { type DiskAnswer, type DiskOp } from "./disk-fs.js";
 import { type SandboxToolOutcome } from "./tools.js";
-import { type SandboxBackend, type SandboxListing } from "./types.js";
-export { sandboxToolSpec } from "./runtime-tools.js";
+import { type SandboxBackend, type SandboxFileBytes, type SandboxListing } from "./types.js";
 export type { SandboxRecord, SandboxRecords, SandboxState } from "./records.js";
 export interface SandboxSessionRef {
     /** The session whose log records the workspace's events: the owning session. */
     readonly id: string;
     readonly activeTurnId: string | null;
-    readonly manifest?: AgentManifest;
     /**
      * The sandbox resource the owning session is attached to. Its workspace is keyed by this id,
      * so every session attached to it shares the files; absent, the workspace is the session's.
@@ -76,12 +55,6 @@ export interface SandboxManagerOptions {
     readonly preference: string | undefined;
     /** Delete sandboxes on close (the Runtime's store does not outlive the process). */
     readonly ephemeral: boolean;
-    /**
-     * A definition file's bytes by `sha256:<hex>`, for the skills a session's workspace mounts:
-     * the Tenant's Object store in core's process, core's answer in a harness (for the run that
-     * made the call, `session.claim`). Without it no skills are mounted.
-     */
-    readonly definitionFile?: (sha256: string, session: SandboxSessionRef) => Promise<Uint8Array>;
     /** Writes a session event (in core, in its own transaction; in a harness, as a claim). */
     readonly emit: <T extends SandboxEventType>(sessionId: string, turnId: string | null, type: T, payload: EventPayload<T>, meta: SandboxEventMeta) => void | Promise<void>;
 }
@@ -119,7 +92,11 @@ export declare class SandboxManager {
     report(): Promise<SandboxSelectionReport & {
         readonly defaultImage: string;
     }>;
-    run(session: SandboxSessionRef, sandbox: SandboxManifest | undefined, toolName: SandboxToolName, input: unknown, signal: AbortSignal): Promise<SandboxToolOutcome>;
+    /**
+     * Runs sandbox operation `toolName` in the session's sandbox, held to `limits`: the harness's
+     * sandbox tool limits (`DEFAULT_SANDBOX_TOOL_LIMITS` when it names none).
+     */
+    run(session: SandboxSessionRef, sandbox: SandboxManifest | undefined, toolName: SandboxToolName, input: unknown, signal: AbortSignal, limits?: SandboxToolLimits): Promise<SandboxToolOutcome>;
     /**
      * Runs `call` in session `sessionId`'s queue on `live`: after its earlier calls, and after any
      * stop or removal pending, beside other sessions' calls (D66).
@@ -130,8 +107,8 @@ export declare class SandboxManager {
     /** The workspace's handle, opened once for the calls that need it at the same time. */
     private handleOf;
     /**
-     * The bytes of one file in the session's sandbox, for `save_artifact` (F8.1), in the same queue
-     * as its tool calls: `missing` when there is no such file, a failed outcome when the sandbox
+     * The bytes of one file in the session's sandbox, for our engine's `save_artifact` and its
+     * outputs folder (`files.read`), in the same queue as its tool calls: `missing` when there is no such file, a failed outcome when the sandbox
      * cannot open or the file is larger than `maxBytes`. Relative paths resolve in the workspace.
      */
     readBytes(session: SandboxSessionRef, sandbox: SandboxManifest | undefined, path: string, maxBytes: number, signal: AbortSignal): Promise<{
@@ -145,8 +122,20 @@ export declare class SandboxManager {
         kind: "failed";
     }>>;
     /**
-     * The files under directory `dir` of the session's sandbox, for the turn-end export (F8.2), in
-     * the same queue as its tool calls. `missing` when the sandbox was never created (nothing is
+     * Writes `body` to one file of the session's sandbox, as it comes, for our engine's
+     * `read_artifact` with `path` (protocol 15), in the same queue as its tool calls: its folders
+     * are made first, and a file there is replaced. Relative paths resolve in the workspace.
+     */
+    writeBytes(session: SandboxSessionRef, sandbox: SandboxManifest | undefined, path: string, body: SandboxFileBytes, signal: AbortSignal): Promise<{
+        kind: "written";
+        path: string;
+        size: number;
+    } | Extract<SandboxToolOutcome, {
+        kind: "failed";
+    }>>;
+    /**
+     * The files under directory `dir` of the session's sandbox, for our engine's outputs folder
+     * (`files.list`, protocol 15), in the same queue as its tool calls. `missing` when the sandbox was never created (nothing is
      * started to look) or `dir` is not a directory. Relative paths resolve in the workspace.
      */
     listFiles(session: SandboxSessionRef, sandbox: SandboxManifest | undefined, dir: string, maxEntries: number, signal: AbortSignal): Promise<{
@@ -171,14 +160,25 @@ export declare class SandboxManager {
     /** The session's live sandbox entry and spec, or why it cannot run here. */
     private prepare;
     private execute;
+    /**
+     * The workspace's handle, opened when there is none. A start that fails is recorded as stopped
+     * and answered as a failed outcome: nothing ran yet, so it is definite, not uncertain.
+     */
+    private started;
     private executeOpen;
     /**
-     * Mounts the skill folders the session needs that the workspace does not hold (D66): on a
-     * handle just opened all of them, later only versions another session has not mounted. Calls
-     * that need one folder at once share its mount. A failed outcome when one cannot be mounted;
-     * the folder is not marked mounted then, so the next call tries again.
+     * Writes `files` (path in `folder` to `sha256:<hex>`) to `folder` of the session's sandbox,
+     * read-only, each one's bytes from `read`, in the session's queue (protocol 15: the harness
+     * decides which folders, and when). A folder the open handle already holds is `present` without
+     * an exec; calls that need one folder at once share its mount. A failed outcome when the sandbox
+     * cannot start or the folder cannot be written; it is not marked mounted then, so the next call
+     * tries again. A reopened handle holds none.
      */
-    private mountSkills;
+    mountFolder(session: SandboxSessionRef, sandbox: SandboxManifest | undefined, folder: string, files: FolderFiles, read: (sha256: string) => SandboxFileBytes | Promise<SandboxFileBytes>, signal: AbortSignal): Promise<{
+        kind: "mounted" | "present";
+    } | Extract<SandboxToolOutcome, {
+        kind: "failed";
+    }>>;
     private open;
     private stop;
     private record;