@jonathangu/openclawbrain 0.3.0

package/src/tools/common.ts

@@ -0,0 +1,53 @@
+import type { AnyAgentTool as OpenClawAnyAgentTool } from "openclaw/plugin-sdk";
+
+export type AnyAgentTool = OpenClawAnyAgentTool;
+
+/** Render structured payloads as deterministic text tool results. */
+export function jsonResult(payload: unknown): {
+  content: Array<{ type: "text"; text: string }>;
+  details: unknown;
+} {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+    details: payload,
+  };
+}
+
+/** Read a string param with optional trimming/required checks. */
+export function readStringParam(
+  params: Record<string, unknown>,
+  key: string,
+  options?: {
+    required?: boolean;
+    trim?: boolean;
+    allowEmpty?: boolean;
+    label?: string;
+  },
+): string | undefined {
+  const raw = params[key];
+  if (raw == null) {
+    if (options?.required) {
+      throw new Error(`${options.label ?? key} is required.`);
+    }
+    return undefined;
+  }
+
+  if (typeof raw !== "string") {
+    throw new Error(`${options?.label ?? key} must be a string.`);
+  }
+
+  const value = options?.trim === false ? raw : raw.trim();
+  if (!options?.allowEmpty && value.length === 0) {
+    if (options?.required) {
+      throw new Error(`${options.label ?? key} is required.`);
+    }
+    return undefined;
+  }
+
+  return value;
+}

package/src/tools/lcm-conversation-scope.ts

@@ -0,0 +1,76 @@
+import type { LcmContextEngine } from "../engine.js";
+import type { LcmDependencies } from "../types.js";
+
+export type LcmConversationScope = {
+  conversationId?: number;
+  allConversations: boolean;
+};
+
+/**
+ * Parse an ISO-8601 timestamp tool parameter into a Date.
+ *
+ * Throws when the value is not a parseable timestamp string.
+ */
+export function parseIsoTimestampParam(
+  params: Record<string, unknown>,
+  key: string,
+): Date | undefined {
+  const raw = params[key];
+  if (typeof raw !== "string") {
+    return undefined;
+  }
+  const value = raw.trim();
+  if (!value) {
+    return undefined;
+  }
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) {
+    throw new Error(`${key} must be a valid ISO timestamp.`);
+  }
+  return parsed;
+}
+
+/**
+ * Resolve LCM conversation scope for tool calls.
+ *
+ * Priority:
+ * 1. Explicit conversationId parameter
+ * 2. allConversations=true (cross-conversation mode)
+ * 3. Current session's LCM conversation
+ */
+export async function resolveLcmConversationScope(input: {
+  lcm: LcmContextEngine;
+  params: Record<string, unknown>;
+  sessionId?: string;
+  sessionKey?: string;
+  deps?: Pick<LcmDependencies, "resolveSessionIdFromSessionKey">;
+}): Promise<LcmConversationScope> {
+  const { lcm, params } = input;
+
+  const explicitConversationId =
+    typeof params.conversationId === "number" && Number.isFinite(params.conversationId)
+      ? Math.trunc(params.conversationId)
+      : undefined;
+  if (explicitConversationId != null) {
+    return { conversationId: explicitConversationId, allConversations: false };
+  }
+
+  if (params.allConversations === true) {
+    return { conversationId: undefined, allConversations: true };
+  }
+
+  let normalizedSessionId = input.sessionId?.trim();
+  if (!normalizedSessionId && input.sessionKey && input.deps) {
+    normalizedSessionId = await input.deps.resolveSessionIdFromSessionKey(input.sessionKey.trim());
+  }
+  if (!normalizedSessionId) {
+    return { conversationId: undefined, allConversations: false };
+  }
+
+  const conversation = await lcm.getConversationStore().getConversationBySessionId(normalizedSessionId);
+  if (!conversation) {
+    return { conversationId: undefined, allConversations: false };
+  }
+
+  return { conversationId: conversation.conversationId, allConversations: false };
+}

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

