Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

20.7 KB
Raw Blame
import type {
  RecallTraceEntry,
  RecallTraceQuery,
  RecallTraceResult,
  RecallTraceSource,
} from "../recall-trace.js";
import type { RecallResourceType } from "../registries/recall-resource-types.js";
import type { RecallTraceRouteHandlers, RecallTraceRouteRequest } from "./recall-trace-routes.js";

export type OpenVikingRecallTraceInput = {
  turn?: "latest" | "all";
  traceId?: string;
  sessionId?: string;
  sessionKey?: string;
  ovSessionId?: string;
  source?: RecallTraceSource;
  resourceTypes?: RecallResourceType[] | string;
  since?: number;
  until?: number;
  includeContent?: boolean;
  limit?: number;
};

export type OpenVikingRecallTraceSession = {
  sessionId?: string;
  sessionKey?: string;
  ovSessionId?: string;
  agentId: string;
  actorPeerId?: string;
};

export type OpenVikingRecallTraceQueryResult = {
  entries: RecallTraceEntry[];
  lookupLayer: "memory" | "persistent";
  warnings: string[];
};

export type OpenVikingRecallTraceRuntimeDeps = {
  getClient: () => Promise<{ read: (uri: string, agentId?: string) => Promise<unknown> }>;
  resolvePluginSessionRouting: (ctx?: {
    agentId?: string;
    sessionId?: string;
    sessionKey?: string;
    ovSessionId?: string;
  }) => OpenVikingRecallTraceSession;
  traceRecorder?: {
    queryWithFallback: (query: RecallTraceQuery) => Promise<OpenVikingRecallTraceQueryResult>;
  };
  registerRecallTraceRoutes: (ctx: unknown, handlers: RecallTraceRouteHandlers) => boolean;
  normalizeResourceTypes: (value: unknown) => RecallResourceType[];
  clampScore: (score: number) => number;
  previewText: (value: unknown, maxChars: number) => string | undefined;
  cfg: {
    traceRecallIncludeContentByDefault: boolean;
    traceRecallPreviewChars: number;
    recallMaxContentChars: number;
  };
};

function getOptionalInteger(value: unknown, fallback: number): number {
  if (typeof value !== "number" || !Number.isFinite(value)) {
    return fallback;
  }
  return Math.floor(value);
}

function getPositiveInteger(value: unknown, fallback: number): number {
  return Math.max(1, getOptionalInteger(value, fallback));
}

function toQueryObject(request?: RecallTraceRouteRequest): Record<string, unknown> {
  const query: Record<string, unknown> = { ...(request?.query ?? {}) };
  if (request?.url) {
    const parsed = new URL(request.url, "http://openclaw.local");
    for (const [key, value] of parsed.searchParams.entries()) {
      query[key] = value;
    }
  }
  return { ...query, ...(request?.params ?? {}) };
}

function toBoolean(value: unknown): boolean | undefined {
  if (typeof value === "boolean") return value;
  if (typeof value !== "string") return undefined;
  return ["1", "true", "yes"].includes(value.trim().toLowerCase());
}

function toNumber(value: unknown): number | undefined {
  if (typeof value === "number") return value;
  if (typeof value === "string" && value.trim()) {
    const parsed = Number(value);
    return Number.isFinite(parsed) ? parsed : undefined;
  }
  return undefined;
}

function toString(value: unknown): string | undefined {
  return typeof value === "string" && value.trim() ? value.trim() : undefined;
}

function queryValue(query: Record<string, unknown>, ...keys: string[]): unknown {
  for (const key of keys) {
    if (query[key] !== undefined) {
      return query[key];
    }
  }
  return undefined;
}

function toSessionKey(query: Record<string, unknown>): string | undefined {
  return toString(queryValue(query, "sessionKey", "sessionkey", "session_key", "session-key"));
}

function toLimitedInteger(value: unknown, fallback: number, min: number, max: number): number | undefined {
  const parsed = toNumber(value);
  const raw = parsed === undefined ? fallback : Math.floor(parsed);
  return Number.isFinite(raw) && raw >= min && raw <= max ? raw : undefined;
}

