@ouro.bot/cli 0.1.0-alpha.75 → 0.1.0-alpha.750

package/dist/repertoire/tools-orientation.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.orientationToolDefinitions = void 0;
+const runtime_1 = require("../nerves/runtime");
+exports.orientationToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "orientation_get",
+                description: "return my current turn orientation frame: user-visible speech, channel/source metadata, active referents from the previous assistant response, and the current action policy. use this before mutating durable state when the user's latest message is terse, corrective, or referent-dependent.",
+                parameters: {
+                    type: "object",
+                    properties: {},
+                    required: [],
+                },
+            },
+        },
+        handler: (_args, ctx) => {
+            (0, runtime_1.emitNervesEvent)({
+                component: "repertoire",
+                event: "repertoire.orientation_get",
+                message: "orientation frame requested",
+                meta: { available: !!ctx?.orientationFrame },
+            });
+            if (!ctx?.orientationFrame)
+                return "no orientation frame is available for this turn.";
+            return JSON.stringify(ctx.orientationFrame, null, 2);
+        },
+    },
+];

package/dist/repertoire/tools-record.js

@@ -0,0 +1,482 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordToolDefinitions = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const session_events_1 = require("../heart/session-events");
+const embedding_provider_1 = require("../mind/embedding-provider");
+const note_search_1 = require("../mind/note-search");
+const record_paths_1 = require("../mind/record-paths");
+const friends_1 = require("@ouro.bot/friends");
+const runtime_1 = require("../nerves/runtime");
+const identity_1 = require("../heart/identity");
+const NOTES_INDEX_VERSION = 1;
+const NOTE_SLUG_MAX_CHARS = 40;
+const DEFAULT_LIMIT = 5;
+const MAX_LIMIT = 25;
+const DEFAULT_MIN_SCORE = 0.5;
+const PREVIEW_CHAR_LIMIT = 500;
+function hasSelfTrust(ctx) {
+    const channel = ctx?.context?.channel?.channel;
+    if (channel !== "inner")
+        return false;
+    const friend = ctx?.context?.friend;
+    return !friend || friend.id === "self";
+}
+function hasRecordReadTrust(ctx) {
+    if (hasSelfTrust(ctx))
+        return true;
+    const friend = ctx?.context?.friend;
+    return Boolean(friend) && (0, friends_1.isTrustedLevel)(friend?.trustLevel);
+}
+function bundleRelativeLocator(filePath, ctx) {
+    const agentRoot = ctx?.agentRoot ?? (0, identity_1.getAgentRoot)();
+    const relativePath = path.relative(agentRoot, filePath);
+    if (relativePath && !relativePath.startsWith("..") && !path.isAbsolute(relativePath)) {
+        return relativePath.split(path.sep).join("/");
+    }
+    return filePath.split(path.sep).join("/");
+}
+function normalizeTags(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const rawTags = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+    const tags = rawTags
+        .map((tag) => (typeof tag === "string" ? tag.trim() : ""))
+        .filter((tag) => tag.length > 0);
+    return tags.length > 0 ? tags : undefined;
+}
+function slugForContent(content) {
+    const slug = content
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, NOTE_SLUG_MAX_CHARS)
+        .replace(/-+$/g, "");
+    return slug || "note";
+}
+function renderNote(createdAt, content, tags) {
+    const frontmatter = [`created_at: ${createdAt}`];
+    if (tags?.length) {
+        frontmatter.push("tags:");
+        for (const tag of tags) {
+            frontmatter.push(`  - ${JSON.stringify(tag)}`);
+        }
+    }
+    return `---\n${frontmatter.join("\n")}\n---\n${content}\n`;
+}
+function ensureUniquePath(notesDir, date, slug) {
+    let candidate = path.join(notesDir, `${date}-${slug}.md`);
+    let suffix = 2;
+    while (fs.existsSync(candidate)) {
+        const suffixText = `-${suffix}`;
+        const cappedSlug = `${slug.slice(0, Math.max(0, NOTE_SLUG_MAX_CHARS - suffixText.length)).replace(/-+$/g, "")}${suffixText}`;
+        candidate = path.join(notesDir, `${date}-${cappedSlug}.md`);
+        suffix += 1;
+    }
+    return candidate;
+}
+function extractPreview(body) {
+    const firstLine = body.trim().split("\n").find((line) => line.trim().length > 0);
+    return (0, session_events_1.capStructuredRecordString)(firstLine.trim()).slice(0, PREVIEW_CHAR_LIMIT);
+}
+function parseTagsFromFrontmatter(lines, startIndex) {
+    const tags = [];
+    let i = startIndex;
+    while (lines[i + 1]?.trimStart().startsWith("- ")) {
+        i += 1;
+        tags.push(lines[i].trimStart().slice(2).trim().replace(/^"|"$/g, ""));
+    }
+    return { tags, nextIndex: i };
+}
+function parseCanonicalNote(filePath, stat) {
+    const raw = fs.readFileSync(filePath, "utf8");
+    let body = raw;
+    let createdAt;
+    let tags;
+    if (raw.startsWith("---\n")) {
+        const end = raw.indexOf("\n---\n", 4);
+        if (end > 0) {
+            const frontmatterRaw = raw.slice(4, end);
+            body = raw.slice(end + "\n---\n".length);
+            const lines = frontmatterRaw.split("\n");
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                if (!line.trim())
+                    continue;
+                const colonIndex = line.indexOf(":");
+                if (colonIndex < 0)
+                    continue;
+                const key = line.slice(0, colonIndex);
+                const value = line.slice(colonIndex + 1).trim();
+                if (key === "created_at" && value) {
+                    createdAt = value.replace(/^"|"$/g, "");
+                }
+                if (key === "tags") {
+                    if (value.startsWith("[") && value.endsWith("]")) {
+                        try {
+                            const parsed = JSON.parse(value);
+                            tags = parsed.filter((tag) => typeof tag === "string");
+                        }
+                        catch {
+                            tags = undefined;
+                        }
+                    }
+                    else {
+                        const parsedTags = parseTagsFromFrontmatter(lines, i);
+                        tags = parsedTags.tags.length > 0 ? parsedTags.tags : undefined;
+                        i = parsedTags.nextIndex;
+                    }
+                }
+            }
+        }
+    }
+    const trimmedBody = body.trim();
+    if (!trimmedBody)
+        return null;
+    return {
+        filename: path.basename(filePath),
+        filePath,
+        body: trimmedBody,
+        preview: extractPreview(trimmedBody),
+        createdAt,
+        tags,
+        mtimeMs: stat.mtimeMs,
+        size: stat.size,
+    };
+}
+function listCanonicalNotes(notesDir) {
+    let dirEntries;
+    try {
+        dirEntries = fs.readdirSync(notesDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return dirEntries
+        .filter((entry) => entry.isFile() && !entry.name.startsWith(".") && entry.name.endsWith(".md"))
+        .map((entry) => {
+        const filePath = path.join(notesDir, entry.name);
+        try {
+            return parseCanonicalNote(filePath, fs.statSync(filePath));
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((record) => record !== null)
+        .sort((left, right) => left.filename.localeCompare(right.filename));
+}
+function readIndex(indexPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(indexPath, "utf8"));
+        if (parsed.version !== NOTES_INDEX_VERSION || !Array.isArray(parsed.entries))
+            return null;
+        if (!parsed.entries.every(isIndexEntry))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function isIndexEntry(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const entry = value;
+    return (typeof entry.filename === "string" &&
+        typeof entry.path === "string" &&
+        typeof entry.preview === "string" &&
+        Array.isArray(entry.embedding) &&
+        entry.embedding.every((item) => typeof item === "number") &&
+        typeof entry.mtimeMs === "number" &&
+        typeof entry.size === "number");
+}
+function entryMatchesRecord(entry, record) {
+    return (entry.filename === record.filename &&
+        entry.path === record.filePath &&
+        entry.mtimeMs === record.mtimeMs &&
+        entry.size === record.size &&
+        entry.preview === record.preview);
+}
+function indexFreshForRecords(index, records) {
+    if (!index)
+        return false;
+    if (index.entries.length !== records.length)
+        return false;
+    const recordsByFilename = new Map(records.map((record) => [record.filename, record]));
+    const seenFilenames = new Set();
+    for (const entry of index.entries) {
+        const record = recordsByFilename.get(entry.filename);
+        if (!record || !entryMatchesRecord(entry, record))
+            return false;
+        seenFilenames.add(entry.filename);
+    }
+    return seenFilenames.size === recordsByFilename.size;
+}
+function indexFreshExcept(index, records, filename) {
+    if (!index)
+        return false;
+    const otherRecords = records.filter((record) => record.filename !== filename);
+    const otherEntries = index.entries.filter((entry) => entry.filename !== filename);
+    return indexFreshForRecords({ version: NOTES_INDEX_VERSION, entries: otherEntries }, otherRecords);
+}
+function makeEntry(record, embedding) {
+    return {
+        filename: record.filename,
+        path: record.filePath,
+        preview: record.preview,
+        embedding,
+        ...(record.createdAt ? { created_at: record.createdAt } : {}),
+        ...(record.tags ? { tags: record.tags } : {}),
+        mtimeMs: record.mtimeMs,
+        size: record.size,
+    };
+}
+function writeIndex(indexPath, index) {
+    fs.writeFileSync(indexPath, `${JSON.stringify(index, null, 2)}\n`, "utf8");
+}
+async function embedRecord(provider, record) {
+    const [embedding] = await provider.embed([record.body]);
+    return makeEntry(record, embedding);
+}
+async function rebuildNotesIndex(notesDir, indexPath, provider) {
+    const records = listCanonicalNotes(notesDir);
+    const entries = [];
+    for (const record of records) {
+        entries.push(await embedRecord(provider, record));
+    }
+    const index = { version: NOTES_INDEX_VERSION, entries };
+    writeIndex(indexPath, index);
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.record_notes_index_rebuilt",
+        message: "notes native index rebuilt",
+        meta: { notesDir, count: entries.length },
+    });
+    return index;
+}
+async function updateIndexForSavedNote(notesDir, indexPath, savedPath, provider) {
+    const savedRecord = parseCanonicalNote(savedPath, fs.statSync(savedPath));
+    const records = [
+        ...listCanonicalNotes(notesDir).filter((record) => record.filePath !== savedPath),
+        savedRecord,
+    ].sort((left, right) => left.filename.localeCompare(right.filename));
+    const existing = readIndex(indexPath);
+    if (!indexFreshExcept(existing, records, savedRecord.filename)) {
+        await rebuildNotesIndex(notesDir, indexPath, provider);
+        return;
+    }
+    const savedEntry = await embedRecord(provider, savedRecord);
+    const entries = [
+        ...existing.entries.filter((entry) => entry.filename !== savedRecord.filename),
+        savedEntry,
+    ].sort((left, right) => left.filename.localeCompare(right.filename));
+    writeIndex(indexPath, { version: NOTES_INDEX_VERSION, entries });
+}
+async function getFreshIndex(notesDir, indexPath, provider) {
+    const records = listCanonicalNotes(notesDir);
+    const existing = readIndex(indexPath);
+    if (indexFreshForRecords(existing, records))
+        return existing;
+    return rebuildNotesIndex(notesDir, indexPath, provider);
+}
+function createProviderForTool(toolName) {
+    const provider = (0, embedding_provider_1.createDefaultEmbeddingProvider)();
+    if (!provider) {
+        return `error: ${toolName} couldn't use notes because embeddings are not configured.`;
+    }
+    return provider;
+}
+function parseLimit(raw) {
+    const parsed = typeof raw === "string" ? Number.parseInt(raw, 10) : typeof raw === "number" ? raw : DEFAULT_LIMIT;
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return DEFAULT_LIMIT;
+    return Math.min(Math.floor(parsed), MAX_LIMIT);
+}
+function parseMinScore(raw) {
+    const parsed = typeof raw === "string" ? Number.parseFloat(raw) : typeof raw === "number" ? raw : DEFAULT_MIN_SCORE;
+    if (!Number.isFinite(parsed))
+        return DEFAULT_MIN_SCORE;
+    return parsed;
+}
+function parseCursor(raw) {
+    const parsed = typeof raw === "string" ? Number.parseInt(raw, 10) : typeof raw === "number" ? raw : 0;
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return 0;
+    return Math.floor(parsed);
+}
+exports.recordToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "note",
+                description: "Write a durable self note as canonical markdown in my Desk record notes. Only available to my self/private-runtime context, not external callers.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        content: { type: "string" },
+                        tags: {
+                            type: "array",
+                            items: { type: "string" },
+                        },
+                    },
+                    required: ["content"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            if (!hasSelfTrust(ctx))
+                return "error: note requires self trust and cannot be used from an external caller context.";
+            const rawArgs = args;
+            const content = typeof rawArgs.content === "string" ? rawArgs.content.trim() : "";
+            if (!content)
+                return "content is required";
+            const provider = createProviderForTool("note");
+            if (typeof provider === "string")
+                return provider;
+            const cappedContent = (0, session_events_1.capStructuredRecordString)(content);
+            const createdAt = new Date().toISOString();
+            const date = createdAt.slice(0, 10);
+            const tags = normalizeTags(rawArgs.tags);
+            try {
+                const notesDir = (0, record_paths_1.resolveRecordNotesRoot)();
+                const indexPath = path.join(notesDir, ".index.json");
+                fs.mkdirSync(notesDir, { recursive: true });
+                const savedPath = ensureUniquePath(notesDir, date, slugForContent(content));
+                fs.writeFileSync(savedPath, renderNote(createdAt, cappedContent, tags), "utf8");
+                await updateIndexForSavedNote(notesDir, indexPath, savedPath, provider);
+                ctx?.habitSession?.recordProducedRef?.({
+                    kind: "desk_record",
+                    locator: bundleRelativeLocator(savedPath, ctx),
+                });
+                (0, runtime_1.emitNervesEvent)({
+                    component: "repertoire",
+                    event: "repertoire.record_note_saved",
+                    message: "canonical note saved",
+                    meta: { path: savedPath, hasTags: Boolean(tags?.length) },
+                });
+                return savedPath;
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "repertoire",
+                    event: "repertoire.record_note_save_error",
+                    message: "canonical note save failed",
+                    meta: { reason: error instanceof Error ? error.message : String(error) },
+                });
+                return "error: couldn't save the note right now.";
+            }
+        },
+        summaryKeys: ["content", "tags"],
+        riskProfile: { mutates: "durable_state_write", risk: "high", reason: "writes canonical Desk record note" },
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "consult_notes",
+                description: "Search my canonical markdown Desk record notes semantically using the notes-native index. Read-only orientation lookup for trusted callers.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        query: { type: "string" },
+                        cursor: { type: "string" },
+                        limit: { type: "string" },
+                        minScore: { type: "string" },
+                    },
+                    required: ["query"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            if (!hasRecordReadTrust(ctx))
+                return "error: consult_notes requires trusted record-read access.";
+            const rawArgs = args;
+            const query = typeof rawArgs.query === "string" ? rawArgs.query.trim() : "";
+            if (!query)
+                return JSON.stringify({ items: [] });
+            const notesDir = (0, record_paths_1.resolveRecordNotesRoot)();
+            const indexPath = path.join(notesDir, ".index.json");
+            const records = listCanonicalNotes(notesDir);
+            if (records.length === 0)
+                return JSON.stringify({ items: [] });
+            const provider = createProviderForTool("consult_notes");
+            if (typeof provider === "string")
+                return provider;
+            try {
+                const index = await getFreshIndex(notesDir, indexPath, provider);
+                const [queryEmbedding] = await provider.embed([query]);
+                const minScore = parseMinScore(rawArgs.minScore);
+                const offset = parseCursor(rawArgs.cursor);
+                const limit = parseLimit(rawArgs.limit);
+                const ranked = index.entries
+                    .filter((entry) => entry.embedding.length > 0)
+                    .map((entry) => ({
+                    path: entry.path,
+                    filename: entry.filename,
+                    excerpt: entry.preview,
+                    score: (0, note_search_1.cosineSimilarity)(queryEmbedding, entry.embedding),
+                }))
+                    .filter((entry) => entry.score >= minScore)
+                    .sort((left, right) => right.score - left.score);
+                const items = ranked.slice(offset, offset + limit);
+                const nextOffset = offset + limit;
+                const result = nextOffset < ranked.length ? { items, nextCursor: String(nextOffset) } : { items };
+                (0, runtime_1.emitNervesEvent)({
+                    component: "repertoire",
+                    event: "repertoire.record_notes_consulted",
+                    message: "canonical notes consulted",
+                    meta: { count: items.length, totalMatches: ranked.length },
+                });
+                return JSON.stringify(result);
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "repertoire",
+                    event: "repertoire.record_notes_consult_error",
+                    message: "canonical notes consult failed",
+                    meta: { reason: error instanceof Error ? error.message : String(error) },
+                });
+                return "error: consult_notes couldn't search notes right now.";
+            }
+        },
+        summaryKeys: ["query"],
+    },
+];

