@openviking/openclaw-plugin 2026.6.2 → 2026.6.17-dev.2

package/dist/memory-ranking.js

@@ -146,6 +146,13 @@ const QUERY_TOKEN_STOPWORDS = new Set([
     "your",
     "you",
 ]);
+const DEFAULT_RANKING_WEIGHTS = {
+    baseScore: 1,
+    leaf: 0.12,
+    event: 0.1,
+    preference: 0.08,
+    lexicalOverlapMax: 0.2,
+};
 function buildRecallQueryProfile(query) {
     const text = query.trim();
     const allTokens = text.toLowerCase().match(QUERY_TOKEN_RE) ?? [];
@@ -156,7 +163,7 @@ function buildRecallQueryProfile(query) {
         wantsTemporal: TEMPORAL_QUERY_RE.test(text),
     };
 }
-function lexicalOverlapBoost(tokens, text) {
+function lexicalOverlapBoost(tokens, text, maxBoost = DEFAULT_RANKING_WEIGHTS.lexicalOverlapMax) {
     if (tokens.length === 0 || !text) {
         return 0;
     }
@@ -167,24 +174,40 @@ function lexicalOverlapBoost(tokens, text) {
             matched += 1;
         }
     }
-    return Math.min(0.2, (matched / Math.min(tokens.length, 4)) * 0.2);
-}
-function rankForInjection(item, query) {
+    return Math.min(maxBoost, (matched / Math.min(tokens.length, 4)) * maxBoost);
+}
+function inferResourceType(item) {
+    if (item.uri.startsWith("viking://resources"))
+        return "resource";
+    if (item.uri.startsWith("viking://session/"))
+        return "session";
+    if (item.uri.startsWith("viking://user/skills") || item.uri.startsWith("viking://skills"))
+        return "agent";
+    if (item.uri.startsWith("viking://user/"))
+        return "user";
+    return undefined;
+}
+function rankForInjection(item, query, options) {
     // Keep ranking simple and stable: semantic score + light query-aware boosts.
-    const baseScore = clampScore(item.score);
+    const weights = { ...DEFAULT_RANKING_WEIGHTS, ...(options?.weights ?? {}) };
+    const baseScore = clampScore(item.score) * weights.baseScore;
     const abstract = (item.abstract ?? item.overview ?? "").trim();
-    const leafBoost = isLeafLikeMemory(item) ? 0.12 : 0;
-    const eventBoost = query.wantsTemporal && isEventMemory(item) ? 0.1 : 0;
-    const preferenceBoost = query.wantsPreference && isPreferencesMemory(item) ? 0.08 : 0;
-    const overlapBoost = lexicalOverlapBoost(query.tokens, `${item.uri} ${abstract}`);
-    return baseScore + leafBoost + eventBoost + preferenceBoost + overlapBoost;
+    const leafBoost = isLeafLikeMemory(item) ? weights.leaf : 0;
+    const eventBoost = query.wantsTemporal && isEventMemory(item) ? weights.event : 0;
+    const preferenceBoost = query.wantsPreference && isPreferencesMemory(item) ? weights.preference : 0;
+    const overlapBoost = lexicalOverlapBoost(query.tokens, `${item.uri} ${abstract}`, weights.lexicalOverlapMax);
+    const category = (item.category ?? "").toLowerCase();
+    const categoryBoost = category ? (options?.categoryWeights?.[category] ?? options?.categoryWeights?.[item.category ?? ""] ?? 0) : 0;
+    const resourceType = inferResourceType(item);
+    const resourceTypeBoost = resourceType ? (options?.resourceTypeWeights?.[resourceType] ?? 0) : 0;
+    return baseScore + leafBoost + eventBoost + preferenceBoost + overlapBoost + categoryBoost + resourceTypeBoost;
 }
