@jonathangu/openclawbrain 0.3.0

package/src/tools/lcm-expansion-recursion-guard.ts

@@ -0,0 +1,286 @@
+import crypto from "node:crypto";
+import { resolveDelegatedExpansionGrantId } from "../expansion-auth.js";
+import type { LcmDependencies } from "../types.js";
+
+export const EXPANSION_RECURSION_ERROR_CODE = "EXPANSION_RECURSION_BLOCKED";
+const EXPANSION_DELEGATION_DEPTH_CAP = 1;
+
+type TelemetryEvent = "start" | "block" | "timeout" | "success";
+
+const telemetryCounters: Record<TelemetryEvent, number> = {
+  start: 0,
+  block: 0,
+  timeout: 0,
+  success: 0,
+};
+
+export type DelegatedExpansionContext = {
+  requestId: string;
+  expansionDepth: number;
+  originSessionKey: string;
+  stampedBy: string;
+  createdAt: string;
+};
+
+export type ExpansionRecursionBlockReason = "depth_cap" | "idempotent_reentry";
+
+export type ExpansionRecursionGuardDecision =
+  | {
+      blocked: false;
+      requestId: string;
+      expansionDepth: number;
+      originSessionKey: string;
+    }
+  | {
+      blocked: true;
+      code: typeof EXPANSION_RECURSION_ERROR_CODE;
+      reason: ExpansionRecursionBlockReason;
+      message: string;
+      requestId: string;
+      expansionDepth: number;
+      originSessionKey: string;
+    };
+
+const delegatedContextBySessionKey = new Map<string, DelegatedExpansionContext>();
+const blockedRequestIdsBySessionKey = new Map<string, Set<string>>();
+
+function normalizeSessionKey(sessionKey?: string): string {
+  return typeof sessionKey === "string" ? sessionKey.trim() : "";
+}
+
+function getOrInitBlockedRequestIds(sessionKey: string): Set<string> {
+  const existing = blockedRequestIdsBySessionKey.get(sessionKey);
+  if (existing) {
+    return existing;
+  }
+  const created = new Set<string>();
+  blockedRequestIdsBySessionKey.set(sessionKey, created);
+  return created;
+}
+
+function resolveFallbackDelegatedContext(
+  sessionKey: string,
+  requestId: string,
+): DelegatedExpansionContext | undefined {
+  if (!sessionKey) {
+    return undefined;
+  }
+  const grantId = resolveDelegatedExpansionGrantId(sessionKey);
+  if (!grantId) {
+    return undefined;
+  }
+  return {
+    requestId,
+    expansionDepth: EXPANSION_DELEGATION_DEPTH_CAP,
+    originSessionKey: sessionKey,
+    stampedBy: "delegated_grant",
+    createdAt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Build actionable recovery guidance for recursion-blocked delegated calls.
+ */
+function buildExpansionRecursionRecoveryGuidance(originSessionKey: string): string {
+  return (
+    "Recovery: In delegated sub-agent sessions, call `lcm_expand` directly and synthesize " +
+    "your answer from that result. Do NOT call `lcm_expand_query` from delegated context. " +
+    `If deeper delegation is required, return to the origin session (${originSessionKey}) ` +
+    "and call `lcm_expand_query` there."
+  );
+}
+
+/**
+ * Create a stable request identifier for delegated expansion orchestration.
+ */
+export function createExpansionRequestId(): string {
+  return crypto.randomUUID();
+}
+
+/**
+ * Resolve the active expansion request id for a session, inheriting from any
+ * stamped delegated context when present.
+ */
+export function resolveExpansionRequestId(sessionKey?: string): string {
+  const key = normalizeSessionKey(sessionKey);
+  return delegatedContextBySessionKey.get(key)?.requestId ?? createExpansionRequestId();
+}
+
+/**
+ * Resolve the next delegated expansion depth to stamp onto a child session.
+ */
+export function resolveNextExpansionDepth(sessionKey?: string): number {
+  const key = normalizeSessionKey(sessionKey);
+  if (!key) {
+    return 1;
+  }
+  const existing = delegatedContextBySessionKey.get(key);
+  if (existing) {
+    return existing.expansionDepth + 1;
+  }
+  return resolveDelegatedExpansionGrantId(key) ? EXPANSION_DELEGATION_DEPTH_CAP + 1 : 1;
+}
+
+/**
+ * Stamp delegated expansion metadata for a child session so re-entry checks can
+ * enforce recursion and depth policies deterministically.
+ */
+export function stampDelegatedExpansionContext(params: {
+  sessionKey: string;
+  requestId: string;
+  expansionDepth: number;
+  originSessionKey: string;
+  stampedBy: string;
+}): DelegatedExpansionContext {
+  const sessionKey = normalizeSessionKey(params.sessionKey);
+  const context: DelegatedExpansionContext = {
+    requestId: params.requestId,
+    expansionDepth: Math.max(0, Math.trunc(params.expansionDepth)),
+    originSessionKey: params.originSessionKey.trim() || "main",
+    stampedBy: params.stampedBy,
+    createdAt: new Date().toISOString(),
+  };
+  if (sessionKey) {
+    delegatedContextBySessionKey.set(sessionKey, context);
+  }
+  return context;
+}
+
+/**
+ * Remove delegated expansion metadata for a child session after cleanup.
+ */
+export function clearDelegatedExpansionContext(sessionKey: string): void {
+  const key = normalizeSessionKey(sessionKey);
+  if (!key) {
+    return;
+  }
+  delegatedContextBySessionKey.delete(key);
+  blockedRequestIdsBySessionKey.delete(key);
+}
+
+/**
+ * Evaluate whether a session is allowed to delegate expansion work.
+ * Delegated contexts are blocked at depth >= 1, with repeated request id
+ * re-entry mapped to an explicit idempotency block reason.
+ */
+export function evaluateExpansionRecursionGuard(params: {
+  sessionKey?: string;
+  requestId: string;
+}): ExpansionRecursionGuardDecision {
+  const sessionKey = normalizeSessionKey(params.sessionKey);
+  const requestId = params.requestId.trim();
+  const delegatedContext =
+    delegatedContextBySessionKey.get(sessionKey) ??
+    resolveFallbackDelegatedContext(sessionKey, requestId || createExpansionRequestId());
+
+  if (!delegatedContext) {
+    return {
+      blocked: false,
+      requestId,
+      expansionDepth: 0,
+      originSessionKey: sessionKey || "main",
+    };
+  }
+
+  if (delegatedContext.expansionDepth < EXPANSION_DELEGATION_DEPTH_CAP) {
+    return {
+      blocked: false,
+      requestId,
+      expansionDepth: delegatedContext.expansionDepth,
+      originSessionKey: delegatedContext.originSessionKey,
+    };
+  }
+
+  const seenRequestIds = getOrInitBlockedRequestIds(sessionKey);
+  const isIdempotentReentry = seenRequestIds.has(requestId);
+  seenRequestIds.add(requestId);
+  const reason: ExpansionRecursionBlockReason = isIdempotentReentry
+    ? "idempotent_reentry"
+    : "depth_cap";
+
+  return {
+    blocked: true,
+    code: EXPANSION_RECURSION_ERROR_CODE,
+    reason,
+    message:
+      `${EXPANSION_RECURSION_ERROR_CODE}: Expansion delegation blocked at depth ` +
+      `${delegatedContext.expansionDepth} (${reason}; requestId=${requestId}; ` +
+      `origin=${delegatedContext.originSessionKey}). ` +
+      buildExpansionRecursionRecoveryGuidance(delegatedContext.originSessionKey),
+    requestId,
+    expansionDepth: delegatedContext.expansionDepth,
+    originSessionKey: delegatedContext.originSessionKey,
+  };
+}
+
+/**
+ * Emit structured delegated expansion telemetry with monotonic counters.
+ */
+export function recordExpansionDelegationTelemetry(params: {
+  deps: Pick<LcmDependencies, "log">;
+  component: string;
+  event: TelemetryEvent;
+  requestId: string;
+  sessionKey?: string;
+  expansionDepth: number;
+  originSessionKey: string;
+  reason?: string;
+  runId?: string;
+}): void {
+  telemetryCounters[params.event] += 1;
+  const payload = {
+    component: params.component,
+    event: params.event,
+    requestId: params.requestId,
+    sessionKey: normalizeSessionKey(params.sessionKey) || undefined,
+    expansionDepth: params.expansionDepth,
+    originSessionKey: params.originSessionKey,
+    reason: params.reason,
+    runId: params.runId,
+    counters: {
+      start: telemetryCounters.start,
+      block: telemetryCounters.block,
+      timeout: telemetryCounters.timeout,
+      success: telemetryCounters.success,
+    },
+  };
+  const line = `[lcm][expansion_delegation] ${JSON.stringify(payload)}`;
+  if (params.event === "start" || params.event === "success") {
+    params.deps.log.info(line);
+    return;
+  }
+  params.deps.log.warn(line);
+}
+
+/**
+ * Return the currently stamped delegated expansion context for test assertions.
+ */
+export function getDelegatedExpansionContextForTests(
+  sessionKey: string,
+): DelegatedExpansionContext | undefined {
+  return delegatedContextBySessionKey.get(normalizeSessionKey(sessionKey));
+}
+
+/**
+ * Return the delegated expansion telemetry counters for tests.
+ */
+export function getExpansionDelegationTelemetrySnapshotForTests(): Record<TelemetryEvent, number> {
+  return {
+    start: telemetryCounters.start,
+    block: telemetryCounters.block,
+    timeout: telemetryCounters.timeout,
+    success: telemetryCounters.success,
+  };
+}
+
+/**
+ * Reset delegated expansion context and telemetry state between tests.
+ */
+export function resetExpansionDelegationGuardForTests(): void {
+  delegatedContextBySessionKey.clear();
+  blockedRequestIdsBySessionKey.clear();
+  telemetryCounters.start = 0;
+  telemetryCounters.block = 0;
+  telemetryCounters.timeout = 0;
+  telemetryCounters.success = 0;
+}

package/src/tools/lcm-grep-tool.ts

@@ -0,0 +1,200 @@
+import { Type } from "@sinclair/typebox";
+import type { LcmContextEngine } from "../engine.js";
+import type { LcmDependencies } from "../types.js";
+import type { AnyAgentTool } from "./common.js";
+import { jsonResult } from "./common.js";
+import { parseIsoTimestampParam, resolveLcmConversationScope } from "./lcm-conversation-scope.js";
+import { formatTimestamp } from "../compaction.js";
+
+const MAX_RESULT_CHARS = 40_000; // ~10k tokens
+
+const LcmGrepSchema = Type.Object({
+  pattern: Type.String({
+    description:
+      "Search pattern. Interpreted as regex when mode is 'regex', or as a text query for 'full_text' mode.",
+  }),
+  mode: Type.Optional(
+    Type.String({
+      description:
+        'Search mode: "regex" for regular expression matching, "full_text" for text search. Default: "regex".',
+      enum: ["regex", "full_text"],
+    }),
+  ),
+  scope: Type.Optional(
+    Type.String({
+      description:
+        'What to search: "messages" for raw messages, "summaries" for compacted summaries, "both" for all. Default: "both".',
+      enum: ["messages", "summaries", "both"],
+    }),
+  ),
+  conversationId: Type.Optional(
+    Type.Number({
+      description:
+        "Conversation ID to search within. If omitted, defaults to the current session conversation.",
+    }),
+  ),
+  allConversations: Type.Optional(
+    Type.Boolean({
+      description:
+        "Set true to explicitly search across all conversations. Ignored when conversationId is provided.",
+    }),
+  ),
+  since: Type.Optional(
+    Type.String({
+      description: "Only return matches created at or after this ISO timestamp.",
+    }),
+  ),
+  before: Type.Optional(
+    Type.String({
+      description: "Only return matches created before this ISO timestamp.",
+    }),
+  ),
+  limit: Type.Optional(
+    Type.Number({
+      description: "Maximum number of results to return (default: 50).",
+      minimum: 1,
+      maximum: 200,
+    }),
+  ),
+});
+
+function truncateSnippet(content: string, maxLen: number = 200): string {
+  const singleLine = content.replace(/\n/g, " ").trim();
+  if (singleLine.length <= maxLen) {
+    return singleLine;
+  }
+  return singleLine.substring(0, maxLen - 3) + "...";
+}
+
+export function createLcmGrepTool(input: {
+  deps: LcmDependencies;
+  lcm: LcmContextEngine;
+  sessionId?: string;
+  sessionKey?: string;
+}): AnyAgentTool {
+  return {
+    name: "lcm_grep",
+    label: "LCM Grep",
+    description:
+      "Search compacted conversation history using regex or full-text search. " +
+      "Searches across messages and/or summaries stored by LCM. " +
+      "Use this to find specific content that may have been compacted away from " +
+      "active context. Returns matching snippets with their summary/message IDs " +
+      "for follow-up with lcm_expand or lcm_describe.",
+    parameters: LcmGrepSchema,
+    async execute(_toolCallId, params) {
+      const retrieval = input.lcm.getRetrieval();
+      const timezone = input.lcm.timezone;
+
+      const p = params as Record<string, unknown>;
+      const pattern = (p.pattern as string).trim();
+      const mode = (p.mode as "regex" | "full_text") ?? "regex";
+      const scope = (p.scope as "messages" | "summaries" | "both") ?? "both";
+      const limit = typeof p.limit === "number" ? Math.trunc(p.limit) : 50;
+      let since: Date | undefined;
+      let before: Date | undefined;
+      try {
+        since = parseIsoTimestampParam(p, "since");
+        before = parseIsoTimestampParam(p, "before");
+      } catch (error) {
+        return jsonResult({
+          error: error instanceof Error ? error.message : "Invalid timestamp filter.",
+        });
+      }
+      if (since && before && since.getTime() >= before.getTime()) {
+        return jsonResult({
+          error: "`since` must be earlier than `before`.",
+        });
+      }
+      const conversationScope = await resolveLcmConversationScope({
+        lcm: input.lcm,
+        deps: input.deps,
+        sessionId: input.sessionId,
+        sessionKey: input.sessionKey,
+        params: p,
+      });
+      if (!conversationScope.allConversations && conversationScope.conversationId == null) {
+        return jsonResult({
+          error:
+            "No LCM conversation found for this session. Provide conversationId or set allConversations=true.",
+        });
+      }
+
+      const result = await retrieval.grep({
+        query: pattern,
+        mode,
+        scope,
+        conversationId: conversationScope.conversationId,
+        limit,
+        since,
+        before,
+      });
+
+      const lines: string[] = [];
+      lines.push("## LCM Grep Results");
+      lines.push(`**Pattern:** \`${pattern}\``);
+      lines.push(`**Mode:** ${mode} | **Scope:** ${scope}`);
+      if (conversationScope.allConversations) {
+        lines.push("**Conversation scope:** all conversations");
+      } else if (conversationScope.conversationId != null) {
+        lines.push(`**Conversation scope:** ${conversationScope.conversationId}`);
+      }
+      if (since || before) {
+        lines.push(
+          `**Time filter:** ${since ? `since ${formatTimestamp(since, timezone)}` : "since -∞"} | ${
+            before ? `before ${formatTimestamp(before, timezone)}` : "before +∞"
+          }`,
+        );
+      }
+      lines.push(`**Total matches:** ${result.totalMatches}`);
+      lines.push("");
+
+      let currentChars = lines.join("\n").length;
+
+      if (result.messages.length > 0) {
+        lines.push("### Messages");
+        lines.push("");
+        for (const msg of result.messages) {
+          const snippet = truncateSnippet(msg.snippet);
+          const line = `- [msg#${msg.messageId}] (${msg.role}, ${formatTimestamp(msg.createdAt, timezone)}): ${snippet}`;
+          if (currentChars + line.length > MAX_RESULT_CHARS) {
+            lines.push("*(truncated — more results available)*");
+            break;
+          }
+          lines.push(line);
+          currentChars += line.length;
+        }
+        lines.push("");
+      }
+
+      if (result.summaries.length > 0) {
+        lines.push("### Summaries");
+        lines.push("");
+        for (const sum of result.summaries) {
+          const snippet = truncateSnippet(sum.snippet);
+          const line = `- [${sum.summaryId}] (${sum.kind}, ${formatTimestamp(sum.createdAt, timezone)}): ${snippet}`;
+          if (currentChars + line.length > MAX_RESULT_CHARS) {
+            lines.push("*(truncated — more results available)*");
+            break;
+          }
+          lines.push(line);
+          currentChars += line.length;
+        }
+        lines.push("");
+      }
+
+      if (result.totalMatches === 0) {
+        lines.push("No matches found.");
+      }
+
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        details: {
+          messageCount: result.messages.length,
+          summaryCount: result.summaries.length,
+          totalMatches: result.totalMatches,
+        },
+      };
+    },
+  };
+}