@loreai/gateway 0.14.0 → 0.15.0

package/src/recall.ts

@@ -1,433 +0,0 @@
-/**
- * Gateway recall interception — transparent memory search for any client.
- *
- * Uses a unified "Marker and Expand" strategy:
- *
- *  1. **On response (to client):** The recall `tool_use` block is replaced
- *     with a human-readable marker text block
- *     (`📚 Searching <scope> for "<query>"…`). The recall is executed
- *     internally and the result is stored in session state.
- *
- *  2. **On request (from client):** Marker text blocks in the conversation
- *     are expanded back into the original `tool_use` + `tool_result` pairs
- *     before forwarding upstream.
- *
- *  For recall-only responses, a follow-up call is still made internally
- *  so the model can continue in the same HTTP response (seamless UX).
- *
- * All recall execution delegates to `runRecall()` from `@loreai/core`.
- */
-import {
-  runRecall,
-  RECALL_TOOL_DESCRIPTION,
-  RECALL_PARAM_DESCRIPTIONS,
-  log,
-  config as loreConfig,
-  type RecallScope,
-} from "@loreai/core";
-
-import type {
-  GatewayTool,
-  GatewayRequest,
-  GatewayResponse,
-  GatewayToolUseBlock,
-  GatewayMessage,
-  RecallStore,
-} from "./translate/types";
-
-// ---------------------------------------------------------------------------
-// Tool definition
-// ---------------------------------------------------------------------------
-
-/** Recall tool definition for injection into upstream requests. */
-export const RECALL_GATEWAY_TOOL: GatewayTool = {
-  name: "recall",
-  description: RECALL_TOOL_DESCRIPTION,
-  inputSchema: {
-    type: "object",
-    properties: {
-      query: {
-        type: "string",
-        description: RECALL_PARAM_DESCRIPTIONS.query,
-      },
-      scope: {
-        type: "string",
-        enum: ["all", "session", "project", "knowledge"],
-        description: RECALL_PARAM_DESCRIPTIONS.scope,
-      },
-    },
-    required: ["query"],
-  },
-};
-
-export const RECALL_TOOL_NAME = "recall";
-
-// ---------------------------------------------------------------------------
-// Marker utilities — human-readable text ↔ recall tool round-trip
-// ---------------------------------------------------------------------------
-
-/** Scope → human-readable label for marker text. */
-const SCOPE_LABELS: Record<string, string> = {
-  all: "all archives",
-  session: "session history",
-  project: "project archives",
-  knowledge: "knowledge base",
-};
-
-/** Reverse: label → scope enum. */
-const LABEL_TO_SCOPE: Record<string, RecallScope> = Object.fromEntries(
-  Object.entries(SCOPE_LABELS).map(([k, v]) => [v, k as RecallScope]),
-);
-
-/** Map a recall scope to a human-readable label. */
-export function scopeToLabel(scope: string = "all"): string {
-  return SCOPE_LABELS[scope] ?? SCOPE_LABELS.all;
-}
-
-/** Map a human-readable label back to a scope enum value. */
-export function labelToScope(label: string): RecallScope {
-  return LABEL_TO_SCOPE[label] ?? "all";
-}
-
-/**
- * Build a marker text string for a recall tool call.
- *
- * Format: `📚 Searching <scope-label> for "<query>"…`
- */
-export function buildRecallMarker(query: string, scope: string = "all"): string {
-  return `📚 Searching ${scopeToLabel(scope)} for "${query}"…`;
-}
-
-/** Regex to parse a recall marker back into query + scope. */
-const MARKER_REGEX = /📚 Searching (.+?) for "(.+?)"…/;
-
-/**
- * Parse a recall marker text block, returning query and scope if valid.
- * Returns null if the text doesn't match the marker format.
- */
-export function parseRecallMarker(
-  text: string,
-): { query: string; scope: RecallScope } | null {
-  const match = MARKER_REGEX.exec(text);
-  if (!match) return null;
-  return {
-    query: match[2],
-    scope: labelToScope(match[1]),
-  };
-}
-
-/** Derive a store key from query + scope. */
-export function recallStoreKey(query: string, scope: string = "all"): string {
-  return `${scope}:${query}`;
-}
-
-// ---------------------------------------------------------------------------
-// Marker expansion — restore tool_use + tool_result from markers on inbound
-// ---------------------------------------------------------------------------
-
-/**
- * Find recall marker text blocks in the conversation and expand them
- * back into tool_use + tool_result pairs for the upstream API.
- *
- * Scans ALL assistant messages (not just the last one) since markers
- * persist across turns until gradient evicts the message.
- *
- * Mutates the request in-place. Returns true if any expansion was performed.
- */
-export function expandRecallMarkers(
-  req: GatewayRequest,
-  store: RecallStore,
-): boolean {
-  let expanded = false;
-
-  // Iterate forward; when we splice messages the index is adjusted.
-  for (let i = 0; i < req.messages.length; i++) {
-    const msg = req.messages[i];
-    if (msg.role !== "assistant") continue;
-
-    // Find the first (should be only) recall marker in this message.
-    // We process one marker per assistant message per pass; the outer
-    // loop will revisit if there's more than one (rare).
-    let markerIdx = -1;
-    let parsed: { query: string; scope: RecallScope } | null = null;
-    for (let j = 0; j < msg.content.length; j++) {
-      const block = msg.content[j];
-      if (block.type !== "text") continue;
-      parsed = parseRecallMarker(block.text);
-      if (parsed) {
-        markerIdx = j;
-        break;
-      }
-    }
-
-    if (markerIdx < 0 || !parsed) continue;
-
-    const key = recallStoreKey(parsed.query, parsed.scope);
-    const stored = store.get(key);
-    if (!stored) continue; // No stored result — leave marker as-is
-
-    // Check if there's non-tool content AFTER the marker in this message.
-    // This happens when recall-only follow-up piped continuation content
-    // (text blocks) into the same assistant message. Tool_use blocks after
-    // the marker are from the same turn (mixed tools) and stay together.
-    const afterMarker = msg.content.slice(markerIdx + 1);
-    const hasContinuationAfter = afterMarker.length > 0 &&
-      afterMarker.some((b) => b.type !== "tool_use");
-
-    // Replace marker with tool_use
-    msg.content[markerIdx] = {
-      type: "tool_use",
-      id: stored.toolUseId,
-      name: RECALL_TOOL_NAME,
-      input: stored.input,
-    };
-
-    // Truncate assistant message at the tool_use (remove continuation)
-    if (hasContinuationAfter) {
-      msg.content.length = markerIdx + 1;
-    }
-
-    // Build synthetic tool_result user message
-    const toolResultMsg: GatewayMessage = {
-      role: "user",
-      content: [
-        {
-          type: "tool_result",
-          toolUseId: stored.toolUseId,
-          content: stored.result,
-        },
-      ],
-    };
-
-    if (hasContinuationAfter) {
-      // Split: insert tool_result user message + continuation assistant
-      // message after the current assistant message.
-      const continuationMsg: GatewayMessage = {
-        role: "assistant",
-        content: afterMarker,
-      };
-      req.messages.splice(i + 1, 0, toolResultMsg, continuationMsg);
-      // Skip past the two newly inserted messages
-      i += 2;
-    } else {
-      // No split needed — insert tool_result into the following user message.
-      // Prepend (unshift) so the recall result appears before existing
-      // tool_results — matching the tool_use order in the assistant message.
-      const nextMsg = req.messages[i + 1];
-      if (nextMsg?.role === "user") {
-        nextMsg.content.unshift({
-          type: "tool_result",
-          toolUseId: stored.toolUseId,
-          content: stored.result,
-        });
-      } else {
-        // No following user message — insert a synthetic one
-        req.messages.splice(i + 1, 0, toolResultMsg);
-        i += 1;
-      }
-    }
-
-    expanded = true;
-  }
-
-  return expanded;
-}
-
-/**
- * Clean up orphaned recall store entries whose markers no longer
- * appear in the conversation (e.g. gradient evicted the turn).
- */
-export function cleanupRecallStore(
-  req: GatewayRequest,
-  store: RecallStore,
-): void {
-  if (store.size === 0) return;
-
-  // Collect all marker keys still present in assistant messages
-  const activeKeys = new Set<string>();
-  for (const msg of req.messages) {
-    if (msg.role !== "assistant") continue;
-    for (const block of msg.content) {
-      if (block.type !== "text") continue;
-      const parsed = parseRecallMarker(block.text);
-      if (parsed) {
-        activeKeys.add(recallStoreKey(parsed.query, parsed.scope));
-      }
-    }
-  }
-
-  // Remove entries not referenced by any current marker
-  for (const key of store.keys()) {
-    if (!activeKeys.has(key)) {
-      store.delete(key);
-    }
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Detection helpers
-// ---------------------------------------------------------------------------
-
-/** Find the recall tool_use block in a GatewayResponse, if any. */
-export function findRecallToolUse(
-  resp: GatewayResponse,
-): GatewayToolUseBlock | undefined {
-  return resp.content.find(
-    (b): b is GatewayToolUseBlock =>
-      b.type === "tool_use" && b.name === RECALL_TOOL_NAME,
-  );
-}
-
-/** Check whether a response contains a recall tool_use. */
-export function hasRecallToolUse(resp: GatewayResponse): boolean {
-  return findRecallToolUse(resp) !== undefined;
-}
-
-/** Check whether the response contains non-recall tool_use blocks. */
-export function hasOtherToolUse(resp: GatewayResponse): boolean {
-  return resp.content.some(
-    (b) => b.type === "tool_use" && b.name !== RECALL_TOOL_NAME,
-  );
-}
-
-/** Check whether the client's tools list already includes a recall tool. */
-export function clientHasRecallTool(tools: GatewayTool[]): boolean {
-  return tools.some((t) => t.name === RECALL_TOOL_NAME);
-}
-
-// ---------------------------------------------------------------------------
-// Recall execution
-// ---------------------------------------------------------------------------
-
-/** Parse recall input from the tool_use block. */
-function parseRecallInput(block: GatewayToolUseBlock): {
-  query: string;
-  scope: RecallScope;
-} {
-  const input = block.input as Record<string, unknown>;
-  return {
-    query: typeof input.query === "string" ? input.query : "",
-    scope: (input.scope as RecallScope) ?? "all",
-  };
-}
-
-/**
- * Execute the recall tool and return formatted results.
- *
- * Wraps `runRecall()` with error handling — on failure returns a
- * user-friendly error string rather than throwing.
- */
-export async function executeRecall(
-  block: GatewayToolUseBlock,
-  projectPath: string,
-  sessionID: string,
-): Promise<{ result: string; input: { query: string; scope?: RecallScope } }> {
-  const { query, scope } = parseRecallInput(block);
-  const cfg = loreConfig();
-
-  try {
-    const result = await runRecall({
-      query,
-      scope,
-      projectPath,
-      sessionID,
-      knowledgeEnabled: cfg.knowledge?.enabled ?? true,
-      searchConfig: cfg.search,
-    });
-
-    return { result, input: { query, scope } };
-  } catch (e) {
-    log.error("gateway recall execution failed:", e);
-    return {
-      result: "Recall search failed. The memory system encountered an error.",
-      input: { query, scope },
-    };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Follow-up request builder (Case 1: recall-only)
-// ---------------------------------------------------------------------------
-
-/**
- * Build a follow-up request after recall execution.
- *
- * The follow-up includes:
- *  - All original messages
- *  - The assistant's full response (including the recall tool_use)
- *  - A user message with the recall tool_result
- *  - Tools list WITHOUT recall (so the model won't call it again)
- *
- * The model continues from where it left off, now with recall results
- * in context. Its new response streams directly to the client.
- */
-export function buildRecallFollowUp(
-  originalReq: GatewayRequest,
-  resp: GatewayResponse,
-  recallResult: string,
-  recallToolUseBlock: GatewayToolUseBlock,
-): GatewayRequest {
-  // Build assistant message with ONLY the recall tool_use block.
-  // Exclude any pre-recall text/thinking blocks — those were already streamed
-  // to the client. By presenting only the tool_use, the model understands it
-  // called recall and hasn't yet produced a substantive response, so it will
-  // generate new content after receiving the tool_result.
-  const assistantMessage: GatewayMessage = {
-    role: "assistant",
-    content: [recallToolUseBlock],
-  };
-
-  // Build user message with tool_result
-  const toolResultMessage: GatewayMessage = {
-    role: "user",
-    content: [
-      {
-        type: "tool_result",
-        toolUseId: recallToolUseBlock.id,
-        content: recallResult || "[No results found.]",
-      },
-    ],
-  };
-
-  // Strip recall from tools list
-  const toolsWithoutRecall = originalReq.tools.filter(
-    (t) => t.name !== RECALL_TOOL_NAME,
-  );
-
-  return {
-    ...originalReq,
-    messages: [
-      ...originalReq.messages,
-      assistantMessage,
-      toolResultMessage,
-    ],
-    tools: toolsWithoutRecall,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Response content rewriting — replace recall tool_use with marker text
-// ---------------------------------------------------------------------------
-
-/**
- * Build a GatewayResponse with recall tool_use blocks replaced by marker text.
- *
- * Used for both recall-only and mixed-tools cases to produce a response
- * where the client sees human-readable markers instead of tool call mechanics.
- */
-export function replaceRecallWithMarker(
-  resp: GatewayResponse,
-): GatewayResponse {
-  return {
-    ...resp,
-    content: resp.content.map((b) => {
-      if (b.type === "tool_use" && b.name === RECALL_TOOL_NAME) {
-        const input = b.input as Record<string, unknown>;
-        const query = typeof input.query === "string" ? input.query : "";
-        const scope = (input.scope as string) ?? "all";
-        return { type: "text" as const, text: buildRecallMarker(query, scope) };
-      }
-      return b;
-    }),
-  };
-}

package/src/recorder.ts

@@ -1,192 +0,0 @@
-/**
- * Fixture recorder and replayer for the Lore gateway.
- *
- * Recording mode: intercepts every upstream API call, writes the
- * (request, response) pair to an NDJSON fixture file, then returns
- * the real response to the caller unchanged.
- *
- * Replay mode: replays stored fixtures in sequence, never touching
- * the upstream API.  Useful for deterministic integration tests.
- */
-import { appendFileSync } from "node:fs";
-import { log } from "@loreai/core";
-
-// ---------------------------------------------------------------------------
-// Public types
-// ---------------------------------------------------------------------------
-
-/** One entry per upstream API call, stored in the fixture file. */
-export interface FixtureEntry {
-  /** Sequence number within the recording session (0-based). */
-  seq: number;
-  /** Wall-clock timestamp (ms since Unix epoch) when the call was made. */
-  ts: number;
-  /** The upstream request body as sent (Anthropic /v1/messages JSON). */
-  request: unknown;
-  /** The full upstream response body (non-streaming, even if original was streaming). */
-  response: unknown;
-  /** Whether the original request asked for a streaming response. */
-  wasStreaming: boolean;
-  /** Model that was used for the request. */
-  model: string;
-}
-
-/**
- * Interceptor function injected into the upstream forwarding path.
- *
- * @param requestBody  - The request body that will be sent upstream.
- * @param model        - Model identifier from the request.
- * @param wasStreaming - Whether the original request was streaming.
- * @param makeRealRequest - Thunk that performs the actual HTTP request.
- *                          The interceptor decides whether to call it.
- */
-export type UpstreamInterceptor = (
-  requestBody: unknown,
-  model: string,
-  wasStreaming: boolean,
-  makeRealRequest: () => Promise<Response>,
-) => Promise<Response>;
-
-// ---------------------------------------------------------------------------
-// Module-level state
-// ---------------------------------------------------------------------------
-
-/** Non-null when recording is active; holds the path of the fixture file. */
-let recordingPath: string | null = null;
-
-/** Monotonically increasing counter for fixture sequence numbers. */
-let seqCounter = 0;
-
-// ---------------------------------------------------------------------------
-// Recording control
-// ---------------------------------------------------------------------------
-
-/** Enable recording mode. All upstream calls will be appended to `fixturePath`. */
-export function startRecording(fixturePath: string): void {
-  recordingPath = fixturePath;
-  seqCounter = 0;
-  log.info(`[recorder] recording to: ${fixturePath}`);
-}
-
-/** Disable recording mode. */
-export function stopRecording(): void {
-  recordingPath = null;
-}
-
-// ---------------------------------------------------------------------------
-// Recording interceptor
-// ---------------------------------------------------------------------------
-
-/**
- * Returns an `UpstreamInterceptor` when recording mode is active, or
- * `null` when it is not.
- *
- * The returned interceptor:
- *  1. Calls `makeRealRequest()` to get the real upstream response.
- *  2. Reads the full response body text (works for both streaming and
- *     non-streaming — the raw body is always valid JSON from Anthropic
- *     even for streaming responses because we force `stream:false` when
- *     we need the body for the fixture; for streaming the body is SSE
- *     text which we store verbatim).
- *  3. Appends a `FixtureEntry` line to the fixture file.
- *  4. Returns a new `Response` with the same status, headers, and body
- *     (the original body stream is already consumed, so we reconstitute it).
- */
-export function getRecordedInterceptor(): UpstreamInterceptor | null {
-  if (!recordingPath) return null;
-
-  // Capture the path at interceptor creation time so closure is stable
-  const fixturePath = recordingPath;
-
-  return async (
-    requestBody: unknown,
-    model: string,
-    wasStreaming: boolean,
-    makeRealRequest: () => Promise<Response>,
-  ): Promise<Response> => {
-    const ts = Date.now();
-    const seq = seqCounter++;
-
-    // Perform the real upstream request
-    const realResponse = await makeRealRequest();
-
-    // Collect all response headers before consuming the body
-    const responseHeaders: Record<string, string> = {};
-    realResponse.headers.forEach((value, key) => {
-      responseHeaders[key] = value;
-    });
-
-    // Read the full body text — this consumes the stream
-    const bodyText = await realResponse.text();
-
-    // Parse body as JSON for structured storage; fall back to raw string
-    let responseBody: unknown;
-    try {
-      responseBody = JSON.parse(bodyText);
-    } catch {
-      responseBody = bodyText;
-    }
-
-    // Write the fixture entry
-    const entry: FixtureEntry = {
-      seq,
-      ts,
-      request: requestBody,
-      response: responseBody,
-      wasStreaming,
-      model,
-    };
-    appendFileSync(fixturePath, JSON.stringify(entry) + "\n", "utf8");
-
-    log.info(`[recorder] captured turn seq=${seq} model=${model}`);
-
-    // Return a new Response with the same status and headers but a fresh body
-    return new Response(bodyText, {
-      status: realResponse.status,
-      headers: responseHeaders,
-    });
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Replay interceptor
-// ---------------------------------------------------------------------------
-
-/**
- * Returns an interceptor that replays the given fixtures in sequence,
- * without ever calling `makeRealRequest()`.
- *
- * Each call advances an internal counter.  When the counter exceeds
- * `fixtures.length`, an error is thrown.
- */
-export function getReplayInterceptor(fixtures: FixtureEntry[]): UpstreamInterceptor {
-  let replayCounter = 0;
-
-  return async (
-    _requestBody: unknown,
-    _model: string,
-    _wasStreaming: boolean,
-    _makeRealRequest: () => Promise<Response>,
-  ): Promise<Response> => {
-    if (replayCounter >= fixtures.length) {
-      throw new Error(
-        `Replay exhausted: no more fixtures (tried to replay entry ${replayCounter}, ` +
-          `but only ${fixtures.length} fixture(s) are available)`,
-      );
-    }
-
-    const fixture = fixtures[replayCounter++];
-
-    log.info(
-      `[recorder] replaying seq=${fixture.seq} model=${fixture.model} ` +
-        `(${replayCounter}/${fixtures.length})`,
-    );
-
-    // Always return a non-streaming JSON response — the pipeline handles
-    // re-streaming if the client originally requested SSE.
-    return new Response(JSON.stringify(fixture.response), {
-      status: 200,
-      headers: { "content-type": "application/json" },
-    });
-  };
-}