@@ -0,0 +1,234 @@
+import { Type } from "@sinclair/typebox";
+import type { LcmContextEngine } from "../engine.js";
+import {
+  getRuntimeExpansionAuthManager,
+  resolveDelegatedExpansionGrantId,
+} from "../expansion-auth.js";
+import type { LcmDependencies } from "../types.js";
+import type { AnyAgentTool } from "./common.js";
+import { jsonResult } from "./common.js";
+import { resolveLcmConversationScope } from "./lcm-conversation-scope.js";
+import { formatTimestamp } from "../compaction.js";
+
+const LcmDescribeSchema = Type.Object({
+  id: Type.String({
+    description: "The LCM ID to look up. Use sum_xxx for summaries, file_xxx for files.",
+  }),
+  conversationId: Type.Optional(
+    Type.Number({
+      description:
+        "Conversation ID to scope describe lookups to. If omitted, uses the current session conversation.",
+    }),
+  ),
+  allConversations: Type.Optional(
+    Type.Boolean({
+      description:
+        "Set true to explicitly allow lookups across all conversations. Ignored when conversationId is provided.",
+    }),
+  ),
+  tokenCap: Type.Optional(
+    Type.Number({
+      description: "Optional budget cap used for subtree manifest budget-fit annotations.",
+      minimum: 1,
+    }),
+  ),
+});
+
+function normalizeRequestedTokenCap(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return undefined;
+  }
+  return Math.max(1, Math.trunc(value));
+}
+
+function formatIso(value: Date | null | undefined, timezone?: string): string {
+  if (!(value instanceof Date)) return "-";
+  if (timezone) {
+    return formatTimestamp(value, timezone);
+  }
+  return value.toISOString();
+}
+
+export function createLcmDescribeTool(input: {
+  deps: LcmDependencies;
+  lcm: LcmContextEngine;
+  sessionId?: string;
+  sessionKey?: string;
+}): AnyAgentTool {
+  return {
+    name: "lcm_describe",
+    label: "LCM Describe",
+    description:
+      "Look up metadata and content for an LCM item by ID. " +
+      "Use this to inspect summaries (sum_xxx) or stored files (file_xxx) " +
+      "from compacted conversation history. Returns summary content, lineage, " +
+      "token counts, and file exploration results.",
+    parameters: LcmDescribeSchema,
+    async execute(_toolCallId, params) {
+      const retrieval = input.lcm.getRetrieval();
+      const timezone = input.lcm.timezone;
+      const p = params as Record<string, unknown>;
+      const id = (p.id as string).trim();
+      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.describe(id);
+
+      if (!result) {
+        return jsonResult({
+          error: `Not found: ${id}`,
+          hint: "Check the ID format (sum_xxx for summaries, file_xxx for files).",
+        });
+      }
+      if (conversationScope.conversationId != null) {
+        const itemConversationId =
+          result.type === "summary" ? result.summary?.conversationId : result.file?.conversationId;
+        if (itemConversationId != null && itemConversationId !== conversationScope.conversationId) {
+          return jsonResult({
+            error: `Not found in conversation ${conversationScope.conversationId}: ${id}`,
+            hint: "Use allConversations=true for cross-conversation lookup.",
+          });
+        }
+      }
+
+      if (result.type === "summary" && result.summary) {
+        const s = result.summary;
+        const requestedTokenCap = normalizeRequestedTokenCap((params as Record<string, unknown>).tokenCap);
+        const sessionKey =
+          (typeof input.sessionKey === "string" ? input.sessionKey : input.sessionId)?.trim() ?? "";
+        const delegatedGrantId = input.deps.isSubagentSessionKey(sessionKey)
+          ? (resolveDelegatedExpansionGrantId(sessionKey) ?? "")
+          : "";
+        const delegatedRemainingBudget =
+          delegatedGrantId !== ""
+            ? getRuntimeExpansionAuthManager().getRemainingTokenBudget(delegatedGrantId)
+            : null;
+        const defaultTokenCap = Math.max(1, Math.trunc(input.deps.config.maxExpandTokens));
+        const resolvedTokenCap = (() => {
+          const base =
+            requestedTokenCap ??
+            (typeof delegatedRemainingBudget === "number" ? delegatedRemainingBudget : defaultTokenCap);
+          if (typeof delegatedRemainingBudget === "number") {
+            return Math.max(0, Math.min(base, delegatedRemainingBudget));
+          }
+          return Math.max(1, base);
+        })();
+
+        const manifestNodes = s.subtree.map((node) => {
+          const summariesOnlyCost = Math.max(0, node.tokenCount + node.descendantTokenCount);
+          const withMessagesCost = Math.max(0, summariesOnlyCost + node.sourceMessageTokenCount);
+          return {
+            summaryId: node.summaryId,
+            parentSummaryId: node.parentSummaryId,
+            depthFromRoot: node.depthFromRoot,
+            depth: node.depth,
+            kind: node.kind,
+            tokenCount: node.tokenCount,
+            descendantCount: node.descendantCount,
+            descendantTokenCount: node.descendantTokenCount,
+            sourceMessageTokenCount: node.sourceMessageTokenCount,
+            childCount: node.childCount,
+            earliestAt: node.earliestAt,
+            latestAt: node.latestAt,
+            path: node.path,
+            costs: {
+              summariesOnly: summariesOnlyCost,
+              withMessages: withMessagesCost,
+            },
+            budgetFit: {
+              summariesOnly: summariesOnlyCost <= resolvedTokenCap,
+              withMessages: withMessagesCost <= resolvedTokenCap,
+            },
+          };
+        });
+
+        const lines: string[] = [];
+        lines.push(`LCM_SUMMARY ${id}`);
+        lines.push(
+          `meta conv=${s.conversationId} kind=${s.kind} depth=${s.depth} tok=${s.tokenCount} ` +
+            `descTok=${s.descendantTokenCount} srcTok=${s.sourceMessageTokenCount} ` +
+            `desc=${s.descendantCount} range=${formatIso(s.earliestAt, timezone)}..${formatIso(s.latestAt, timezone)} ` +
+            `budgetCap=${resolvedTokenCap}`,
+        );
+        if (s.parentIds.length > 0) {
+          lines.push(`parents ${s.parentIds.join(" ")}`);
+        }
+        if (s.childIds.length > 0) {
+          lines.push(`children ${s.childIds.join(" ")}`);
+        }
+        lines.push("manifest");
+        for (const node of manifestNodes) {
+          lines.push(
+            `d${node.depthFromRoot} ${node.summaryId} k=${node.kind} tok=${node.tokenCount} ` +
+              `descTok=${node.descendantTokenCount} srcTok=${node.sourceMessageTokenCount} ` +
+              `desc=${node.descendantCount} child=${node.childCount} ` +
+              `range=${formatIso(node.earliestAt, timezone)}..${formatIso(node.latestAt, timezone)} ` +
+              `cost[s=${node.costs.summariesOnly},m=${node.costs.withMessages}] ` +
+              `budget[s=${node.budgetFit.summariesOnly ? "in" : "over"},` +
+              `m=${node.budgetFit.withMessages ? "in" : "over"}]`,
+          );
+        }
+        lines.push("content");
+        lines.push(s.content);
+
+        return {
+          content: [{ type: "text", text: lines.join("\n") }],
+          details: {
+            ...result,
+            manifest: {
+              tokenCap: resolvedTokenCap,
+              budgetSource:
+                requestedTokenCap != null
+                  ? "request"
+                  : typeof delegatedRemainingBudget === "number"
+                    ? "delegated_grant_remaining"
+                    : "config_default",
+              nodes: manifestNodes,
+            },
+          },
+        };
+      }
+
+      if (result.type === "file" && result.file) {
+        const f = result.file;
+        const lines: string[] = [];
+        lines.push(`## LCM File: ${id}`);
+        lines.push("");
+        lines.push(`**Conversation:** ${f.conversationId}`);
+        lines.push(`**Name:** ${f.fileName ?? "(no name)"}`);
+        lines.push(`**Type:** ${f.mimeType ?? "unknown"}`);
+        if (f.byteSize != null) {
+          lines.push(`**Size:** ${f.byteSize.toLocaleString()} bytes`);
+        }
+        lines.push(`**Created:** ${formatIso(f.createdAt, timezone)}`);
+        if (f.explorationSummary) {
+          lines.push("");
+          lines.push("## Exploration Summary");
+          lines.push("");
+          lines.push(f.explorationSummary);
+        } else {
+          lines.push("");
+          lines.push("*No exploration summary available.*");
+        }
+
+        return {
+          content: [{ type: "text", text: lines.join("\n") }],
+          details: result,
+        };
+      }
+
+      return jsonResult(result);
+    },
+  };
+}