@opendatalabs/personal-server-ts-core 1.34.2 → 1.35.0

package/dist/mcp/tools.js

@@ -1,18 +1,25 @@
-import { isSystemScope } from "../policy/reserved-scopes.js";
+import { isMemoryScope, isSystemScope } from "../policy/reserved-scopes.js";
 /**
  * MCP tool surface. Phase 1 / §4 of 260604-PLAN-vana-mcp-personal-server.md.
  *
- * Read-only, small, and only over scopes that the connection's grants cover.
- * No write tools. No grant-approval tools. No raw owner/admin status tools.
+ * Small, and only over scopes that the connection's grants cover. No
+ * grant-approval tools. No raw owner/admin status tools.
  *
  * Every tool that returns data first picks a covering grant from the
  * connection's grant list, signs a Web3Signed request as the per-connection
  * grantee, and uses the bounded sidecar read path — so reads are grant-gated,
  * access-logged, and safe for large scopes.
+ *
+ * The one write tool, `remember`, saves only into a scope a `write:` grant
+ * entry covers, and goes through the delegated-write path a builder uses
+ * (see write-client.ts). A read grant never confers write access, and a
+ * `write:` entry never confers read access.
  */
 import { z } from "zod";
 import { MCP_SCOPE_ACCESS_REQUEST_LIMIT, } from "./types.js";
 import { McpDataReadError } from "./read-client.js";
+import { McpDataWriteError } from "./write-client.js";
+import { isWriteScopeEntry, writeScopePatterns, WRITE_SCOPE_PREFIX, } from "../policy/data-write.js";
 import { toMcpScopeAccessRequestView } from "./connection-api.js";
 import { MiniSearchIndex } from "./search/index.js";
 import { MAX_SELECTED_BLOCK_IDS } from "../storage/blocks/index.js";
@@ -47,20 +54,83 @@ function textResult(value, isError = false) {
         ...(isError ? { isError: true } : {}),
     };
 }
+/** A grant entry that names readable data: not a system scope, not `write:`. */
+function isReadableScopeEntry(scope) {
+    return !isSystemScope(scope) && !isWriteScopeEntry(scope);
+}
 function uniqueScopes(connection) {
     const set = new Set();
     for (const grant of connection.grants) {
         for (const scope of grant.scopes) {
-            if (!isSystemScope(scope))
+            if (isReadableScopeEntry(scope))
                 set.add(scope);
         }
     }
     return Array.from(set).sort();
 }