package/dist/repertoire/tools-rsvp.js

@@ -0,0 +1,139 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rsvpToolDefinitions = void 0;
+const fs = __importStar(require("node:fs"));
+const runtime_1 = require("../nerves/runtime");
+const query_1 = require("../rsvp/query");
+const snapshot_1 = require("../rsvp/snapshot");
+function readSnapshot(snapshotPath) {
+    if (!snapshotPath || snapshotPath.trim().length === 0) {
+        return { ok: false, reason: "missing", message: "RSVP snapshot not found." };
+    }
+    try {
+        const raw = fs.readFileSync(snapshotPath, "utf-8");
+        const parsed = (0, snapshot_1.parseRsvpSnapshot)(JSON.parse(raw));
+        if (!parsed.ok) {
+            return { ok: false, reason: "invalid", message: "RSVP snapshot could not be read or failed integrity validation." };
+        }
+        return { ok: true, snapshot: parsed.snapshot };
+    }
+    catch (error) {
+        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+            return { ok: false, reason: "missing", message: "RSVP snapshot not found." };
+        }
+        return { ok: false, reason: "invalid", message: "RSVP snapshot could not be read or failed integrity validation." };
+    }
+}
+function emitToolRead(toolName, result) {
+    (0, runtime_1.emitNervesEvent)({
+        component: "repertoire",
+        event: "repertoire.rsvp_tool_read",
+        message: "RSVP tool read snapshot",
+        meta: result.ok
+            ? { toolName, snapshotId: result.snapshot.snapshotId, total: result.snapshot.summary.total }
+            : { toolName, reason: result.reason },
+    });
+}
+exports.rsvpToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "rsvp_query",
+                description: "answer deterministic questions about a native RSVP snapshot file, such as who is pending, declined, attending, unknown, or matching a guest name.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        snapshot_path: {
+                            type: "string",
+                            description: "absolute path to a native RSVP snapshot JSON file.",
+                        },
+                        query: {
+                            type: "string",
+                            description: "natural-language query or guest-name filter.",
+                        },
+                        status: {
+                            type: "string",
+                            enum: ["attending", "declined", "pending", "unknown", "all"],
+                            description: "optional explicit RSVP status filter.",
+                        },
+                    },
+                    required: ["snapshot_path"],
+                },
+            },
+        },
+        handler: async (args) => {
+            const result = readSnapshot(args.snapshot_path);
+            emitToolRead("rsvp_query", result);
+            if (!result.ok)
+                return result.message;
+            return (0, query_1.queryRsvpSnapshot)(result.snapshot, {
+                query: args.query,
+                status: args.status,
+            }).text;
+        },
+        summaryKeys: ["snapshot_path", "query", "status"],
+        riskProfile: { mutates: "none", risk: "low", reason: "reads a local native RSVP snapshot" },
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "rsvp_summary",
+                description: "summarize counts and provenance for a native RSVP snapshot file.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        snapshot_path: {
+                            type: "string",
+                            description: "absolute path to a native RSVP snapshot JSON file.",
+                        },
+                    },
+                    required: ["snapshot_path"],
+                },
+            },
+        },
+        handler: async (args) => {
+            const result = readSnapshot(args.snapshot_path);
+            emitToolRead("rsvp_summary", result);
+            if (!result.ok)
+                return result.message;
+            return (0, query_1.summarizeRsvpSnapshot)(result.snapshot);
+        },
+        summaryKeys: ["snapshot_path"],
+        riskProfile: { mutates: "none", risk: "low", reason: "reads a local native RSVP snapshot" },
+    },
+];