@nylorun/runtime 0.25.0-beta → 0.27.0-beta

package/dist/sandbox/session-sandbox.js

@@ -1,77 +0,0 @@
-/**
- * Gives a session the sandbox chosen when it was opened, and the Runtime tools its agents need.
- * An agent session's pinned manifest is its definition with a `runtime` block
- * (`runtimeManifestFor`) on each agent of the tree:
- *
- * - with a sandbox, the six sandbox tools, their instructions and the resolved spec, and
- *   `save_artifact`, so files the agent makes reach the user (F8.1). The agents it uses as tools
- *   get the same spec, so the tree shares one sandbox. The sandbox's instructions name the
- *   agent's skills' folders (`/skills/<name>@<hash>/`);
- * - with or without a sandbox, `read_artifact` (R2b C11, protocol 12): the Runtime stores a result
- *   of an MCP or HTTP tool too large to show as an artifact, and the model reads it in pages; a
- *   file of an earlier turn is a reference line the model reads again with it;
- * - with skills, `load_skill`, `read_skill_resource` and the skill catalog.
- *
- * `tool_search` and `tool_call` are not pinned: they are session tools, given per run when the
- * session defers some MCP tools (R2b C10). An author tool may not take any of these names (the
- * manifest schema refuses it), so a tool's name alone says whose it is. The definition in the
- * registry never changes.
- */
-import { AgentManifestSchema } from "@nylorun/core/contracts";
-import { hashManifest, runtimeManifestFor, } from "@nylorun/core/define";
-function isAgentManifest(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        value.kind !== "workflow" &&
-        typeof value.id === "string");
-}
-/** `manifest` with its `runtime` block, and each agent it uses as a tool with its own. */
-function pinRuntime(manifest, spec) {
-    let changed = false;
-    const tools = manifest.tools?.map((tool) => {
-        // Agents used as tools share the session's sandbox; flow agents used as tools run in linked
-        // sessions that inherit it.
-        if (tool.agent === undefined || !isAgentManifest(tool.agent))
-            return tool;
-        const agent = pinRuntime(tool.agent, spec);
-        if (agent === tool.agent)
-            return tool;
-        changed = true;
-        return { ...tool, agent };
-    });
-    const runtime = runtimeManifestFor(manifest, {
-        ...(spec === undefined ? {} : { sandbox: spec }),
-        save: spec !== undefined,
-        read: true,
-    });
-    if (runtime === undefined && !changed)
-        return manifest;
-    return {
-        ...manifest,
-        ...(changed ? { tools } : {}),
-        ...(runtime === undefined ? {} : { runtime }),
-    };
-}
-/** `pinned` checked as a manifest, with its hash. */
-function checked(original, pinned) {
-    const parsed = AgentManifestSchema.safeParse(pinned);
-    if (!parsed.success) {
-        const issues = parsed.error.issues.map((issue) => issue.message);
-        return {
-            ok: false,
-            message: `'${original.id}' cannot take the Runtime's tools: ${[...new Set(issues)].join("; ")}`,
-        };
-    }
-    return { ok: true, manifest: pinned, manifestHash: hashManifest(pinned) };
-}
-/** The agent's pinned manifest with the session's sandbox, or why it cannot take one. */
-export function withSandbox(manifest, spec) {
-    return checked(manifest, pinRuntime(manifest, spec));
-}
-/**
- * The pinned manifest of an agent session without a sandbox: `read_artifact` for each agent of
- * the tree (R2b C11, protocol 12), and the skill tools for each with skills.
- */
-export function withRuntimeTools(manifest) {
-    return checked(manifest, pinRuntime(manifest, undefined));
-}

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

@@ -1,13 +0,0 @@
-import type { SandboxToolOutcome } from "@nylorun/core/contracts";
-import { type ToolResultFile } from "@nylorun/core/define";
-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 a file the model reads. */
-interface ReadOutcome {
-    readonly kind: "completed";
-    readonly output: Record<string, unknown>;
-    readonly files?: readonly ToolResultFile[];
-}
-export declare function callReadArtifact(ctx: TenantContext, request: HostEffect, signal: AbortSignal): Promise<ReadOutcome | SandboxToolOutcome>;