+/**
+ * A scope `remember` may save into under these grant entries: an exact
+ * `write:<scope>` entry. MCP writes never honor a `write:` wildcard, even one
+ * an older grant still carries, although builder writes do: a memory grant
+ * names the one scope the agent saves into.
+ */
+function exactWriteScopes(grantScopes) {
+    return writeScopePatterns(grantScopes).filter((scope) => !scope.includes("*") && !isSystemScope(scope));
+}
+/** Scopes the connection may save into, `write:` prefix stripped. */
+function uniqueWritableScopes(connection) {
+    const set = new Set();
+    for (const grant of connection.grants) {
+        for (const scope of exactWriteScopes(grant.scopes))
+            set.add(scope);
+    }
+    return Array.from(set).sort();
+}
+/**
+ * Every data scope (or pattern) the connection may read or write, `write:`
+ * prefix stripped. A host that copies data in before serving a connection
+ * (the enclave) must copy write targets too: `remember` rewrites the whole
+ * memory list from the local copy, so a missing copy would drop memories.
+ */
+export function connectionDataScopes(connection) {
+    const set = new Set();
+    for (const grant of connection.grants) {
+        for (const scope of grant.scopes) {
+            const target = isWriteScopeEntry(scope)
+                ? scope.slice(WRITE_SCOPE_PREFIX.length)
+                : scope;
+            if (target)
+                set.add(target);
+        }
+    }
+    return Array.from(set).sort();
+}
+/**
+ * Resolve a scope to a grant with an exact `write:` entry for it (see
+ * exactWriteScopes). The server-side write policy still runs on every save;
+ * this only narrows what the tool will attempt.
+ */
+export function resolveWriteGrantForScope(connection, scope) {
+    for (const grant of connection.grants) {
+        if (exactWriteScopes(grant.scopes).includes(scope)) {
+            return { grantId: grant.grantId, scopes: grant.scopes };
+        }
+    }
+    return null;
+}
+/**
+ * Whether the connection already holds `scope` as a scope request names it:
+ * a `write:` entry is covered only by write grants, anything else by reads.
+ */
+function connectionCoversRequestedScope(connection, scope) {
+    return isWriteScopeEntry(scope)
+        ? Boolean(resolveWriteGrantForScope(connection, scope.slice(WRITE_SCOPE_PREFIX.length)))
+        : Boolean(resolveGrantForScope(connection, scope));
+}
 function uniqueSources(connection) {
     const set = new Set();
     for (const grant of connection.grants) {
-        if (!grant.scopes.some((scope) => !isSystemScope(scope)))
+        if (!grant.scopes.some(isReadableScopeEntry))
             continue;
         const sourceId = typeof grant.sourceId === "string" ? grant.sourceId.trim() : "";
         if (sourceId) {
@@ -68,7 +138,7 @@ function uniqueSources(connection) {
             continue;
         }
         for (const scope of grant.scopes) {
-            if (isSystemScope(scope))
+            if (!isReadableScopeEntry(scope))
                 continue;
             const [scopeSourceId] = scope.split(".");
             if (scopeSourceId && scopeSourceId !== "*") {
@@ -170,7 +240,7 @@ const scopeAccessRequestInputShape = {
         .array(z.string().min(1).max(SEARCH_SCOPE_MAX_CHARS))
         .min(1)
         .max(MCP_SCOPE_ACCESS_REQUEST_LIMIT)
-        .describe("Exact scope ids the MCP client wants to read."),
+        .describe("Exact scope ids to read, or write:<scope> to save into."),
     reason: z
         .string()
         .max(500)
@@ -558,8 +628,10 @@ const listGrantedScopes = {
         }));
         // Lets an agent that asked for more scopes see whether the owner has
         // answered yet without re-recording the request.
+        const writableScopes = uniqueWritableScopes(connection);
         return textResult({
             scopes: scopeEntries,
+            ...(writableScopes.length > 0 ? { writableScopes } : {}),
             ...(connection.scopeAccessRequest
                 ? {
                     pendingScopeRequest: toMcpScopeAccessRequestView(connection.scopeAccessRequest),
@@ -582,8 +654,8 @@ const requestScopeAccess = {
         // answer from the agent that is checking back.
         const previousDecision = connection.scopeAccessDecision;
         let effectiveConnection = connection;
-        let grantedRequestedScopes = requestedScopes.filter((scope) => Boolean(resolveGrantForScope(effectiveConnection, scope)));
-        let missingScopes = requestedScopes.filter((scope) => !resolveGrantForScope(connection, scope));
+        let grantedRequestedScopes = requestedScopes.filter((scope) => connectionCoversRequestedScope(effectiveConnection, scope));
+        let missingScopes = requestedScopes.filter((scope) => !connectionCoversRequestedScope(connection, scope));
         const reason = typeof args.reason === "string" ? args.reason.trim() : "";
         const approvalRequired = missingScopes.length > 0;
         const alreadyRecorded = approvalRequired &&
@@ -598,8 +670,8 @@ const requestScopeAccess = {
             effectiveConnection = outcome.connection;
             requestRecorded = outcome.requestRecorded;
             readToken = outcome.readToken;
-            grantedRequestedScopes = requestedScopes.filter((scope) => Boolean(resolveGrantForScope(effectiveConnection, scope)));
-            missingScopes = requestedScopes.filter((scope) => !resolveGrantForScope(effectiveConnection, scope));
+            grantedRequestedScopes = requestedScopes.filter((scope) => connectionCoversRequestedScope(effectiveConnection, scope));
+            missingScopes = requestedScopes.filter((scope) => !connectionCoversRequestedScope(effectiveConnection, scope));
         }
         const finalApprovalRequired = missingScopes.length > 0;
         const recorded = finalApprovalRequired && requestRecorded;
@@ -1435,6 +1507,316 @@ const getScopeFile = {
         }
     },
 };
+const REMEMBER_TOOL = "remember";
+const FORGET_TOOL = "forget";
+const REMEMBER_TEXT_MAX_CHARS = 4_000;
+const REMEMBER_KEY_MAX_CHARS = 128;
+const MEMORY_ID_MAX_CHARS = 64;
+/**
+ * Every save stores a new snapshot of the scope's record list, so the list is
+ * bounded by size rather than count. Sync publishes only the newest snapshot of
+ * a memory scope (see `isCoalescedScope` in sync/workers/upload.ts).
+ */
+export const MEMORY_SCOPE_MAX_BYTES = 20 * 1024 * 1024;
+class RememberRefusal extends Error {
+    body;
+    constructor(body) {
+        super(String(body.message));
+        this.body = body;
+        this.name = "RememberRefusal";
+    }
+}
+/** A save that would only repeat a memory the scope already holds. */
+class DuplicateMemory extends Error {
+    record;
+    constructor(record) {
+        super("duplicate memory");
+        this.record = record;
+        this.name = "DuplicateMemory";
+    }
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * The memory records of a stored body. A memory scope holds exactly
+ * `{ records: [...] }` of memory rows, or the earlier `{ memories: [...] }`
+ * list, which is converted here (ids kept). Anything else was written by
+ * someone else and is never overwritten.
+ */
+function storedMemoryRecords(scope, data) {
+    const keys = Object.keys(data);
+    if (keys.length === 1 &&
+        Array.isArray(data.records) &&
+        data.records.every((row) => isPlainRecord(row) &&
+            typeof row.id === "string" &&
+            typeof row.content === "string")) {
+        return data.records;
+    }
+    if (keys.length === 1 &&
+        Array.isArray(data.memories) &&
+        data.memories.every((item) => isPlainRecord(item) &&
+            typeof item.id === "string" &&
+            typeof item.text === "string")) {
+        return data.memories.map((item) => {
+            const at = typeof item.savedAt === "string" ? item.savedAt : "";
+            return {
+                id: item.id,
+                content: item.text,
+                created_at: at,
+                updated_at: at,
+                ...(typeof item.key === "string" ? { key: item.key } : {}),
+                written_by: null,
+            };
+        });
+    }
+    throw new RememberRefusal({
+        error: "scope_not_memory",
+        scope,
+        message: `Scope ${scope} holds data that is not a memory list; it will not be changed. Use another write scope.`,
+    });
+}
+/**
+ * The scope a memory tool acts on and the grant that covers it, or the error
+ * result to return. A call may omit `scope` when the connection can write to
+ * exactly one scope.
+ */
+function resolveMemoryTarget(args, connection) {
+    const writableScopes = uniqueWritableScopes(connection);
+    const namedScope = typeof args.scope === "string" ? args.scope.trim() : "";
+    const onlyScope = writableScopes.length === 1 && !writableScopes[0].includes("*")
+        ? writableScopes[0]
+        : "";
+    const scope = namedScope || onlyScope;
+    if (!scope) {
+        return {
+            error: textResult({
+                error: "scope_required",
+                writableScopes,
+                message: writableScopes.length === 0
+                    ? 'This connection cannot save memories. Call request_scope_access with scopes ["write:memory.<app>"] and ask the user to approve it.'
+                    : "Name the scope; this connection can write to more than one.",
+            }, true),
+        };
+    }
+    if (!isMemoryScope(scope)) {
+        return {
+            error: textResult({
+                error: "scope_not_memory",
+                scope,
+                message: `Memories live in memory.<app> scopes; ${scope} is not one.`,
+            }, true),
+        };
+    }
+    const grant = resolveWriteGrantForScope(connection, scope);
+    if (!grant) {
+        const requestScope = `${WRITE_SCOPE_PREFIX}${scope}`;
+        return {
+            error: textResult({
+                error: "scope_not_granted",
+                scope,
+                requestScope,
+                writableScopes,
+                message: `This connection may not write to ${scope}. Call request_scope_access with scopes ["${requestScope}"] and ask the user to approve it.`,
+            }, true),
+        };
+    }
+    return { scope, grantId: grant.grantId };
+}
+const WRITE_UNAVAILABLE = textResult({
+    error: "write_unavailable",
+    message: "This Personal Server does not accept MCP writes.",
+}, true);
+/** Map a refused or failed memory write to the tool's error result. */
+function memoryWriteError(err, scope) {
+    if (err instanceof RememberRefusal)
+        return textResult(err.body, true);
+    if (err instanceof McpDataWriteError) {
+        const body = err.body;
+        const detail = typeof body?.error === "object" && body.error !== null
+            ? body.error
+            : { errorCode: body?.error, message: body?.message };
+        return textResult({
+            error: err.status === 401 || err.status === 403
+                ? "unauthorized"
+                : err.status === 412
+                    ? "write_conflict"
+                    : "write_failed",
+            status: err.status,
+            scope,
+            ...(detail.errorCode ? { errorCode: detail.errorCode } : {}),
+            ...(detail.message ? { message: detail.message } : {}),
+        }, true);
+    }
+    throw err;
+}
+function memoryBody(records, scope) {
+    const body = { records };
+    if (new TextEncoder().encode(JSON.stringify(body)).byteLength >
+        MEMORY_SCOPE_MAX_BYTES) {
+        throw new RememberRefusal({
+            error: "memory_full",
+            scope,
+            limitBytes: MEMORY_SCOPE_MAX_BYTES,
+            message: `Scope ${scope} is full. Forget or replace memories to make room.`,
+        });
+    }
+    return body;
+}
+const remember = {
+    name: REMEMBER_TOOL,
+    title: "Remember",
+    description: "Save a fact, preference, goal or decision the user shares, without being asked, so any allowed agent can recall it. Tell the user briefly. Never save secrets, passwords, IDs or account numbers. Needs a write:<scope> grant (writableScopes).",
+    inputSchema: {
+        text: z
+            .string()
+            .min(1)
+            .max(REMEMBER_TEXT_MAX_CHARS)
+            .describe("Self-contained; readable without this chat."),
+        scope: z
+            .string()
+            .min(1)
+            .max(SEARCH_SCOPE_MAX_CHARS)
+            .optional()
+            .describe("e.g. memory.claude; optional with one writable scope."),
+        key: z
+            .string()
+            .min(1)
+            .max(REMEMBER_KEY_MAX_CHARS)
+            .optional()
+            .describe("Saving again with the same key replaces the memory."),
+    },
+    async handler(args, { connection, writeClient }) {
+        const content = typeof args.text === "string" ? args.text.trim() : "";
+        if (!content) {
+            return textResult({ error: "invalid_arguments", message: "text must not be empty." }, true);
+        }
+        const key = typeof args.key === "string" && args.key.trim()
+            ? args.key.trim()
+            : undefined;
+        const target = resolveMemoryTarget(args, connection);
+        if ("error" in target)
+            return target.error;
+        const { scope, grantId } = target;
+        if (!writeClient)
+            return WRITE_UNAVAILABLE;
+        const now = new Date().toISOString();
+        let saved;
+        let replaced = false;
+        let memoryCount = 0;
+        try {
+            await writeClient.updateScope({
+                scope,
+                grantId,
+                update(current) {
+                    const records = current.data === null
+                        ? []
+                        : storedMemoryRecords(scope, current.data);
+                    const previous = key
+                        ? records.find((record) => record.key === key)
+                        : undefined;
+                    if (!key) {
+                        const same = records.find((record) => record.content === content);
+                        if (same)
+                            throw new DuplicateMemory(same);
+                    }
+                    replaced = previous !== undefined;
+                    saved = {
+                        id: previous?.id ?? crypto.randomUUID(),
+                        content,
+                        created_at: previous?.created_at ?? now,
+                        updated_at: now,
+                        ...(key ? { key } : {}),
+                        written_by: connection.granteeAddress,
+                    };
+                    // Newest last: a replaced memory moves to the end, so list order is
+                    // the order the memories were last saved in.
+                    const next = [
+                        ...records.filter((record) => record !== previous),
+                        saved,
+                    ];
+                    memoryCount = next.length;
+                    return memoryBody(next, scope);
+                },
+            });
+        }
+        catch (err) {
+            if (err instanceof DuplicateMemory) {
+                return textResult({
+                    saved: false,
+                    duplicate: true,
+                    scope,
+                    id: err.record.id,
+                    message: "This memory is already saved.",
+                });
+            }
+            return memoryWriteError(err, scope);
+        }
+        return textResult({
+            saved: true,
+            scope,
+            id: saved.id,
+            savedAt: saved.updated_at,
+            ...(key ? { key } : {}),
+            replaced,
+            memoryCount,
+        });
+    },
+};
+const forget = {
+    name: FORGET_TOOL,
+    title: "Forget",
+    description: "Delete a saved memory by id or key. Needs a write:<scope> grant.",
+    inputSchema: {
+        id: z.string().min(1).max(MEMORY_ID_MAX_CHARS).optional(),
+        key: z.string().min(1).max(REMEMBER_KEY_MAX_CHARS).optional(),
+        scope: z.string().min(1).max(SEARCH_SCOPE_MAX_CHARS).optional(),
+    },
+    async handler(args, { connection, writeClient }) {
+        const id = typeof args.id === "string" ? args.id.trim() : "";
+        const key = typeof args.key === "string" ? args.key.trim() : "";
+        if (!id && !key) {
+            return textResult({ error: "invalid_arguments", message: "Pass id or key." }, true);
+        }
+        const target = resolveMemoryTarget(args, connection);
+        if ("error" in target)
+            return target.error;
+        const { scope, grantId } = target;
+        if (!writeClient)
+            return WRITE_UNAVAILABLE;
+        let forgotten = [];
+        let memoryCount = 0;
+        try {
+            await writeClient.updateScope({
+                scope,
+                grantId,
+                update(current) {
+                    const records = current.data === null
+                        ? []
+                        : storedMemoryRecords(scope, current.data);
+                    // With both id and key, a record must match both.
+                    const matches = (record) => (!id || record.id === id) && (!key || record.key === key);
+                    const keep = records.filter((record) => !matches(record));
+                    if (keep.length === records.length) {
+                        throw new RememberRefusal({
+                            error: "not_found",
+                            scope,
+                            message: "No saved memory matches that id or key.",
+                        });
+                    }
+                    // Reset on every attempt: a 412 retry re-runs this callback.
+                    forgotten = records.filter(matches).map((record) => record.id);
+                    memoryCount = keep.length;
+                    return memoryBody(keep, scope);
+                },
+            });
+        }
+        catch (err) {
+            return memoryWriteError(err, scope);
+        }
+        return textResult({ forgotten: true, scope, ids: forgotten, memoryCount });
+    },
+};
 export const MCP_TOOLS = [
     listGrantedSources,
     listGrantedScopes,
@@ -1443,5 +1825,7 @@ export const MCP_TOOLS = [
     listScopeBlocks,
     getScopeFile,
     searchPersonalContext,
+    remember,
+    forget,
 ];
 //# sourceMappingURL=tools.js.map