@nylorun/runtime 0.26.0-beta → 0.28.0-beta

package/dist/mcp/snapshot.js

@@ -1,20 +1,19 @@
-import { createHash } from "node:crypto";
-import { delegatesOf, pluginOf, deferredToolsInstructions, deferredToolsTools, delegateManifest, mcpToolSettings, } from "@nylorun/core/define";
+import { delegatesOf, pluginOf, delegateManifest, mcpToolSettings, } from "@nylorun/core/define";
+import { findServer } from "./pool.js";
 /**
- * The `mcp.discovered` payload: each server's outcome, with the tools it added to the snapshot,
- * and the Agent Plugin that brought the server (from `manifest`, the session's pinned one).
+ * The `mcp.discovered` payload: each server's outcome, with the tools it added to the snapshot
+ * that its settings in `manifest` (the session's pinned one) leave enabled, and the Agent Plugin
+ * that brought the server.
  */
 export function mcpDiscovered(snapshot, diagnostics, manifest) {
     const agents = new Map(manifest === undefined
         ? []
         : [[undefined, manifest], ...delegatesOf(manifest).map(({ manifest: child }) => [child.id, child])]);
-    const key = (item) => JSON.stringify([item.agentId ?? null, item.serverName]);
+    const key = (agentId, serverName) => JSON.stringify([agentId ?? null, serverName]);
     const tools = new Map();
-    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);
+    for (const server of snapshot.servers) {
+        const enabled = server.tools.filter((tool) => manifest === undefined || isEnabledIn(manifest, server.agentId, server.name, tool.name));
+        tools.set(key(server.agentId, server.name), enabled.length);
     }
     return {
         servers: diagnostics.map((item) => ({
@@ -23,149 +22,108 @@ export function mcpDiscovered(snapshot, diagnostics, manifest) {
             ...withPlugin(pluginOf(agents.get(item.agentId), { server: item.serverName })),
             outcome: item.outcome,
             message: item.message,
-            tools: tools.get(key(item)) ?? 0,
-            ...(deferred.has(key(item)) ? { deferred: deferred.get(key(item)) } : {}),
+            tools: tools.get(key(item.agentId, item.serverName)) ?? 0,
             ...(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 })) } : {}),
         })),
     };
 }
 function withPlugin(plugin) {
     return plugin === undefined ? {} : { plugin };
 }
-/** 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}`;
-}
-/** The names of the agent's tools: its own and those the Runtime pinned. */
-export function declaredToolNames(manifest) {
-    return new Set([...(manifest.tools ?? []), ...(manifest.runtime?.tools ?? [])].map((tool) => tool.name));
-}
-/** 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?.mcpServers?.[tool.serverName];
+/** The tool `tool` of server `server` of agent `agentId` (the root when absent), as discovered. */
+export function mcpToolIn(snapshot, agentId, server, tool) {
+    return snapshot?.servers
+        .find((item) => item.agentId === agentId && item.name === server)
+        ?.tools.find((item) => item.name === tool);
 }
 /** The tool's settings in `manifest` (R2b C9); the defaults when its server is not there. */