function inferUriType(uri: string): string {
  if (uri.startsWith("viking://resources") || uri.startsWith("viking://resource")) return "resource";
  if (/^viking:\/\/(?:user\/[^/]+|~)\/sessions(?:\/|$)/.test(uri)) return "session";
  if (uri.startsWith("viking://user/skills") || uri.startsWith("viking://~/skills") || uri.startsWith("viking://skills")) return "skill";
  if (uri.startsWith("viking://user/") || uri.startsWith("viking://~/")) return "user_memory";
  if (uri.includes("/archive") || uri.includes("/history/")) return "archive";
  return "unknown";
}

function hasExplicitRecallTraceIdentityFilter(input: OpenVikingRecallTraceInput): boolean {
  const traceId = typeof input.traceId === "string" && input.traceId.trim();
  const sessionId = typeof input.sessionId === "string" && input.sessionId.trim();
  const sessionKey = typeof input.sessionKey === "string" && input.sessionKey.trim();
  const ovSessionId = typeof input.ovSessionId === "string" && input.ovSessionId.trim();
  return !!(traceId || sessionId || sessionKey || ovSessionId);
}

function findTraceItem(entry: RecallTraceEntry, uri: string): {
  category?: string;
  score?: number;
  level?: number;
  abstractPreview?: string;
  resultType?: RecallTraceResult["resultType"];
  sourceTraceId?: string;
  source?: RecallTraceSource;
} | undefined {
  const selected = entry.selected.find((item) => item.uri === uri);
  const searchResult = entry.searches.flatMap((search) => search.results).find((item) => item.uri === uri);
  if (!selected && !searchResult) {
    return undefined;
  }
  return {
    category: selected?.category ?? searchResult?.category,
    score: selected?.score ?? searchResult?.score,
    level: searchResult?.level,
    abstractPreview: selected?.abstractPreview ?? searchResult?.abstractPreview,
    resultType: searchResult?.resultType,
    sourceTraceId: entry.traceId,
    source: entry.source,
  };
}

