@nylorun/runtime 0.27.0-beta → 0.29.0-beta

package/dist/mcp/connect.d.ts

@@ -142,7 +142,7 @@ export declare class McpCallFailed extends Error {
  */
 export declare class CredentialRejected extends McpCallFailed {
     readonly server: string;
-    /** Whether a credential of the session's Environment was sent. */
+    /** Whether a credential of the session's Agent was sent. */
     readonly sent: boolean;
     /**
      * The answer's `WWW-Authenticate`, which may name the server's protected-resource metadata
@@ -150,7 +150,7 @@ export declare class CredentialRejected extends McpCallFailed {
      */
     readonly challenge?: string | undefined;
     constructor(server: string, 
-    /** Whether a credential of the session's Environment was sent. */
+    /** Whether a credential of the session's Agent was sent. */
     sent: boolean, 
     /**
      * The answer's `WWW-Authenticate`, which may name the server's protected-resource metadata

package/dist/mcp/connect.js

@@ -49,7 +49,7 @@ export class CredentialRejected extends McpCallFailed {
     sent;
     challenge;
     constructor(server, 
-    /** Whether a credential of the session's Environment was sent. */
+    /** Whether a credential of the session's Agent was sent. */
     sent, 
     /**
      * The answer's `WWW-Authenticate`, which may name the server's protected-resource metadata
@@ -59,8 +59,8 @@ export class CredentialRejected extends McpCallFailed {
         super({
             code: "credential_rejected",
             message: sent
-                ? `The MCP server '${server}' answered HTTP 401: it rejected the credential from the session's Environment`
-                : `The MCP server '${server}' answered HTTP 401: it needs a credential, and the session's Environment holds none for it`,
+                ? `The MCP server '${server}' answered HTTP 401: it rejected the credential from the session's Agent`
+                : `The MCP server '${server}' answered HTTP 401: it needs a credential, and the session's Agent holds none for it`,
             sent: true,
             retryable: false,
             server,

package/dist/mcp/preview.js

@@ -121,18 +121,18 @@ export async function previewMcpServer(body, options) {
     }
 }
 /**
- * The credential of Environment `environmentId`'s vault for the URL; none without an
- * Environment (a preview without a credential). An Environment that does not exist is a 404.
+ * The credential of Agent `agentId`'s vault for the URL; none without an Agent (a preview without
+ * a credential). An Agent that does not exist is a 404.
  */
 async function credentialFor(vault, request) {
-    if (request.environmentId === undefined)
+    if (request.agentId === undefined)
         return { status: "unauthenticated", url: request.url, headers: {} };
-    // The 404 of a missing Environment, before any request leaves.
-    await vault.listEnvironmentSecrets(request.environmentId);
-    const result = await vault.authorize({ environmentId: request.environmentId, url: request.url });
+    // The 404 of a missing Agent, before any request leaves.
+    await vault.listEnvironmentSecrets(request.agentId);
+    const result = await vault.authorize({ environmentId: request.agentId, url: request.url });
     if (result.status !== "refused")
         return result;
-    throw new HttpError(409, `Environment ${request.environmentId}'s credential for this URL cannot be used (${result.reason})`, { code: "request_rejected", details: { reason: result.reason, credentialIds: result.credentialIds } });
+    throw new HttpError(409, `Agent ${request.agentId}'s credential for this URL cannot be used (${result.reason})`, { code: "request_rejected", details: { reason: result.reason, credentialIds: result.credentialIds } });
 }
 /** A preview that listed nothing: `mcp_preview_failed`, with the code a tool call would have had. */
 function failed(server, error, signal, secrets, limits) {

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 {};

package/dist/memory/service.js

@@ -0,0 +1,335 @@
+/**
+ * Agent memory (track T5, D72): the one place memories change. The `memory` tool's commands
+ * (Anthropic's memory tool: `create`, `str_replace`, `insert`, `delete`, `rename`) and the API's
+ * writes both go through `applyMemoryCommand`, so paths, limits, versions and locks are the same
+ * for a model and for a person. Reads are `viewMemory` (the tool's `view`) and the API's.
+ *
+ * Every change is a new row in `memory_versions` attributed to who made it; the Runtime never
+ * rewrites what was written. A write takes a lock on each path it touches, in path order, so
+ * writes to different memories never wait on each other. Answers to the model are Anthropic's
+ * result strings; a refusal also carries a `memory.*` code.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { MEMORY_ROOT, memoryDescriptionOf, memoryPathOf, memoryPathWithin, } from "@nylorun/core/contracts";
+/** A new version id: increasing with time, so versions page newest first by id. */
+export function newMemoryVersionId(now = Date.now()) {
+    return `mv_${now.toString(36).padStart(9, "0")}${randomBytes(8).toString("hex")}`;
+}
+export function sha256(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+const refused = (code, text) => ({ ok: false, code, text });
+const missing = (path) => refused("memory.not_found", `The path ${path} does not exist. Please provide a valid path.`);
+function pathOf(raw, kind) {
+    const parsed = memoryPathOf(raw, kind);
+    return "error" in parsed ? refused("memory.path_invalid", parsed.error) : parsed;
+}
+/** A file's text with Anthropic's line numbers: six columns, a tab, the line. */
+function numbered(text, start = 1) {
+    return text
+        .split("\n")
+        .map((line, index) => `${String(index + start).padStart(6, " ")}\t${line}`)
+        .join("\n");
+}
+function sizeOf(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}K`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
+}
+/**
+ * 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 async function viewMemory(t, agentId, rawPath, viewRange) {
+    const parsed = pathOf(rawPath, "any");
+    if (!("path" in parsed))
+        return parsed;
+    const path = parsed.path;
+    const row = path.endsWith(".md") ? await t.memory(agentId, path) : undefined;
+    if (row) {
+        const lines = row.content.split("\n");
+        if (viewRange === undefined)
+            return { ok: true, text: `Here's the content of ${path} with line numbers:\n${numbered(row.content)}` };
+        const [start, end] = viewRange;
+        const last = end === -1 ? lines.length : end;
+        if (!Number.isInteger(start) || !Number.isInteger(last) || start < 1 || start > lines.length || last < start || last > lines.length)
+            return refused("memory.invalid_line", `Invalid view_range [${start}, ${end}]: ${path} has ${lines.length} lines.`);
+        return {
+            ok: true,
+            text: `Here's the content of ${path} with line numbers:\n${numbered(lines.slice(start - 1, last).join("\n"), start)}`,
+        };
+    }
+    const rows = await t.memories(agentId, { folder: path });
+    if (rows.length === 0 && path !== MEMORY_ROOT)
+        return missing(path);
+    // Folders are the prefixes of memory paths: list what is one or two levels below `path`.
+    const sizes = new Map();
+    for (const memory of rows) {
+        const rest = memory.path.slice(path.length + 1).split("/");
+        for (let depth = 1; depth <= Math.min(2, rest.length); depth++) {
+            const entry = `${path}/${rest.slice(0, depth).join("/")}`;
+            sizes.set(entry, (sizes.get(entry) ?? 0) + memory.bytes);
+        }
+    }
+    const total = rows.reduce((sum, memory) => sum + memory.bytes, 0);
+    const lines = [`${sizeOf(total)}\t${path}`, ...[...sizes.keys()].sort().map((entry) => `${sizeOf(sizes.get(entry))}\t${entry}`)];
+    return {
+        ok: true,
+        text: `Here're the files and directories up to 2 levels deep in ${path}, excluding hidden items and node_modules:\n${lines.join("\n")}`,
+    };
+}
+function tooLarge(content, limits) {
+    const bytes = Buffer.byteLength(content, "utf8");
+    return bytes > limits.memoryBytes
+        ? refused("memory.too_large", `A memory is at most ${limits.memoryBytes} bytes (the Runtime limit memoryBytes); this one would be ${bytes}. Split it into smaller files.`)
+        : undefined;
+}
+/** Writes `content` at `path` (row `before`, locked, when it exists) and records the version. */
+async function write(a, path, before, content, operation, fromPath) {
+    const contentSha256 = sha256(content);
+    const bytes = Buffer.byteLength(content, "utf8");
+    const version = (before?.version ?? 0) + 1;
+    await a.t.putMemory({
+        agentId: a.agentId,
+        path,
+        content,
+        contentSha256,
+        bytes,
+        description: memoryDescriptionOf(content),
+        version,
+        updatedAt: a.now,
+    });
+    await a.t.insertMemoryVersion(versionRow(a, { path, fromPath: fromPath ?? null, operation, content, contentSha256, bytes }));
+    return { path, operation, version };
+}
+function versionRow(a, change) {
+    return {
+        id: newMemoryVersionId(Date.parse(a.now)),
+        agentId: a.agentId,
+        ...change,
+        actor: a.author.actor,
+        sessionId: a.author.sessionId ?? null,
+        turnId: a.author.turnId ?? null,
+        triggerRunId: a.author.triggerRunId ?? null,
+        createdAt: a.now,
+    };
+}
+/** Deletes `row` (locked) and records the delete. */
+async function remove(a, row) {
+    await a.t.deleteMemory(a.agentId, row.path);
+    await a.t.insertMemoryVersion(versionRow(a, { path: row.path, fromPath: null, operation: "delete", content: null, contentSha256: null, bytes: null }));
+    return { path: row.path, operation: "delete", version: row.version + 1 };
+}
+/** Locks the memories at `paths` (in path order, so two writes never wait on each other's locks). */
+async function lockPaths(t, agentId, paths) {
+    const rows = new Map();
+    for (const path of [...new Set(paths)].sort())
+        rows.set(path, await t.memory(agentId, path, { lock: true }));
+    return rows;
+}
+/**
+ * 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 async function applyMemoryCommand(t, agentId, command, author, limits, now = new Date().toISOString()) {
+    const a = { t, agentId, author, limits, now };
+    switch (command.command) {
+        case "create":
+            return create(a, command.path, command.fileText);
+        case "str_replace":
+            return strReplace(a, command.path, command.oldStr, command.newStr ?? "");
+        case "insert":
+            return insert(a, command.path, command.insertLine, command.insertText);
+        case "delete":
+            return del(a, command.path);
+        case "rename":
+            return rename(a, command.oldPath, command.newPath);
+    }
+}
+async function create(a, rawPath, content) {
+    const parsed = pathOf(rawPath, "file");
+    if (!("path" in parsed))
+        return parsed;
+    const path = parsed.path;
+    const big = tooLarge(content, a.limits);
+    if (big)
+        return big;
+    const before = (await lockPaths(a.t, a.agentId, [path])).get(path);
+    // A memory can't share its path with a folder of memories.
+    if (!before && (await a.t.memories(a.agentId, { folder: path, limit: 1 })).length > 0)
+        return refused("memory.exists", `${path} is a folder of memories`);
+    if (before?.content === content)
+        return { ok: true, text: `File created successfully at: ${path}`, changes: [] };
+    if (!before && (await a.t.countMemories(a.agentId)) >= a.limits.memoriesPerAgent)
+        return refused("memory.limit", `This Agent holds ${a.limits.memoriesPerAgent} memories, the most the Runtime limit memoriesPerAgent allows. Delete or merge some first.`);
+    const change = await write(a, path, before, content, "create");
+    return { ok: true, text: `File created successfully at: ${path}`, changes: [change] };
+}
+async function strReplace(a, rawPath, oldStr, newStr) {
+    const parsed = pathOf(rawPath, "file");
+    if (!("path" in parsed))
+        return parsed;
+    const path = parsed.path;
+    const before = (await lockPaths(a.t, a.agentId, [path])).get(path);
+    if (!before)
+        return missing(path);
+    if (oldStr === "")
+        return refused("memory.no_match", "old_str is empty: give the text to replace.");
+    const lines = [];
+    for (let at = before.content.indexOf(oldStr); at !== -1; at = before.content.indexOf(oldStr, at + 1))
+        lines.push(before.content.slice(0, at).split("\n").length);
+    if (lines.length === 0)
+        return refused("memory.no_match", `No replacement was performed, old_str \`${oldStr}\` did not appear verbatim in ${path}.`);
+    if (lines.length > 1)
+        return refused("memory.not_unique", `No replacement was performed. Multiple occurrences of old_str \`${oldStr}\` in lines: ${lines.join(", ")}. Please ensure it is unique`);
+    const content = before.content.replace(oldStr, () => newStr);
+    const big = tooLarge(content, a.limits);
+    if (big)
+        return big;
+    const change = await write(a, path, before, content, "str_replace");
+    // Anthropic answers with the edited lines around the change.
+    const line = lines[0];
+    const all = content.split("\n");
+    const from = Math.max(1, line - 4);
+    const to = Math.min(all.length, line + newStr.split("\n").length + 3);
+    return {
+        ok: true,
+        text: `The memory file has been edited.\n${numbered(all.slice(from - 1, to).join("\n"), from)}`,
+        changes: [change],
+    };
+}
+async function insert(a, rawPath, insertLine, insertText) {
+    const parsed = pathOf(rawPath, "file");
+    if (!("path" in parsed))
+        return parsed;
+    const path = parsed.path;
+    const before = (await lockPaths(a.t, a.agentId, [path])).get(path);
+    if (!before)
+        return missing(path);
+    const lines = before.content.split("\n");
+    if (!Number.isInteger(insertLine) || insertLine < 0 || insertLine > lines.length)
+        return refused("memory.invalid_line", `Invalid \`insert_line\` parameter: ${insertLine}. It should be within the range of lines of the file: [0, ${lines.length}]`);
+    const added = insertText.endsWith("\n") ? insertText.slice(0, -1) : insertText;
+    lines.splice(insertLine, 0, ...added.split("\n"));
+    const content = lines.join("\n");
+    const big = tooLarge(content, a.limits);
+    if (big)
+        return big;
+    const change = await write(a, path, before, content, "insert");
+    return { ok: true, text: `The file ${path} has been edited.`, changes: [change] };
+}
+async function del(a, rawPath) {
+    const parsed = pathOf(rawPath, "any");
+    if (!("path" in parsed))
+        return parsed;
+    const path = parsed.path;
+    if (path === MEMORY_ROOT)
+        return refused("memory.path_invalid", `${MEMORY_ROOT} itself can't be deleted: delete what is in it.`);
+    const file = path.endsWith(".md") ? (await lockPaths(a.t, a.agentId, [path])).get(path) : undefined;
+    const rows = file ? [file] : await a.t.memories(a.agentId, { folder: path, lock: true });
+    if (rows.length === 0)
+        return missing(path);
+    const changes = [];
+    for (const row of rows)
+        changes.push(await remove(a, row));
+    return { ok: true, text: `Successfully deleted ${path}`, changes };
+}
+async function rename(a, rawOld, rawNew) {
+    const from = pathOf(rawOld, "any");
+    if (!("path" in from))
+        return from;
+    const oldPath = from.path;
+    if (oldPath === MEMORY_ROOT)
+        return refused("memory.path_invalid", `${MEMORY_ROOT} itself can't be renamed.`);
+    const isFile = oldPath.endsWith(".md") && (await a.t.memory(a.agentId, oldPath)) !== undefined;
+    const to = pathOf(rawNew, isFile ? "file" : "any");
+    if (!("path" in to))
+        return to;
+    const newPath = to.path;
+    if (newPath === MEMORY_ROOT || memoryPathWithin(newPath, oldPath))
+        return refused("memory.path_invalid", `Can't rename ${oldPath} to ${newPath}: it would move into itself.`);
+    if (isFile) {
+        const rows = await lockPaths(a.t, a.agentId, [oldPath, newPath]);
+        const row = rows.get(oldPath);
+        if (!row)
+            return missing(oldPath);
+        if (rows.get(newPath) || (await a.t.memories(a.agentId, { folder: newPath, limit: 1 })).length > 0)
+            return refused("memory.exists", `The destination ${newPath} already exists`);
+        await a.t.deleteMemory(a.agentId, oldPath);
+        const change = await write(a, newPath, { ...row, version: 0 }, row.content, "rename", oldPath);
+        return { ok: true, text: `Successfully renamed ${oldPath} to ${newPath}`, changes: [change] };
+    }
+    const rows = await a.t.memories(a.agentId, { folder: oldPath, lock: true });
+    if (rows.length === 0)
+        return missing(oldPath);
+    const targets = rows.map((row) => `${newPath}${row.path.slice(oldPath.length)}`);
+    for (const target of targets)
+        if ("error" in memoryPathOf(target, "file"))
+            return refused("memory.path_invalid", `Renaming ${oldPath} to ${newPath} would make ${target}, which is too long or invalid.`);
+    const taken = await lockPaths(a.t, a.agentId, [newPath, ...targets]);
+    if ([...taken.values()].some(Boolean) || (await a.t.memories(a.agentId, { folder: newPath, limit: 1 })).length > 0)
+        return refused("memory.exists", `The destination ${newPath} already exists`);
+    const changes = [];
+    for (const [index, row] of rows.entries()) {
+        await a.t.deleteMemory(a.agentId, row.path);
+        changes.push(await write(a, targets[index], { ...row, version: 0 }, row.content, "rename", row.path));
+    }
+    return { ok: true, text: `Successfully renamed ${oldPath} to ${newPath}`, changes };
+}
+// --- the pinned index ------------------------------------------------------------
+/**
+ * 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 async function renderMemoryIndex(t, agentId, limits) {
+    const rows = await t.recentMemories(agentId, limits.memoryIndexLines + 1);
+    const lines = [];
+    let bytes = 0;
+    let truncated = rows.length > limits.memoryIndexLines;
+    for (const row of rows.slice(0, limits.memoryIndexLines)) {
+        const line = row.description ? `- ${row.path} — ${row.description}` : `- ${row.path}`;
+        const size = Buffer.byteLength(line, "utf8") + 1;
+        if (bytes + size > limits.memoryIndexBytes) {
+            truncated = true;
+            break;
+        }
+        lines.push(line);
+        bytes += size;
+    }
+    return { index: lines.join("\n"), truncated };
+}
+// --- views ---------------------------------------------------------------------
+export function memorySummaryOf(row) {
+    return {
+        path: row.path,
+        bytes: row.bytes,
+        contentSha256: row.contentSha256,
+        description: row.description,
+        version: row.version,
+        updatedAt: row.updatedAt,
+    };
+}
+export function memoryVersionOf(row) {
+    return {
+        id: row.id,
+        path: row.path,
+        fromPath: row.fromPath,
+        operation: row.operation,
+        bytes: row.bytes,
+        contentSha256: row.contentSha256,
+        actor: row.actor,
+        sessionId: row.sessionId,
+        turnId: row.turnId,
+        triggerRunId: row.triggerRunId,
+        createdAt: row.createdAt,
+    };
+}
+export function memoryVersionDetailOf(row) {
+    return { ...memoryVersionOf(row), content: row.content };
+}

package/dist/memory/tool.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The `memory` tool's calls (track T5, D72): a `runtime` effect, operation `memory`, which core
+ * serves in the transaction that journals the call, as it does `schedule_wake`. So a replayed turn
+ * applies a write once and sees the same `view`, and a BYO harness gets the same answers by sending
+ * the same target. The input is Anthropic's memory tool's: `command` and its parameters.
+ *
+ * Core checks every call, whichever harness sent it (our engine runs the same `checkMemoryCall`
+ * before it sends one): a call missing a command's parameter, or with a parameter of the wrong
+ * type, fails with Anthropic-style text (`Error: create requires file_text.`) and changes nothing. Writes need `access: "read_write"` in the version the session runs and the
+ * root agent: a sub-agent's call (one that names its `agent`) may only view (`memory.forbidden`).
+ */
+import { type AgentMemorySettings } from "@nylorun/core/contracts";
+import type { Tx } from "../store/types.js";
+import type { Session } from "../tenant/context.js";
+type Outcome = {
+    kind: "completed";
+    output: string;
+} | {
+    kind: "failed";
+    code: string;
+    message: string;
+};
+/** `harness.memory` of the agent manifest version session `s` runs, when it sets one. */
+export declare function memorySettingsOf(t: Tx, s: Pick<Session, "definition">): Promise<AgentMemorySettings | undefined>;
+/**
+ * Serves one `memory` call of session `s`'s active turn in `t`: a view, or a write recorded as a
+ * version attributed to the turn (`agent:<manifest>@<version>`, the session, turn and the trigger
+ * run that started it), with `memory.updated` in the session and `agent.memory_updated` on the
+ * Agent's stream when something changed.
+ */
+export declare function serveMemoryTool(t: Tx, s: Session, request: {
+    effectId: string;
+    input?: unknown;
+    agent?: unknown;
+}): Promise<Outcome>;
+export {};

package/dist/memory/tool.js

@@ -0,0 +1,84 @@
+/**
+ * The `memory` tool's calls (track T5, D72): a `runtime` effect, operation `memory`, which core
+ * serves in the transaction that journals the call, as it does `schedule_wake`. So a replayed turn
+ * applies a write once and sees the same `view`, and a BYO harness gets the same answers by sending
+ * the same target. The input is Anthropic's memory tool's: `command` and its parameters.
+ *
+ * Core checks every call, whichever harness sent it (our engine runs the same `checkMemoryCall`
+ * before it sends one): a call missing a command's parameter, or with a parameter of the wrong
+ * type, fails with Anthropic-style text (`Error: create requires file_text.`) and changes nothing. Writes need `access: "read_write"` in the version the session runs and the
+ * root agent: a sub-agent's call (one that names its `agent`) may only view (`memory.forbidden`).
+ */
+import { checkMemoryCall } from "@nylorun/core/contracts";
+import { readRuntimeLimits } from "../tenant/runtime-limits.js";
+import { applyMemoryCommand, viewMemory } from "./service.js";
+/** `harness.memory` of the agent manifest version session `s` runs, when it sets one. */
+export async function memorySettingsOf(t, s) {
+    if (!s.definition)
+        return undefined;
+    const version = await t.agentManifest(s.definition.name, s.definition.version);
+    const harness = version?.body.harness;
+    return harness?.kind === "workflow" ? undefined : harness?.memory;
+}
+function commandOf(command, args) {
+    switch (command) {
+        case "create":
+            return { command, path: args.path, fileText: args.file_text };
+        case "str_replace":
+            return {
+                command,
+                path: args.path,
+                oldStr: args.old_str,
+                ...(typeof args.new_str === "string" ? { newStr: args.new_str } : {}),
+            };
+        case "insert":
+            return { command, path: args.path, insertLine: Number(args.insert_line), insertText: args.insert_text };
+        case "delete":
+            return { command, path: args.path };
+        case "rename":
+            return { command, oldPath: args.old_path, newPath: args.new_path };
+    }
+}
+/**
+ * Serves one `memory` call of session `s`'s active turn in `t`: a view, or a write recorded as a
+ * version attributed to the turn (`agent:<manifest>@<version>`, the session, turn and the trigger
+ * run that started it), with `memory.updated` in the session and `agent.memory_updated` on the
+ * Agent's stream when something changed.
+ */
+export async function serveMemoryTool(t, s, request) {
+    const settings = await memorySettingsOf(t, s);
+    if (!settings)
+        return { kind: "failed", code: "tool.unavailable", message: "This session's agent has no memory (harness.memory)." };
+    const parsed = checkMemoryCall(request.input);
+    if ("error" in parsed)
+        return { kind: "failed", code: "tool.invalid-input", message: parsed.error };
+    const { command, args } = parsed;
+    if (command === "view") {
+        const range = Array.isArray(args.view_range) ? [Number(args.view_range[0]), Number(args.view_range[1])] : undefined;
+        const viewed = await viewMemory(t, s.agentId, args.path, range);
+        return viewed.ok ? { kind: "completed", output: viewed.text } : { kind: "failed", code: viewed.code, message: viewed.text };
+    }
+    if ((settings.access ?? "read_write") === "read_only" || request.agent !== undefined)
+        return {
+            kind: "failed",
+            code: "memory.forbidden",
+            message: request.agent !== undefined
+                ? "Error: memory is read-only for a sub-agent; only the main agent writes it."
+                : "Error: this agent's memory is read-only (harness.memory.access); view it, but don't change it.",
+        };
+    const turnId = s.activeTurnId;
+    const result = await applyMemoryCommand(t, s.agentId, commandOf(command, args), {
+        actor: `agent:${s.definition.name}@${s.definition.version}`,
+        sessionId: s.id,
+        turnId,
+        ...(s.turnCause ? { triggerRunId: s.turnCause.runId } : {}),
+    }, await readRuntimeLimits(t));
+    if (!result.ok)
+        return { kind: "failed", code: result.code, message: result.text };
+    if (result.changes.length > 0) {
+        const changes = result.changes.map((change) => ({ ...change }));
+        await t.event(s.id, turnId, "memory.updated", { effectId: request.effectId, changes });
+        await t.agentEvent(s.agentId, "agent.memory_updated", { effectId: request.effectId, changes, sessionId: s.id, turnId });
+    }
+    return { kind: "completed", output: result.text };
+}

package/dist/model/pi-model.js

@@ -225,6 +225,13 @@ export function piModel(options = {}) {
                     // pi-ai initializes missing counters to zero; reporting provenance is unknown.
                     tokensReported: null,
                     costKnown: !selection.custom,
+                    // The cost by token kind, at the catalog's prices: the usage ledger keeps it.
+                    costSplit: {
+                        input: response.usage.cost.input,
+                        cacheRead: response.usage.cost.cacheRead,
+                        cacheWrite: response.usage.cost.cacheWrite,
+                        output: response.usage.cost.output,
+                    },
                     producer: {
                         provider: selected.provider,
                         api: selected.api,