-export function pickMemoriesForInjection(items, limit, queryText, scoreThreshold = 0) {
+export function pickMemoriesForInjection(items, limit, queryText, scoreThreshold = 0, rankingOptions) {
     if (items.length === 0 || limit <= 0) {
         return [];
     }
     const query = buildRecallQueryProfile(queryText);
-    const sorted = [...items].sort((a, b) => rankForInjection(b, query) - rankForInjection(a, query));
+    const sorted = [...items].sort((a, b) => rankForInjection(b, query, rankingOptions) - rankForInjection(a, query, rankingOptions));
     const deduped = [];
     const seen = new Set();
     for (const item of sorted) {

package/dist/plugin/command-registration.js

@@ -0,0 +1,5 @@
+export function registerOpenVikingCommands(api, commands) {
+    for (const command of commands) {
+        api.registerCommand?.(command);
+    }
+}

package/dist/plugin/openviking-archive-tools.js

@@ -0,0 +1,210 @@
+import { Type } from "@sinclair/typebox";
+function previewText(value, maxChars) {
+    const text = typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "";
+    if (!text) {
+        return undefined;
+    }
+    return text.length <= maxChars ? text : `${text.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+export function registerOpenVikingArchiveTools(deps) {
+    deps.registerTool((ctx) => ({
+        name: "ov_archive_search",
+        label: "Archive Search (OpenViking)",
+        description: "Keyword-grep across all archived original conversation messages of the current session. " +
+            "Use this whenever the [Session History Summary] does not contain the specific detail " +
+            "the user is asking about. Extract 2-3 concrete entity words from the question " +
+            "(names, places, objects, dates) and search each separately. " +
+            "Only conclude information is unavailable after trying at least 2 different keyword variations.",
+        parameters: Type.Object({
+            query: Type.String({
+                description: "A single keyword or short phrase to grep. Use concrete nouns, names, dates, " +
+                    "or distinctive phrases. Case-insensitive. Prefer entity words over full sentences.",
+            }),
+            archiveId: Type.Optional(Type.String({
+                description: 'Optional: limit search to one archive (e.g. "archive_005")',
+            })),
+        }),
+        async execute(_toolCallId, params) {
+            if (deps.isBypassedSession(ctx)) {
+                return deps.makeBypassedToolResult("ov_archive_search");
+            }
+            deps.rememberSessionAgentId(ctx);
+            const sessionId = ctx.sessionId ?? "";
+            const sessionKey = ctx.sessionKey ?? "";
+            if (!sessionId && !sessionKey) {
+                return {
+                    content: [{ type: "text", text: "Error: no active session." }],
+                    details: { error: "no_session" },
+                };
+            }
+            const ovSessionId = deps.toOvSessionId(ctx.sessionId, ctx.sessionKey);
+            const query = String(params.query ?? "").trim();
+            const archiveId = params.archiveId;
+            if (!query) {
+                return {
+                    content: [{ type: "text", text: "Error: query is required." }],
+                    details: { error: "missing_param", param: "query" },
+                };
+            }
+            const escapedQuery = query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            deps.logger?.info?.(`openviking: ov_archive_search query="${query}" escaped="${escapedQuery}" archive=${archiveId ?? "all"} session=${ovSessionId}`);
+            try {
+                const client = await deps.getClient();
+                const agentId = deps.resolveAgentId(ctx.sessionId, ctx.sessionKey);
+                const started = Date.now();
+                const result = await client.grepSessionArchives(ovSessionId, escapedQuery, {
+                    archiveId,
+                    caseInsensitive: true,
+                    agentId,
+                });
+                const traceResults = (result.matches ?? []).slice(0, deps.traceRecallMaxResultsPerSearch).map((match) => ({
+                    uri: match.uri,
+                    resourceType: "archive",
+                    abstractPreview: previewText(match.content, deps.traceRecallPreviewChars),
+                    resultType: "archive_match",
+                }));
+                const recordArchiveTrace = async (displayed) => {
+                    await deps.traceRecorder?.recordAndFlush({
+                        schemaVersion: "1.0",
+                        traceId: deps.createTraceId("ov_archive_search"),
+                        ts: Date.now(),
+                        sessionId: ctx.sessionId,
+                        sessionKey: ctx.sessionKey,
+                        ovSessionId,
+                        agentId,
+                        source: "ov_archive_search",
+                        operationType: "archive_grep",
+                        resourceTypes: ["session"],
+                        trigger: { query, derivedKeywords: [query] },
+                        searches: [{
+                                resourceType: "archive",
+                                targetUriResolved: archiveId ? `viking://session/${ovSessionId}/history/${archiveId}` : `viking://session/${ovSessionId}/history`,
+                                limit: deps.traceRecallMaxResultsPerSearch,
+                                durationMs: Date.now() - started,
+                                total: result.matches?.length ?? result.count ?? 0,
+                                results: traceResults,
+                                archiveId,
+                                caseInsensitive: true,
+                            }],
+                        selected: displayed.map((match) => ({
+                            uri: match.uri,
+                            resourceType: "archive",
+                            line: match.line,
+                            abstractPreview: previewText(match.content, deps.traceRecallPreviewChars),
+                            displayed: true,
+                        })),
+                        stats: {
+                            candidateCount: result.matches?.length ?? result.count ?? 0,
+                            selectedCount: displayed.length,
+                            injectedCount: 0,
+                        },
+                    });
+                };
+                if (!result.matches || result.matches.length === 0) {
+                    await recordArchiveTrace([]);
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `No matches found for "${query}". Try a different keyword — ` +
+                                    "the original conversation may use different wording than the question. " +
+                                    "Try synonyms, related terms, or shorter fragments.",
+                            }],
+                        details: { query, matchCount: 0 },
+                    };
+                }
+                const MAX_MATCHES = 12;
+                const MAX_LINE_LEN = 1500;
+                const shown = result.matches.slice(0, MAX_MATCHES);
+                await recordArchiveTrace(shown);
+                const blocks = shown.map((m, i) => {
+                    const archiveTag = m.uri.match(/archive_\d+/)?.[0] ?? "unknown";
+                    const truncated = m.content.length > MAX_LINE_LEN
+                        ? m.content.slice(0, MAX_LINE_LEN) + "…(truncated)"
+                        : m.content;
+                    return `## Match ${i + 1}: ${archiveTag} (line ${m.line})\n${truncated}`;
+                });
+                const header = `Found ${result.matches.length} match(es) for "${query}"` +
+                    (result.matches.length > MAX_MATCHES ? ` (showing first ${MAX_MATCHES})` : "") + ":";
+                return {
+                    content: [{ type: "text", text: header + "\n\n" + blocks.join("\n\n") }],
+                    details: { query, matchCount: result.matches.length },
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                deps.logger?.error?.(`openviking: ov_archive_search error: ${msg}`);
+                return {
+                    content: [{ type: "text", text: `Archive search failed: ${msg}` }],
+                    details: { error: msg },
+                };
+            }
+        },
+    }), { name: "ov_archive_search" });
+    deps.registerTool((ctx) => ({
+        name: "ov_archive_expand",
+        label: "Archive Expand (OpenViking)",
+        description: "Retrieve original messages from a compressed session archive. " +
+            "Use when a session summary lacks specific details " +
+            "such as exact commands, file paths, code snippets, or config values. " +
+            "Check [Archive Index] to find the right archive ID.",
+        parameters: Type.Object({
+            archiveId: Type.String({
+                description: 'Archive ID from [Archive Index] (e.g. "archive_002")',
+            }),
+        }),
+        async execute(_toolCallId, params) {
+            if (deps.isBypassedSession(ctx)) {
+                return deps.makeBypassedToolResult("ov_archive_expand");
+            }
+            const session = deps.resolvePluginSessionRouting(ctx);
+            const archiveId = String(params.archiveId ?? "").trim();
+            const sessionId = session.sessionId ?? "";
+            deps.logger?.info?.(`openviking: ov_archive_expand invoked (archiveId=${archiveId || "(empty)"}, sessionId=${sessionId || "(empty)"})`);
+            if (!archiveId) {
+                deps.logger?.warn?.("openviking: ov_archive_expand missing archiveId");
+                return {
+                    content: [{ type: "text", text: "Error: archiveId is required." }],
+                    details: { error: "missing_param", param: "archiveId" },
+                };
+            }
+            if (!session.ovSessionId) {
+                return {
+                    content: [{ type: "text", text: "Error: no active session." }],
+                    details: { error: "no_session" },
+                };
+            }
+            try {
+                const client = await deps.getClient();
+                const detail = await client.getSessionArchive(session.ovSessionId, archiveId, session.agentId);
+                const header = [
+                    `## ${detail.archive_id}`,
+                    detail.abstract ? `**Summary**: ${detail.abstract}` : "",
+                    `**Messages**: ${detail.messages.length}`,
+                    "",
+                ].filter(Boolean).join("\n");
+                const body = detail.messages
+                    .map((message) => deps.formatMessage(message))
+                    .join("\n\n");
+                deps.logger?.info?.(`openviking: ov_archive_expand expanded ${detail.archive_id}, messages=${detail.messages.length}, chars=${body.length}, sessionId=${sessionId}`);
+                return {
+                    content: [{ type: "text", text: `${header}\n${body}` }],
+                    details: {
+                        action: "expanded",
+                        archiveId: detail.archive_id,
+                        messageCount: detail.messages.length,
+                        sessionId,
+                        ovSessionId: session.ovSessionId,
+                    },
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                deps.logger?.warn?.(`openviking: ov_archive_expand failed (archiveId=${archiveId}, sessionId=${sessionId}): ${msg}`);
+                return {
+                    content: [{ type: "text", text: `Failed to expand ${archiveId}: ${msg}` }],
+                    details: { error: msg, archiveId, sessionId, ovSessionId: session.ovSessionId },
+                };
+            }
+        },
+    }), { name: "ov_archive_expand" });
+}

