@batalabs/virlow-mcp-core 3.84.2 → 3.85.0

package/dist/cjs/memories.d.ts

@@ -212,6 +212,9 @@ export declare class MemoryStore {
     /** The namespace of a memory this session has seen, without a sync;
      *  undefined for a global memory or one not cached yet. */
     namespaceOfCached(id: string): string | undefined;
+    /** One memory as this session has it, without a sync; undefined when it
+     *  is not cached. */
+    cached(id: string): CachedMemory | undefined;
     /** Requires a prior sync() in the same unlock to have populated the cache. */
     list(namespace?: string): CachedMemory[];
     update(id: string, changes: {

package/dist/cjs/memories.js

@@ -654,6 +654,11 @@ class MemoryStore {
     namespaceOfCached(id) {
         return this.cache.get(id)?.namespace;
     }
+    /** One memory as this session has it, without a sync; undefined when it
+     *  is not cached. */
+    cached(id) {
+        return this.cache.get(id);
+    }
     /** Requires a prior sync() in the same unlock to have populated the cache. */
     list(namespace) {
         this.requireSession();

package/dist/cjs/memory-secrets.d.ts

@@ -1,5 +1,6 @@
 /**
- * Refuses memories that contain credentials, before anything is written.
+ * Refuses memories that contain credentials, payment card and bank account
+ * numbers, or government ID numbers, before anything is written.
  *
  * Memories are captured automatically, so the rule cannot depend on the AI
  * remembering not to save a key: a memory is encrypted, but it is recalled
@@ -8,7 +9,11 @@
  * left out instead of retrying with the secret reworded.
  *
  * Deliberately narrow: patterns that are credentials with near certainty,
- * plus long high-entropy tokens. A false positive costs one memory; a false
+ * plus long high-entropy tokens, plus the restricted data that has a shape
+ * to match (card numbers and security codes, IBANs and labelled account
+ * numbers, US Social Security numbers, labelled passport, licence and
+ * national ID numbers). Health information has no such shape; the server
+ * instructions tell the model not to save it. A false positive costs one memory; a false
  * negative puts a live key into every future prompt that recalls it.
  */
 /** What secret the text holds, or null when it holds none. */

package/dist/cjs/memory-secrets.js

@@ -1,6 +1,7 @@
 "use strict";
 /**
- * Refuses memories that contain credentials, before anything is written.
+ * Refuses memories that contain credentials, payment card and bank account
+ * numbers, or government ID numbers, before anything is written.
  *
  * Memories are captured automatically, so the rule cannot depend on the AI
  * remembering not to save a key: a memory is encrypted, but it is recalled
@@ -9,7 +10,11 @@
  * left out instead of retrying with the secret reworded.
  *
  * Deliberately narrow: patterns that are credentials with near certainty,
- * plus long high-entropy tokens. A false positive costs one memory; a false
+ * plus long high-entropy tokens, plus the restricted data that has a shape
+ * to match (card numbers and security codes, IBANs and labelled account
+ * numbers, US Social Security numbers, labelled passport, licence and
+ * national ID numbers). Health information has no such shape; the server
+ * instructions tell the model not to save it. A false positive costs one memory; a false
  * negative puts a live key into every future prompt that recalls it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
@@ -31,7 +36,47 @@ const PATTERNS = [
         test: /\b(password|passwd|pwd|passphrase|api[_ -]?key|secret|token)\s*[:=]\s*\S{6,}/i,
     },
     { what: 'a connection string with a password', test: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:[^\s@/]{3,}@/i },
+    { what: 'a card security code', test: /\b(cvv2?|cvc2?|card security code)\s*[:#=]?\s*\d{3,4}\b/i },
+    {
+        // The issued format: no 000/666/9xx area, no 00 group, no 0000 serial.
+        // Phone numbers (3-3-4) and dates (4-2-2) do not take this shape.
+        what: 'a Social Security number',
+        test: /\b(?!000|666|9\d\d)\d{3}-(?!00)\d{2}-(?!0000)\d{4}\b/,
+    },
+    {
+        what: 'a Social Security number',
+        test: /\b(ssn|social security(\s+(number|no\.?|#))?)\b\D{0,20}\d{3}[ -]?\d{2}[ -]?\d{4}\b/i,
+    },
+    {
+        what: 'a bank account number',
+        test: /\b((bank\s+)?account|acct|routing)\s*(number|num|no\.?|#)\s*[:#=]?\s*\d[\d -]{4,}\d\b/i,
+    },
+    {
+        // A labelled ID followed by something with a digit in it, so "passport
+        // renewal is due in March" is a fact and "passport no. X1234567" is not.
+        what: 'a government ID number',
+        test: /\b(passport|driver'?s?\s+licen[cs]e|national\s+(id|insurance)|tax\s+(id|identification)|aadhaar|nino)(\s+(number|num|no\.?|#))?\s*[:#=]?\s*(?=[A-Z0-9-]*\d)[A-Z0-9][A-Z0-9-]{4,}\b/i,
+    },
 ];
+/** An IBAN that passes its ISO 13616 mod-97 check: country code, two check
+ *  digits, then 11 to 30 letters and digits, spaces allowed in groups of 4. */
+function hasIban(text) {
+    for (const [match] of text.matchAll(/\b[A-Z]{2}\d{2}(?: ?[A-Z0-9]){11,30}\b/g)) {
+        const iban = match.replace(/ /g, '');
+        if (iban.length < 15 || iban.length > 34)
+            continue;
+        const rearranged = iban.slice(4) + iban.slice(0, 4);
+        let remainder = 0;
+        for (const ch of rearranged) {
+            const value = ch >= 'A' && ch <= 'Z' ? String(ch.charCodeAt(0) - 55) : ch;
+            for (const digit of value)
+                remainder = (remainder * 10 + Number(digit)) % 97;
+        }
+        if (remainder === 1)
+            return true;
+    }
+    return false;
+}
 /** Luhn-valid runs of 13 to 19 digits, spaces or dashes allowed. */
 function hasCardNumber(text) {
     for (const match of text.matchAll(/\b(?:\d[ -]?){13,19}\b/g)) {
@@ -87,14 +132,17 @@ function findSecret(text) {
     }
     if (hasCardNumber(text))
         return 'a card number';
+    if (hasIban(text))
+        return 'a bank account number';
     if (hasHighEntropyToken(text))
         return 'what looks like a key or token';
     return null;
 }
 class SecretInMemoryError extends Error {
     constructor(what) {
-        super(`Not saved: this memory contains ${what}. Memories are recalled into prompts, so credentials are never ` +
-            'stored. Save the fact without the secret (for example "the API key is in 1Password"), not the secret.');
+        super(`Not saved: this memory contains ${what}. Memories are recalled into prompts, so credentials, card and ` +
+            'account numbers and ID numbers are never stored. Save the fact without it (for example "the API key ' +
+            'is in 1Password"), not the value itself.');
         this.name = 'SecretInMemoryError';
     }
 }

package/dist/cjs/tool-annotations.d.ts

@@ -0,0 +1,82 @@
+/** The four fields every tool carries. Required, so a missing hint is a
+ *  compile error rather than an omission a reviewer finds. */
+export interface VirlowToolAnnotations {
+    title: string;
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    openWorldHint: boolean;
+}
+export declare const TOOL_ANNOTATIONS: {
+    readonly unlock: VirlowToolAnnotations;
+    readonly lock: VirlowToolAnnotations;
+    readonly status: VirlowToolAnnotations;
+    readonly add_memory: VirlowToolAnnotations;
+    readonly search_memory: VirlowToolAnnotations;
+    readonly list_memories: VirlowToolAnnotations;
+    readonly recall_entity: VirlowToolAnnotations;
+    readonly link_memory: VirlowToolAnnotations;
+    readonly merge_entities: VirlowToolAnnotations;
+    readonly memory_context: VirlowToolAnnotations;
+    readonly memory_health: VirlowToolAnnotations;
+    readonly describe_entity: VirlowToolAnnotations;
+    readonly untyped_entities: VirlowToolAnnotations;
+    readonly update_memory: VirlowToolAnnotations;
+    readonly delete_memory: VirlowToolAnnotations;
+    readonly search_notes: VirlowToolAnnotations;
+    readonly list_notes: VirlowToolAnnotations;
+    readonly list_folders: VirlowToolAnnotations;
+    readonly read_note: VirlowToolAnnotations;
+    readonly create_note: VirlowToolAnnotations;
+    readonly update_note: VirlowToolAnnotations;
+    readonly get_backlinks: VirlowToolAnnotations;
+    readonly list_folder_view: VirlowToolAnnotations;
+    readonly list_properties: VirlowToolAnnotations;
+    readonly define_property: VirlowToolAnnotations;
+    readonly read_dashboard: VirlowToolAnnotations;
+    readonly set_dashboard: VirlowToolAnnotations;
+    readonly set_properties: VirlowToolAnnotations;
+    readonly move_note: VirlowToolAnnotations;
+    readonly set_star: VirlowToolAnnotations;
+    readonly archive_note: VirlowToolAnnotations;
+    readonly trash_note: VirlowToolAnnotations;
+    readonly create_folder: VirlowToolAnnotations;
+    readonly list_attachments: VirlowToolAnnotations;
+    readonly add_attachment: VirlowToolAnnotations;
+    readonly read_attachment: VirlowToolAnnotations;
+    readonly rename_attachment: VirlowToolAnnotations;
+    readonly move_attachment: VirlowToolAnnotations;
+    readonly delete_attachment: VirlowToolAnnotations;
+    readonly restore_attachment: VirlowToolAnnotations;
+};
+export type ToolName = keyof typeof TOOL_ANNOTATIONS;
+/**
+ * A tool's annotations for this host. Only read_attachment varies: with file
+ * access its `save_to` / `overwrite` can replace a file on the user's disk.
+ * A fresh object each call, so nothing downstream can mutate the table.
+ */
+export declare function toolAnnotations(name: ToolName, opts?: {
+    fileAccess?: boolean;
+}): VirlowToolAnnotations;
+/**
+ * Short status lines ChatGPT shows while a tool runs and once it returns
+ * (`openai/toolInvocation/invoking` and `.../invoked`, 64 characters at most).
+ * Other clients ignore `_meta`. Only the tools a user sees most often in a
+ * conversation carry them.
+ */
+export declare const INVOCATION_STATUS: Partial<Record<ToolName, {
+    invoking: string;
+    invoked: string;
+}>>;
+/**
+ * Everything registerTool takes besides the description, schema and handler:
+ * the display title, the annotations and, where there are any, the `_meta`
+ * keys: the status line, and the inline card for the tools that have one
+ * (see widgets.ts). Spread into each registerTool config.
+ */
+export declare function toolConfig(name: ToolName, opts?: {
+    fileAccess?: boolean;
+}): {
+    title: string;
+    annotations: VirlowToolAnnotations;
+    _meta?: Record<string, unknown>;
+};

package/dist/cjs/tool-annotations.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INVOCATION_STATUS = exports.TOOL_ANNOTATIONS = void 0;
+exports.toolAnnotations = toolAnnotations;
+exports.toolConfig = toolConfig;
+/**
+ * MCP tool annotations for every tool the server registers.
+ *
+ * Clients use these to decide when to ask the user before a call: ChatGPT,
+ * for one, confirms a write and asks again for anything marked destructive,
+ * and its plugin review requires all three hints to be explicit booleans on
+ * every tool. They live in one table, rather than inline at each
+ * registerTool call, so the whole surface can be read and reviewed at once
+ * and a test can hold every registered tool to it.
+ *
+ * The rules applied:
+ *
+ * - readOnlyHint: true only when the call changes nothing the user owns
+ *   (retrieval, search, listings, status). Refreshing this process's own
+ *   cache does not count as a change.
+ * - destructiveHint: true when the call can overwrite, remove, hide, move or
+ *   rewrite something the user already has, even when the app can undo it
+ *   (Trash, version history, a kept previous dashboard). false only for
+ *   additive writes and for state changes that lose nothing.
+ * - openWorldHint: false everywhere. Every tool acts on the user's own
+ *   private Virlow workspace; none searches the web or writes to an arbitrary
+ *   destination.
+ *
+ * Judgment calls, so the next reader does not have to rediscover them:
+ *
+ * - add_memory and link_memory are not destructive. add_memory only folds
+ *   into an existing memory when it is a near-identical restatement
+ *   (similarity at or above DEDUPE_UPDATE_THRESHOLD) and never when the new
+ *   fact contradicts the old one; superseded facts get an end date and are
+ *   kept as history, never removed. link_memory only adds entities and
+ *   relations, ending superseded facts the same way.
+ * - describe_entity is destructive: a kind or note given there replaces the
+ *   one stored, and an empty note clears it.
+ * - set_star is not destructive: a star is a reversible marker with nothing
+ *   behind it. archive_note is: it takes the note out of the user's lists.
+ * - unlock and lock change session state, not data, so neither is read-only
+ *   and neither is destructive. lock only discards this session's in-memory
+ *   key and caches; nothing stored is touched and unlock restores access.
+ * - read_attachment depends on the host. Without file access it only returns
+ *   the file. With it (local CLI, desktop app) `save_to` writes to the user's
+ *   disk and `overwrite: true` replaces an existing file, so it is a
+ *   destructive write there.
+ */
+const widgets_js_1 = require("./widgets.js");
+const read = (title) => ({
+    title,
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: false,
+});
+const additive = (title) => ({
+    title,
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: false,
+});
+const destructive = (title) => ({
+    title,
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: false,
+});
+exports.TOOL_ANNOTATIONS = {
+    // vault lifecycle
+    unlock: additive('Unlock Virlow'),
+    lock: additive('Lock Virlow'),
+    status: read('Check Virlow status'),
+    // memories
+    add_memory: additive('Save a memory'),
+    search_memory: read('Search memories'),
+    list_memories: read('List memories'),
+    recall_entity: read('Recall a person or project'),
+    link_memory: additive('Link a memory to entities'),
+    merge_entities: destructive('Merge two entities'),
+    memory_context: read('Get memory briefing'),
+    memory_health: read('Check memory health'),
+    describe_entity: destructive('Describe an entity'),
+    untyped_entities: read('List entities without a kind'),
+    update_memory: destructive('Update a memory'),
+    delete_memory: destructive('Delete a memory'),
+    // notes
+    search_notes: read('Search notes'),
+    list_notes: read('List notes'),
+    list_folders: read('List folders'),
+    read_note: read('Read a note'),
+    create_note: additive('Create a note'),
+    update_note: destructive('Update a note'),
+    get_backlinks: read('Get backlinks'),
+    list_folder_view: read('Read folder table view'),
+    list_properties: read('List folder properties'),
+    define_property: additive('Define a folder property'),
+    read_dashboard: read('Read a dashboard'),
+    set_dashboard: destructive('Replace a dashboard'),
+    set_properties: destructive('Set note properties'),
+    move_note: destructive('Move a note'),
+    set_star: additive('Star or unstar a note'),
+    archive_note: destructive('Archive or unarchive a note'),
+    trash_note: destructive('Move a note to the trash'),
+    create_folder: additive('Create a folder'),
+    // attachments
+    list_attachments: read('List attachments'),
+    add_attachment: additive('Attach a file'),
+    read_attachment: read('Read an attachment'),
+    rename_attachment: destructive('Rename an attachment'),
+    move_attachment: destructive('Move an attachment'),
+    delete_attachment: destructive('Delete an attachment'),
+    restore_attachment: additive('Restore an attachment'),
+};
+/**
+ * A tool's annotations for this host. Only read_attachment varies: with file
+ * access its `save_to` / `overwrite` can replace a file on the user's disk.
+ * A fresh object each call, so nothing downstream can mutate the table.
+ */
+function toolAnnotations(name, opts = {}) {
+    if (name === 'read_attachment' && opts.fileAccess === true) {
+        return destructive('Read or save an attachment');
+    }
+    return { ...exports.TOOL_ANNOTATIONS[name] };
+}
+/**
+ * Short status lines ChatGPT shows while a tool runs and once it returns
+ * (`openai/toolInvocation/invoking` and `.../invoked`, 64 characters at most).
+ * Other clients ignore `_meta`. Only the tools a user sees most often in a
+ * conversation carry them.
+ */
+exports.INVOCATION_STATUS = {
+    add_memory: { invoking: 'Saving to Virlow…', invoked: 'Saved to Virlow' },
+    update_memory: { invoking: 'Updating Virlow…', invoked: 'Updated Virlow' },
+    search_memory: { invoking: 'Checking Virlow…', invoked: 'Checked Virlow' },
+    memory_context: { invoking: 'Checking Virlow…', invoked: 'Checked Virlow' },
+    recall_entity: { invoking: 'Checking Virlow…', invoked: 'Checked Virlow' },
+};
+/**
+ * Everything registerTool takes besides the description, schema and handler:
+ * the display title, the annotations and, where there are any, the `_meta`
+ * keys: the status line, and the inline card for the tools that have one
+ * (see widgets.ts). Spread into each registerTool config.
+ */
+function toolConfig(name, opts = {}) {
+    const annotations = toolAnnotations(name, opts);
+    const status = exports.INVOCATION_STATUS[name];
+    const widget = (0, widgets_js_1.widgetToolMeta)(name);
+    const meta = {
+        ...(status && {
+            'openai/toolInvocation/invoking': status.invoking,
+            'openai/toolInvocation/invoked': status.invoked,
+        }),
+        ...widget,
+    };
+    return {
+        title: annotations.title,
+        annotations,
+        ...(Object.keys(meta).length > 0 && { _meta: meta }),
+    };
+}

package/dist/cjs/widgets.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Inline cards for hosts that render MCP Apps UI: ChatGPT (Apps SDK) and any
+ * other client that implements the MCP Apps extension.
+ *
+ * Two cards, each one self-contained HTML document served as a `ui://`
+ * resource:
+ *
+ * - saved-memory: shown after add_memory and update_memory. "Saved to
+ *   Virlow" (or "Updated in Virlow"), the label, the fact, the entities as
+ *   kind-coloured chips, and at most two actions: Undo (a fresh save only)
+ *   and Open in Virlow.
+ * - memory-context: shown after memory_context. "What Virlow knows": a few
+ *   recent facts and the people and projects they are about, with one
+ *   action, Open in Virlow.
+ *
+ * Why it is registered for every deployment, not only the hosted connector:
+ *
+ * - Nothing changes for a client that does not render UI. The text `content`
+ *   every tool returned before is returned unchanged; `structuredContent` and
+ *   `_meta` are extra fields such a client ignores, and a client that never
+ *   reads a `ui://` resource never sees the HTML.
+ * - "Hosted only" would not mean "ChatGPT only": the hosted connector also
+ *   serves claude.ai, and Claude Desktop (the local CLI's main host) renders
+ *   MCP Apps too. So the card has to be right in every host anyway, which is
+ *   why it speaks both bridges (window.openai and the MCP Apps postMessage
+ *   protocol) rather than ChatGPT's alone.
+ * - One tool surface for both deployments is the rule this package exists
+ *   for (see tools.ts); a host-specific `_meta` would be the first exception.
+ *
+ * The page loads nothing from the network: inline CSS and script, system
+ * fonts, the brand mark as inline SVG. Its only way out is the host's own
+ * bridge (callTool, openExternal), so its CSP declares no domains at all.
+ * Data is written with textContent, never as markup: a memory's text is
+ * whatever a model or a person typed.
+ */
+import type { EntityKind } from './memory-graph.js';
+/** The MCP Apps resource type. ChatGPT reads it too. */
+export declare const WIDGET_MIME_TYPE = "text/html;profile=mcp-app";
+export declare const SAVED_MEMORY_URI = "ui://widget/saved-memory.html";
+export declare const MEMORY_CONTEXT_URI = "ui://widget/memory-context.html";
+/** Where "Open in Virlow" goes. The web app has no per-memory route, so it
+ *  opens the app itself. */
+export declare const VIRLOW_APP_URL = "https://app.virlow.com";
+/**
+ * The thirteen kind colours, light and dark. A copy of KIND_COLORS in the
+ * web app (src/lib/entityKinds.ts), which cannot be imported here: that
+ * module pulls in lucide-react. A test holds the two to the same values.
+ */
+export declare const KIND_COLORS: Record<EntityKind, {
+    light: string;
+    dark: string;
+}>;
+export interface CardEntity {
+    name: string;
+    kind: EntityKind;
+}
+/** structuredContent of add_memory and update_memory. */
+export interface SavedMemoryContent {
+    id: string;
+    label: string;
+    text: string;
+    /** The project it was saved under; null for a memory that applies everywhere. */
+    namespace: string | null;
+    entities: CardEntity[];
+    /** True when an existing memory changed (update_memory, or add_memory
+     *  folding a near-identical restatement into one), false for a new one. */
+    updated: boolean;
+}
+/** structuredContent of memory_context. */
+export interface MemoryContextContent {
+    namespace: string | null;
+    /** Saving is paused for the account or this project (recall still works). */
+    paused: boolean;
+    /** The most recent current facts, newest first. */
+    facts: Array<{
+        id: string;
+        label: string;
+        text: string;
+    }>;
+    /** The entities these memories name most, most first. */
+    entities: Array<CardEntity & {
+        facts: number;
+    }>;
+}
+/** How many facts the context card shows; the text result keeps them all. */
+export declare const CONTEXT_CARD_FACTS = 5;
+type WidgetView = 'saved' | 'context';
+/** Which tools show which card. Tools not named here have no UI. */
+export declare const TOOL_WIDGETS: Partial<Record<string, WidgetView>>;
+/** The tool-side `_meta` linking a tool to its card: the MCP Apps key and
+ *  ChatGPT's alias for it. add_memory's card calls delete_memory (Undo), so
+ *  it is marked as allowed to call tools. */
+export declare function widgetToolMeta(tool: string): Record<string, unknown> | undefined;
+/** Everything the server needs to list and serve the two resources. */
+export declare const WIDGET_RESOURCES: Array<{
+    name: string;
+    uri: string;
+    title: string;
+    description: string;
+    view: WidgetView;
+}>;
+/** A `resources/read` result for one card. */
+export declare function readWidget(view: WidgetView): {
+    contents: {
+        uri: string;
+        mimeType: string;
+        text: string;
+        _meta: Record<string, unknown>;
+    }[];
+};
+/** The whole page for one card. */
+export declare function widgetHtml(view: WidgetView): string;
+/** The pieces, for the widget tests: they run the script against the page
+ *  body in jsdom without a host. */
+export declare const WIDGET_PARTS: {
+    css: string;
+    script: string;
+};
+export {};