-export function mcpToolSettingsIn(manifest, tool) {
-    const server = serverOf(manifest, tool);
-    return server ? mcpToolSettings(server, tool.serverToolName) : { enabled: true, approval: "never" };
+export function mcpToolSettingsIn(manifest, agentId, server, tool) {
+    const declared = findServer(manifest, agentId, server);
+    return declared ? mcpToolSettings(declared.server, tool) : { enabled: true, approval: "never" };
+}
+/** True when the tool's settings in `manifest` leave it enabled (R2b C9). */
+export function isEnabledIn(manifest, agentId, server, tool) {
+    return mcpToolSettingsIn(manifest, agentId, server, tool).enabled;
 }
 /**
- * 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); the Tool Gate holds a call its approval
- *   or the Tenant's tool policy asks a person about (R5 step 2);
- * - a deferred tool (R2b C10) is marked so, out of the model's list, and its agent gets the
- *   session tools `tool_search`, with the note on the servers it holds deferred tools of, and
- *   `tool_call`. Their names are reserved: no tool of the agent's own takes them.
- *
- * Nothing here changes between the steps of a turn, so neither does the model's tool list.
+ * The snapshot's facts for a turn whose manifest is `manifest` (the session's pin, or a turn
+ * variant that tightened its MCP servers' tools): each tool with whether its settings leave it
+ * `enabled` and, when they say, whether to defer it. A server the turn's manifest no longer
+ * declares is left out.
  */
-export function sessionToolsOf(snapshot, manifest) {
-    if (!snapshot?.mcpTools.length)
-        return undefined;
-    const inline = [];
-    const deferred = new Map();
-    const notes = new Map();
-    for (const tool of snapshot.mcpTools) {
-        const settings = mcpToolSettingsIn(manifest, tool);
-        if (!settings.enabled)
-            continue;
-        const defer = tool.deferred === true;
-        const entry = {
-            ...(tool.agentId === undefined ? {} : { agentId: tool.agentId }),
-            name: tool.name,
-            ...(tool.description === undefined ? {} : { description: tool.description }),
-            inputSchema: tool.inputSchema,
-            ...(tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }),
-            ...(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 session = [];
-    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,
-        ])
-            session.push({ ...(agentId === undefined ? {} : { agentId }), ...tool });
-        session.push(...tools);
-    }
-    return [...inline, ...session];
+export function mcpFactsOf(snapshot, manifest) {
+    return {
+        servers: snapshot.servers.flatMap((server) => {
+            if (!findServer(manifest, server.agentId, server.name))
+                return [];
+            return [
+                {
+                    ...(server.agentId === undefined ? {} : { agentId: server.agentId }),
+                    name: server.name,
+                    ...(server.instructions === undefined ? {} : { instructions: server.instructions }),
+                    tools: server.tools.map((tool) => {
+                        const settings = mcpToolSettingsIn(manifest, server.agentId, server.name, tool.name);
+                        return {
+                            ...tool,
+                            enabled: settings.enabled,
+                            ...(settings.deferred === undefined ? {} : { deferred: settings.deferred }),
+                        };
+                    }),
+                },
+            ];
+        }),
+    };
+}
+/** The manifest of the agent an effect belongs to: the root, or an agent it uses as a tool. */
+export function manifestFor(manifest, agent) {
+    return agent ? delegateManifest(manifest, agent.id) : manifest;
 }
-/** 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).
+ * `snapshot` within the Tenant's Runtime limit `mcpSnapshotBytes` (its JSON, which every
+ * `turn.start.mcp` carries): its servers in order while they fit. A server that does not is left
+ * out, so the session never offers its tools, and its diagnostic says so (`failed`, replacing
+ * the one it had). Unchanged when the whole snapshot fits.
  */
-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) => mcpToolSettingsIn(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);
+export function fitSnapshot(snapshot, diagnostics, limitBytes) {
+    const bytes = (value) => Buffer.byteLength(JSON.stringify(value));
+    if (bytes(snapshot) <= limitBytes)
+        return { snapshot, diagnostics: [...diagnostics] };
+    const kept = [];
+    const dropped = new Map();
+    const key = (agentId, serverName) => JSON.stringify([agentId ?? null, serverName]);
+    for (const server of snapshot.servers) {
+        const next = { ...snapshot, servers: [...kept, server] };
+        const size = bytes(next);
+        if (size <= limitBytes)
+            kept.push(server);
+        else
+            dropped.set(key(server.agentId, server.name), bytes(server));
+    }
+    const tooLarge = (agentId, serverName, size) => ({
+        ...(agentId === undefined ? {} : { agentId }),
+        serverName,
+        outcome: "failed",
+        message: `The server's tools and instructions take ${size} bytes, past what the session may pin with the rest: the Runtime limit mcpSnapshotBytes (${limitBytes} bytes; PUT /v1/tenant/limits). Its tools are not offered.`,
     });
-    const mcpTools = snapshot.mcpTools.map((tool, i) => {
-        const { deferred: _, ...rest } = tool;
-        const defer = set[i] ?? (listed.get(tool.agentId) ?? 0) > limit;
-        return defer ? { ...rest, deferred: true } : rest;
+    const out = diagnostics.map((item) => {
+        const size = dropped.get(key(item.agentId, item.serverName));
+        return size === undefined ? item : tooLarge(item.agentId, item.serverName, size);
     });
-    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.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 mcpToolSettingsIn(manifest, tool).enabled;
+    for (const server of snapshot.servers) {
+        const size = dropped.get(key(server.agentId, server.name));
+        if (size !== undefined && !out.some((item) => key(item.agentId, item.serverName) === key(server.agentId, server.name)))
+            out.push(tooLarge(server.agentId, server.name, size));
+    }
+    return { snapshot: { ...snapshot, servers: kept }, diagnostics: out };
 }
-/** The manifest of the agent an effect belongs to: the root, or an agent it uses as a tool. */
-export function manifestFor(manifest, agent) {
-    return agent ? delegateManifest(manifest, agent.id) : manifest;
+/** True for a snapshot of the shape this Runtime pins (`snapshotSchemaVersion` 2). */
+export function isSnapshot(value) {
+    const snapshot = value;
+    return (typeof snapshot === "object" &&
+        snapshot !== null &&
+        snapshot.snapshotSchemaVersion === 2 &&
+        typeof snapshot.manifestHash === "string" &&
+        Array.isArray(snapshot.servers));
 }

package/dist/memory/service.d.ts

@@ -0,0 +1,97 @@
+import { type MemoryOperation, type MemorySummary, type MemoryVersion, type MemoryVersionDetail, type RuntimeLimits } from "@nylorun/core/contracts";
+import type { MemoryRow, MemoryVersionRow, Tx } from "../store/types.js";
+/** Who makes a write: `agent:<manifest>@<n>` with its session, turn and run, or an API caller. */
+export interface MemoryAuthor {
+    readonly actor: string;
+    readonly sessionId?: string;
+    readonly turnId?: string;
+    readonly triggerRunId?: string;
+}
+/** One of the `memory` tool's write commands, with Anthropic's parameters. */
+export type MemoryCommand = {
+    readonly command: "create";
+    readonly path: string;
+    readonly fileText: string;
+} | {
+    readonly command: "str_replace";
+    readonly path: string;
+    readonly oldStr: string;
+    readonly newStr?: string;
+} | {
+    readonly command: "insert";
+    readonly path: string;
+    readonly insertLine: number;
+    readonly insertText: string;
+} | {
+    readonly command: "delete";
+    readonly path: string;
+} | {
+    readonly command: "rename";
+    readonly oldPath: string;
+    readonly newPath: string;
+};
+/**
+ * Why a command did not apply. `path_invalid`, `too_large` and `limit` are the Runtime's rules;
+ * the rest are Anthropic's ordinary failures (a missing path, an `old_str` that is not there or
+ * not unique, an `insert_line` out of range, a rename onto an existing path).
+ */
+export type MemoryRefusal = "memory.path_invalid" | "memory.too_large" | "memory.limit" | "memory.not_found" | "memory.no_match" | "memory.not_unique" | "memory.invalid_line" | "memory.exists";
+/** A memory a command changed: its path, what changed it and its version after. */
+export interface MemoryChange {
+    readonly path: string;
+    readonly operation: MemoryOperation;
+    readonly version: number;
+}
+/** A refused command or view: the code, and the text for the model. */
+export interface MemoryRefused {
+    readonly ok: false;
+    readonly code: MemoryRefusal;
+    readonly text: string;
+}
+/** What a command came to: the text for the model, and the changes, or why it was refused. */
+export type MemoryResult = {
+    readonly ok: true;
+    readonly text: string;
+    readonly changes: readonly MemoryChange[];
+} | MemoryRefused;
+/** What a view came to: the listing or the text, or why it was refused. */
+export type MemoryViewResult = {
+    readonly ok: true;
+    readonly text: string;
+} | MemoryRefused;
+/** A new version id: increasing with time, so versions page newest first by id. */
+export declare function newMemoryVersionId(now?: number): string;
+export declare function sha256(text: string): string;
+/**
+ * The tool's `view`: a memory's text with line numbers (`viewRange` `[start, end]`, 1-based,
+ * `end` -1 for the last line), or a folder's listing two levels deep with sizes. `/memories`
+ * lists even when the Agent has no memories.
+ */
+export declare function viewMemory(t: Tx, agentId: string, rawPath: string, viewRange?: readonly [number, number]): Promise<MemoryViewResult>;
+interface Applied {
+    readonly t: Tx;
+    readonly agentId: string;
+    readonly author: MemoryAuthor;
+    readonly limits: Pick<RuntimeLimits, "memoryBytes" | "memoriesPerAgent">;
+    readonly now: string;
+}
+/**
+ * Applies one write command to Agent `agentId`'s memories in `t`, as `author`, within the
+ * Runtime limits. Access is the caller's to check. A command that changes nothing (a `create`
+ * with the same text) makes no version.
+ */
+export declare function applyMemoryCommand(t: Tx, agentId: string, command: MemoryCommand, author: MemoryAuthor, limits: Applied["limits"], now?: string): Promise<MemoryResult>;
+/**
+ * The index a session pins (`turn.start.memory.index`, design §6.3): a line per memory, newest
+ * first, `- <path>`, then ` — <description>` when it has one, within `memoryIndexLines` lines and
+ * `memoryIndexBytes` bytes. `truncated` when some memories were left out; the harness tells the
+ * model to view folders for the rest.
+ */
+export declare function renderMemoryIndex(t: Tx, agentId: string, limits: Pick<RuntimeLimits, "memoryIndexLines" | "memoryIndexBytes">): Promise<{
+    index: string;
+    truncated: boolean;
+}>;
+export declare function memorySummaryOf(row: MemoryRow): MemorySummary;
+export declare function memoryVersionOf(row: MemoryVersionRow): MemoryVersion;
+export declare function memoryVersionDetailOf(row: MemoryVersionRow): MemoryVersionDetail;
+export {};