export function createOpenVikingRecallTraceRuntime(deps: OpenVikingRecallTraceRuntimeDeps): {
  queryRecallTraces: (input: OpenVikingRecallTraceInput, session: OpenVikingRecallTraceSession) => Promise<OpenVikingRecallTraceQueryResult>;
  formatRecallTraceText: (result: { entries: RecallTraceEntry[]; lookupLayer: string; warnings: string[] }) => string;
  routeHandlers: RecallTraceRouteHandlers;
  registerRecallTraceRoutes: (ctx?: unknown) => boolean;
} {
  const parseRecallTraceInput = (
    input: OpenVikingRecallTraceInput,
    ctx: { sessionId?: string; sessionKey?: string; ovSessionId?: string },
  ): RecallTraceQuery => {
    const traceId = typeof input.traceId === "string" && input.traceId.trim() ? input.traceId.trim() : undefined;
    const explicitSessionId = typeof input.sessionId === "string" && input.sessionId.trim() ? input.sessionId.trim() : undefined;
    const explicitSessionKey = typeof input.sessionKey === "string" && input.sessionKey.trim() ? input.sessionKey.trim() : undefined;
    const explicitOvSessionId = typeof input.ovSessionId === "string" && input.ovSessionId.trim() ? input.ovSessionId.trim() : undefined;
    const hasExplicitIdentityFilter = !!(traceId || explicitSessionId || explicitSessionKey || explicitOvSessionId);
    const defaultSessionKey = !hasExplicitIdentityFilter ? ctx.sessionKey : undefined;
    const defaultSessionId = !hasExplicitIdentityFilter && !defaultSessionKey ? ctx.sessionId : undefined;
    const defaultOvSessionId = !hasExplicitIdentityFilter && !defaultSessionKey && !defaultSessionId ? ctx.ovSessionId : undefined;
    return {
      turn: input.turn === "all" ? "all" : "latest",
      traceId,
      sessionId: explicitSessionId ?? defaultSessionId,
      sessionKey: explicitSessionKey ?? defaultSessionKey,
      ovSessionId: explicitOvSessionId ?? defaultOvSessionId,
      source: typeof input.source === "string" && input.source.trim() ? input.source as RecallTraceSource : undefined,
      resourceTypes: input.resourceTypes ? deps.normalizeResourceTypes(input.resourceTypes) : undefined,
      since: typeof input.since === "number" ? input.since : undefined,
      until: typeof input.until === "number" ? input.until : undefined,
      limit: getPositiveInteger(input.limit, 20),
    };
  };

  const shouldIncludeTraceContent = (input?: { includeContent?: boolean }): boolean =>
    typeof input?.includeContent === "boolean" ? input.includeContent : deps.cfg.traceRecallIncludeContentByDefault;

  const enrichTraceEntriesWithContent = async (
    result: OpenVikingRecallTraceQueryResult,
    includeContent: boolean,
    agentId?: string,
  ): Promise<OpenVikingRecallTraceQueryResult> => {
    if (!includeContent || result.entries.length === 0) {
      return result;
    }
    const client = await deps.getClient();
    const warnings = [...result.warnings];
    const entries = await Promise.all(result.entries.map(async (entry) => {
      const selected = await Promise.all(entry.selected.map(async (item) => {
        try {
          const content = await client.read(item.uri, agentId);
          const text = typeof content === "string" ? content : JSON.stringify(content);
          return { ...item, contentPreview: deps.previewText(text, deps.cfg.recallMaxContentChars) };
        } catch (err) {
          const readError = err instanceof Error ? err.message : String(err);
          warnings.push(`Failed to read recall trace content ${item.uri}: ${readError}`);
          return { ...item, readError };
        }
      }));
      return { ...entry, selected };
    }));
    return { ...result, entries, warnings };
  };

  const queryTraceForRoute = async (query: OpenVikingRecallTraceInput, session: OpenVikingRecallTraceSession) => deps.traceRecorder
    ? deps.traceRecorder.queryWithFallback(parseRecallTraceInput(query, session))
    : Promise.resolve({ entries: [], lookupLayer: "memory" as const, warnings: ["traceRecall is disabled"] });

  const queryRecallTraces = async (
    input: OpenVikingRecallTraceInput,
    session: OpenVikingRecallTraceSession,
  ): Promise<OpenVikingRecallTraceQueryResult> => {
    const query = parseRecallTraceInput(input, session);
    const base = deps.traceRecorder
      ? await deps.traceRecorder.queryWithFallback(query)
      : { entries: [], lookupLayer: "memory" as const, warnings: ["traceRecall is disabled"] };
    if (
      deps.traceRecorder &&
      base.entries.length === 0 &&
      !hasExplicitRecallTraceIdentityFilter(input) &&
      query.sessionKey
    ) {
      const fallbackIdentities: RecallTraceQuery[] = [];
      if (session.sessionId) {
        fallbackIdentities.push({ ...query, sessionKey: undefined, sessionId: session.sessionId, ovSessionId: undefined });
      }
      if (session.ovSessionId) {
        fallbackIdentities.push({ ...query, sessionKey: undefined, sessionId: undefined, ovSessionId: session.ovSessionId });
      }
      for (const fallbackQuery of fallbackIdentities) {
        const fallback = await deps.traceRecorder.queryWithFallback(fallbackQuery);
        if (fallback.entries.length > 0) {
          return enrichTraceEntriesWithContent(fallback, shouldIncludeTraceContent(input), session.actorPeerId);
        }
      }
    }
    return enrichTraceEntriesWithContent(base, shouldIncludeTraceContent(input), session.actorPeerId);
  };

  const handleUriDetail = async (request?: RecallTraceRouteRequest) => {
    const query = toQueryObject(request);
    const uri = toString(query.uri);
    if (!uri || !uri.startsWith("viking://") || uri.endsWith("...") || uri.includes("…")) {
      return { status: 400, body: { ok: false, uri: uri ?? "", readStatus: "not_requested", warnings: [], error: { code: "invalid_uri", message: "uri must be a complete viking:// URI" } } };
    }
    const offset = toLimitedInteger(query.offset, 0, 0, 1_000_000_000);
    const contentLimit = toLimitedInteger(queryValue(query, "contentLimit", "content-limit", "content_limit"), 20_000, 1, 100_000);
    if (offset === undefined || contentLimit === undefined) {
      return { status: 400, body: { ok: false, uri, readStatus: "not_requested", warnings: [], error: { code: "invalid_param", message: "offset or contentLimit is invalid" } } };
    }
    const includeContent = toBoolean(queryValue(query, "includeContent", "include-content", "include_content")) ?? true;
    const preferTracePreview = toBoolean(queryValue(query, "preferTracePreview", "prefer-trace-preview", "prefer_trace_preview")) ?? true;
    const session = deps.resolvePluginSessionRouting(query);
    const traceId = toString(queryValue(query, "traceId", "trace-id", "trace_id"));
    let traceMetadata: ReturnType<typeof findTraceItem> | undefined;
    const warnings: string[] = [];
    if (preferTracePreview && traceId && deps.traceRecorder) {
      const traceResult = await queryTraceForRoute({ traceId, turn: "latest", limit: 1 }, session);
      warnings.push(...traceResult.warnings);
      traceMetadata = traceResult.entries[0] ? findTraceItem(traceResult.entries[0], uri) : undefined;
    }
    const baseBody = {
      ok: true,
      uri,
      uriType: inferUriType(uri),
      abstractPreview: traceMetadata?.abstractPreview,
      metadata: {
        category: traceMetadata?.category,
        score: traceMetadata?.score,
        level: traceMetadata?.level,
        resultType: traceMetadata?.resultType,
        sourceTraceId: traceMetadata?.sourceTraceId,
        source: traceMetadata?.source,
      },
      readStatus: "not_requested" as const,
      warnings,
    };
    if (!includeContent) {
      return { status: 200, body: baseBody };
    }
    try {
      const client = await deps.getClient();
      const content = await client.read(uri, session.actorPeerId);
      const text = typeof content === "string" ? content : JSON.stringify(content, null, 2);
      const chars = Array.from(text);
      const slice = chars.slice(offset, offset + contentLimit).join("");
      return {
        status: 200,
        body: {
          ...baseBody,
          content: {
            text: slice,
            offset,
            limit: contentLimit,
            returnedChars: Array.from(slice).length,
            totalChars: chars.length,
            hasMore: offset + contentLimit < chars.length,
          },
          readStatus: "ok" as const,
        },
      };
    } catch (err) {
      return {
        status: 502,
        body: {
          ...baseBody,
          ok: false,
          readStatus: "read_failed" as const,
          error: { code: "read_failed", message: err instanceof Error ? err.message : String(err) },
        },
      };
    }
  };

  const handleLatestOvSearchList = async (request?: RecallTraceRouteRequest) => {
    const query = toQueryObject(request);
    const session = deps.resolvePluginSessionRouting(query);
    const limit = toLimitedInteger(query.limit, 20, 1, 100);
    if (limit === undefined) {
      return { status: 400, body: { ok: false, items: [], totalItems: 0, warnings: [], error: { code: "invalid_param", message: "limit is invalid" } } };
    }
    const includeSelected = toBoolean(query.includeSelected) ?? true;
    const dedupe = toBoolean(query.dedupe) ?? true;
    const includeSkills = toBoolean(query.includeSkills) ?? true;
    const strict = toBoolean(query.strict) ?? false;
    const result = await queryTraceForRoute({
      turn: "latest",
      source: "ov_search",
      sessionId: toString(query.sessionId),
      sessionKey: toSessionKey(query),
      ovSessionId: toString(query.ovSessionId),
      limit: 1,
    }, session);
    const agentId = toString(query.agentId);
    const entry = agentId ? result.entries.find((candidate) => candidate.agentId === agentId) : result.entries[0];
    if (!entry) {
      const body = {
        ok: !strict,
        lookupLayer: "none" as const,
        fallbackUsed: false,
        query: { sessionId: toString(query.sessionId), sessionKey: toString(query.sessionKey), ovSessionId: toString(query.ovSessionId), agentId, limit, lookup: toString(query.lookup) ?? "auto" },
        items: [],
        totalItems: 0,
        warnings: [...result.warnings, "no ov_search trace found for latest interaction"],
        ...(strict ? { error: { code: "not_found", message: "no ov_search trace found for latest interaction" } } : {}),
      };
      return { status: strict ? 404 : 200, body };
    }
    const searchResultByUri = new Map<string, RecallTraceResult & { targetUri?: string }>();
    for (const search of entry.searches) {
      for (const item of search.results) {
        searchResultByUri.set(item.uri, { ...item, targetUri: search.targetUriResolved ?? search.targetUriInput });
      }
    }
    const items: Array<Record<string, unknown>> = [];
    const addItem = (item: { uri: string; resourceType?: unknown; category?: string; score?: number; abstractPreview?: string }, source: "search_result" | "selected") => {
      const matched = searchResultByUri.get(item.uri);
      const resultType = matched?.resultType ?? (inferUriType(item.uri) === "skill" ? "skill" : inferUriType(item.uri).includes("memory") ? "memory" : "resource");
      if (!includeSkills && resultType === "skill") {
        return;
      }
      const row = {
        uri: item.uri,
        abstractPreview: item.abstractPreview ?? matched?.abstractPreview,
        resourceType: item.resourceType ?? matched?.resourceType,
        resultType,
        category: item.category ?? matched?.category,
        score: item.score ?? matched?.score,
        source,
        targetUri: matched?.targetUri,
        detailUrl: `/api/openviking/uri-detail?uri=${encodeURIComponent(item.uri)}&traceId=${encodeURIComponent(entry.traceId)}`,
      };
      if (dedupe) {
        const existing = items.findIndex((candidate) => candidate.uri === item.uri);
        if (existing >= 0) {
          if (source === "selected") items[existing] = row;
          return;
        }
      }
      items.push(row);
    };
    if (includeSelected) {
      entry.selected.forEach((item) => addItem(item, "selected"));
    }
    for (const search of entry.searches) {
      search.results.forEach((item) => addItem(item, "search_result"));
    }
    const limited = items.slice(0, limit);
    return {
      status: 200,
      body: {
        ok: true,
        lookupLayer: result.lookupLayer,
        fallbackUsed: result.lookupLayer === "persistent",
        query: { sessionId: toString(query.sessionId), sessionKey: toString(query.sessionKey), ovSessionId: toString(query.ovSessionId), agentId, limit, lookup: toString(query.lookup) ?? "auto" },
        trace: {
          traceId: entry.traceId,
          ts: entry.ts,
          isoTime: new Date(entry.ts).toISOString(),
          triggerQuery: entry.trigger.query,
          totalSearches: entry.searches.length,
        },
        items: limited,
        totalItems: limited.length,
        warnings: result.warnings,
      },
    };
  };

  const handleRecallTraces = async (request?: RecallTraceRouteRequest) => {
    const query = toQueryObject(request);
    const session = deps.resolvePluginSessionRouting(query);
    const result = await queryRecallTraces({
      turn: query.turn === "all" ? "all" : "latest",
      traceId: toString(queryValue(query, "traceId", "trace-id", "trace_id")),
      sessionId: typeof query.sessionId === "string" ? query.sessionId : undefined,
      sessionKey: toSessionKey(query),
      ovSessionId: typeof query.ovSessionId === "string" ? query.ovSessionId : undefined,
      source: typeof query.source === "string" ? query.source as RecallTraceSource : undefined,
      resourceTypes: typeof query.resourceTypes === "string" ? query.resourceTypes : undefined,
      since: toNumber(query.since),
      until: toNumber(query.until),
      includeContent: toBoolean(queryValue(query, "includeContent", "include-content", "include_content")),
      limit: toNumber(query.limit),
    }, session);
    return { status: 200, body: { ok: true, ...result } };
  };

  const formatRecallTraceText = (result: { entries: RecallTraceEntry[]; lookupLayer: string; warnings: string[] }): string => {
    if (result.entries.length === 0) {
      return `No OpenViking recall traces found (lookupLayer=${result.lookupLayer}).`;
    }
    const blocks = result.entries.map((entry, index) => {
      const selected = entry.selected.slice(0, 8)
        .map((item) => `  - ${item.uri}${item.score !== undefined ? ` (${(deps.clampScore(item.score) * 100).toFixed(0)}%)` : ""}`)
        .join("\n");
      return [
        `## Trace ${index + 1}: ${entry.source}`,
        `traceId: ${entry.traceId}`,
        `query: ${entry.trigger.query}`,
        `resourceTypes: ${entry.resourceTypes.join(", ")}`,
        `stats: candidates=${entry.stats.candidateCount}, selected=${entry.stats.selectedCount}, injected=${entry.stats.injectedCount}`,
        selected ? `selected:\n${selected}` : "selected: (none)",
      ].join("\n");
    });
    const warnings = result.warnings.length > 0
      ? `\n\nWarnings:\n${result.warnings.map((w) => `- ${w}`).join("\n")}`
      : "";
    return `${blocks.join("\n\n")}${warnings}`;
  };

  const routeHandlers = {
    handleRecallTraces,
    handleUriDetail,
    handleLatestOvSearchList,
  };

  return {
    queryRecallTraces,
    formatRecallTraceText,
    routeHandlers,
    registerRecallTraceRoutes: (ctx?: unknown) => deps.registerRecallTraceRoutes(ctx, routeHandlers),
  };
}