@nylorun/runtime 0.20.0-beta → 0.21.0-beta

package/dist/mcp/snapshot.js

@@ -1,10 +1,15 @@
-import { delegateManifest } from "@nylorun/core/define";
+import { createHash } from "node:crypto";
+import { TOOLS_CAPABILITY_ID, deferredToolsInstructions, deferredToolsTools, delegateManifest, mcpToolSettings, } from "@nylorun/core/define";
 /** The `mcp.discovered` payload: each server's outcome, with the tools it added to the snapshot. */
 export function mcpDiscovered(snapshot, diagnostics) {
     const key = (item) => JSON.stringify([item.agentId ?? null, item.capabilityId, item.serverName]);
     const tools = new Map();
-    for (const tool of snapshot.mcpTools)
+    const deferred = new Map();
+    for (const tool of snapshot.mcpTools) {
         tools.set(key(tool), (tools.get(key(tool)) ?? 0) + 1);
+        if (tool.deferred)
+            deferred.set(key(tool), (deferred.get(key(tool)) ?? 0) + 1);
+    }
     return {
         servers: diagnostics.map((item) => ({
             ...(item.agentId === undefined ? {} : { agentId: item.agentId }),
@@ -13,12 +18,32 @@ export function mcpDiscovered(snapshot, diagnostics) {
             outcome: item.outcome,
             message: item.message,
             tools: tools.get(key(item)) ?? 0,
+            ...(deferred.has(key(item)) ? { deferred: deferred.get(key(item)) } : {}),
+            ...(item.disabled ? { disabled: item.disabled } : {}),
+            ...(item.unknownTools?.length ? { unknownTools: [...item.unknownTools] } : {}),
             ...(item.credentialIds === undefined ? {} : { credentialIds: [...item.credentialIds] }),
+            ...(item.renamed?.length ? { renamed: item.renamed.map((tool) => ({ ...tool })) } : {}),
         })),
     };
 }
-export function modelToolName(serverName, serverToolName) {
-    return `${serverName}__${serverToolName}`;
+/** The longest tool name every model provider accepts (R2b C6, Q14). */
+export const MODEL_TOOL_NAME_MAX = 64;
+/**
+ * The name the model knows an MCP tool by (R2b C6, Q13): `server__tool`, with each character
+ * outside `[A-Za-z0-9_-]` replaced by `_`, since MCP allows `.` and 128 characters and OpenAI,
+ * Bedrock and Gemini on Vertex do not. A name over 64 characters, or one that collides
+ * (`suffixed`), keeps 55 and adds `_` and 8 hex characters of the SHA-256 of the raw
+ * `server/tool`.
+ */
+export function normalizeToolName(serverName, serverToolName, options = {}) {
+    const name = `${serverName}__${serverToolName}`.replace(/[^A-Za-z0-9_-]/gu, "_");
+    if (name.length <= MODEL_TOOL_NAME_MAX && !options.suffixed)
+        return name;
+    const hash = createHash("sha256")
+        .update(`${serverName}/${serverToolName}`)
+        .digest("hex")
+        .slice(0, 8);
+    return `${name.slice(0, MODEL_TOOL_NAME_MAX - 9)}_${hash}`;
 }
 export function declaredToolNames(manifest) {
     const names = new Set();
@@ -27,37 +52,130 @@ export function declaredToolNames(manifest) {
             names.add(tool.name);
     return names;
 }
+/** The declaration of the server a tool of the snapshot comes from, in `manifest`. */
+function serverOf(manifest, tool) {
+    const agent = tool.agentId === undefined ? manifest : delegateManifest(manifest, tool.agentId);
+    return agent?.capabilities.find((item) => item.id === tool.capabilityId)?.mcpServers?.[tool.serverName];
+}
+/** The tool's settings in `manifest` (R2b C9); the defaults when its server is not there. */
+function settingsOf(manifest, tool) {
+    const server = serverOf(manifest, tool);
+    return server ? mcpToolSettings(server, tool.serverToolName) : { enabled: true, approval: "never" };
+}
+/** True when the agent the tool belongs to has `tool_search` and `tool_call` (`nylorun.tools`). */
+function reachesDeferred(manifest, agentId) {
+    const agent = agentId === undefined ? manifest : delegateManifest(manifest, agentId);
+    return agent?.capabilities.some((capability) => capability.id === TOOLS_CAPABILITY_ID) === true;
+}
 /**
- * The tools of a snapshot, as the engine advertises them. A tool of a server whose `approval` is
- * `always` in the session's `manifest` waits for approval on each call.
+ * The tools of a snapshot, as the engine gets them for a turn whose manifest is `manifest` (the
+ * session's pin, or a turn variant that tightened its MCP servers' tools):
+ *
+ * - a tool its settings disable is left out (R2b C9); one whose approval resolves to `always`
+ *   waits for approval on each call;
+ * - a deferred tool (R2b C10) is marked so, out of the model's list, and its agent gets
+ *   `tool_search`, with the note on the servers it holds deferred tools of, and `tool_call` in
+ *   its `nylorun.tools` capability. An agent whose turn has no such capability keeps its tools in
+ *   its list.
+ *
+ * Nothing here changes between the steps of a turn, so neither does the model's tool list.
  */
 export function sessionToolsOf(snapshot, manifest) {
     if (!snapshot?.mcpTools.length)
         return undefined;
-    const approved = (tool) => {
-        const agent = tool.agentId === undefined ? manifest : delegateManifest(manifest, tool.agentId);
-        const server = agent?.capabilities.find((item) => item.id === tool.capabilityId)?.mcpServers?.[tool.serverName];
-        return server !== undefined && "approval" in server && server.approval === "always";
-    };
-    return snapshot.mcpTools.map((tool) => ({
-        ...(tool.agentId === undefined ? {} : { agentId: tool.agentId }),
-        capabilityId: tool.capabilityId,
-        name: tool.name,
-        ...(tool.description === undefined
-            ? {}
-            : { description: tool.description }),
-        inputSchema: tool.inputSchema,
-        ...(tool.outputSchema === undefined
-            ? {}
-            : { outputSchema: tool.outputSchema }),
-        ...(approved(tool) ? { approval: "always" } : {}),
-    }));
+    const inline = [];
+    const deferred = new Map();
+    const notes = new Map();
+    for (const tool of snapshot.mcpTools) {
+        const settings = settingsOf(manifest, tool);
+        if (!settings.enabled)
+            continue;
+        const defer = tool.deferred === true && reachesDeferred(manifest, tool.agentId);
+        const entry = {
+            ...(tool.agentId === undefined ? {} : { agentId: tool.agentId }),
+            capabilityId: tool.capabilityId,
+            name: tool.name,
+            ...(tool.description === undefined ? {} : { description: tool.description }),
+            inputSchema: tool.inputSchema,
+            ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
+            ...(settings.approval === "always" ? { approval: "always" } : {}),
+            ...(defer ? { deferred: true } : {}),
+        };
+        if (!defer) {
+            inline.push(entry);
+            continue;
+        }
+        deferred.set(tool.agentId, [...(deferred.get(tool.agentId) ?? []), entry]);
+        const servers = notes.get(tool.agentId) ?? new Map();
+        servers.set(tool.serverName, (servers.get(tool.serverName) ?? 0) + 1);
+        notes.set(tool.agentId, servers);
+    }
+    const platform = [];
+    for (const [agentId, tools] of deferred) {
+        const servers = [...notes.get(agentId)].map(([serverName, count]) => {
+            const instructions = snapshot.servers?.find((item) => item.agentId === agentId && item.serverName === serverName)?.instructions;
+            return { serverName, tools: count, ...(instructions ? { instructions } : {}) };
+        });
+        const [search, call] = deferredToolsTools();
+        for (const tool of [
+            { ...search, instructions: [deferredToolsInstructions(servers)] },
+            call,
+        ])
+            platform.push({
+                ...(agentId === undefined ? {} : { agentId }),
+                capabilityId: TOOLS_CAPABILITY_ID,
+                ...tool,
+            });
+        platform.push(...tools);
+    }
+    return [...inline, ...platform];
 }
-/** The snapshot's record of an MCP tool call, or undefined when the call is not an MCP tool. */
-export function mcpToolOf(snapshot, request) {
-    return snapshot?.mcpTools.find((tool) => tool.agentId === request.agent?.id &&
+/** The share of the model's context window past which an agent's MCP tools are deferred (Q21). */
+export const DEFER_CONTEXT_SHARE = 0.1;
+/** Characters per token, to estimate what tool definitions take of a context window (Q21). */
+export const CHARS_PER_TOKEN = 4;
+/**
+ * The snapshot with its deferred tools marked (R2b C10, Q21), decided once for the session when
+ * core records it. A tool's own setting, then `"*"`'s, then its server's, decides; a tool none
+ * sets is deferred when the JSON of its agent's MCP tools that would be listed passes a tenth of
+ * the model's context window (`contextWindow` tokens, at 4 characters a token). An agent without
+ * the `nylorun.tools` capability (its definition names a tool `tool_search` or `tool_call`, or the
+ * session was opened before it existed) defers nothing.
+ */
+export function pinDeferral(snapshot, manifest, contextWindow) {
+    const limit = contextWindow * CHARS_PER_TOKEN * DEFER_CONTEXT_SHARE;
+    const listed = new Map();
+    const set = snapshot.mcpTools.map((tool) => settingsOf(manifest, tool).deferred);
+    snapshot.mcpTools.forEach((tool, i) => {
+        if (set[i] === true)
+            return;
+        const size = JSON.stringify({ name: tool.name, description: tool.description ?? "", inputSchema: tool.inputSchema }).length;
+        listed.set(tool.agentId, (listed.get(tool.agentId) ?? 0) + size);
+    });
+    const mcpTools = snapshot.mcpTools.map((tool, i) => {
+        const { deferred: _, ...rest } = tool;
+        if (!reachesDeferred(manifest, tool.agentId))
+            return rest;
+        const defer = set[i] ?? (listed.get(tool.agentId) ?? 0) > limit;
+        return defer ? { ...rest, deferred: true } : rest;
+    });
+    return { ...snapshot, mcpTools };
+}
+/**
+ * The snapshot's record of an MCP tool call, or undefined when the call is not an MCP tool. With
+ * the turn's `manifest`, a tool its settings disable is not one either (R2b C9).
+ */
+export function mcpToolOf(snapshot, request, manifest) {
+    const tool = snapshot?.mcpTools.find((tool) => tool.agentId === request.agent?.id &&
         tool.capabilityId === request.capabilityId &&
         tool.name === request.toolName);
+    if (tool && manifest && !isEnabledIn(manifest, tool))
+        return undefined;
+    return tool;
+}
+/** True when the tool's settings in `manifest` leave it enabled (R2b C9). */
+export function isEnabledIn(manifest, tool) {
+    return settingsOf(manifest, tool).enabled;
 }
 /** The manifest of the agent an effect belongs to: the root, or an agent it uses as a tool. */
 export function manifestFor(manifest, agent) {

package/dist/model/catalog.d.ts

@@ -1,4 +1,18 @@
 import type { HostModelCatalog } from "@nylorun/core/contracts";
 export type { HostModelCatalog };
+/**
+ * The context window, in tokens, of the Tenant's model (`GET /v1/tenant/model`'s view): the
+ * custom endpoint's setting, else the provider catalog's. A model the catalog does not know, or
+ * none configured, is assumed small (`CUSTOM_CONTEXT_WINDOW`), as for a custom endpoint.
+ */
+export declare function contextWindowOf(view: {
+    configured: boolean;
+    provider?: string;
+    model?: string;
+    baseUrl?: string;
+    settings?: {
+        contextWindow?: number;
+    };
+}): number;
 /** Public provider and model names. No credentials. */
 export declare function hostModelCatalog(): HostModelCatalog;

package/dist/model/catalog.js

@@ -1,4 +1,4 @@
-import { modelsFor } from "./models.js";
+import { CUSTOM_CONTEXT_WINDOW, modelsFor } from "./models.js";
 const emptyStore = {
     async read() {
         return undefined;
@@ -11,6 +11,19 @@ const emptyStore = {
     },
     async delete() { },
 };
+/**
+ * The context window, in tokens, of the Tenant's model (`GET /v1/tenant/model`'s view): the
+ * custom endpoint's setting, else the provider catalog's. A model the catalog does not know, or
+ * none configured, is assumed small (`CUSTOM_CONTEXT_WINDOW`), as for a custom endpoint.
+ */
+export function contextWindowOf(view) {
+    if (!view.configured || !view.provider || !view.model)
+        return CUSTOM_CONTEXT_WINDOW;
+    if (view.baseUrl)
+        return view.settings?.contextWindow ?? CUSTOM_CONTEXT_WINDOW;
+    const models = modelsFor({ provider: "", model: "" }, emptyStore, { environment: false });
+    return models.getModel(view.provider, view.model)?.contextWindow ?? CUSTOM_CONTEXT_WINDOW;
+}
 /** Public provider and model names. No credentials. */
 export function hostModelCatalog() {
     const models = modelsFor({ provider: "", model: "" }, emptyStore, {

package/dist/model/pi-model.js

@@ -226,11 +226,45 @@ export function piModel(options = {}) {
 async function buildContext(call, selected, options) {
     const messages = [];
     const instructions = [];
-    const content = async (parts) => {
+    const content = async (parts, toolResult = false) => {
         const result = [];
         for (const part of parts) {
             if (part.type === "text")
                 result.push({ type: "text", text: part.text });
+            else if (part.type === "media" && toolResult) {
+                // An image a tool returned, stored as an artifact (R2b C11): shown to a model that
+                // reads images. Otherwise, or when it cannot be read, a note: the call still goes.
+                const note = (why) => ({
+                    type: "text",
+                    text: `(The tool returned an image, ${essence(part.mediaType)}, that is not shown: ${why}.)`,
+                });
+                if (!selected.input.includes("image") || !isModelImage(part.mediaType)) {
+                    result.push(note(selected.input.includes("image")
+                        ? "the model reads PNG, JPEG, GIF and WebP images only"
+                        : "this model does not accept images"));
+                    continue;
+                }
+                if (!options.files) {
+                    result.push(note("files are unavailable"));
+                    continue;
+                }
+                try {
+                    const file = await options.files(part.reference);
+                    if (!isModelImage(file.mediaType))
+                        result.push(note(`it is ${essence(file.mediaType)}`));
+                    else
+                        result.push({
+                            type: "image",
+                            data: Buffer.from(file.bytes).toString("base64"),
+                            mimeType: essence(file.mediaType),
+                        });
+                }
+                catch (error) {
+                    if (!(error instanceof FileUnavailableError))
+                        throw error;
+                    result.push(note(error.message.replace(/\.$/u, "")));
+                }
+            }
             else if (part.type === "media") {
                 // A file the message named by artifact (protocol 6): its bytes go only into the
                 // provider request built here, never into the transcript or the journal.
@@ -284,7 +318,7 @@ async function buildContext(call, selected, options) {
                 toolName: item.toolName,
                 isError: item.status !== "completed",
                 timestamp: Date.now(),
-                content: await content(item.content),
+                content: await content(item.content, true),
             });
         }
         else if (item.kind === "message" && item.role === "assistant") {