package/dist/plugin/openviking-bypass-runtime.js

@@ -0,0 +1,8 @@
+import { compileSessionPatterns, shouldBypassSession, } from "../text-utils.js";
+export function createOpenVikingBypassRuntime(options) {
+    const bypassSessionPatterns = compileSessionPatterns(options.cfg.bypassSessionPatterns);
+    const isBypassedSession = (ctx) => shouldBypassSession(ctx ?? {}, bypassSessionPatterns);
+    return {
+        isBypassedSession,
+    };
+}

package/dist/plugin/openviking-client-runtime.js

@@ -0,0 +1,28 @@
+import { OpenVikingClient } from "../client.js";
+export function createOpenVikingClientRuntime(options) {
+    const { cfg, logger } = options;
+    if (cfg.logFindRequests) {
+        logger.info("openviking: routing debug logging enabled (config logFindRequests, or env OPENVIKING_LOG_ROUTING=1 / OPENVIKING_DEBUG=1)");
+    }
+    const verboseRoutingInfo = (message) => {
+        if (cfg.logFindRequests) {
+            logger.info(message);
+        }
+    };
+    verboseRoutingInfo(`openviking: loaded plugin config peer_role="${cfg.peer_role}" peer_prefix="${cfg.peer_prefix}" ` +
+        `(raw peer_prefix=${JSON.stringify(options.rawPeerPrefix ?? "(missing)")}; ` +
+        `${cfg.peer_prefix
+            ? 'non-empty → assistant peer_id is <peer_prefix>_<ctx.agentId> when peer_role="assistant", or <peer_prefix>_main when ctx.agentId is unknown'
+            : 'empty → assistant peer_id follows OpenClaw ctx.agentId when peer_role="assistant", or "main" when ctx.agentId is unknown'})`);
+    const routingDebugLog = cfg.logFindRequests
+        ? (msg) => {
+            logger.info(msg);
+        }
+        : undefined;
+    const clientPromise = Promise.resolve(new OpenVikingClient(cfg.baseUrl, cfg.apiKey, cfg.peer_prefix, cfg.timeoutMs, cfg.accountId, cfg.userId, routingDebugLog, { transport: options.transport }));
+    const getClient = () => clientPromise;
+    return {
+        getClient,
+        verboseRoutingInfo,
+    };
+}