package/dist/tenant/artifact-tool.js

@@ -1,243 +0,0 @@
-/**
- * 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:
- * - `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.
- *
- * `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 } from "@nylorun/core/define";
-import { isArtifactId } from "@nylorun/core/compatibility";
-import { readArtifactLimits } from "../artifacts/config.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 { sandboxToolSpec } from "../sandbox/manager.js";
-import { sandboxWorkspaceOf } from "../sandbox/share.js";
-import { sessionOf } from "./context.js";
-import { HttpError } from "./http.js";
-import { manifestFor } from "./session.js";
-import { jsonBytes, utf8Boundary } from "./tool-results.js";
-import { toolIds } from "./transcript.js";
-export { isReadArtifactCall, 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);
-        // 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),
-            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 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.environmentId === undefined ? {} : { environmentId: workspace.environmentId }),
-        }, spec, 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;
-    }
-}
-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 ||
-        typeof length !== "number" ||
-        !Number.isSafeInteger(length) ||
-        length < 1 ||
-        length > 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;
-        // 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 &&
-                !(artifact.sessionId === null && s.fileArtifacts?.includes(artifact.id))))
-            return 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,
-        version: version.version,
-        name: artifact.name,
-        contentType: version.contentType,
-        size: version.size,
-    };
-    if (artifact.kind !== "file")
-        return failed("artifact.not_text", `${artifact.name} is a folder; read_artifact reads a file.`);
-    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,
-                        size: version.size,
-                    },
-                },
-            ],
-        };
-    }
-    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);
-    const bytes = end === offset ? new Uint8Array() : await readRange(ctx, version.blobKey, offset, end - 1, signal);
-    const page = textPage(bytes, end === version.size);
-    const next = offset + page.bytes;
-    return {
-        kind: "completed",
-        output: {
-            ...about,
-            offset,
-            content: page.text,
-            ...(next < version.size ? { nextOffset: next } : {}),
-        },
-    };
-}
-/** Bytes `start` to `end` (both inclusive) of a version's blob. */
-async function readRange(ctx, blobKey, start, end, signal) {
-    const got = await ctx.blobs.get(blobKey, { range: { start, end }, signal });
-    if (!got)
-        throw new Error("The artifact's bytes are missing from the Object store");
-    return new Uint8Array(await new Response(got.body).arrayBuffer());
-}
-/**
- * The text of a page of UTF-8 `bytes` in whole characters, at most `READ_ARTIFACT_MAX_BYTES`
- * once escaped as JSON, and how many bytes it used: the next page starts there. A page that
- * starts inside a character skips its rest, and one that ends inside one (not `last`) stops
- * before it.
- */
-function textPage(bytes, last) {
-    const from = utf8Boundary(bytes, 0, "up");
-    let to = last ? bytes.byteLength : utf8Boundary(bytes, bytes.byteLength, "down");
-    // A page shorter than one character: take what there is.
-    if (to <= from)
-        to = bytes.byteLength;
-    const decode = () => Buffer.from(bytes.subarray(from, to)).toString("utf8");
-    let text = decode();
-    // Escaped (quotes, newlines, control characters), text takes more room than its bytes: each
-    // byte left out frees at least one.
-    for (let size = jsonBytes(text); to > from && size > READ_ARTIFACT_MAX_BYTES; size = jsonBytes(text)) {
-        to = utf8Boundary(bytes, Math.max(from, to - (size - READ_ARTIFACT_MAX_BYTES)), "down");
-        text = decode();
-    }
-    return { text, bytes: to };
-}

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

