@ouro.bot/cli 0.1.0-alpha.83 → 0.1.0-alpha.831

package/dist/senses/sanctuary-media-catalog-contract.js

@@ -0,0 +1,297 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanctuaryMediaCatalogRequiredToolCalls = sanctuaryMediaCatalogRequiredToolCalls;
+const runtime_1 = require("../nerves/runtime");
+const sanctuary_media_optimization_1 = require("./sanctuary-media-optimization");
+const LEGACY_CATALOG_TOOL = "sanctuary_search_media_catalog";
+const MEDIA_SEARCH_TOOL = "media_search";
+const MEDIA_REQUEST_TOOL = "media_request";
+const HOUSEHOLD_JARGON = /\b(?:bounded|catalog|inventory|endpoint|backend|data shape|pars(?:e|ed|ing)|json|jellyfin|unmanic|sanctuary_search_media_catalog)\b/iu;
+const NEGATED_MEDIA_ACCESS = /\b(?:not|never|none|nothing|zero|inaccessible|invisible|unavailable|broken|failed|failing)\b|\b(?:isn[’']t|won[’']t)\b|\bno\s+access\b|\b(?:lost|lacks?|lacking|without)\s+access\b|\bonly\s+\d|\bfewer\s+than\b|\bsome\s+of\b|\b(?:part|portion|subset)\s+of\b|\bi\s+(?:can(?:not|[’']t)|do\s+not|don[’']t|have\s+no)\b|\bi[’']m\s+not\b/iu;
+const UNSOLICITED_PIVOT = /\b(?:what would you like|what are you in the mood for|would you like me to|do you want me to|want me to|recommend we add)\b/iu;
+const REPORT_LABEL = /(?:^|\n)\s*(?:version|house|the house|render check|status|result)\s*:/iu;
+const TITLE_LIST_GLUE = new Set(["and", "are", "catalog", "film", "films", "from", "have", "here", "in", "is", "library", "movie", "movies", "on", "shelf", "show", "shows", "the", "these", "titles", "we"]);
+const COUNT_ANSWER_GLUE = new Set(["and", "are", "currently", "episodes", "film", "films", "have", "in", "items", "library", "movie", "movies", "on", "shelf", "show", "shows", "the", "there", "tv", "we"]);
+function requestKind(request, titleQuery) {
+    if (/\b(?:favorite|favourite|recommend|suggest|pick|what (?:movie|film|show) should|should (?:we|i) (?:watch|add)|what to watch|missing from|must (?:watch|add|get))\b/u.test(request))
+        return "taste_recommendation";
+    if (/\b(?:see|visible|visibility|access|accessible|browse|browseable|browsable)\b.*\b(?:jellyfin|library|lib|catalog|shelf)\b|\b(?:jellyfin|library|lib|catalog|shelf)\b.*\b(?:see|visible|visibility|access|accessible|browse|browseable|browsable)\b/u.test(request))
+        return "visibility";
+    if (titleQuery)
+        return "title_lookup";
+    return "other";
+}
+function requestedListCount(request) {
+    const match = request.match(/\b(?:show|list)\s+(?:me\s+)?(one|two|three|four|five|six|seven|eight|nine|ten|[1-9]|1[0-9]|20)\b/u);
+    if (!match)
+        return null;
+    const words = { one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10 };
+    return words[match[1]] ?? Number(match[1]);
+}
+function requestedTitle(request) {
+    const conversationalSuffixRemoved = request.replace(/\s+(?:please|(?:right\s+)?now|currently)$/u, "");
+    const haveMatch = conversationalSuffixRemoved.match(/\b(?:do|did|can|could)\s+(?:we|you)\s+(?:have|got|stock)\s+(.+)$/u);
+    if (haveMatch)
+        return haveMatch[1].replace(/^(?:the\s+)?(?:movie|film|show)\s+/u, "").trim();
+    const locationMatch = conversationalSuffixRemoved.match(/\b(?:is|are)\s+(.+?)\s+(?:in|on)\s+(?:(?:the|our)\s+)?(?:jellyfin|library|lib|catalog|shelf)$/u);
+    return locationMatch?.[1]?.replace(/^(?:the\s+)?(?:movie|film|show)\s+/u, "").trim() ?? "";
+}
+function includesNormalizedPhrase(text, phrase) {
+    return ` ${(0, sanctuary_media_optimization_1.normalizeSanctuaryMediaText)(text)} `.includes(` ${(0, sanctuary_media_optimization_1.normalizeSanctuaryMediaText)(phrase)} `);
+}
+function catalogTitleGroundingRejection(answer, current, expectedCount) {
+    let remainder = ` ${(0, sanctuary_media_optimization_1.normalizeSanctuaryMediaText)(answer)} `;
+    const titles = [...new Set(current.titles.map(sanctuary_media_optimization_1.normalizeSanctuaryMediaText).filter(Boolean))].sort((left, right) => right.length - left.length);
+    const mentioned = [];
+    for (const title of titles) {
+        const phrase = ` ${title} `;
+        if (!remainder.includes(phrase))
+            continue;
+        mentioned.push(title);
+        remainder = remainder.replaceAll(phrase, " ");
+    }
+    const hasUnverifiedWords = remainder.split(/\s+/u).some((word) => word && !TITLE_LIST_GLUE.has(word));
+    const hasExactCount = expectedCount === null || (titles.length === expectedCount && mentioned.length === expectedCount);
+    if (mentioned.length === 0 || !hasExactCount || hasUnverifiedWords)
+        return "Name exactly the returned catalog titles; do not add or substitute unverified titles.";
+    return undefined;
+}
+function catalogCountGroundingRejection(answer, current) {
+    const formattedCount = new Intl.NumberFormat("en-US").format(current.totalItems);
+    let remainder = ` ${(0, sanctuary_media_optimization_1.normalizeSanctuaryMediaText)(answer)} `;
+    const countPhrase = ` ${(0, sanctuary_media_optimization_1.normalizeSanctuaryMediaText)(formattedCount)} `;
+    const countOccurrences = remainder.split(countPhrase).length - 1;
+    if (countOccurrences === 0)
+        return `Report the current verified shelf count of ${formattedCount}.`;
+    if (countOccurrences !== 1)
+        return "Report the verified shelf count once.";
+    remainder = remainder.replaceAll(countPhrase, " ");
+    if (remainder.split(/\s+/u).some((word) => word && !COUNT_ANSWER_GLUE.has(word)))
+        return "Report only the verified count in ordinary household language.";
+    return undefined;
+}
+function parseCatalogEvidence(result, args) {
+    try {
+        const parsed = JSON.parse(result);
+        if (parsed.ok !== true || !parsed.data || !Number.isSafeInteger(parsed.data.totalItems) || !Number.isSafeInteger(parsed.data.matchedItems) || !Array.isArray(parsed.data.items))
+            return null;
+        const titles = parsed.data.items.flatMap((item) => {
+            if (!item || typeof item !== "object" || Array.isArray(item))
+                return [];
+            const title = item.untrustedTitle;
+            return typeof title === "string" && title.trim() ? [title.trim()] : [];
+        });
+        return {
+            query: (0, sanctuary_media_optimization_1.normalizeSanctuaryMediaText)(args.query ?? ""),
+            totalItems: parsed.data.totalItems,
+            matchedItems: parsed.data.matchedItems,
+            titles,
+            offShelfTitles: [],
+            fromMediaSearch: false,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * media_search reports shelf state per title, so it can ground both "what do we own"
+ * and "what is worth adding" from one read. The legacy catalog read can only prove
+ * absence by returning zero matches for an exact title query.
+ */
+function parseMediaSearchEvidence(result, args) {
+    try {
+        const parsed = JSON.parse(result);
+        if (!Number.isSafeInteger(parsed.matched) || !Array.isArray(parsed.items))
+            return null;
+        const titles = [];
+        const offShelfTitles = [];
+        for (const entry of parsed.items) {
+            if (!entry || typeof entry !== "object" || Array.isArray(entry))
+                continue;
+            const item = entry;
+            if (typeof item.title !== "string" || !item.title.trim())
+                continue;
+            titles.push(item.title.trim());
+            if (item.on_shelf === false)
+                offShelfTitles.push(item.title.trim());
+        }
+        return {
+            query: (0, sanctuary_media_optimization_1.normalizeSanctuaryMediaText)(args.query ?? ""),
+            totalItems: parsed.matched,
+            matchedItems: parsed.matched,
+            titles,
+            offShelfTitles,
+            fromMediaSearch: true,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function sentenceCount(answer) {
+    return answer.split(/[.!?]+(?:\s+|$)/u).filter((part) => part.trim()).length;
+}
+function hasGroundedFirstPersonVisibility(answer, formattedCount) {
+    if (NEGATED_MEDIA_ACCESS.test(answer) || answer.split(formattedCount).length - 1 !== 1)
+        return false;
+    const escapedCount = formattedCount.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+    const mediaNoun = "(?:titles?|movies?|films?|shows?|episodes?|items?)";
+    const countedObject = `(?:all\\s+|about\\s+|around\\s+|exactly\\s+|roughly\\s+)?${escapedCount}\\s+${mediaNoun}\\b`;
+    const contextObject = `(?:it|(?:(?:the|our)\\s+)?(?:full\\s+)?(?:library|shelf))(?:\\s+(?:now|again))?(?=\\s*(?:[.!?;,:—-]|$))`;
+    const accessObject = `(?:${contextObject}|${countedObject})`;
+    const firstPersonAccess = [
+        new RegExp(`\\bi\\s+(?:(?:can\\s+(?:(?:absolutely|clearly|currently|definitely|now|plainly|readily)\\s+)?|(?:currently|now)\\s+)?(?:see|browse|access|view))\\s+${accessObject}`, "iu"),
+        new RegExp(`\\bi(?:\\s+have|[’']ve\\s+got)\\s+(?:(?:full\\s+)?access\\s+to\\s+${accessObject}|${countedObject})`, "iu"),
+        new RegExp(`\\bi(?:\\s+am|[’']m)\\s+(?:(?:currently|now)\\s+)?(?:looking\\s+at|able\\s+to\\s+(?:see|browse|access|view))\\s+${accessObject}`, "iu"),
+        /\b(?:(?:the|our)\s+)?(?:full\s+)?(?:library|shelf)\s+is\s+(?:fully\s+)?(?:visible|accessible)\s+to\s+me\b/iu,
+    ];
+    const groundedCount = new RegExp(`\\b${escapedCount}\\s+${mediaNoun}\\b`, "iu");
+    return firstPersonAccess.some((pattern) => pattern.test(answer)) && groundedCount.test(answer);
+}
+function commonAnswerRejection(answer, technicalDetailRequested) {
+    if (/\b(?:just|only|actually|merely)\s+(?:a\s+)?(?:bot|ai|assistant)\b|\bi\s+(?:can[’']?t|cannot|don[’']?t|do not)\s+(?:actually\s+)?watch\b|\bif i had to pick\b/iu.test(answer)) {
+        return "Answer from the catalog evidence with a confident, personable choice; do not retreat into an AI or 'I cannot watch' disclaimer.";
+    }
+    if (/\b(?:you'?d|you\s+would|you\s+need\s+to|please)\b.*\b(?:check|look at|poke|nudge)\b.*\b(?:log|logs|dashboard|jellyfin|unmanic)\b/iu.test(answer)) {
+        return "Do not send Ari to check Jellyfin, Unmanic, dashboards, or logs for ordinary library visibility while safe catalog tools are available. Use the catalog evidence, or if the catalog read itself fails, say exactly what I could and could not verify.";
+    }
+    if (UNSOLICITED_PIVOT.test(answer))
+        return "Answer the media question that was asked, then stop; do not append an unsolicited question or recommendation pivot.";
+    if (REPORT_LABEL.test(answer))
+        return "Answer conversationally; do not use status-report labels such as version:, house:, render check:, status:, or result:.";
+    if (!technicalDetailRequested && HOUSEHOLD_JARGON.test(answer))
+        return "Use household language such as shelf or library; omit implementation jargon unless technical detail was requested.";
+    return undefined;
+}
+function sanctuaryMediaCatalogRequiredToolCalls(request, advertisedToolNames) {
+    // Prefer media_search when the media surface is installed: it grounds both what is
+    // on the shelf and what is worth adding. Fall back to the legacy restricted read.
+    const catalogTool = advertisedToolNames.includes(MEDIA_SEARCH_TOOL) ? MEDIA_SEARCH_TOOL : LEGACY_CATALOG_TOOL;
+    const canRequestMedia = advertisedToolNames.includes(MEDIA_REQUEST_TOOL);
+    if (!advertisedToolNames.includes(catalogTool))
+        return undefined;
+    const normalized = (0, sanctuary_media_optimization_1.normalizeSanctuaryMediaText)(request);
+    const mentionsMedia = /\b(?:film|films|movie|movies|shows|tv|jellyfin|watch|shelf|stock|catalog|library|lib)\b/u.test(normalized);
+    const asksCatalog = /\b(?:have|got|stock|catalog|library|lib|shelf|jellyfin|favorite|favourite|recommend|suggest|pick|watch|add|see|show|list|browse|access)\b/u.test(normalized);
+    const requestedTitleQuery = requestedTitle(normalized);
+    const operationalOnly = /\b(?:restart|reboot|start|stop|stopped|stopping|running|down|investigate|redeploy|deploy|crash|crashed)\b/u.test(normalized)
+        && !requestedTitleQuery
+        && !/\b(?:film|films|movie|movies|shows|tv|watch|shelf|stock|catalog|library|lib|have|got|favorite|favourite|recommend|suggest|pick|add|see|show|list|browse|access|find|search|count|contents)\b/u.test(normalized);
+    if (operationalOnly || (!mentionsMedia && !requestedTitleQuery) || !asksCatalog)
+        return undefined;
+    const kind = requestKind(normalized, requestedTitleQuery);
+    const asksForAddition = /\b(?:add|missing from|must get)\b/u.test(normalized);
+    const asksForCount = /\b(?:how many|count)\b/u.test(normalized);
+    const listCount = requestedListCount(normalized);
+    const technicalDetailRequested = /\b(?:technical|technically|implementation|endpoint|backend|debug|detail|internals?)\b/u.test(normalized);
+    let latestEvidence;
+    const names = [catalogTool];
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.sanctuary_media_catalog_obligation",
+        message: "media catalog intent requires safe restricted catalog evidence",
+        meta: { requiredToolNames: names },
+    });
+    return {
+        names,
+        requireSuccessfulResults: true,
+        retryMessage: asksForCount
+            ? `Use ${catalogTool} before answering, then report only the current shelf count in ordinary household language.`
+            : kind === "visibility"
+                ? `Use ${catalogTool} before answering. Lead with the direct answer from current catalog evidence, report the shelf count in ordinary household language, and stop without sampled titles or a follow-up question.`
+                : kind === "title_lookup"
+                    ? `Use ${catalogTool} with the requested title before answering. Confirm its presence or absence directly from current catalog evidence.`
+                    : kind === "taste_recommendation"
+                        ? `Use ${catalogTool} before answering. Make one concise, decisive choice grounded in returned catalog evidence; do not volunteer an AI or 'I cannot watch' disclaimer.`
+                        : listCount
+                            ? `Use ${catalogTool} with limit ${listCount} before answering, then name exactly the returned catalog titles.`
+                            : `Use ${catalogTool} before answering and base any named titles on the returned catalog evidence.`,
+        validateRequiredToolResult(name, result, args) {
+            if (name !== catalogTool)
+                return false;
+            const current = catalogTool === MEDIA_SEARCH_TOOL ? parseMediaSearchEvidence(result, args) : parseCatalogEvidence(result, args);
+            if (!current)
+                return false;
+            latestEvidence = current;
+            return true;
+        },
+        validateToolCallBeforeDispatch(name, args) {
+            if (name !== catalogTool)
+                return undefined;
+            const query = (0, sanctuary_media_optimization_1.normalizeSanctuaryMediaText)(args.query ?? "");
+            if (kind === "title_lookup" && !query)
+                return "Search for the requested title by name before answering whether it is on the shelf.";
+            if (kind === "title_lookup" && query !== requestedTitleQuery)
+                return `Search for the requested title ${requestedTitleQuery} before answering whether it is on the shelf.`;
+            // media_search browses by genre, keyword and year and reports shelf state per
+            // title, so an addition question does not need a per-candidate title query.
+            if (asksForAddition && !query && catalogTool !== MEDIA_SEARCH_TOOL)
+                return "Search for one candidate title by name before recommending it as an addition.";
+            if (listCount && Number(args.limit) !== listCount && catalogTool !== MEDIA_SEARCH_TOOL)
+                return `Set the catalog limit to ${listCount} so the answer is grounded in exactly the requested number of titles.`;
+            return undefined;
+        },
+        validateTerminalAnswer(answer) {
+            const commonRejection = commonAnswerRejection(answer, technicalDetailRequested);
+            if (commonRejection)
+                return commonRejection;
+            const latest = latestEvidence;
+            if (asksForCount && latest)
+                return catalogCountGroundingRejection(answer, latest);
+            if (kind === "visibility") {
+                if (answer.length > 240 || answer.includes("\n") || sentenceCount(answer) > 2)
+                    return "Answer library visibility in no more than two short sentences and 240 characters.";
+                if (!/^yes\b/iu.test(answer.trim()))
+                    return "Lead with a direct yes when the current catalog read succeeds.";
+                if (latest) {
+                    const formattedCount = new Intl.NumberFormat("en-US").format(latest.totalItems);
+                    if (!hasGroundedFirstPersonVisibility(answer, formattedCount))
+                        return `Reply in one or two sentences. A valid shape is: Yes—I can see the library now. It contains ${formattedCount} titles.`;
+                }
+                if (/\b(?:titles? like|such as|including)\b/iu.test(answer))
+                    return "Do not sample titles for a visibility question; answer whether the shelf is visible and give the current count.";
+                if ([...answer.matchAll(/\byes\b/giu)].length > 1)
+                    return "Give one answer once; do not repeat the yes or restate the response.";
+                if (answer.includes("?"))
+                    return "Answer the visibility question and stop without asking a new question.";
+            }
+            if (kind === "title_lookup" && latest?.query) {
+                const exactMatch = latest.titles.some((title) => (0, sanctuary_media_optimization_1.normalizeSanctuaryMediaText)(title) === requestedTitleQuery);
+                const expectedLead = exactMatch ? /^yes\b/iu : /^no\b/iu;
+                if (!expectedLead.test(answer.trim()))
+                    return `Lead with ${exactMatch ? "yes" : "no"} based on the current title search.`;
+                if (!includesNormalizedPhrase(answer, requestedTitleQuery))
+                    return "Name the requested title in the direct answer.";
+            }
+            if (kind === "taste_recommendation" && latest) {
+                if (asksForAddition) {
+                    if (latest.fromMediaSearch) {
+                        // media_search states shelf membership per title, so a recommendation is
+                        // grounded when the named candidate came back marked absent.
+                        if (!latest.offShelfTitles.some((title) => includesNormalizedPhrase(answer, title))) {
+                            return "Recommend only a title the current search returned as not on the shelf.";
+                        }
+                    }
+                    else if (!latest.query || latest.matchedItems !== 0 || !includesNormalizedPhrase(answer, latest.query)) {
+                        return "Recommend an addition only after an exact current catalog search shows that candidate is absent.";
+                    }
+                    if (!canRequestMedia && /\b(?:i|we)\s+(?:added|requested|submitted|queued)\b/iu.test(answer)) {
+                        return "Do not claim the title was added or requested when no media-request action was available.";
+                    }
+                }
+                else if (!latest.titles.some((title) => includesNormalizedPhrase(answer, title))) {
+                    return "Make the choice from a title returned by the current catalog evidence.";
+                }
+            }
+            if (kind === "other" && latest) {
+                if (!latest.fromMediaSearch)
+                    return catalogTitleGroundingRejection(answer, latest, listCount);
+                if (latest.titles.length > 0 && !latest.titles.some((title) => includesNormalizedPhrase(answer, title))) {
+                    return "Name titles the current search returned; do not add unverified ones.";
+                }
+            }
+            return undefined;
+        },
+    };
+}