package/dist/plugin/openviking-command-args.js

@@ -0,0 +1,146 @@
+export function tokenizeCommandArgs(args) {
+    const tokens = [];
+    let current = "";
+    let quote = null;
+    let escaping = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const ch = args[i];
+        const next = args[i + 1];
+        if (escaping) {
+            current += ch;
+            escaping = false;
+            continue;
+        }
+        if (ch === "\\") {
+            const shouldEscape = quote === '"'
+                ? next === '"' || next === "\\"
+                : !quote && Boolean(next && (/\s/.test(next) || next === '"' || next === "'"));
+            if (shouldEscape) {
+                escaping = true;
+                continue;
+            }
+            current += ch;
+            continue;
+        }
+        if ((ch === '"' || ch === "'") && (!quote || quote === ch)) {
+            quote = quote ? null : ch;
+            continue;
+        }
+        if (!quote && /\s/.test(ch)) {
+            if (current) {
+                tokens.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += ch;
+    }
+    if (escaping) {
+        current += "\\";
+    }
+    if (quote) {
+        throw new Error("Unterminated quoted argument");
+    }
+    if (current) {
+        tokens.push(current);
+    }
+    return tokens;
+}
+function parseFlagArgs(args) {
+    const tokens = tokenizeCommandArgs(args);
+    const positionals = [];
+    const flags = new Map();
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (!token.startsWith("--")) {
+            positionals.push(token);
+            continue;
+        }
+        const raw = token.slice(2);
+        if (!raw) {
+            continue;
+        }
+        const eqIndex = raw.indexOf("=");
+        if (eqIndex >= 0) {
+            flags.set(raw.slice(0, eqIndex), raw.slice(eqIndex + 1));
+            continue;
+        }
+        const next = tokens[i + 1];
+        if (next && !next.startsWith("--")) {
+            flags.set(raw, next);
+            i += 1;
+        }
+        else {
+            flags.set(raw, true);
+        }
+    }
+    return { positionals, flags };
+}
+function getStringFlag(flags, name) {
+    const value = flags.get(name);
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function getNumberFlag(flags, name) {
+    const raw = getStringFlag(flags, name);
+    if (!raw) {
+        return undefined;
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        throw new Error(`--${name} must be a number`);
+    }
+    return value;
+}
+function getBoolFlag(flags, name) {
+    return flags.get(name) === true;
+}
+export function parseAddResourceCommandArgs(args) {
+    const parsed = parseFlagArgs(args);
+    const source = parsed.positionals.length <= 1 ? parsed.positionals[0] : parsed.positionals.join(" ").trim();
+    if (!source) {
+        throw new Error("Usage: /add-resource <source> [--to URI] [--parent URI] [--reason TEXT] [--instruction TEXT] [--wait] [--timeout SEC]");
+    }
+    const to = getStringFlag(parsed.flags, "to");
+    const parent = getStringFlag(parsed.flags, "parent");
+    if (to && parent) {
+        throw new Error("Cannot specify both --to and --parent.");
+    }
+    return {
+        source,
+        to,
+        parent,
+        reason: getStringFlag(parsed.flags, "reason"),
+        instruction: getStringFlag(parsed.flags, "instruction"),
+        wait: getBoolFlag(parsed.flags, "wait"),
+        timeout: getNumberFlag(parsed.flags, "timeout"),
+    };
+}
+export function parseAddSkillCommandArgs(args) {
+    const parsed = parseFlagArgs(args);
+    const source = parsed.positionals.length <= 1 ? parsed.positionals[0] : parsed.positionals.join(" ").trim();
+    if (!source) {
+        throw new Error("Usage: /add-skill <source> [--wait] [--timeout SEC]");
+    }
+    if (parsed.flags.has("to") || parsed.flags.has("parent") || parsed.flags.has("reason") || parsed.flags.has("instruction")) {
+        throw new Error("--to, --parent, --reason, and --instruction are resource-only options.");
+    }
+    return {
+        source,
+        wait: getBoolFlag(parsed.flags, "wait"),
+        timeout: getNumberFlag(parsed.flags, "timeout"),
+    };
+}
+export function parseOVSearchCommandArgs(args) {
+    const parsed = parseFlagArgs(args);
+    // `/ov-search` only accepts a single query string, so positional segments are
+    // always re-joined to preserve unquoted multi-word searches.
+    const query = parsed.positionals.join(" ").trim();
+    if (!query) {
+        throw new Error('Usage: /ov-search "<query>" [--uri URI] [--limit N]');
+    }
+    return {
+        query,
+        uri: getStringFlag(parsed.flags, "uri"),
+        limit: getNumberFlag(parsed.flags, "limit"),
+    };
+}

package/dist/plugin/openviking-command-definitions.js

@@ -0,0 +1,206 @@
+function tokenizeCommandArgs(args) {
+    const tokens = [];
+    let current = "";
+    let quote = null;
+    let escaping = false;
+    for (let i = 0; i < args.length; i += 1) {
+        const ch = args[i];
+        const next = args[i + 1];
+        if (escaping) {
+            current += ch;
+            escaping = false;
+            continue;
+        }
+        if (ch === "\\") {
+            const shouldEscape = quote === '"'
+                ? next === '"' || next === "\\"
+                : !quote && Boolean(next && (/\s/.test(next) || next === '"' || next === "'"));
+            if (shouldEscape) {
+                escaping = true;
+                continue;
+            }
+            current += ch;
+            continue;
+        }
+        if ((ch === '"' || ch === "'") && (!quote || quote === ch)) {
+            quote = quote ? null : ch;
+            continue;
+        }
+        if (!quote && /\s/.test(ch)) {
+            if (current) {
+                tokens.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += ch;
+    }
+    if (escaping) {
+        current += "\\";
+    }
+    if (quote) {
+        throw new Error("Unterminated quoted argument");
+    }
+    if (current) {
+        tokens.push(current);
+    }
+    return tokens;
+}
+function parseFlagArgs(args) {
+    const tokens = tokenizeCommandArgs(args);
+    const flags = new Map();
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (!token.startsWith("--")) {
+            continue;
+        }
+        const raw = token.slice(2);
+        if (!raw) {
+            continue;
+        }
+        const eqIndex = raw.indexOf("=");
+        if (eqIndex >= 0) {
+            flags.set(raw.slice(0, eqIndex), raw.slice(eqIndex + 1));
+            continue;
+        }
+        const next = tokens[i + 1];
+        if (next && !next.startsWith("--")) {
+            flags.set(raw, next);
+            i += 1;
+        }
+        else {
+            flags.set(raw, true);
+        }
+    }
+    return { flags };
+}
+function getStringFlag(flags, name) {
+    const value = flags.get(name);
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function getNumberFlag(flags, name) {
+    const raw = getStringFlag(flags, name);
+    if (!raw) {
+        return undefined;
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        throw new Error(`--${name} must be a number`);
+    }
+    return value;
+}
+function getBoolFlag(flags, name) {
+    return flags.get(name) === true;
+}
+function parseRecallTraceCommandArgs(args) {
+    const flags = parseFlagArgs(args).flags;
+    return {
+        turn: getStringFlag(flags, "turn"),
+        traceId: getStringFlag(flags, "trace-id"),
+        sessionId: getStringFlag(flags, "session-id"),
+        sessionKey: getStringFlag(flags, "session-key"),
+        ovSessionId: getStringFlag(flags, "ov-session-id"),
+        source: getStringFlag(flags, "source"),
+        resourceTypes: getStringFlag(flags, "resource-types"),
+        since: getNumberFlag(flags, "since"),
+        until: getNumberFlag(flags, "until"),
+        includeContent: getBoolFlag(flags, "include-content"),
+        limit: getNumberFlag(flags, "limit"),
+    };
+}
+function toCommandResult(result) {
+    return { text: result.content[0].text, details: result.details };
+}
+export function createOpenVikingCommandDefinitions(deps) {
+    return [
+        {
+            name: "add-resource",
+            description: "Add a resource into OpenViking.",
+            acceptsArgs: true,
+            handler: async (ctx) => {
+                try {
+                    if (deps.isBypassedSession(ctx)) {
+                        return toCommandResult(deps.makeBypassedToolResult("add_resource"));
+                    }
+                    const session = deps.resolvePluginSessionRouting(ctx);
+                    const input = deps.parseAddResourceCommandArgs(ctx.args ?? "");
+                    return toCommandResult(await deps.addResourceOpenViking(input, session.agentId));
+                }
+                catch (err) {
+                    return { text: `OpenViking add resource failed: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            },
+        },
+        {
+            name: "add-skill",
+            description: "Add a skill into OpenViking.",
+            acceptsArgs: true,
+            handler: async (ctx) => {
+                try {
+                    if (deps.isBypassedSession(ctx)) {
+                        return toCommandResult(deps.makeBypassedToolResult("add_skill"));
+                    }
+                    const session = deps.resolvePluginSessionRouting(ctx);
+                    const input = deps.parseAddSkillCommandArgs(ctx.args ?? "");
+                    return toCommandResult(await deps.addSkillOpenViking(input, session.agentId));
+                }
+                catch (err) {
+                    return { text: `OpenViking add skill failed: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            },
+        },
+        {
+            name: "ov-search",
+            description: "Search OpenViking resources and skills.",
+            acceptsArgs: true,
+            handler: async (ctx) => {
+                try {
+                    if (deps.isBypassedSession(ctx)) {
+                        return toCommandResult(deps.makeBypassedToolResult("ov_search"));
+                    }
+                    const session = deps.resolvePluginSessionRouting(ctx);
+                    const input = deps.parseOVSearchCommandArgs(ctx.args ?? "");
+                    return toCommandResult(await deps.searchOpenViking(input, session.agentId, session));
+                }
+                catch (err) {
+                    return { text: `OpenViking search failed: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            },
+        },
+        {
+            name: "ov-query-config",
+            description: "Get or set runtime OpenViking query parameters for the current claw/session.",
+            acceptsArgs: true,
+            handler: async (ctx) => {
+                try {
+                    return await deps.handleQueryConfigCommand(ctx);
+                }
+                catch (err) {
+                    return { text: `OpenViking query config failed: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            },
+        },
+        {
+            name: "ov-recall-trace",
+            description: "Query OpenViking recall trace records.",
+            acceptsArgs: true,
+            handler: async (ctx) => {
+                try {
+                    if (deps.isBypassedSession(ctx)) {
+                        return toCommandResult(deps.makeBypassedToolResult("ov_recall_trace"));
+                    }
+                    const session = deps.resolvePluginSessionRouting(ctx);
+                    const input = parseRecallTraceCommandArgs(ctx.args ?? "");
+                    const result = await deps.queryRecallTraces(input, session);
+                    return {
+                        text: deps.formatRecallTraceText(result),
+                        details: { count: result.entries.length, lookupLayer: result.lookupLayer, warnings: result.warnings, entries: result.entries },
+                    };
+                }
+                catch (err) {
+                    return { text: `OpenViking recall trace query failed: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            },
+        },
+    ];
+}