@@ -1,20 +0,0 @@
-/**
- * The skill tools (track R2 M4): `load_skill` and `read_skill_resource`, which the Runtime pins
- * in the `runtime` block of an agent with skills. The Runtime runs them itself, like `save_artifact`, from the
- * definition files uploaded with the agent: no developer process is involved.
- *
- * - `load_skill`: the skill's instructions (its `SKILL.md` after the frontmatter), the paths of
- *   its other files, and, when the session has a sandbox, where they are in it
- *   (`/skills/<name>@<hash>/`, read-only, D66).
- * - `read_skill_resource`: one text file of the skill. A binary file is refused: the model reads
- *   it in the sandbox, when there is one.
- *
- * Expected problems are failed outcomes the model sees; only infrastructure errors throw.
- */
-import type { SandboxToolOutcome } from "@nylorun/core/contracts";
-import { type AgentManifest } from "@nylorun/core/define";
-import type { HostEffect } from "@nylorun/harness/run";
-import type { TenantContext } from "./context.js";
-/** True when `request` calls a skill tool the Runtime serves for `manifest`'s agent. */
-export declare function isSkillToolCall(manifest: AgentManifest | undefined, request: HostEffect): boolean;
-export declare function callSkillTool(ctx: TenantContext, manifest: AgentManifest, request: HostEffect, signal: AbortSignal): Promise<SandboxToolOutcome>;

package/dist/tenant/skill-tool.js

@@ -1,67 +0,0 @@
-import { LOAD_SKILL_TOOL, SKILL_ENTRY, skillFolderOf, isSkillTool, skillInstructions, } from "@nylorun/core/define";
-import { sandboxToolSpec } from "../sandbox/runtime-tools.js";
-import { readDefinitionFile } from "./definition-files.js";
-const failed = (code, message) => ({ kind: "failed", code, message });
-/** True when `request` calls a skill tool the Runtime serves for `manifest`'s agent. */
-export function isSkillToolCall(manifest, request) {
-    return request.kind === "tool" && isSkillTool(manifest, request.toolName);
-}
-/** Every skill of the agent, by name. */
-function skillsOf(manifest) {
-    return new Map(Object.values(manifest.skills ?? {}).map((skill) => [skill.name, skill]));
-}
-/** UTF-8 text, or undefined for bytes that are not (a NUL byte, or invalid UTF-8). */
-function textOf(bytes) {
-    if (bytes.includes(0))
-        return undefined;
-    try {
-        return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-    }
-    catch {
-        return undefined;
-    }
-}
-export async function callSkillTool(ctx, manifest, request, signal) {
-    const input = (request.input ?? {});
-    const skills = skillsOf(manifest);
-    const name = typeof input.name === "string" ? input.name : "";
-    const skill = skills.get(name);
-    if (!skill)
-        return request.toolName === LOAD_SKILL_TOOL
-            ? { kind: "completed", output: { unknown: name, available: [...skills.keys()].sort() } }
-            : failed("skill.unknown", `There is no skill '${name}'.`);
-    const sandboxed = sandboxToolSpec(manifest, "bash") !== undefined;
-    const directory = `${skillFolderOf(skill)}/`;
-    const read = async (path) => {
-        const bytes = await readDefinitionFile(ctx.blobs, skill.files[path], signal);
-        if (!bytes)
-            throw new Error(`The bytes of ${skill.files[path]} (${skill.name}/${path}) are missing from the Object store`);
-        return bytes;
-    };
-    if (request.toolName === LOAD_SKILL_TOOL) {
-        const text = textOf(await read(SKILL_ENTRY));
-        if (text === undefined)
-            return failed("skill.binary_resource", `${SKILL_ENTRY} of '${skill.name}' is not text.`);
-        const resources = Object.keys(skill.files)
-            .filter((path) => path !== SKILL_ENTRY)
-            .sort();
-        return {
-            kind: "completed",
-            output: {
-                name: skill.name,
-                content: skillInstructions(text),
-                ...(resources.length === 0 ? {} : { resources }),
-                ...(sandboxed ? { sandboxPath: directory } : {}),
-            },
-        };
-    }
-    const path = typeof input.path === "string" ? input.path : "";
-    if (skill.files[path] === undefined)
-        return failed("skill.unknown_resource", `Skill '${skill.name}' has no resource '${path}'.`);
-    const content = textOf(await read(path));
-    if (content === undefined)
-        return failed("skill.binary_resource", sandboxed
-            ? `${path} is not a text file. It is in the sandbox at ${directory}${path}; use it there.`
-            : `${path} is not a text file; only text files can be read without a sandbox.`);
-    return { kind: "completed", output: { name: skill.name, path, content } };
-}

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

@@ -1,57 +0,0 @@
-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;